Introduction

The AdTag Management System simplifies the integration of ad server JavaScript Tags by means of a central library. Instead of integrating multiple AdTags into the HTML documents of your site individually, it assumes the function of the deployment and control of the AdTags based on predefined parameters.

By way of an example, the present documentation will guide the reader through a complete integration process for the system.
You can use code examples from this documentation in a test site at any time.

Glossary

This documentation will use some recurring technical terms.

ad slot/Slot

This term describes a location on an HTML site which can be filled with advertising media. The ad slot will have a name assigned to it depending on its position on the website. This name (which is often an abbreviation consisting of a few letters only) is the same for all ad slots throughout the website which are placed in the same way.
Example: An ad slot is placed centrally preceding the content and even preceding the navigation structure. The ad slot will receive the abbreviated designation of “banner” (short for “Superbanner”).  Independently of whether it will be placed on the homepage of the website or in articles, this slot will always be named “banner”.

AdServer

A web server whose function is the administration and delivery of advertising campaigns. The ad server waits for a user request, often based on additional information such as the website visited, user interests and so forth, and responds by delivering a suitable advertising campaign for that user.

AdTag

Refers to a request of the ad server, usually via JavaScript. After communication with the ad server, the AdTag delivers the content for the ad slot in which the AdTag was placed. MetaTag will automatically generate all the AdTags for the different ad slots on the basis of different kinds of information, without any additional assistance from the website.

Advertising format

An advertising format is composed of one or two media (Image- Flash, Video) of a particular size. The sizes are, as a rule, standardized, which means that a medium of a certain size is always designated to be a certain advertising format.
Example: An image of a pixel size of 728x90 is designated as a “Leaderboard”. A combined format consisting of the sizes 728x90 and 160x600 pixels placed next to each other is known as a “Hockeystick” or a “Wallpaper”.
A list of all possible “desktop” formats can be found under: Formatspezifikationen (Ad Format Specifications)

HeaderBidding

When using a so called "HeaderBidder", all ad slots of a page will be analyzed by an auction in realtime, before the slots are fully loaded. Advertisers have the possibility to decide how much money the display of an ad on the site is worth to them and place a bid accordingly. This leads to a better, targeted utilization of all possible ad slots and improves the loading speed of the site and all displayed ads.

Single Request Architecture

Instead of sending a separate request for each ad slot to the ad server, SRA will use a single, bundled request for all ad slots at once. This will improve the load speed of the website and decrease the workload on the device and browser of the user caused by ads. SRA is incompatible with a few advertising formats, therefore usage of SRA should be discussed up front with us, so we can depict any negative impact clearly.

Table of Contents

Cache time of file: 900 sec
Size: ~ 25 kB
Employed CDN: Cloudfront
Server locations used: closest to user, see map
Compression: gzip, brotli

SDG.cmd

cmd: Array<Function => void>

Reference to MetaTag command queue for asynchronous execution of interface methods.
Will be initalized as an empty JavaScript array, exposing cmd.push with standard Array.push method.

Wrap all your commands send to MetaTag inside a function, pushing it into cmd.

Example

_{> back to method list}

SDG.Publisher

Publisher: PublisherApi

Returns a reference to the PublisherApi, containing all interface methods to interact with metaTags gloabl commands, described below.

Returns

• PublisherApi

SDG.Publisher.setZone( zone )

setZone(zone: string): boolean

Sets the AdTag Zone for the HTML page.
A zone allows ad systems to differentiate the current section of your website, making it possible to target ad campaigns to one or more specific zones/sections.

For a detailed view, which zones can be used on your website, please consult the “marketing structure” file.

Example

_{> back to method list}

Argument(s)

• zone: string - The zone for the matching web site category from the marketing structure provided in table form

Returns

• boolean - true if successful, otherwise false

SDG.Publisher.addKeywords( keywords )

addKeywords(keywords: Array<string>): boolean

Transfers multiple keywords to the ad server. These can be used to describe the content of a website. Be it keywords for optimizing the search engine, or specific information contained in your site (such as the ingredients for a recipe displayed on the site).

Example

_{> back to method list}

Argument(s)

• keywords: Array<string> -  An array in which keywords are arranged one after the other in the form of a string, separated by commas. It can consist of 15 words maximum.

