English MetaTag Documentation NEW DESIGN WORK IN PROGRESS

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.

Table of Contents


By way of an example, the present documentation will guide the reader through a complete integration process for the system. You may use the examples and fragments of code introduced here in a test site at any time.
Please note, however, that these examples may not be used in a productive/live site for any purposes.

Glossary


This documentation will use some recurring technical terms.

Term

Description

Term

Description

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 “sb” (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 “sb”.

AdServer

A web server whose function is the administration and delivery of advertising campaigns. The ad server waits for a user request and - ; often based on additional information such as the website visited, user interests and so forth - 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. The MetaTag System will automatically generate all the AdTags for the different ad slots on the basis of different kinds of information, without any additional interference 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, standardised, 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 utilisation 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.

Integration of metaTag.min.js


Please include the provided library (ending in metaTag.min.js) in the <HEAD> tag of your website. The file either can be served by the domain of your website or be loaded directly from our CDN.
The library is created for each website individually and will only work correctly on this specific site.

Request from our CDN (Content Delivery Network)

You will receive the path to the file from a Partner Manager responsible for your account (and, as a rule, with the same E-Mail as this documentation).


Example

<!DOCTYPE html> <html> <head> ... <script src="https://cdn.stroeerdigitalgroup.de/metatag/live/beispielseite/metaTag.min.js" type="text/javascript"></script> ... </head> <body> ... </body> </html>

For performance reasons, having been requested once by the user of a website, the file will be automatically cached by the browser. Subsequent visits by the user will utilize the cached version of the file.
The employed CDN is provided by Akamai, featuring servers near the users access point around the globe. If you like to know more how Akamai ensures peak performance and security, please visit: https://www.akamai.com/

You can view the uncompressed file by removing the character string “.min” from the file name. This version of the file will feature human-readable source code including all comments and JSdoc entries.
The library will receive new features and updates regularly. Please see our Release Log for in-depth information about those changes.

Request from your domain

Feel free to serve the library directly from your domain, this might help the user to download the library faster.
Please make sure that the file will need to be re-downloaded from our CDN to your domain at regular intervals (at least once a day).

Should you like to know more about performance gains, when serving the file from your domain, please see our documentation https://stroeerdigitalgroup.atlassian.net/wiki/spaces/SDGPUBLIC/pages/1027736096

 

Integration of additional Ads.txt file


In order to participate safely in an automatic (programmatic) auctioning network environment, it is possible to lodge an additional file in the domain of the website. This file contains a list of all approved and certified parties, that are eligible for the sale of advertisements on your website. During the auction process, advertisers can scan the file and check if they are negotiating with an authorized party. This assures that the relation between seller, buyer, and the website is established. In addition unauthorized parties will be strictly excluded.

We already offer a prepared file ready to use via the following URL http://cdn.stroeerdigitalmedia.de/Ads/adstxt/ads.txt
Please download this file and place it in the root domain of your website, for example //mydomain.com/ads.txt

Please make sure this file stays updated. We recommend a synchronization every 24 hours (e.g. via Cronjob).  This guarantees that changes will be applied as soon as possible for your website.

Feel free to add further entries concerning Ads.txt into your data set, e.g. if you like to include any additional marketing partners. Please make sure that on automatic retrivial of our version of adx.txt, your changes are applied regularly to your version of the file.
You can check your version of the file for errors or problems, with several freely avaible, online validators. For example: https://adstxt.guru/validator/

Further Information about Ads.txt can be found on the website of the Interactive Advertising Bureau, initiator of the Ads.txt initiative.

 

Configuration of the page parameters


In order to be able to allocate the correct AdTags to your website, the library requires further information.
This information varies depending from which HTML page the advertisements are being called up. For instance, the library needs different information for the start page of your website than for an article in the category “Fashion”.

For the transfer of this information different options are available, each functioning as an interface between your website and the Tag Management System.
Most of these methods can likewise be called up in the <head> of the HTML page, right after loading the „metaTag.min.js“ script.

In case if this is not possible, the functions may also be called up from another location within the HTML source text. However, the information must be complete and fully available before the first ad slot is called up via the registerSlot() method).
When loading the „metaTag.min.js “ asynchronously, you must ensure that the configuration will not be executed until the file has been fully loaded. Archive this by using the JavaScript "EventListener onLoad" on the <script> tag of the library and include the configuration in its callback.

In order to fill the functions with content, you need the marketing structure of your website to be available in table form. You should have received this with the same e-mail as your documentation, or you may request this table from your Ströer Partner Manager.

Marketing Structure

The marketing structure of a website does not necessarily correspond to the actual structure of that website. The names for the sections/sub-sections may be different and some sections might not be used for marketing purposes. This allows us to integrate the website into a uniform product world for advertising customers in the best possible way.

For testing purposes, you may use the following marketing structure:

Main-section

Sub-Section

MetaTag - Zone

Avaible ad slots

Main-section

Sub-Section

MetaTag - Zone

Avaible ad slots

Homepage

 

homepage

banner,sky,out-of-page,rectangle,billboard

News

 

nachrichten

banner,sky,out-of-page,rectangle,topmobile,interstitial,topmobile2

News

 

nachrichten

