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.

Please note, that these code examples will not work in a production/live site.

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.

1 Introduction
2 Glossary
3 Table of Contents
4 Integration of metaTag.min.js
- 4.1 Request from our CDN (Content Delivery Network)
- 4.2 Hosting on your domain
5 Integration of Ads.txt file
6 Configuration of your website
7 PublisherApi
8 Example for a complete configuration
9 PublisherSlotApi
10 Guidelines for integrating ad slots
- 10.1 General guidelines for integrating ad slots
- 10.2 Guidelines for integrating specific ad slots
  - 10.2.1 “banner” Ad Slot
  - 10.2.2 “sky” Ad Slot
  - 10.2.3 “rectangle” Ad Slot
  - 10.2.4 “stickyfooter” Ad Slot
11 Event System
- 11.1 System Events
- 11.2 Slot Events
12 Additional Features
- 12.1 Labeling ad slots with "Anzeige" (advertisements)
- 12.2 Define local ad slots
- 12.3 MetaTag Video-Ads
- 12.4 Lazy Load
- 12.5 Avoiding Cumulative Layout Shift
  - 12.5.1 Solutions
  - 12.5.2 Loading Animations
13 Consent Management Platform
- 13.1 TagManager behaviour with user consent
- 13.2 CMP interfaces for user consent
  - 13.2.1 Embedding social media plugins

Integration of metaTag.min.js

Please implement the provided JavaScript file (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).

<!-- Integrating metaTag.min.js into the <head> of your website --!>
<!DOCTYPE html>
<html>
  <head>
    ...
    <script async src="https://cdn.stroeerdigitalgroup.de/metatag/live/beispielseite/metaTag.min.js" type="text/javascript" fetchpriority="high"></script>
    ...
  </head>
  <body>
    ...
  </body>
</html>

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

For integrations via javascript it could look like this:

(function() {
  var channel = !!document.location.href.match(/sdgmt=preview/i) ? 'preview' : 'live';
  var script = document.createElement('script');
  script.type = 'text/javascript';
  script.async = true;
  script.setAttribute('fetchpriority', 'high');
  script.src = 'https://cdn.stroeerdigitalgroup.de/metatag/' + channel + '/beispielseite/metaTag.min.js';
  document.head.appendChild(script);
})();

You can view the human-readable version of our code by enabling “source maps” in your prefered browsers “Development tools”. Please see your browsers documentation on how to enable this.
The library will receive new features and updates regularly. Please see our Release Log for in-depth information about those changes.

Hosting on your domain

For performance and data-privacy reasons, it might be beneficial to host all MetaTag2 files on your own domain.
Examples on how to update MetaTag2 files regularly and host on your CDN, can be found in our documentation: https://stroeerdigitalgroup.atlassian.net/wiki/spaces/SDGPUBLIC/pages/4061134850

Integration of 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 https://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.
A missing or faulty file, will result in revenue loss.

Feel free to add further entries to this file, e.g. if you like to include any of your own 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 available, online validators. For example: ads.txt Validator - Free ads.txt Validation Tool by ads.txt Guru - ads.txt Guru

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

Configuration of your website

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

There are several JavaScript methods available, which you can call and fill with information, to allow our TagManager to render the correct AdTags to your website. See “Publisher Api” further below for a list of available methods.

In order to fill the functions with content, we will provide a file detailing the marketing structure of your website 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.

PublisherApi

Calling these methods should always be wrapped inside a JavaScript “command queue”, please use the namespace “window.SDG.cmd”.
This will allow you to send commands, even if “metaTag.min.js” file is not fully loaded yet.

<script>
  window.SDG = window.SDG || {};
  window.SDG.cmd = window.SDG.cmd || [];
  window.SDG.cmd.push(function() {
      SDG.Publisher.setZone('homepage')
      SDG.Publisher.setPageType('rubrik')
  })
</script>