Returns

• boolean - true if successful, otherwise false

SDG.Publisher.addKeyword( keyword )

addKeyword(keyword: string): boolean

Transfers a single keyword to the ad server.

Example

_{> back to method list}

Argument(s)

• keyword: string =  The keyword to be transferred.

Returns

• boolean -  true if successful, otherwise false

SDG.Publisher.removeKeywords( keywords )

removeKeywords(keyword: Array<string>): boolean

Removes multiple previously added keywords. Useful in Single-page-applications, where the content (and its descriptive keywords) change on user navigation.

Example

_{> back to method list}

Argument(s)

• keywords: Array<string> -   Array in which the keywords are arranged one after the other in the form of a string, separated by commas. It can consist of 15 words maximum.

Returns

• boolean -  true if successful, otherwise false

SDG.Publisher.removeKeyword( keyword )

removeKeyword(keyword: string): boolean

Removes a single previously added keyword.

Example

_{> back to method list}

Argument(s)

• keyword: string - The keyword to be deleted.

Returns

• boolean -  true if successful, otherwise false

SDG.Publisher.addKeyValue( key, value )

addKeyValue(key: string, value: string): boolean

Transfers a pair of parameters consisting of a key and a value to the ad server.
You can use so-called “key values” to transfer further information to the ad server.

These can be data referring to the website or to the user, such as the interests of the user or the location of a request for a weather forecast.

Please consult your Partner Manager before using this function. The data to be used should be coordinated before the implementation, and should be in conformity with current data protection laws.

Example

_{> back to method list}

Argument(s)

• key: string - The key to be transferred.

• value: string - The value to be transferred for the keyword

Returns

• boolean -  true if successful, otherwise false

SDG.Publisher.addKeyValues( keyValues )

addKeyValues(keyValues: Object<string, string[]>): boolean

Transfers a pair of parameters to the ad server which consists of a key and multiple words surrounded by a JavaScript Literal-Object. The values are arranged in a sequence in an array and separated by commas. A maximum of 15 values can be transferred at a time.
You can use so-called “key values” to transfer further information to the ad server. These can be data referring to the website or to the user, such as the interests of the user or the location of a request for a weather forecast.

Example

_{> back to method list}

Argument(s)

• keyValues: Object<string, string[]> - An object of keys consisting of arrays, each containing multiple values as string

Returns

• boolean -  true if successful, otherwise false

SDG.Publisher.removeKeyValue( key )

removeKeyValue(key: string): boolean

Removes a previously added key and all its assigned values.

Example

_{> back to method list}

Argument(s)

• key: string -  The key to be removed.

Returns

• boolean -  true if successful, otherwise false

SDG.Publisher.removeKeyValues( keyChain )

removeKeyValues(keyChain: Array<string>): boolean

Removes multiple previously added keys and all of their assigned values.

Example

_{> back to method list}

Argument(s)

• keyChain: Array<string> - A chain of key names as array

Returns

• boolean -  true if successful, otherwise false

SDG.Publisher.registerSlot( slotname, container )

registerSlot(slotname: string, container: string | HTMLElement): PublisherSlotApi | null

Creates a new ad slot in the container indicated.

The container can be any HTML element capable of accepting multiple further child elements. For the best results, <div> elements are recommended as containers.
When executing the method registerSlot, the container does not have to be rendered fully by the browser.

In the section Integration of the different advertising formats, we have provided a summary of the best practice for creating the different containers dependent on the advertising format.

This method only serves to register the slot with the system. To enable the slot to start requesting an advertising medium from the ad server afterwards, please use the slot methods or the Publisher methods loadSlot() and loadAllSlots().

Example

_{> back to method list}

Argument(s)

• slotname: string - The name for the desired slot

• container: string | HTMLElement - The container for the slot either as string of its "ID" attribute, or as a DOM node (such as using document.getElementById(), document.querySelector(), etc.)

Returns

• PublisherSlotApi | null = If successful, this method will return an interface object, allowing further interaction with the created AdSlot, called PublisherSlotAPI.
  In case of an error, the return value will be null.

SDG.Publisher.finalizeSlots()

finalizeSlots(): void

Will signal the system that all relevant ad slots for the HTML page have been registered.