banner2,banner3,sky,out-of-page,rectangle,topmobile,interstitial,topmobile2

News

 

nachrichten

banner, sky

Beauty

 

beauty

banner,sky,out-of-page,rectangle

Beauty

Mode

beauty_mode

banner,sky,out-of-page,rectangle

Beauty

Health

beauty_health

banner,sky,out-of-page,rectangle

Contact

 

rest

banner,sky,rectangle

About Us

 

rest

banner,sky,rectangle

  • The columns “Website Section” and “Webpage Sub-Section” correspond to the actual names of the respective navigation points on your website.

  • The column “AdTag-Zone” shows the name under which Ströer will administer and market your respective sections/sub-sections. Please use this value when executing the setZone() function.

  • The column “Avaible ad slots” lists the abbreviations of the ad slots, which are available for a given category; This column is required for using the registerSlot() function.



Interface methods


These methods will be available on your website at any time, as soon as „metaTag.min.js“ has been fully loaded.

SDG.Publisher.setZonezone )

Sets the zone for all ad slots of the HTML page to the same indicated value.

SDG.Publisher.addKeywordskeyWords )

Transfers multiple words to the ad server for which specific advertising media can be booked.

SDG.Publisher.addKeywordkeyWord )

Transfers a word in the form of a string, for which specific advertising media can be booked, to the ad server.

SDG.Publisher.removeKeywordskeyWords )

Removes multiple previously added “keywords”.

SDG.Publisher.removeKeywordkeyWord )

Removes a single previously added “keyword”.

SDG.Publisher.addKeyValuekey, value )

Transfers a key and a single value assigned to it to the ad server.

SDG.Publisher.addKeyValueskeyValuesObject )

Transfers a key and multiple values assigned to it.

SDG.Publisher.removeKeyValuekey )

Removes a key and all of the assigned value.

SDG.Publisher.removeKeyValues( keyChain )

Removes multiple keys and all their assigned values.

SDG.Publisher.registerSlotslotName, container )

Creates a new ad slot on the HTML page.

SDG.Publisher.finalizeSlots()

Should be executed as soon as all relevant ad slots of a page have been registered.

SDG.Publisher.unregisterSlotslotName, deleteAdContent )

Removes a specific ad slot from the page.

SDG.Publisher.unregisterAllSlotsdeleteLoadedAds )

Removes all ad slots from the page.

SDG.Publisher.loadSlotslotName )

Requests new advertising media from the ad server for a particular ad slot and displays them on the page.

SDG.Publisher.loadMultipleSlots( slotNames )

Request new ad media from the ad server for a given amount of ad slots and displays them on the page.

SDG.Publisher.loadAllSlotsredoLoadedSlots )

Requests new ad media for all existing ad slots on the page from the ad server and displays them on the page.

SDG.Publisher.generateVastUrlsvastPositions )

Requests VAST-Adtags from the video ad server and returns these for further handling.

SDG.Publisher.setAdServerConsent ( perzonalizedAdsAllowed )

Will notify the tag manager if you, as the Publisher of your website, object to using personalized advertisments on your site.
This can be used if the content of the page (texts, url) will allow to draw privacy sensitive conclussion from the users (ex: illnesses, religious or sexual orientation).

SDG.Publisher.getIABVendorConsent ( iabVendorId, callback )

Retrieves the users current state of consent for a specific IAB vendor / service provider. See our Consent Management Plattform section for more details.

SDG.Publisher.getCustomVendorConsent ( vendorName )

Retrieves the users current state of consent for a custom vendor / service provider. See our Consent Management Plattform section for more details.

SDG.Publisher.transitionAdvertisements()

Allows “Interstitial” ads to be loaded when the user is navigating the website.

 

SDG.Publisher.setZone( zone )

Sets the AdTag Zone for the complete HTML page.
Argument(s)

  • zone { String } = The zone for the matching web site category from the marketing structure provided in table form

Returned value (returns)

  • { Boolean } =  true if successful

Example

SDG.Publisher.setZone('homepage');

> back to table



SDG.Publisher.addKeywords( keyWords )

Transfers multiple keywords to the ad server. As a rule, these are used to describe the content of a website. These can be the usual keywords for optimizing the search engine, but they can also include more specific information (such as the ingredients for a recipe displayed on the site).

Argument(s)

  • keywords { Array<String> } =  An 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.

Returned value (returns)

  • { Boolean } = true if successful, otherwise false

Example

SDG.Publisher.addKeywords(['auto','auto_news','naesse','reifen']);

> back to table



SDG.Publisher.addKeyword(keyWord)

Transfers a single keyword to the ad server.

Argument(s)

  • keyword { String } =  The keyword to be transferred.

Returned value (returns)

  • { Boolean } =  true if successful

Example

addKeyword

> back to table



SDG.Publisher.removeKeywords( keyWords)

Removes multiple previously added keywords.

Argument(s)

  • keywords { Array<String> } =  An 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.

Returned value (returns)

  • { Boolean } = true if successful, otherwise false

Example

> back to table



SDG.Publisher.removeKeyword( keyWord )

Removes a single previously added keyword.

Argument(s)

  • keyword { String } =  The keyword to be transferred.

Returned value (returns)

  • { Boolean } =  true if successful

Example

> back to table



