Tagging Overview

After initiating the Tag Manager loader, you can start using the following API for the configuration of the ad slots (placements) on your page.

We are using an asynchronous queue based API, which can be filled with your calls anytime by adding them to the admTagMan.q array using the push() method. You do not need to wait with the configuration of ad slots until all tag manager dependencies are loaded and ready.

★ Note: The only Ringier Advertising object in the global javascript scope of your website is the

admTagMan object. Everything else is scoped and kept clean.

Functions & Events

Please find an overview of the currently available tag manager functions with a short description below.

Function	Description & Example
init()	This is the initial call to the tag manager which is setting up the current page.
registerSlot()	Register an ad slot with slot-specific options.
loadSlots()	Call this function after the queue is filled with all needed ad slots on a page. In the standard case (default setting), this is the moment of truth, when the tag manager will execute an ad-request for all registered slots and will show the ads automatically (including impression counting) as the ad slots approach the viewport (configurable by Ringier Advertising).
refreshSlot()	On long-form pages, you can refresh an already created and possibly filled ad slot with this function call. This function requests a new ad and fires a new impression if an ad is returned by an adserver.
onEvent() / offEvent()	Register event listeners to ad events. This function can be used instead of or in addition to callback registration in registerSlot().
showSlot()*	Show the ad for an ad slot manually and fire the impression count. *This function should only be called, if lazy loading is deactivated by Ringier Advertising for an ad slot and if it is fully implemented on publisher side (for example in image galleries). Please also refer to loadSlots().
resizeSlot()	Resize an ad slot from within it's creative iFrame
version()	Returns the running Tag Manager version.
isMinVersion()	Let's you check, if the running Tag Manager is greater-than or equals a given version

The following events are fired on your ad slots (containers):

Event	Description & Example
adReady	Returns the dimensions of the ad to be shown in a width and height property.
adLoaded	Returns the dimensions of the shown ad in a width and height property.
adEmpty	Returns an error message with the empty error in a message property.
adError	Returns an error message with the error in a message property.
adStatus	Is fired on all ad events and can be used to attach only one ad event listener per container. Returns the current event in the property status (adLoaded, etc.) and the payload in the property detail.

We are also adding custom CSS classes to your ad slot (container), so you can style the container dependent on the ad response:

CSS class	Description & Example
adm-loaded	This class is added in case the ad was shown properly.
adm-empty	This class is added in case the ad could not be shown.
adm-error	This class is added in case the ad could not be shown and threw an error.

API Reference

init()

This function call is setting up the current page based on the passed options object. The init() function must be called on each new page setup, for example on each SPA page transition.

Example code

admTagMan.q.push(function() {
  admTagMan.init({
    platform: 'Desktop',
    channel: 'Sport',
    targeting: {
      'examplekey': ['set', 'multiple', 'values', 'like', 'this'],
      'pagetype': 'article',
      'subsection': 'football',
      'articleid': '12345'
    }
  });
});

Possible options properties for init(options)

Key	Required	Type	Description
platform	required	string	Should match one of our supported platforms like Desktop or MobileWeb
channel	required	string	Should match one of your channels. A list of supported channels will be provided by Ringier Advertising
targeting	optional	object	Additional targeting data, for example article IDs, channel IDs, etc. in lowercase

registerSlot(options)

Registers an ad slot with slot-specific options object

Example code

admTagMan.q.push(function() {

  // minimal config
  admTagMan.registerSlot({
    slot: 'WB_1',
    container: 'apn-ad-slot-wb1',
  });

  // optional targetings and callbacks         
  admTagMan.registerSlot({
    slot: 'WB_2',
    container: 'apn-ad-slot-wb2',
    events: {
      adReady: function(data) {
        console.log('ad is ready to be shown', data);
      },
      adLoaded: function(data) {
        console.log('ad is displayed', data);
      },
      adEmpty: function(data) {
        console.log('no ad available', data);
      },
      adError: function(data) {
        console.log('an error has occurred', data);
      },
      adStatus: function(data) {
        console.log('all events here', data);
      }
    },
    targeting: {
      // 'pagetype': 'overview', // optional if set on init already!  Set to overview or article according to current page
      // 'examplekey': ['set', 'multiple', 'values', 'like', 'this'], // optional
    }
  });

  // additional registerSlot calls can be added here
  // [...] 

  admTagMan.loadSlots();
});

Possible options properties for registerSlot(options)

Key	Required	Type	Description
slot	required	string	Should match one of your slots in our system like WB_1 (first wide board), HPA_2 (second half page ad), etc.
container	required	string	Must match the unique container ID of the element inside your DOM, which will be used to render the ad into.
events	optional	object	Various callbacks can be registered here: adReady, adLoaded, adEmpty and adStatus adReady, adLoaded: The passed data object contains a width and height property of the ad. If a special ad is shown, there could be an optional message property with a value like brandingday. In case of a PREROLL or other video ad slot, the vastUrl property in the adReady event is available which contains the VAST URL for further player configuration, for example: {vastUrl: 'https://vast.adserver.com/preroll...'} adEmpty: The passed data object contains a message property. adStatus: The passed data object contains a status property with the event name and a detail property with the payload.
targeting	optional	object	Additional targeting based on the current ad slot can be provided here as key-value pairs in lowercase.