The system will prepare all registered slots and bundle them for the request to the ad server and collect data concerning the page environment and user data. This will enhance load performance of your website and ensures that all slots are known to connected ad systems.

You can register additional slots, even after executing finalizeSlots(). Additional slots will execute their ad delivery as soon as they receive a load command.

Example

_{> back to method list}

Argument(s)

• no further arguments needed

Returns

• no return value

SDG.Publisher.unregisterSlot( slotName, deleteAdContent )

unregisterSlot(slotName: string, deleteAdContent: boolean): boolean

Deletes a specific ad slot from the page. On request, the method will also delete all advertising media loaded by the slot up to that point.
This will free up the ad slot, making it available for re-registering if needed.

Example

_{> back to method list}

Argument(s)

• slotname: string - The name for the desired slot

• deleteAdContent: boolean - If true, all advertising media already loaded by the slot will be deleted from the page. If false, the advertising media continue to be available. If no value has been entered, the system will use the value "true" by default.

Returns

• boolean - true if successful, otherwise false

SDG.Publisher.loadSlot( slotName )

loadSlot(slotName: string): boolean

Initiates a request to the ad server for a single, previously registered ad slot. This method serves to load an ad slot at a later point in time after registration, for example if the user has interacted with the site and a single slot should display new ads.
When using this method, the ad slot will be loaded independently of all other slots on the page. It might miss additional features like competitor exclusions or lack functionality to display ads spanning over multiple slots.

Example

_{> back to method list}

Argument(s)

• slotname: string - The name for the desired slot

Returns

• boolean - true if successful, otherwise false

SDG.Publisher.loadMultipleSlots( slotNames )

loadMultipleSlots(slotNames: Array<string>): boolean

Initiates request to the ad server for all stated and registered ad slots. You can use this method to load ad slots at a later point in time after registration. For example, if the user has interacted with the site and multiple slot should display new ads.

All slots loaded via this method will act together. They can use additional features like competitor exclusions or use functionality to display ads spanning over multiple slots.
The order of the slotnames inside the array has a direct influence on the load sequence of the slots. Please make sure to consider our "Guidelines for integrating advertising spaces" and the recommended load sequence within.

Example

_{> back to method list}

Argument(s)

• slotnames: Array<String> - The names of the ad slots to load. The order of the names is relevant (look above).

Returns

• boolean - true if successful, otherwise false

SDG.Publisher.loadAllSlots( redoLoadedSlots )

loadAllSlots(redoLoadedSlots: boolean): boolean

Initiates a request to the ad server for all hitherto registered ad slots. This method serves to load all ad slots at a later point in time after registration, for example in SinglePage Webapplications, as soon as the user is provided with new content.

This method will automatically load the slots in correct sequence and lets all slots act together. Additional features like competitor exclusions and the ability to display ads spanning over multiple slots are provided.

Example

_{> back to method list}

Argument(s)

• redoLoadedSlots: boolean -  If true, all ad slots will be loaded, even if they have already been loaded previously. Already existing advertising media will be deleted from the page and new ones will be delivered by the ad server. Will be automatically assigned the value “false” by default.

Returns

• boolean- true if successful, otherwise false

SDG.Publisher.generateVastUrls( vastPositions )

This method returns a JSON formatted object, containing a VAST-Adtag for each requested video ad format.

Call this method once you know that the video player should deliver an advertisement.
The URLs that get returned from this method can be passed directly to your video player. Please see the documentation of your video player on how to pass VAST URLs on run-time.

Here you will find example documentations for the most used VAST-components or publically available players. Your video player might differ, please contact your player provider in case of questions or problems.
Google IMA SDK: https://developers.google.com/interactive-media-ads/docs/sdks/html5/client-side#6.-initialize-the-adsloader-and-make-an-ads-request
JW Player:

Example

If you like to test your video player with an PreRoll ad, you can call the generateVastUrls() method with these arguments:

_{> back to method list}

Additional Types

• videoFormats: "preroll" | "midroll" | "postroll" | "overlay" - video format name, for which a VAST URL can be requested.

• videoZone: string - dependend on the zone, different VAST URLs can be generated. Used to differentiate sections of your website from each other and to allow campaigns to deliver only on specific sections.

Argument(s)