SDG.Publisher.addKeyValue( key, value )

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 they should be in conformity with current data protection laws.

Argument(s)

  • key { String } =  The key to be transferred.

  • value { String } = The value to be transferred for the keyword

Returned value (returns)

  • { Boolean } = true if successful, otherwise false

Example

> back to table



SDG.Publisher.addKeyValues( keyValueObject )

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.

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

 

Argument(s)

keyValueObject { Object<string, string[]> } - An object consisting of multiple keys as arrays, each containing multiple values as string

  • key1 { String } =  Name of key to be transferred.

    • value1 { String } = First value for the keyword

    • value2 { String } = Second value for the keyword

    • value3 { String } = Third value for the keyword

    • usw.

  • key2..... etc

Returned value (returns)

  • { Boolean } = true if successful, otherwise false

Example

addKeyValues

> back to table



SDG.Publisher.removeKeyValue( key )

Removes a previously added key and the assigned value.

Argument(s)

  • key { String } =  The key to be removed.

Returned value (returns)

  • { Boolean } = true if successful, otherwise false

Example

> back to table



SDG.Publisher.removeKeyValues( keyChain )

Removes multiple previously added keys and all of their values.

Argument(s)

  • keyChain { Array<String>} - A chain of key names as array

    • key1 <string> = First key to be removed.

    • key2 <string> = Second key to be removed

    • key3 <string> = Third key to be removed

    • key4 <string> = Fourth key to be removed

    • etc.

Returned value (returns)

  • { Boolean }  = true if successful, otherwise false

Example

> back to table



SDG.Publisher.registerSlot( slotName, container )

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().

Argument(s)

  • slotname { String } = The name for the desired slot

  • container { String || object.DOM-Node } = 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.)

Returned value (returns)

  • { object.Slot> || <null } = If successful, this method will return to slot object; in case of an error, the return value will be null
    Apart from that, there are further control methods available for the slot object; for this purpose, please refer to Slot Methods.

Example

> back to table



SDG.Publisher.finalizeSlots()

Will signal the system that all relevant ad slots for the HTML page have been registered. Please make absolutely sure to execute this method, when using advanced features like HeaderBidding or Single Request Architecture.

The system will prepare all registered ad slots for the request to the ad server and collect data concerning the page environment. You can still register further ad slots, even after excuting this method. Additionally registered ad slot however might not have all relevant informations or lack some features to display all ads.

Argument(s)

  • no further arguments needed

Returned value (returns)

  • { Boolean } = true if successful, otherwise false

Example

> back to table



