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.
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)
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.
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.
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 slotstcString required transparency and consent stringpageUrl optional page URL, if no value is provided it will be automatically populated by the FrameworkadditionalData additional data for the ad server, keys should not contain any URL-breaking characters and will be transported as is, values need to be encodedConfiguration 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 pagesupportedDimensions an array of supported ad sizes (width and height) for this ad slotThe 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 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 ErrorsAd slot events will concern a single ad on the page.
onAdDelivered when an ad has been deliveredonAdLoaded when an ad has finished loadingonAdError when an error has been detected with the ad, see section ErrorsVarious errors can be detected and will be passed via the corresponding (Global or AdSlot) error event.
List of errors that affect the integration of display advertisement on the whole page.
List of errors that affect individual ad slots on the page.
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.
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 adscrexreq=1 static value for creative selection and reporting in SmartxAutomatically populated URL-parameters are:
ang_ref full URL of the top-level page where the end user will view the adang_sch screen height, for example 1080ang_scw screen width, for example 1920rnd cachebuster, 8-digit random numberstream so called stream ID, which must be identical for all requests of that page, 9-digit random numberThe 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.
Values to the following URL-parameters will be taken from the configuration as provided by the publisher:
s inventory referencebkey 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 stringAn 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:
The Client-side Framework is going to support the following ad formats:
All ad formats will be served as html code from Smartx ad server.
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