Logo

Application collectors

MediaTailor Ad Framework

For the Javascript Collector with Bitmovin Media Player

The MediaTailor Ad Framework Extension is a configuration option for the Javascript Collector by Datazoom when it is configured with the Bitmovin Media Player to make the following additional data points automatically collectable in real time.

Integration Instructions

Prerequisites

Import the Datazoom collector library

To work with MediaTailor, it is important to pick a Datazoom collector library that has the MediaTailor SDK bundled as a sub-module (for more information, see Datazoom's platform guide). The Datazoom collector library should be added to the client application as described in Datazoom's collector initialization tutorial.

Import the Google PAL SDK library (optional)

Optionally, to leverage the Google PAL SDK for the benefits of improved ad targeting, add the script https://imasdk.googleapis.com/pal/sdkloader/pal.js to the client application, as described in Google's PAL SDK get-started page.

Import the IAB Open Measurement SDK (OM SDK) service script (optional)

Optionally, to leverage the IAB Open Measurement SDK to facilitate third-party ad viewability and verification measurement, the client application can import the OM SDK service script (e.g., omweb-v1.js) which is provided by IAB and should be hosted under the client's own domain. Please refer to IAB's OM SDK for Web Video and Iframes guide for the different options of loading the OM SDK service script.

Procure a MediaTailor session-init URL or ad-tracking URL

In most common cases the client application initiates the initialization of MediaTailor playback sessions using a session-init URL (specific to a given content) procured through MediaTailor's services. The session-init URLs are in the following format:

HLS:

https://<mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>.m3u8

MPEG-DASH:

https://<mediatailorURL>/v1/session/<hashed-account-id>/<origin-id>/<asset-id>.mpd

Alternatively, the client application may utilize a third-party web service to handle the MediaTailor session initialization on its behalf. In such a case, the client application will receive both a content-playback URL and an ad-tracking URL from the web service. The former should be handed to a player to start playback, while the latter should be used in a step described later in this document.

Please refer to MediaTailor's ad-reporting-client-side page for detailed information.

Configure the Datazoom collector

The Datazoom collector must be initialized, with a Datazoom configuration ID, before its functionalities become available. Please refer to Datazoom's platform guide on how to set up a new configuration (and receive the ID) or find the ID of an existing configuration. Once the Datazoom configuration ID is procured, follow Datazoom's collector initialization tutorial to finish configuring the collector.

Locate and Configure the Root Object of the MediaTailor SDK

The root object of the MediaTailor SDK is located under datazoom.mediatailor of a Datazoom collector library which has the MediaTailor SDK bundled as a sub-module.

The root object of the MediaTailor SDK provides some global configuration options, such as:

  • The log-level can be changed (with the mediatailor.setLogLevel() method) to output more or less debug information to the console. The log-level definitions are listed in the API reference of LogLevel.

  • Optionally, invoke the mediatailor.initPal() method to enable Google PAL SDK integration if desired.

For example:

let mediatailor;

function initMediaTailor(options) {

    // Store the root object of the MediaTailor SDK in a variable for convenience
    mediatailor = datazoom.mediatailor;

    if (options.debug) {
        mediatailor.setLogLevel(mediatailor.LogLevel.DEBUG);
    }

    if (options.enableGooglePAL) {
        const palConsentSettings = {
            // Note that the value of `allowStorage` must be based on user consents
            allowStorage: false
        };
        mediatailor.initPal(null, palConsentSettings);
    }
}

Please note that it's the application's responsibility to obtain user consent in order to set the settings like allowStorage accordingly.

MediaTailor Session Initialization

The process to initialize a MediaTailor playback session (with client-side ad tracking support) involves the following steps:

Prepare a MediaTailor session-config object

The MediaTailor session initialization can be done through either a session-init URL or an ad-tracking URL. In both cases, a session-config object should be created with the corresponding field set to the URL procured through MediaTailor's services. As demonstrated below.

With session-init URL (common use cases):

const sessionConfig = {
    sessionInitUrl: sessionInitURL,
    ....

With ad-tracking URL (use cases with third-party web services):

const sessionConfig = {
    trackingUrl: trackingUrl,
    ....

Add Google PAL nonce-request parameters (optional)

Optionally, to leverage the Google PAL SDK, add Google PAL nonce-request parameters to the MediaTailor session-config object (see the API reference of PalNonceRequestParams), as demonstrated below:

if (options.enableGooglePAL) {
    sessionConfig.palNonceRequestParams = {
        adWillAutoPlay: true,
        adWillPlayMuted: true,
        continuousPlayback: false,
        descriptionUrl: "https://example.com",
        iconsSupported: true,
        playerType: "Sample Player Type",
        playerVersion: "1.0",
        ppid: "12JD92JD8078S8J29SDOAKC0EF230337",
        url: "https://developers.google.com/ad-manager/pal/html5",
        videoHeight: 480,
        videoWidth: 640,
        omidPartnerName: datazoom.omidPartnerName,
        omidPartnerVersion: datazoom.omidPartnerVersion
    };
}

For the omidPartnerName and omidPartnerVersion parameters, as shown in the example above, the corresponding values can be retrieved from the Datazoom collector properties datazoom.omidPartnerName and datazoom.omidPartnerVersion, respectively.

Please note that it's important to invoke the mediatailor.initPal() method before creating MediaTailor sessions that are intended to be integrated with Google PAL SDK.

If the MediaTailor session-config object was created with an ad-tracking URL (instead of a session-init URL), enabling Google PAL SDK and adding nonce-request parameters will not have any effects since the actual session initialization request (to which the PAL SDK nonce is attached) was performed outside the control of the MediaTailor SDK.

Add other optional configurations

The MediaTailor session-config object has more configuration options defined (such as incomingAdCountdownInterval) as documented in the API reference of SessionConfiguration.

Create a MediaTailor Session object

With the MediaTailor session-config object prepared in the steps above, create a MediaTailor Session object as demonstrated below:

function createMediaTailorSession(sessionInitURL, options, ....) {

    const sessionConfig = {
        sessionInitUrl: sessionInitURL,
        incomingAdCountdownInterval: 10
    };

    if (options.enableGooglePAL) {
        sessionConfig.palNonceRequestParams = {
            adWillAutoPlay: true,
            adWillPlayMuted: true,
            continuousPlayback: false,
            descriptionUrl: "https://example.com",
            iconsSupported: true,
            playerType: "Sample Player Type",
            playerVersion: "1.0",
            ppid: "12JD92JD8078S8J29SDOAKC0EF230337",
            url: "https://developers.google.com/ad-manager/pal/html5",
            videoHeight: 480,
            videoWidth: 640,
            omidPartnerName: datazoom.omidPartnerName,
            omidPartnerVersion: datazoom.omidPartnerVersion
        };
    }

    mediatailor.createSession(sessionConfig).then(
        session => {
            ....
        },
        error => {
            ....
        }
    );
}

The mediatailor.createSession() method returns a Promise object which will be either rejected with an error or resolved into a MediaTailor Session object. The object represents a MediaTailor playback session and provides methods to interact with the session and observe its status, as documented in the API reference of Session.

Manage the MediaTailor Session

Once the MediaTailor session is created, the following steps should be taken to manage the session:

Create a media player instance and the associated Datazoom collector context

The process of creating a media player instance and the associated Datazoom collector context is specific to the kind of media player chosen by the client application. Please refer to Datazoom's player integration tutorial for instructions.

Some media players require the content playback URL being passed as a parameter for creating instances. If so, use the value returned by session.getPlaybackUrl() for this purpose.

Attach the MediaTailor session object to the Datazoom collector context

For the MediaTailor SDK to track ads effectively, it needs to have timely access to the media player's playback progress and other information. The Datazoom collector context serves an essential role in facilitating this communication, so it's important to attach the MediaTailor session object to the Datazoom collector context as demonstrated below:

datazoomContext.attachMediaTailorSession(session);

Start the IAB Open Measurement SDK (OM SDK) session client (optional)

Optionally, if the IAB OM SDK is to be leveraged (to facilitate third-party ad measurement), invoke the Datazoom collector context's startOmidSessionClient() method as described in Datazoom's OM SDK integration tutorial.

Set up playback of the content

The process of setting the content playback URL and initiate playback is specific to the kind of media player chosen by the client application. In all cases, the content playback URL is retrieved by invoking session.getPlaybackUrl(), but the method of playback URL assignment differs among player vendors. Please refer to the player vendor's documentation or Datazoom's player integration tutorial for instructions.

Please note that if a third-party web service is used to perform session initialization, the session.getPlaybackUrl() method will return null and the application should set up content playback based on information derived from the third-party web service.

Listen to UI events related to the MediaTailor session

The MediaTailor SDK defines several listener events observable from a MediaTailor session object. They are useful for implementing ad-related UI features. Each listener event has its detail property set to provide detailed information about the current ad (see the API reference of SessionUiEventData for detailed information). The listener event definitions are listed in the API reference of SessionUiEvent.

As demonstrated below, the client application can register various handlers for these listener events:

function addSessionUiEventListeners(session, listeners) {
    session.addEventListener(mediatailor.SessionUiEvent.AD_START, event => {
        listeners.onAdStart?.(event.type, event.detail);
    });
    session.addEventListener(mediatailor.SessionUiEvent.AD_END, event => {
        listeners.onAdEnd?.(event.type, event.detail);
    });
    session.addEventListener(mediatailor.SessionUiEvent.AD_PROGRESS, event => {
        listeners.onAdProgress?.(event.type, event.detail);
    });
    session.addEventListener(mediatailor.SessionUiEvent.AD_CLICK, event => {
        listeners.onAdClick?.(event.type, event.detail);
    });
    session.addEventListener(mediatailor.SessionUiEvent.AD_CAN_SKIP, event => {
        listeners.onAdCanSkip?.(event.type, event.detail);
    });
    session.addEventListener(mediatailor.SessionUiEvent.AD_INCOMING, event => {
        listeners.onAdIncoming?.(event.type, event.detail);
    });
    session.addEventListener(mediatailor.SessionUiEvent.NONLINEAR_AD_START, event => {
        listeners.onNonlinearAdStart?.(event.type, event.detail);
    });
    session.addEventListener(mediatailor.SessionUiEvent.NONLINEAR_AD_END, event => {
        listeners.onNonlinearAdEnd?.(event.type, event.detail);
    });
    session.addEventListener(mediatailor.SessionUiEvent.AD_TRACKING_INFO_RESPONSE, event => {
        listeners.onAdTrackingInfoResponse?.(event.type, event.detail);
    });
}

Advanced Topics

Additional References

Previous
Google IMA DAI Ad Framework
Next
Player Default Ad Framework