SDG.Publisher.unregisterSlot( slotName, deleteAdContent )

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.

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.
    [Note: currently setting this parameter doesn't have any effect, any content of unregistered slots will be deleted.]

Returned value (returns)

  • <boolean> = true if successful, otherwise false

Example

> back to table



SDG.Pubisher.unregisterAllSlots( deleteAdContent )

Deletes all ad slots of an HTML page. On request, the method will also delete all advertising media loaded by the slots up to that point.
This will free up the ad slots, making them avaible for re-registering if needed.

Argument(s)

  • deleteAdContent { Boolean } = If true, all advertising media already loaded by the slots 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.
    [Note: currently setting this parameter doesn't have any effect, any content of unregistered slots will be deleted.]

Returned value (returns)

  • { Boolean } = true if successful, otherwise false

Example

> back to table



SDG.Publisher.loadSlot( slotName )

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 from all other slots on the page. It might miss additional features like competitor exclusions or lack functionality to display ads spanning over multiple slots.

Argument(s)

  • slotname <string> = The name for the desired slot

Returned value (returns)

  • <boolean> = true if successful, otherwise false

Example

> back to table



SDG.Publisher.loadMultipleSlots( slotNames )

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.

Argument(s)

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

Returned value (returns)

  • { Boolean } = true if successful, otherwise false

Example

> back to table



SDG.Publisher.loadAllSlots( redoLoadedSlots )

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.


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.

Returned value (returns)

  • { Boolean } = true if successful, otherwise false

Example

> back to table



SDG.Publisher.generateVastUrls( vastPositions )

This method returns a JSON formatted object for each requested position with a VAST-Adtag for use within the video player, implemented onto your website.
Through this method maintaining VAST-AdTags in your CMS or VMS is not necessary.

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:
JW Player:


Argument

  • vastPositions <object> = 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.

Return

  • <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.

Example

 

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

> back to table



SDG.Publisher.setAdServerConsent( perzonalizedAdsAllowed )

Will notify the tag manager, if you as the Publisher of your website, object 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. However you as the publisher can digress from this decision and mark the content of the page as especially revelant 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.) allow to draw privacy sensitive conclusion from the visitor (ex: illnesses, religious or sexual orientation).
While the visit of a user on 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.

Argument(s)

  • perzonalizedAdsAllowed { Boolean} = Use false if you want to object to personlized ads

Returned value (returns)

  • { void } 

Example

> back to table

 

SDG.Publisher.getIABVendorConsent ( iabVendorId, callback )

Asks for a users current state of consent for a specific tech vendor / service provider, who is part of the “IAB Transparency & Consent Framework (TCF 2.0)”.
For more information about consent and the IAB Transparency & Consent Framework, please see our section “Consent Mangement Platform (CMP)

Unlike for “custom vendors”, you will not need to take action to allow or disallow the usage of an IAB vendor. IAB Vendors are bound to independently read and act upon the consent of the user according to the IAB Framework.
Nevertheless this method allows to read the current consent of your site visitor and helps you to implement your own logic, acting on visitors decision.

A list of all currently available and active vendors, including their respective vendor IDs, can be found in the official registry of the IAB: IAB TCF 2.0 vendor-list

Argument(s)

  • iabVendorId { Number } = Official id of an IAB vendor from the IAB TCF2.0 register.

  • callback { Function } = A javascript callback, containing your logic. As first argument of the callback, the return value of this method will be passed.

Returned value (returns)

  • { Boolean } = true if the user has decided to allow the IAB vendor, false if not. Since the return will be delivered asynchronously, you will need to use a callback to act on it.

Example

> back to table

SDG.Publisher.getCustomVendorConsent ( vendorName )

Asks for a users current state of consent for a specific tech vendor / service provider, who is not part of the IAB TCF2.0 Framework.
Such a service provider might be integrated into your website and might use personalized user data, but has not been registered with the IAB framework for some reason. Nevertheless the usage of such vendors falls under the GDPR (General Data Protection Regulation) and your visitors might object to such vendors.

To ease the process for your visitors, you can add your own vendors to our “Consent Management Platform”, please contact your Ströer contact person to start the process. Afterwards we will ask visitors for consent to IAB and your “Custom” vendors in one step, to which you can react to with this method.

More information on this topic can be found in the section “Consent Management Platform (CMP)

Argument(s)

Returned value (returns)

  • { Boolean } = true if user has permitted the usage of personalized data for this vendor, otherwise false.

Example

> back to table



SDG.Publisher.transitionAdvertisements()

This enables interstitial advertisement to be displayed on mobile environments.

Argument(s)

  • no further arguments needed

Returned value (returns)

  • { Boolean } = true if successful, otherwise false

Example

> back to table



Example for a complete configuration


In this example, the three ad slots "banner", "sky" and "mrec" will be registered directly in the <head> of the page, after all relevant site parameters have been configured.
We know these ad slots should always be loaded, no matter how the user interacts with the site. Therefor we execute the finalizeSlot() method as soon as all "save" ad slots are registered. During registration we mark all ad slots for loading, via .load(). However the slots will only be loaded as soon as their respective containers are rendered by the browser. The ads will not interfere with the loading of the site, since all slots are loaded "asynchronous", meaning parallel, to the site.

The user has furthermore the possibility to load further content, if he clicks on the site. This content should also include ads, but it might happen that the content is never loaded by the user. It makes no sense to send the content (as well as the ads) to the user, as long as he/she does not wish so. Suitably we only register the 4th slot "posterad", after the user has clicked the content.


Additionally the ads should be reloaded after 60 seconds. This would never be done in a live environment, but illustrates the use of the Publisher.loadAllSlots() method for this example.

Example for a complete configuration

 

Slot Interfacing Methods


These methods are available to you for all registered ad slots.

Slot.load()

Will start the call to the ad server for this specific ad slot.

Slot.setTargetingobject )

Passes a given key and its value/s just to this ad slot.

Slot.blockFormats( formatList )

Excludes an amount of formats from this ad slot.

 

You can combine or “chain” methods with each other:

All methods will return the “Slot” object itself, which in turn can be saved as a variable, so you can easily access the ad slot later on.

 

Slot.load()

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 avaible. 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 avaible), nor the site be influenced negativly.

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 Publisher interface methods loadMultipleSlots() or loadAllSlots().

Argument(s)

  • no arguments required

Returned value (returns)

  • { Object } = The ad slot for calling up further methods of the slot

Example

> back to table

Slot.setTargeting( keyValueObject )

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 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.
As opposed to the method addKeyValues() the pair is only transferred to the respective slot.


Parameter(s)

keyValueObject { Object<string, string[]> } - An object consisting of multiple keys as arrays, each containing multiple values as string

  • key1 { String } =  Name of key to be transferred.

    • value1 { String } = First value for the keyword

    • value2 { String } = Second value for the keyword

    • value3 { String } = Third value for the keyword

    • usw.

  • key2..... etc

Returned value (returns)

  • { Object } = The ad slot for calling up further methods of the slot

Example

> back to table



Slot.removeTargeting ( key, value )

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.

Argument(s)

  • key { String } = the key you like to edit / remove

  • value { String } [optional] = the value that should be removed

Returned value (returns)

  • <object> = The ad slot for calling up further methods of the slot

Example

> back to table

Slot.removeSizes([ [width1,height1], [width2,height2], ... ])

Outdated

This method is outdated. It will continue to work, however for full functionality to administer ad slots and their corresponding formats, please use the Slot.blockFormats() method

Removes one or two combinations of height and width indications (as an array bracketed by another JavaScript Array) from a specific ad slot. One ad slot is capable of displaying several advertising formats of different sizes, and will be pre-configured with these sizes.

 

Argument(s)

  • width1 <number> = The width of the first width/height pair

  • height1 <number> = The height of the first width/height pair

  • width2 <number> = The width of the second width/height pair

  • height2 <number> = The height of the second width/height pair

  • etc.

