smartclip Client-side Framework for display advertisement

smartclientdisplay, the smartclip Client-side Framework for display advertisement, will handle ad server communication, request display advertisement, and deliver the creatives into defined div elements on the page. The Client-side Framework will also communicate life cycle events for served creatives as well as error information.

Supported browsers

It is planned to support the two most recent versions of the following browsers: Chrome, Safari, Firefox, Edge. Additionally, IE 11 would be supported -- and all versions that are still supported by their vendors (cf. support.google.com/admanager/answer/188087?hl=en).

Implementation

The smartclip Client-side Framework is available as a compiled JavaScript file that can be inserted into the header of a page or loaded alongside other scripts relevant to a web page. A configuration needs to be provided with necessary information to request display advertisements from Smartx ad server on the page. To start processing the configuration and requesting the ads, a run function has to be called.

After the smartclientdisplay script, add the following snippet:

!function(e){ e.s7p=e.s7p||function(){(s7p.q=s7p.q||[]).push(arguments)}; }(window);

..and create an instance with minimal configuration for one ad slot:

s7p('create', {
  inventoryReference: 'foo/bar',
  consentString: '[INSERT_GDPR_CONSENTSTRING_HERE]',
  slots: [
    {
      id: '[ELEMENT_ID_FOR_AD]',
      supportedDimensions: [
        {
          width: [DESIRED_WIDTH_OF_AD],
          height:  [DESIRED_HEIGHT_OF_AD]
        }
      ]
    }
  ]
});

Following your initialization, call run to request advertisement from the Smartx ad server:

window.s7p('cmd', 'run');

The Smartx ad server will respond with a JSON object which contains the creative code and additional data. Callbacks will inform about an ad having been delivered and loaded.

If the run command happens to be executed a second time, the ad server will treat the request as new and unrelated.

Elements that are designated for display ads in the configuration are assumed to be empty containers. No styles are added or manipulated. Whether an element is empty or not, smartclientdisplay will not check for existing code or manipulate the content, it will only add an iFrame of the correct size and insert the code of the creative. Please note that the use of colons as part of the element ID is not supported.

Configuration

The smartclientdisplay configuration can be created on the page. It consists of a brief general part followed by one or more ad slots. The configuration parameters control communication to the ad server and details from the publisher-side. smartdisplayclient does not (and cannot) validate user input. Initial setup and later adjustment should be coordinated closely with a Smartx representative.

General values

This information will be used as default for all ad slots on the same page unless a different value is set on slot level.

inventoryReference optional ad server inventory reference to function as default for all slots
tcString required transparency and consent string
pageUrl optional page URL, if no value is provided it will be automatically populated by smartdisplayclient
additionalData additional data for the ad server, keys should not contain any URL-breaking characters and will be transported as is, values will be encoded for transmission
Event Callbacks can be configured for events listed in Client-side Framework communication

Configuration of one or more ad slots will require the following data for each individual slot.

elementId ID of the div element in the page
deliveryMode ad server can be requested for 1 (unfriendly iFrame, default) or 2 (friendly iFrame)
supportedDimensions an array of supported ad sizes (width and height) for this ad slot
inventoryReference is optional and will override the general value for inventoryReference
Event Callbacks can be configured for events listed in section Client-side Framework communication

Client-side Framework communication

The Client-side Framework will pass information about the current status via Callbacks. A publisher will be able to listen for events about the global ad request and the individual ad slots. Ad slot Callbacks are passing an ad object, Error Callbacks an error object.

General events

General events will concern the basic function of the Framework and the request for ads.

onError when an error has been detected in the page DOM, configuration object or ad request, see section Errors

Ad slot events will concern a single ad on the page.

onAdDelivered when an ad has been delivered
onAdLoaded when an ad has finished loading
onAdError when an error has been detected with the ad, see section Errors

Minimal configuration with Callbacks:

s7p('create', {
  inventoryReference: 'foo/bar',
  consentString: '[INSERT_GDPR_CONSENTSTRING_HERE]',
  onError: myCustomFunctionForGeneralError,
  slots: [
    {
      id: '[ELEMENT_ID_FOR_AD]',
      supportedDimensions: [
        {
          width: [DESIRED_WIDTH_OF_AD],
          height:  [DESIRED_HEIGHT_OF_AD]
        },
        {
          width: [OPTIONAL_ALTERNATIVE_WIDTH_OF_AD],
          height:  [OPTIONAL_ALTERNATIVE_HEIGHT_OF_AD]
        }
      ],
      onAdDelivered: myCustomFunctionForAdDeliveredEvent,
      onAdLoaded: myCustomFunctionForAdLoadedEvent,
      onError: myCustomFunctionForAdSlotError
    }
  ]
});

Errors

Errors will be passed via the corresponding (General or Ad Slot) error event.

General Errors

A general error occurs if the configuration is incomplete, if one of the designated slots (id: '[ELEMENT_ID_FOR_AD]') cannot be found, if the returned advertisement does not match the supported dimensions of a slot, or if the ad server response does not contain any advertisements.

function myCustomFunctionForGeneralError(e){
  console.log('General Error! ', e);
}

In case the ad response does not match supported dimensions, the output would be: General Error! CompatibilityError: ad does not fit into slot displaybanner.

An ad slot error occurs if the ad server response signals that no advertisement can be delivered at this time (which can happen because of frequency capping, geographical targeting or other settings) or if the returned advertisement is incomplete.

function myCustomFunctionForAdSlotError(e){
  console.log('Ad Slot Error! ', e);
}

In case the ad server response was found empty, the output would be: Ad Slot Error! NoAdFoundError: Received empty response for slot 'displaybanner'

Ad requests to Smartx ad server

Ad requests are going to carry various parameters. Some of them will automatically be populated by the Framework, some will have to be passed by the publisher via configuration.

URL-parameters from the Client-side Framework

Values to the following URL-parameters will be static or populated by the Client-side Framework. Static parameters are:

type=banner signaling a request for display ads

Automatically populated URL-parameters are:

ang_ref full URL of the top-level page where the end user will view the ad
ang_sch screen height, for example 1080
ang_scw screen width, for example 1920
rnd cachebuster, 8-digit random number

URL-Parameters from the Publisher

Values to the following URL-parameters will be taken from the configuration as provided by the publisher:

s inventory reference
bkey definition of ad slots, a colon-separated list consisting of one element ID, one or more supported ad dimensions and one delivery mode ("banner key"). A delivery mode value signals the beginning of a new slot to the ad server.
consent consent string

Supported ad formats

Smartclientdisplay is going to support the following ad formats:

Medium Rectangle (display or video)
Floor ad (display or video; always a friendly iframe)
Native ads (card or video; always a friendly iframe)

All ad formats will be served as html code from Smartx ad server.

Handling empty ad slots

If the ad server cannot fill an ad slot, smartclientdisplay will not render the empty slot and trigger an onError Callback.