IMA SDK Adapter Integration Guide

Overview

Follow these instructions to integrate Integral Ad Science's (IAS's) web video SDK in Campaign Monitoring mode with your ads running with the Google IMA SDK for HTML5. After pulling in the accompanying JavaScript code, IAS's web video SDK can be initialized with macros.

IAS recommends using the IAS IMA SDK Adapter (vans-adapter-google-ima.js) hosted by IAS which ensures you always use the latest available version of the adapter.

Environmental requirements

Before going live, send IAS a page for test and sign-off. IAS performs certification tests to confirm the implementation qualifies for live campaigns. Therefore, when you keep these environmental features constant across implementations, you can use the integration on multiple pages without needing IAS to re-test.

Your integration must ensure the ad node provided to googleImaVansAdapter.init as the videoElement argument fulfills the following properties:

• is a real HTML element ('adNode.nodeType === 1' should return 'true') and not a proxy object

• is attached to the DOM (inserted into a rendered document) at the time SDK measurement is initialized

• is without styling (on itself or on a container) that renders it invisible (such as dimensions of 0x0 (and overflow:none); display:none; visibility:hidden). You can ensure it is visible by checking that "adNode.getBoundingClientRect().width > 0 AND adNode.getBoundingClientRect().height > 0"

You must confirm the following is true of the document/environment that you initialize IAS measurement in:

• window.document.readyState !== "loading" before and during playback

• able to inject more elements into the page (under the ad node)

Important note on required arguments for initialization

Whether you can implement the IAS IMA SDK Adapter depends if the player SDK and IMA SDK integration you are using exposes the Google IMA google and adsManager objects to you. IAS expects you to satisfy one of the following use cases:

1) use a player's SDK with a built-in IMA SDK integration, or

2) use a player's SDK without a built-in IMA SDK integration, in which case you are implementing the IMA SDK integration external to the player

To initialize measurement, you need to provide the googleImaVansAdapter references to both the global google and the adsManager object from the Google IMA SDK integration to your player.

Use case #1 has two further possibilities:

1a) the player's IMA SDK built-in integration exposes the adsManager object to you through an API which allows you to implement the IAS IMA SDK Adapter. For example, the Brightcove player has player.ima3.adsManager and the JW Player has the player.on('adsManager', callback) event.

1b) the player SDK's IMA SDK built-in integration does not expose the adsManager object to you. Rather than implement a workaround, IAS recommends you work with your IAS representative to determine the best course of action, whether that is working with the player SDK developer to expose the adsManager object, or switching to a player that does expose the adsManager object.

In use case #2, since you are working with the IMA SDK directly, google and adsManager are exposed to you, and therefore you can implement the IAS IMA SDK Adapter.

Step One

Include the script tag in your HTML:

Note: This tag must be included after the IMA SDK <script> tag for the integration to work.

Step Two

After initializing the Google IMA SDK for HTML5, initialize the IAS adapter in a callback to the Google IMA SDK's google.ima.AdsManagerLoadedEvent. First, create a config object containing the macros and IDs that will be passed to IAS to enable campaign monitoring.

You must use the anId values IAS gave you and the size of the ad (via campId) in the config object.

Here is an example of a valid config object containing all the required macros:

You can optionally include additional data and IDs in your reporting through additional macros (listed in the table below) in your config object.

• All macros listed in the table below are tracked by IAS log-level reporting

• If you need to pass other data to be tracked, you may remap the macro fields that are not required for initialization

• IAS does not track any other arbitrary data passed as config properties

Here is an example of another valid config object containing required and optional macros:

IDs available from IMA (line item ID placementId, creative ID pubCreative, and advertiser ID pubId) supplied by the adapter overwrite any values for those keys (placementId, pubCreative, and pubId) that you pass into your config.

Note: Provide as many of the optional configuration macros as possible.

All the macros are a string data type. The following table shows you the various macros, how the macro appears in the IAS UI, whether you must supply this in your implementation, and if the macro is available in IMA and populated by IAS:

Step Three

In the same script, inside the callback for google.ima.AdsManagerLoadedEvent, initialize IAS's web video SDK with the googleImaVansAdapter.init function (made available to you by the script from Step One). Supply as arguments the global google object, the IMA adsManager, the video HTML element for your player, and the config object created in the previous step.

Note: perform all initialization of the IAS Google IMA Adapter for your IMA player script inside the 'onAdsManagerLoaded' callback. The callback function is the only place where modification is needed to initialize the IAS adapter code.

Example

Check your implementation against this example:

index.html

imaPlayerInit.js