Returned value (returns)

  • <object> = The ad slot for calling up further methods of the slot

Example

> back to table



Slot.blockFormats( formatList )

Excludes multiple ad formats from delivering on the current HTML page, only for the used ad slot. This method should be used if the current page is not capable to display the format correctly. This might be because the format has not enough room to be displayed fully or because delivering the format makes no sense in the context of the site. 

During the initial set up of your website in our system, we will make sure to only serve formats fitting to your webseite. 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.

 

Argument(s)

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

banderole
billboard
brandbooster
bridgead
cubead
doubledynamicsitebar
fireplace
flex1x1
flex1x2
flex1x3
flex1x4
flex2x1
flex3x1
flex3x4
flex4x1
flex6x1
flex8x1
flex9x16
flex10x1
floorad
fullframead
halfpagead
intextspot
largeinline
leaderboard
maxiad
mediumrectangle
mobilead2x1
mobilead3x1
mobilead4x1
mobilead6x1
mobilehalfpagead
mobilemrec
mobilepresenter2x1
mobilepresenter3x1
mobilepresenter4x1
mobilepresenter6x1
mobilestickyad
posterad
qualityfooter
sitebar
skyscraper
tickeraddisplay
wallpaper
videotakeover
videowall

Returned value (returns)

  • { Object } = The ad slot for calling up further methods of the slot

Example

> back to table

 

Guidelines for integrating advertising spaces


In the following guidelines, we will give you a short collection of tips and best practices for handling ad slots.
These guidelines are not compulsory, but they do help to prepare your page or site for the different forms of advertising formats as efficiently as possible.

General guidelines for integrating ad slots

  • An ad slot must always be bracketed by an HTML tag, preferably a <div>, which has been assigned a unique ID value.
    The ID can be chosen freely an must be included in the method registerSlot() for all related forms of advertising which are used.


Example using two “Superbanner” advertising forms (728x90 pixels)



  • The HTML tags surrounding the ad slot should in no way hinder the visibility of the advertising material.
    Please avoid CSS attributes such as “overflow:hidden” or “clip:rect()”.

  • When having to position the advertising spaces, please avoid the CSS attribute “text-align” in the directly surrounding HTML tags. The interpretation of this attribute is browser specific and can be different from one browser to the next. Particularly in special advertising forms such as Wallpaper or Fireplace, imprecise positioning can lead to errors. As contrasted with that, the CSS attributes “position:relative”, “left” and “top” are implemented in exactly the same way in all browsers.

  • If you want to mark your advertising spaces with the label “Anzeige”, we can do this for you. The label can, in general, be freely designed and be seamlessly integrated into the rest of your typographical and color design.
    Please send us a sample design for the label, together with the desired CSS rules. If you do not want to use a self-designed label, we can employ a standard label for all ad slots inserted automatically.

  • In order to ensure a clean delivery of special advertising forms which are delivered via multiple advertising spaces at the same time, the three slots “Leaderboard”, “Skyscraper” and “Popup” should be delivered in a fixed sequence. Before, between or after these three types of ad slots it is possible to integrate additional ad slots without further difficulties as long as the sequence of these three locations is not changed.
    1.) Superbanner
    2.) Skyscraper
    3.) PopUp

Guidelines for integrating specific ad slots

Leaderboard

In case of centred pages or so called “responsive design” pages in which the width of the page or the distance between the left margin of the content and the left margin of the browser window changes depending on the screen resolution set by the user, you should make sure that the distance between the left margin of the Superbanner and the right margin of the content always remains the same.

The following example shows a solution for this problem using the Hockeystick/Wallpaper format for visualisation. This format wraps around the outer upper and right margins of the content of the page and as such can easily collide with the content of the page in responsible web pages.
In order to avoid this, we have the browser calculate the most favourable position for the slot automatically, while at the same time setting fixed distances in order to make the positioning, albeit dynamic, always clearly predictable at the same time.

For this purpose, we will always leave a 300 pixel margin on the right-hand side of the content while at the same time still allowing the Skyscraper slot to deliver all formats.
To emphasize this, the most important CSS rules have been written inline, directly to the elements, while the less important rules have been relegated to <style> tags.

Example: Hockeystick, left-justified

Skyscraper

Some formats such as the “Dynamic Sidebar”, for instance, reserve the complete space between the left beginning of the skyscraper and the right browser margin. When integrating the Skyscraper it is therefore advisable to avoid the use of the attribute “float” in the surrounding HTML tags. This attribute positions elements in keeping with their height and width depending on the rest of the page and can result in the Skyscraper not being displayed on the right-hand side of the content any more from a certain value onwards. This problem, however, is strongly related to the structure of the website and does not have to occur every time the attribute “float” is used.

Medium Rectangle

It is, however, also possible to deliver the advertising form"HalfpageAd" (300x600) using the “Medium Rectangle” advertising space. To realise this, you have to ensure that the ad slot embedded within the content is able to change its height dynamically without covering up the surrounding content or otherwise rendering it illegible. In this context, it is advisable to use the CSS attribute "min-height:250px;" on the surrounding DIV element. This will cause the browser to allocate the smallest possible area upon first rendering the page, while still enabling the slot to alter the height of the space dynamically.