• vastPositions: Record<videoFormats: boolean>, videoZone - The formats you wish to get VAST-adtags for. Every entry within the object is optional. Each entry that gets passed through this method will return a value. If a format does not get passed in the argument, there will be no return value.

Returns

• object - Returns a JSON formatted object with the position names as values and the corresponding VAST-adTag as keys which were passed within the argument.

SDG.Publisher.generateVastUrlsPromise( vastPositions )

Returns a Promise resolving into a JSON formatted object, containing a VAST-Adtag for each requested video ad format.
To learn about the way promises work and how you can use them, we advise you to read Using promises first.

A common good practice for displaying a video player with ads:

• Insert your video player in the website and let it render.

• Disable autoplay, so the user needs to start the video player by clicking on a “start” button.

• As soon as user wants to start video, use generateVastUrlsPromise()

• When Promise resolves, use returned VAST Urls and configure your video player accordingly.

  • Please see the documentation of your video player on how to pass VAST URLs on run-time.

This Promise will never reject, making it necessary to implement a fallback. Otherwise, your player might wait indefinitely for the Promise to settle.

Examples

If you like to test your video player with an PreRoll ad, you can call the generateVastUrlsPromise() method with these arguments:

_{> back to method list}

Additional Types

• videoFormats: "preroll" | "midroll" | "postroll" | "overlay" - video format name, for which a VAST URL can be requested.

• videoZone: string - dependend on the zone, different VAST URLs can be generated. Used to differentiate sections of your website from each other and to allow campaigns to deliver only on specific sections.

Argument(s)

• vastPositions: Record<videoFormats: boolean>, videoZone - The formats you wish to get VAST-adtags for. Every entry within the object is optional. Each entry that gets passed through this method will return a value. If a format does not get passed in the argument, there will be no return value.

Returns

• Promise<object> - Returns a JSON formatted object with the position names as values and the corresponding VAST-adTag as keys which were passed within the argument.

SDG.Publisher.setAdServerConsent( personalizedAdsAllowed )

setAdserverConsent(personalizedAdsAllowed: boolean): void

Will notify the tag manager if, as the Publisher of your website, you reject the usage of personalized user data in the delivery process of advertisements. As a default, we assume your permission.

Site visitors can allow the usage of personalized data on your site through a Consent Management Platform (CMP). However, you as the publisher can digress from this decision and mark the content of the page as especially relevant for protection of data privacy and explicitly forbid the usage of personalized data.

This can be useful if the content of your site (texts, URL, etc.) allows to drawing privacy-sensitive conclusion from the visitor (ex: illnesses, religious or sexual orientation).
While the visit of a user to such content will never be directly or permanently linked to the profile of the user, visited URLs and content keywords might be used in the selection of personalized ads as long as the user visits the page.

Example

_{> back to method list}

Argument(s)

• personalizedAdsAllowed: boolean - Use false if you want to object to personalized ads

Returns

• no return value

SDG.Publisher.transitionAdvertisements()

transitionAdvertisements(): boolean

This enables interstitial advertisement to be displayed on both mobile and desktop environments depending on user device type.

Example

_{> back to method list}

Argument(s)

• no further arguments needed

Returns

• boolean - true if successful, otherwise false

Slot.load()

load(): AdSlotClass

Initiates a request to the ad server for a single ad slot, as soon as the container of the slot is rendered by the browser. The purpose of this method is to mark the ad slot for loading directly upon registration.

You don't have to send any further commands for the slot to load. It will automatically monitor the page and only send the request to the ad server as soon as the container becomes available. If the container is already present on the site, the slot will start the request at once. Therfore, you can use this method already in the <head> of the page. Neither the slot will be loaded (until the container is available), nor the site be influenced negatively.

Should you want to load the slot again, for example because the content of the site was changed and, the user should receive new ads, you can use the PublisherApi methods loadMultipleSlots() or loadAllSlots().

Example

_{> back to method list}

Argument(s)

• no arguments required

Returns

• AdSlotClass- The ad slot for calling up further methods of the slot

Slot.setTargeting( keyValues )

setTargeting(keyValues: Object<string, string[]>): AdSlotClass

Transfers a pair of parameters to the ad slot which consists of a key and multiple words bracketed by a JavaScript Literal-Object. The values are arranged in sequence in an array and separated by commas. A maximum of 15 values can be transferred at a time.

