Video Advertising Suite

Docs

Migration Notes v5 to v6

Last Modified on 2022-01-18T13:05:35.692Z

Table of contents

Introduction

With version 6 of the smartclientcore there are now two ways to supply ads. As in previous versions ads for a specific ad-slot can be requested or ad playlists can be requested, 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 former PublisherAPI has been renamed to AdSlotAPI, which keeps working with VAST responses.

PlayerFacade

No matter whether one wants to use VAST or VMAP and VAST together, two changes have to be made 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 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 instead want to receive VMAP documents see how to do this 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 call initAdSlot and then startAdSlot:

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

VMAP and VAST

This way is now supported and needs to be used if you want to receive VMAP-AdTags. There are only minor differences towards the VAST-only implementation.

connect

From now on you can also connect with the vmap-submodule which returns two APIs, the AdSlotAPI (former 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

Similar to VAST-only setups you initialize the ad server request (initAdPlaylist()) and process the ad server response (startAdPlaylist()). Instead of providing the entire environmentVars as beforehand, you only supply the vastMacros property. The other environmentVars are requested from the PlayerFacade at runtime.

Think of all the required macros and set the optional ones. See IAB-Page. Implement it like this:

var vastMacros = {
    'CLICKTYPE': '3'
};

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 smartclientcore.connect(PlayerFacade), PlayerFacade must match the FacadeBase interface v3.1
setup(GlobalConfig) to instantiate the PublisherAPI setup(GlobalConfig), but the API has been renamed to AdSlotAPI
n/a introduces smartclientcore.vmap.connect(PlayerFacade) to create a instance of the smartclientcore VMAP and VAST implementation for the given PlayerFacade (based upon FacadeBase interface v3.1)
n/a setup(GlobalConfig) to instantiate the AdPlaylistAPI and AdSlotAPI
setup() parameter globalConfig GlobalConfig.adVerification.OMID nested properties moved to GlobalConfig.adVerification
setup() parameter globalConfig The GlobalConfig.adVerification.nonOMID property has been removed

PublisherAPI -> AdSlotAPI

Now that the smartclientcore offers two publisher APIs, the former 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.
initAdSlot() parameter environmentVars The EnvironmentVars property macro has been renamed to vastMacros.
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 move all the logic related to bypassing AdBlockers away from the event and into the callback method.

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 caught but fail with a Runtime Error.

Configuration

Pre Open Measurement methods are no longer supported. Logic and setup options (GlobalConfig.adVerification.nonOMID) have been removed.