Billboard

As contrasted with the Leaderboard or the Skyscraper, however, the Billboard will not be delivered each time the page is called up. In keeping with this, the ad slot has to be integrated into the page in such a way as not to reserve any space in case of non-delivery of the advertising content.
The ad server itself reserves the space on the page only when actually delivering the content. In this case, it will automatically create a distance between the upper navigation elements and the content below them and use the entire width of the content for displaying the advertising medium.
In some cases, it is possible to omit the ad slot for the Leaderboard, with the formats of the Leaderboard being taken over by the Billboard slot. This special arrangement is used for pages whose design cannot cleanly accommodate the Leaderboard slot above the content.

Sample integration Billboard



Changes made by ad server on delivery of a Billboard



Event System

MetaTag has its own set of JavaScript-Events which can be listened to over the JavScript method “addEventListener”. The system differentiates between two types of events:

  • system events

  • slot events

System Events:

All system events use the "window" object, in where the metatag library is implemented under, as the "eventTarget".
Each event passes information about itself within the first argument given within the listener method.

Example for a system event:

Available events on the window object:

Event

Description

Event

Description

metaTagSystemBeforeLoadAll

Gets triggered before the first call from an ad slot is send to the ad server.

metaTagSystemContentLoaded

Gets triggered once the event DOMContentLoaded has fired

metaTagSystemLoadedAll

Gets triggered when the "readyState" is "complete" from the current "document"

metaTagSystemAdServerModuleLoaded

Gets triggered once MetaTag has decided which ad server to use on the website.

metaTagSystemContentElementLoaded

Gets triggered when an Element has been found on the page which measurements coincide with the width and height of the content. Some formats do not start loading until this event has been fired.

metaTagSystemPrebidResponded

Gets triggered once all real time auctions have finished from the open source solution "Prebid". Prebid is not active on all websites

metaTagSystemZoneSet

Gets triggered once our interface method setZone() has been completed

metaTagSystemPageTypeSet

Gets triggered once our interface method setPageType() has been completed

metaTagSystemSlotRegistered

Gets triggered as soon as an ad slot is registered. This event contains general information for the ad slots. For more specific information about an ad slot please use the slot events

metaTagSystemSlotDeleted

Gets triggered as soon as an ad slot is deleted or unregistered. This event contains general information for the ad slots.
For more specific information about an ad slot please use the slot events

metaTagSystemSlotPrepared

Gets triggered once an ad slot has received all information needed to start a call to the ad server.
This event contains general information for the ad metaTagSystemSlotCallingslots. For more specific information about an ad slot please use the slot events

metaTagSystemSlotCalling

Gets triggered once an ad slot starts a call to the ad server. This event contains general information for the ad slots.
For more specific information about an ad slot please use the slot events

metaTagSystemSlotResponded

Gets triggered once an ad slot receives an answer from the ad server. This event contains general information for the ad slots.
For more specific information about an ad slot please use the slot events

metaTagSystemSlotDone

Gets triggered once an ad slot processes and renders the answer from the ad server. This event contains general information for the ad slots. For more specific information about an ad slot please use the slot events

metaTagSystemSlotEmpty

Gets triggered once an ad slot receives an answer from the ad server that no advertisement is available.
This event will not necessarilly fire consistently. It can depend on if the impression gets passed to another system from our original system. The 3rd system might deliver an empty repsonse but not pass it on to us.

metaTagSystemSlotEntersViewport

Gets triggered after the user has scrolled the website and any ad slot is “near” or directly inside the viewport of the user’s browser. When calculating the viewport of the browser, we will enlarge it artifically (normally desktop: + factor 0.2, mobile: + factor 2 ) so you can react (load data, change website) in time before the user actually sees the slot in question.
Please be aware: Most user scroll a lot during a page visit. This event will catch all changes of all slots in relation to the viewport and therefor will be triggered repeatly.

metaTagSystemSlotLeavesViewport

Gets triggered after the user has scrolled the website and any ad slot is leaving the viewport of the user’s browser.
Please be aware: Most user scroll a lot during a page visit. This event will catch all changes of all slots in relation to the viewport and therefor will be triggered repeatly.

metaTagSystemCmpConsentAvailable

Gets triggered once the user has set his/her consent for all vendors (IAB/Non IAB). At this point in the systems process you are able to get the consent information pro vendor from our publisher interface methods: SDG.Publisher.getIABVendorConsent() or SDG.Publisher.getCustomVendorConsent().
This event only gets fired once per page impression even if a user changes his consent while on the page.
(for example by opening the privacy manager)

metaTagSystemCmpChoiceUiShown

This event signals that the user is being shown a message layer from the consent manager. This layer covers most of the elements from the webpage. It is encouraged that
certain load processes from the website, which are not initially essential, only load once the user can see/interact with them. In the case that a vendor relies on legitimate interest (some vendors are essential for the use of a website), this vendor will be classified as 'allowed' at this point.
Keep in mind that the user has the possibility to decline his/her consent for legitimate interest.
Once the message gets accepted or closes, the event: metaTagSystemCmpChoiceSelected gets fired.

metaTagSystemCmpChoiceSelected