You can use so-called “key values” to transfer further information to the ad server. These can be data referring to the website or to the user, such as the interests of the user or the location of a request for a weather forecast.
As opposed to the method Publisher.addKeyValues() the pair is only transferred to the respective slot.

Example

_{> back to method list}

Arguments(s)

• keyValues: Object<string, string[]>- An object consisting of multiple keys as arrays, each containing multiple values as string

Returns

• AdSlotClass- The ad slot for calling up further methods of the slot

Slot.removeTargeting ( key, value )

removeTargeting(key: string, value:string?): AdSlotClass

Removes a key value pair from an ad slot

Should you pass a key and value, only the given value will be removed from the key. Should you pass only a key, without the value argument, the whole key including all values will be deleted.

Example

_{> back to method list}

Argument(s)

• key: string - the key you like to edit / remove

• value: string? [optional] - the value that should be removed

Returns

• AdSlotClass- The ad slot for calling up further methods of the slot

Slot.blockFormats( formatList )

blockFormats(formatList: Array<string>): AdSlotClass

Excludes multiple ad formats from delivering on the current HTML page, only for the used ad slot.

During the initial set up of your website in our system, we will make sure to only serve formats fitting to your website. Therefor, you will only need to block a format, if a given HTML page deviates significantly from your normal website design and the format (otherwise causing no trouble) will not work correctly.

Should you wish a block a format for your whole website for good (for example: after you made some changes to the design of your site) please contact your Ströer representative, so we can exclude the format permanently.

Example

_{> back to method list}

Argument(s)

• formatList: Array<String>- An array which contains the to be blocked format names as a string.
  The following format names can be used : 

Returns

• AdSlotClass- The ad slot for calling up further methods of the slot

Slot.configure ( configObject)

configure(configObject: Record <string, number | boolean>): AdSlotClass

Changes how the ad slot behaves on your website. You are able to control features like “Cumulative Layout Shift” avoidance, showing advertisements labels, showing loading animations or how and when to position or load ads inside the slot.

If you do not use this function, default settings from our base configuration are used without any further need to intervene.

Example

_{> back to method list}

Argument(s)

• configObject: Record <string, number | boolean> - All properties of the object are optional. Available options:

  • reserveSpace: boolean - slot will reserve space on the site, to avoid Cumulative Layout Shift (CLS). If no fixedHeight is set, the slot will reserve the largest height of all formats it's capable of.
    For more information on CLS, please see: Avoiding "Layout Shifts"
    
    

  • fixedHeight: number - slot will reserve this height on the site, to avoid Cumulative Layout Shift (CLS).
    
    

  • showAdvertLabel: boolean - slot will show a label on the site next to the slot, indicating an advertisement to the site visitor. Advertisement labels are shown by default.
    
    

  • showLoadingAnimation: boolean - Shows a small loading animation, when slot will reserve space. Animations will help the site visitor to recognize that content is still loading and gaps inside the site will be filled in due time.
    
    

  • centerAds: boolean - slot will position all advertisement elements in its center. By default, ads are positioned on the left side of the slot.
    
    

  • lazyLoad: boolean - When you send a load command to the slot, it will be delayed until the slot is scrolled into view by site visitor. For more information on lazy loading ad slots, please see: .
    Depending on the website, “lazyLoad” might have significant impact on your advertisement revenue. Please reach out to your Ströer contact before implementing LazyLoad for further information.
    
    

  • pinToBottom: boolean - Ads delivered in this slot will be positioned at the bottom of the browser window, scrolling along with the user. A highly visible close button will remove the ad slot when clicked by the user. Mostly used for the mobile ad slot “stickyfooter”.

Returns

• AdSlotClass- The ad slot for calling up further methods of the slot

Slot.nativeBackfill ( fallbackAd )

nativeBackfill(fallbackAd: Function() => HTMLElement): AdSlotClass

If an ad slot does not receive an advertisement from any ad server, you can pass an “fallback” advertisement to render instead.

Example

_{> back to method list}

Argument(s)

• fallbackAd: Function() => HTMLElement - Passed function must return an HTMLElement. The slot will then render the element inside the ad slot, treating it as an advertisement.

Returns

• AdSlotClass- The ad slot for calling up further methods of the slot