★ Attention: Re-using of the same container ID when registering a slot on the same page is not permitted. This will result in ads not being delivered!

★ Note: Should you register an ad slot more than once on a page (for example a WB_3 slot on pages with infinite scrolling), please set the pos targeting key and increment its value at each register call, for example targeting: {'pos': '2'} on the second register call.

loadSlots()

This function must be called after the queue is filled with all needed ad slots on a page. Please also refer to registerSlot().

showSlot(options)

This function should only be called, if lazy loading is deactivated by Ringier Advertising for an ad slot and if it is fully implemented on publisher side (for example in image galleries). Otherwise the function should not be called. Please also refer to loadSlots().

Example code

admTagMan.q.push(function() {
  admTagMan.showSlot('apn-ad-slot-wb1');
});

Possible options properties for showSlot()

Key	Required	Type	Description
container	required	string	Must match the container ID of the element inside your DOM, which will be used to render the ad into.

resizeSlot(iFrameWindow, width, height)

The resizeSlot() function should be used by partners, who have to change the displayed width and height of an ad slot according to their creative dimensions. Our primary ad server doesn't always receive the correct dimensions initially, so this API can be used. Additionally, setting the width and height to 0 fires the adEmpty event.

★ Note: This has to be called from within the iFrame, that's rendering the creative!

Example code

parent.admTagMan.resizeSlot(window, 10, 10);

version()

In case you need to know which tag manager version is running on your page, you can call the version() method.

Example code

admTagMan.q.push(function() {
    console.log(admTagMan.version()); // version string
});

isMinVersion(string)

If you need to distinguish between different versions of the Tag Manager framework, you can check easily if the running version is greater-than or equals a given minimum version. For example if you want to register a very special ad slot only if the tag manager is running on v1.4.0 or later.

Example code

admTagMan.q.push(function() {
    const result = admTagMan.isMinVersion("1.4.0");
    console.log(result); // boolean true or false
});

refreshSlot(options)

You can refresh an already created and possibly filled ad slot with this function call. This function requests a new ad and fires a new impression if an ad is returned by an adserver.

★ Note: After calling refreshSlot() there's no need to call showSlot() - ever. Even not on a not lazy loading slot. It's refreshing immediately. ⚡️

Example code

admTagMan.q.push(function() {
  admTagMan.refreshSlot({
    slot: 'MR_4',
    container: 'apn-ad-slot-mr4',
  });
});

Possible options properties for refreshSlot()

Key	Required	Type	Description
slot	required	string	Should match one of your slots in our system like WB_1 (first wide board), HPA_2 (second half page ad), etc.
container	required	string	Should match the container ID of the element inside your DOM, which will be used to render the ad into.
targeting	optional	object	same as registerSlot()

The options object is almost the same as in registerSlot(). If not overridden, the default values from the initial registerSlot() call are used.

onEvent() / offEvent()

Registers / unregisters ad event listeners of a slot. This function can be used instead of or in addition to callback registration in registerSlot().

Example code

// register events
admTagMan.q.push(function() {
  admTagMan.onEvent('adReady', 'apn-ad-slot-wb1', function(data) {
    console.log('onEvent event ready', data)
  });
  admTagMan.onEvent('adLoaded', 'apn-ad-slot-wb1', function(data) {
    console.log('onEvent event loaded', data)
  });
  admTagMan.onEvent('adEmpty', 'apn-ad-slot-wb1', function(data) {
    console.log('onEvent event empty', data)
  });
  admTagMan.onEvent('adError', 'apn-ad-slot-wb1', function(data) {
    console.log('onEvent event error', data)
  });
  admTagMan.onEvent('adStatus', 'apn-ad-slot-wb1', function(data) {
    console.log('all events', data)
  });
});

// unregister events
admTagMan.q.push(function() {
  admTagMan.offEvent('adReady', 'apn-ad-slot-wb1');
  admTagMan.offEvent('adLoaded', 'apn-ad-slot-wb1');
  admTagMan.offEvent('adEmpty', 'apn-ad-slot-wb1');
  admTagMan.offEvent('adError', 'apn-ad-slot-wb1');
  admTagMan.offEvent('adStatus', 'apn-ad-slot-wb1');
});

Events

Your website or SPA page can listen to the following events on each ad slot (container).

Example code

var wb1Container = document.getElementById('apn-ad-slot-wb1');

wb1Container.addEventListener('adReady', function(data) {
  console.log('addEventListener received event ready', data)
});

wb1Container.addEventListener('adLoaded', function(data) {
  console.log('addEventListener received event loaded', data)
});

wb1Container.addEventListener('adEmpty', function(data) {
  console.log('addEventListener received event empty', data)
});

wb1Container.addEventListener('adError', function(data) {
  console.log('addEventListener received event error', data)
});

wb1Container.addEventListener('adStatus', function(data) {
  console.log('addEventListener received event', data)
});

CSS classes

The tag manager automatically ads custom CSS classes to your ad slot (container). You can freely define these CSS classes on your page to style the container dependent on the ad response.

Example code

<div id="apn-ad-slot-wb1" class="ad-container adm-loaded">
  <!-- [...] -->
</div>

<div id="apn-ad-slot-wb1" class="ad-container adm-empty">
  <!-- [...] -->
</div>

<div id="apn-ad-slot-wb1" class="ad-container adm-error">
  <!-- [...] -->
</div>