Gets triggered once the user has finished interacting with the communication layer of the consent manager platform.
At this point not all the necessary information will be available. In order to listen for the complete available consent information please use the event: metaTagSystemCmpConsentAvailable
Attention: A deprecated version of MetaTag used the event: "metaTagSystemChoiceSelected". This event as the now updated event: metaTagSystemCmpConsentAvailable are still both available

Slot Events

These events use the DOM node in which the ad slot was registered as the "eventTarget".
Aside from the information available about the event itself, additionally you can access information about the ad slot. For this use the first argument given through the listener method.
The data from the ad slot is available in "eventObject.detail". Since the ad slot starts firing multiple events after its registration it is advised to set your listeners before the ad slot gets registered.

Example for a slot event:


Available slot events:

Event

Description

Event

Description

metaTagSlotRegistered

The slot beeing listend on has been registerd and is available

metaTagSlotDeleted

The slot beeing listend on has been unregistered/deleted and will not fire any more events.

metaTagSlotCalling

The slot being listened on got the command to load an advertisement and will call the ad server

metaTagSlotResponded

The slot being listened on has received and answer from the ad server, slot has not been rendered yet.

metaTagSlotDone

The slot being listend on has completed its process. It has received an answer from the ad server and the slot has finished rendering an advertisement

metaTagSlotEmpty

The slot being listened on did not receive an advertisement from the ad server. The slot removes itself from the webpage and does not reserve any more space on the page. This event will not necessarily fire consistently.
It can depend on if the impression gets passed to another system from our original system. The 3rd system might deliver an empty response but not pass it on to us.

metaTagSlotEntersViewport

Gets triggered after the user has scrolled the website and the ad slot is “near” or directly inside the viewport of the user’s browser. When calculating the viewport of the browser, we will enlarge it artifically (desktop: + factor 0.2, mobile: + factor 2 ) so you can react (load data, change website) in time before the user actually sees the ad.

metaTagSlotLeavesViewport

Gets triggered after the user has scrolled the website and the ad slot is no longer “near” or directly inside the viewport. Should the user scroll back to the position of the ad slot, it will again signal “metaTagSlotEntersViewport”.

 

Additional Features

This system brings a few additional features in which it helps with the day to day handling of ad formats.
If you have any questions concerning which options are available please consult your Partner Account Manager at Ströer.

Labeling ad slots with "Anzeige" (advertisements)

MetaTag can label your ad slots with the word "Anzeige" (advertisements). This label can be localized to your needs or changed for example into "promotion" if this is preferred.
Ad labels should always be attached and are required under certain circumstances by law.
Per default MetaTag will always deliver ad labels, this can be turned off if you would like to take care of the labeling yourself.
If you wish to change/remove/add these labels please contact your Publisher Account Manager from Ströer.

Define local ad slots

For your website you can define your own ad slots (for example: to book your own local advertisements). Please contact us before implementing a local ad slot.
In order to create and register a local ad slot you will need to use a different method than usual.

Method arguments for registerModularSlot()

 

 

local Zones

Publishers that have the option to set local ad slots also have the option to define local zones. These "sub zones" can be used to create a deep hierarchical structure in the ad server if you want a detailed collection of data from your website structure.

A sub zone can be created with this method:

Be aware local ad slots and local zones come with these restrictions:

  • Names and zones can only have a maximum length of 24 characters

  • Names and zones can not contain any special characters or spaces

  • Names and Zones must be unique

MetaTag Video

MetaTag-Video provides the Publisher with the possibility to easily setup a connection to any video ad server per VAST or VPAID. Formats like "Pre-Roll", "Mid-roll" or "Post-Roll" can be implemented into your video player.
Your video player must support VAST-Video-Advertisements which support the current IAB standards. In order to get VAST URLs please use the MetaTag method getVastUrls()

We can gladly discuss an individual integration in your current video system. Questions regarding IAB-Standards, Video formats or popular video-SDK's for desktop or mobile feel free to contact
your Publisher Account Manager at Ströer.

Lazy Load:

When setting up an ad slot as a lazy load slot, the ad slot will load once the user has scrolled the registered DIV container from the ad slot into the view port.
This ensures that slots which are integrated below the fold do not load and hinder performance when the website initially loads.
Advertisers prefer to book placements that have a high visibility rate.

Using this feature on ad slots can drop the amount of impressions that are delivered but on the other hand the visibility for this slot will improve.

 

 

Consent Managment Platform

 

 

A Consent Management Platform (CMP) allows to collect users decisions, how their personalized data can be processed by the website and connected service providers. For more information about how to integrate such a CMP, please see our documentation: Consent Management for Websites

The consent of the user for processing personalized data is informed by an categorisation of different, possible usages of this data. Each service provider integrated into a website might use some or all data in diverse ways (deliver personalized content, display only relevant ads, etc). To allow the user to give a well-informed decision, these usages are clustered into manageable amount of categories, which in turn the user can consent or decline.
By consenting or declining a category, all service providers inside such a category will be allowed or blocked,

Classification and categorisation of service providers is done by the industry association “Interactive Advertising Bureau (IAB)” based upon the advertising industry-standard “Transparency & Consent Framework (TCF)” . Service providers, which already have been classified, are named “IAB vendors” in the upcoming guide. Non-classified service providers are used as “non-IAB vendors”.

