Video Advertising Suite

Docs

Migration Notes v5 to v6

Last Modified on 2021-06-10T08:47:29.422Z

Table of contents

Introduction

With version 6 of the smartclientcore there are now two ways to supply Ads. You can either keep requesting ads for a specific ad-slot as in previous versions, therefore less changes have to be implemented, or go with ad playlists, which contain a collection of ads for the entire underlying content.

The smartclientcore introduces its second publisher API, the AdPlaylistAPI to work with VMAP responses. The formerly known and only PublisherAPI so far has been renamed to AdSlotAPI, which keeps working with VAST responses, a bit better again than before.

PlayerFacade

No matter whether one want to use VAST-only or VMAP and VAST together, two changes have to be done in the PlayerFacade.

The smartclientcore v6 first requires facade version 3.1 to properly prepare both of the publisher APIs. The FacadeBase interface has been extended with a new method getEnvironmentVars(). It is called whenever it requires fresh data from the publisher. Up to v5 to EnvironmentVars could only be defined once when calling PublisherAPI.initAdSlot().

/**
 * Requests the player facade version (API version) to ensure the particular versions of `smartclientcore` and player
 * facade are supported.
 * @param {string} apiFacadeVersion - Required API version
 * @returns {string} Supported API version
 */
PlayerFacade.prototype.handshakeVersion = function (apiFacadeVersion) {
    return '3.1';
};

/**
 * Requests the latest status of the video player, site, and other external factors.
 * @param {string} adBreakType - Linearity of the upcoming ad slot. See [`AdBreak.type`](setup-sequential-config#adbreak+type)
 * @returns {EnvironmentVars} Description object of current states or `null`.
 */
PlayerFacade.prototype.getEnvironmentVars = function (adBreakType) {
    try {
        return this.environmentVars;
    } catch (error) {
        return {};
    }
};

Initialization

As said in the beginning you now have two ways to use the smartclientcore. Follow the next two steps if you only want to receive VAST-AdTags (ideally zero changes have to be done). If you additionally want to receive VMAPs see how it's done with the AdPlaylistAPI.

VAST-only usage

The following two steps should already look like your implementation. But keep in mind, if you use it like this you can't receive VMAP-AdTags.

connect

Typically in your AdController you connect with the smartclientcore like this.

AdController.prototype.initSmartclientcore = function () {
    var that = this;

    window.smartclientcore
        .connect(this.playerFacade)
        .setup(this.globalConfig)
        .then(function (adSlotAPI) {
            that.adSlotAPI = adSlotAPI;
        });
};

request

After connecting to the core you use the AdSlotAPI to do initAdSlot and then startAdSlot which should look like this:

that.adSlotAPI.initAdSlot(adBreak, that.environmentVars).then(function () {
    that.adSlotAPI.startAdSlot();
}, function (failure) {
    console.log('something went wrong while requesting VAST', failure);
});

VAST and VMAP

This way is further on supported and usable if you want to receive VMAP- along to your VAST-AdTags. Those are some minimalistic, almost equal changes and it should be really easy to update your implementation.

connect

From now on you can also connect with the vmap-submodule which returns two APIs, the well known AdSlotAPI (formerly PublisherAPI) and additionally a AdPlaylistAPI to use with VMAP.

AdController.prototype.initSmartclientcore = function () {
    var that = this;

    window.smartclientcore
        .vmap
        .connect(this.playerFacade)
        .setup(this.globalConfig)
        .then(function([adPlaylistAPI, adSlotAPI]) {
            that.adPlaylistAPI = adPlaylistAPI;
            that.adSlotAPI = adSlotAPI;
        });
};

request

Pretty similar to previous versions you now use initAdPlaylist and then startAdPlaylist. But instead of providing the entire environmentVars as beforehand, you only supply the macros property. The other environmentVars are requested from the PlayerFacade at runtime. Think of all the required macros and set the optional ones as desired, see IAB-Page. Implement it like this:

var vastMacros = {
    'PAGEURL': location.href
};

this.adPlaylistAPI.initAdPlaylist(adBreak, vastMacros).then(function () {
    this.adPlaylistAPI.startAdPlaylist();
}, function (failure) {
    console.log('something went wrong while requesting VMAP', failure);
});

Initialization comparison

v5 v6
smartclientcore.connect(PlayerFacade) to create a instance of the smartclientcore VAST implementation for the given PlayerFacade same process, but PlayerFacade must match the FacadeBase interface v3.1
setup(GlobalConfig) to instantiate the PublisherAPI same process, but the API has been renamed to AdSlotAPI
n/a introduces smartclientcore.vmap.connect(PlayerFacade) to create a instance of the smartclientcore VMAP + VAST implementation for the given PlayerFacade (based upon FacadeBase interface v3.1)
n/a setup(GlobalConfig) to instantiate the AdPlaylistAPI and AdSlotAPI

PublisherAPI -> AdSlotAPI

Now that the smartclientcore offers two publisher APIs, the former only PublisherAPI has been renamed to AdSlotAPI

Methods

v5 PublisherAPI v6 AdSlotAPI
initAdSlot() parameter adBreak The AdBreak introduces a new property adBreakPosition that defines the execution point within the timeline of the underlying content.
stopAdSlot() returns void stopAdSlot() returns Promise

Removals

Events

The EVENT.ON_HOMAD_ACTIVATION is no longer triggered in response to resolving the AdReinsertion.activationCallback, because things need to be updated before AdReinsertion is activated. So once you resolve the activationCallback, make sure to adjust everything else related to bypassing AdBlockers.

Initialization

Since v5.2 the setup method must be called from the smartclientcore instance, that is returned from calling connect. Calls to smartclientcore.setup() are no longer catched but fail with a Runtime Error.