SDG.Publisher.setZone( zone )	Sets the zone for all ad slots of the HTML page to the same indicated value.
SDG.Publisher.addKeywords( keyWords )	Transfers multiple words to the ad server for which specific advertising media can be booked.
SDG.Publisher.addKeyword( keyWord )	Transfers a word in the form of a string, for which specific advertising media can be booked, to the ad server.
SDG.Publisher.removeKeywords( keyWords )	Removes multiple previously added “keywords”.
SDG.Publisher.removeKeyword( keyWord )	Removes a single previously added “keyword”.
SDG.Publisher.addKeyValue( key, value )	Transfers a key and a single value assigned to it to the ad server.
SDG.Publisher.addKeyValues( keyValuesObject )	Transfers a key and multiple values assigned to it.
SDG.Publisher.removeKeyValue( key )	Removes a key and all of the assigned value.
SDG.Publisher.removeKeyValues( keyChain )	Removes multiple keys and all their assigned values.
SDG.Publisher.registerSlot( slotName, 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.unregisterSlot( slotName, deleteAdContent )	Removes a specific ad slot from the page.
SDG.Publisher.unregisterAllSlots( deleteLoadedAds )	Removes all ad slots from the page.
SDG.Publisher.loadSlot( slotName )	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.loadAllSlots( redoLoadedSlots )	Requests new ad media for all existing ad slots on the page from the ad server and displays them on the page.
SDG.Publisher.generateVastUrls( vastPositions )	Requests VAST-Adtags from the video ad server.
SDG.Publisher.generateVastUrlsPromise( vastPositions )	Request VAST-AdTags and return them as a `Promise`.
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.transitionAdvertisements()	Allows “Interstitial” ads to be loaded when the user is navigating the website.

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

<script>
  window.SDG = window.SDG || {};
  window.SDG.cmd = window.SDG.cmd || [];
  window.SDG.cmd.push(function() {
      SDG.Publisher.setZone('homepage')
      SDG.Publisher.setPageType('rubrik')
  })
</script>

_{> 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

SDG.Publisher.setZone('homepage');

_{> 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).

Please bear in mind that keywords may not contain any special characters, blanks or vowel mutations and must be completely written in lower-case letters.
Vowel mutations have to be changed into ae, ue and oe and blanks and special characters into underscores.

Example

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

_{> 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.

Please bear in mind that keywords may not contain any special characters, blanks or vowel mutations and must be completely written in lower-case letters.
Vowel mutations have to be changed into ae, ue and oe and blanks and special characters into underscores.

Example

SDG.Publisher.addKeyword('autobahn');

_{> 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

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

_{> 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

SDG.Publisher.removeKeyword('autobahn')

_{> 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.

Please note that keys and values may not contain any special characters, blanks or vowel mutations and must be completely written in lower-case letters.
Vowel mutations have to be changed into ae, ue and oe and blanks and special characters into underscores.

Example

SDG.Publisher.addKeyValue('stadt','hamburg')

_{> 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.

Please consult your Ströer representative before using this function. The data to be used should be coordinated before the implementation and should be in conformity with data protection laws of your country and the country of your users.

Note that the keys and values may not contain any special characters, blanks or vowel mutations and must be completely written in lower-case letters.
Vowel mutations have to be changed into ae, ue and oe and blanks and special characters into underscores before the transfer.

Example

SDG.Publisher.addKeyValues({ 'interessen': ['finanzen', 'autosport', 'mode', 'kosmetika'] })

_{> 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

SDG.Publisher.removeKeyValue('age')

_{> 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

SDG.Publisher.removeKeyValues(['age', 'interests', 'segments'])

_{> 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.

We recommend to register the slots as early as possible, ideally in the <head> of the site. In this case, the container of the ad slot might not been fully loaded/rendered by the browser. Instead of passing the container as DOM-Node, you can also pass the "ID" of the future container as string. Please make implicitly sure that the "ID" passed is correct and will be used at some point in the page. Otherwise errors might occur in the page.

An ad slot can only be registered once per HTML page. Example: If the ad slot with the Name “mrec” has already been registered, the same name cannot be registered a second time.
Should you need multiple advertising media of the same advertising format on you site, we can provide you with additional ad slots (such as "rectangle2", “rectangle3”, and so on).

Please consult the marketing structure available to you for your website. There you will find all available ad slot names for the categories existing in your website. Not all slot names are available in each category.

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

SDG.Publisher.registerSlot('banner', 'myBannerContainerId');
SDG.Publisher.registerSlot('sky', document.getElementById('mySkyContainerId'));
SDG.Publisher.registerSlot('rectangle', document.querySelector('.myCssClass'));

_{> 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.

Please make absolutely sure to execute this method after registering your initial AdSlots.

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

SDG.Publisher.registerSlot('banner', 'myBannerContainer').load()
SDG.Publisher.registerSlot('sky', 'mySkyContainer').load()
SDG.Publisher.registerSlot('rectangle', 'myRectangleContainer').load()
SDG.Publisher.finalizeSlots()

_{> 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

SDG.Publisher.unregisterSlot('sky', true);

_{> 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

SDG.Publisher.loadSlot('sky');

_{> back to method list}

Argument(s)

slotname: string - The name for the desired slot

Returns

boolean - true if successful, otherwise false

English MetaTag Documentation

Introduction

Glossary

ad slot/Slot

AdServer

AdTag

Advertising format

HeaderBidding

Single Request Architecture

Table of Contents

Integration of metaTag.min.js

Request from our CDN (Content Delivery Network)

Hosting on your domain

Integration of Ads.txt file

Configuration of your website

PublisherApi

SDG.cmd

SDG.Publisher

SDG.Publisher.setZone( zone )

SDG.Publisher.addKeywords( keywords )

SDG.Publisher.addKeyword( keyword )

SDG.Publisher.removeKeywords( keywords )

SDG.Publisher.removeKeyword( keyword )

SDG.Publisher.addKeyValue( key, value )

SDG.Publisher.addKeyValues( keyValues )

SDG.Publisher.removeKeyValue( key )

SDG.Publisher.removeKeyValues( keyChain )

SDG.Publisher.registerSlot( slotname, container )

SDG.Publisher.finalizeSlots()

SDG.Publisher.unregisterSlot( slotName, deleteAdContent )

SDG.Publisher.loadSlot( slotName )

SDG.Publisher.loadMultipleSlots( slotNames )