After the user chooses whether to give consent or not, we (Ströer) block/allow all IAB-vendors, which are related and responsible for advertisement. You will not need to do anything for managing these vendors.

Should you use any vendors yourself (IAB or Non-IAB), you will need to ask your users for permission to send personalized data to these vendors.
In case the user does not wish to consent to specific service providers or whole categories, you will have to block these vendors and make sure they will not be activated or delivered to the user.
This might have different impacts for each vendor. Some can still function without any form of personalized data, some will not function at all.
Please contact your vendors / service providers to understand the full technical implementation.

 

As soon as a Consent Management Platform is detected on your website, MetaTag will not deliver any advertisements, until the user has decided how their personalized data should be handled.

Some scripts and or vendors, which do not collect any personalized data, might be loaded before the user gives their consent. These scripts are rigorously tested and monitored, to always ensure full compliance.
Other vendors or scripts, which might collect personalized data, are delayed until the user’s decision.

To subsequently deliver any ads (even non-personalized), the user needs at minimum allow the following IAB Transparency & Consent Framework data usages for all involved vendors:

  • Select basic ads (Purpose 2)

  • Measure ad performance (Purpose 7)

  • Apply market research to generate audience insights (Purpose 9)

  • Develop and improve products (Purpose 10)

These purposes need to be either consented to by the user (user opts-in to the purposes), or the website needs to claim “legitimate interest” for these purpose (meaning the user does not explicitly refuse / opt-out)

For delivering personalized ads and to allow for full monetization of a website, users need to consent fully to the above purposes and additionally to:

  • Store and/or access information on a device (Purpose 1)

  • Create a personalized ads profile (Purposes 3)

  • Select personalized ads (Purposes 4)

 

First you will need to add your vendors to your CMP.
When employing the Ströer CMP, please contact your Ströer representative for adding your required IAB or Non-IAB vendors. If you manage your own CMP, you can add your vendors easily by contacting the provider of your CMP.

Afterwards the Ströer TagManager offers two interfaces to make the decisions of your users visible to you, so you can react accordingly to their choices.

SDG.Publisher.getIABVendorConsent ( iabVendorId, callback )

Retrieves the users current state of consent for a specific IAB vendor / service provider.

SDG.Publisher.getCustomVendorConsent ( vendorName )

Retrieves the users current state of consent for a custom vendor / service provider. This interface will only work when using the Ströer CMP.


Since the users decision can take some time, you will have to wait for the user to finish and close the user interface of your Consent Manager, before you react further.
After the user has finished interacting with a “Consent Manager”, the StröerTagManager will send a JavaScript Event, in turn allowing you to react with your own scripts or logic.
Please see the documentation of our Event System for in-depth explanations on how to wait and react to such an event.

We provide the following events connected to Consent Management:

metaTagSystemCmpConsentAvailable

Gets triggered once the user has decided how personalized data may be processed.

metaTagSystemCmpChoiceUiShown

This event signals that the user is being shown a message layer from the consent manager. This layer covers most of the elements from the webpage. It is encouraged that
certain load processes from the website, which are not initially essential, only load once the user can see/interact with them.

metaTagSystemCmpChoiceSelected

Gets triggered once the user has finished interacting with the communication layer of the consent manager platform.
At this point not all necessary information will be available. In order to listen for the complete available consent information please use the event: metaTagSystemCmpConsentAvailable


Simplified Example

 

When trying to build complex logic based on the consent or refusal of the user (especially when you try to determine which data usage categories specifically where declined), it might be easier to bypass the Ströer TagManager and interface directly with the CMP.
Each IAB TCF compatible CMP provides a JavaScript interface method called “__tcfapi()” present on the main window object, to which the CMP was delivered.
Extensive documentation for this interface is available on the GitHub page of the IAB: InteractiveAdvertisingBureau / GDPR-Transparency-and-Consent-Framework / Consent Management Platform API

Simplified Example


Another use case might be to pass the complete consent information to another system / vendor, so these systems can decide for themselves which usages of personalized data are allowed and react on their own.
For this the __tcfapi() provides a “base-64” encoded string, which includes information about all vendors, purposes and the users decision in a compact, easily transmittable format. To signal a vendor that the user is originating from an GDPR relevant country, most vendors require an indicator, often a boolean switch called “gdprApplies”. These “tcString” and “gdprApllies” parameters are recognized and useable by most vendors in the web eco-system. Please consult the documentation of you vendor to see how you can specifically pass along this information.

Subsequenly the following example shows calling the tcfapi(), requesting “tcString” and “gdprApplies” and forwarding them to a video player.

 

Embedding social media plugins

In some cases users might decline consent for some data usages or vendors, but later would like to see content from these vendors (for example: User refused Twitter to use personalized data, but the content of your website includes a Twitter plugin. The user likes to change their decision.)

Most CMPs allow the change of consent for a single vendor on the fly.
Depending on your used CMP, the necessary steps might be different. Please see the documentation of your CMP.
Example for SourcePoint CMP (allowing CustomVendor “Twitter Inc”, internal Id: “5ec85c9cb8e05c4a2002f42e”) after the user clicked some kind of “I accept Twitter Inc.” button:

Documentation for other CMPs: