Options
All
  • Public
  • Public/Protected
  • All
Menu

@smartclip/display-client

smartclip Client-side Framework for display advertisement

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 object 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 append 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 Client-side Framework configuration object can be created on the page. The configuration consists of a brief "global" part followed by one or more ad slots.

Global 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 the Framework
  • additionalData additional data for the ad server, keys should not contain any URL-breaking characters and will be transported as is, values need to be encoded
  • Event Callbacks can be configured for events listed in Client-side Framework communication

Ad Slot values

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

  • inventoryReference is optional in case a global value is present; it is the only global value for inventoryReference that can be overridden on individual ad slot level.
  • deliveryMode ad server can be requested for 1 (unfriendly iFrame, default) or 2 (friendly iFrame). This value signals the beginning of a new slot to the ad server.
  • elementId ID of the div element in the page
  • supportedDimensions an array of supported ad sizes (width and height) for this ad slot
  • 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 API. A publisher will be able to listen for events about the global ad request and the individual ad slots.

Global events

Global 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

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

Errors

Various errors can be detected and will be passed via the corresponding (Global or AdSlot) error event.

Global Errors

List of errors that affect the integration of display advertisement on the whole page.

  • TBD

AdSlot Errors

List of errors that affect individual ad slots on the page.

  • TBD

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
  • crexreq=1 static value for creative selection and reporting in Smartx

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
  • stream so called stream ID, which must be identical for all requests of that page, 9-digit random number

The Client-side Framework would also be able to query the TCF API v2.0 to get a consent string. However, the publisher can pass a consent string as part of the configuration which will overwrite any value received by the API. For the time being, the publisher will be required to pass a consent string.

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

Sample

An example configuration for the smartclip Client-side Framework for display advertisement:

var sample_configuration = {
inventoryReference : 'primaryInventory',
tcString : '[INSERT_GDPR_CONSENTSTRING_HERE]',
additionalData : {
'moreData' : 'canBeAddedHere'
},
onError : myErrorEvent,
slots : [
{
deliveryMode : 2,
id : 'firstElementforBannerAds',
supportedDimensions : [
{ width : 300, height : 250 },
{ width : 300, height : 160 }
],
onAdDelivered: slotDeliveredCallback,
onAdLoaded: slotLoadedCallback,
onError: slotErrorCallback
},
{
inventoryReference : 'primaryInventory/secondaryLevel',
deliveryMode : 2,
id : 'secondElementforBannerAds',
supportedDimensions : [
{ width : 160, height : 600 },
{ width : 475, height : 0 }
],
onAdDelivered: secondSlotDeliveredCallback,
onAdLoaded: secondSlotLoadedCallback,
onError: secondSlotErrorCallback
}
]
};

The example above would result in two ad requests by the Client-side Framework:

  • ad.sxp.smartclip.net/select?type=banner&s=primaryInventory&bkey=2:firstElementforBannerAds:300x250:300x160&ang_sch=1080&ang_scw=1920&ang_ref=https%3A%2F%2Fdev.smartclip.net%2Fusr%2Ffko%2Ft%2Fbanner%2Falpha.html&dom=dev.smartclip.net&consent=undefined&rnd=16469988
  • ad.sxp.smartclip.net/select?type=banner&s=primaryInventory%2FsecondaryLevel&bkey=2:secondElementforBannerAds:160x600:475x0&ang_sch=1080&ang_scw=1920&ang_ref=https%3A%2F%2Fdev.smartclip.net%2Fusr%2Ffko%2Ft%2Fbanner%2Falpha.html&dom=dev.smartclip.net&consent=undefined&rnd=16469988

Supported ad formats

The Client-side Framework 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, the Client-side Framework will not render the empty slot and trigger an onError Callback.

Generated using TypeDoc