CTV SDK Integration

Overview

The VI CTV SDK is intended for publishers that would like to integrate video ads into their CTV applications. It’s built using JavaScript and is able to run on all SmartTV platforms that deploy web apps.

Note: On AndroidTV and Amazon FireTV this SDK can only be integrated in web apps that run inside a WebView, not in native Android apps.

Integration Options

The VI CTV SDK offers 2 APIs: the VI API and the VPAID API.

The VI API

Description:

The API was specifically designed for integration in TV apps. It’s advantage over the VPAID API is the integration simplicity: you do not have to create iframes, handle communication or handle UI, everything is built in.

Available here: http://c.vi-serve.com/viadstv/vi.min.js

Reference:

Class: vi.Ad

Methods:

  • initAd
  • startAd
  • pauseAd
  • resumeAd
  • stopAd
  • onAdReady
  • onAdStarted
  • onAdImpression
  • onAdStopped
  • onAdError
Options:

Options can be passed when creating a new ad instance:


var ad = new window.vi.Ad({
    option1 : value2,
    option2 : value2
});

The available options are:

Option Type Default Mandatory Description
appId String Yes The application ID
appVer String Yes The application version
placementId String Yes The placement ID
showBranding Boolean true No Show the vi logo
showProgress Boolean true No Show the progress bar
showProgressCountdown Boolean false No Show the remaining time countdown
handleKeys Boolean true No Handle key input (i.e. the ‘VK_BACK’ key)
Usage example:

Add the vi SDK into your app:


< script type="text/javascript" src="http://c.vi-serve.com/viadstv/vi.min.js" >< /script >

Create an ad:


var ad = new window.vi.Ad({
    appId       : appId,      // your app id
    appVer      : appVer,     // your app version
    placementId : placementId // the id of the placement to be loaded
});
ad.onAdReady = function() {
    // Pause and hide the main video stream
    // ...
 
    // Start the ad
    this.startAd();
};
ad.onAdStarted = function() {
};
ad.onAdStopped = function(reason) {
    if(reason === 'complete') { 
        // The user has watched the ad all the way to the end
        // Resume and show the main video stream
        // ...
    } 
    else if(reason === 'userexit') { 
        // The user has stopped the ad
        // ...
    }
};
ad.onAdError = function(msg) {
    // Handle errors
    // ...
};
ad.initAd();

The VPAID API

Description:

The API is based on the IAB VPAID 2.0 specifications (http://www.iab.com/guidelines/digital-video-player-ad-interface-definition-vpaid-2-0/).

The VPAID API establishes a common interface between video players and ad units, in order to make your video player compatible with the VPAID spec you will need to:

  • create an IFRAME and load the ad unit
  • provide a video slot to the ad unit
  • handle messaging between the video player and the ad unit
  • handle UI elements (if your situation requires any)

Available here: http://c.vi-serve.com/viadstv/viFrame.min.js

Supported VPAID events:
  • AdLoaded
  • AdStarted
  • AdStopped
  • AdImpression
  • AdVideoStart
  • AdVideoFirstQuartile
  • AdVideoMidpoint
  • AdVideoThirdQuartile
  • AdVideoComplete
  • AdPaused
  • AdPlaying
  • AdSkipped
  • AdError
Supported VPAID methods:
  • handshakeVersion
  • initAd
  • startAd
  • stopAd
  • pauseAd
  • resumeAd
  • subscribe
  • unsubscribe
Options:

Options can be passed through the environment variables parameter:

var environmentVars = {
    option1 : value1,
    option2 : value2

};

The available options are:

Option Type Default Mandatory Description
VI_APP_ID String Yes The application ID
VI_APP_VER String Yes The application version
VI_PLACEMENT_ID String Yes The placement ID
VI_MANUFACTURER String No The device manufacturer
VI_MODEL String No The device model
VI_LANG String No The language of the app’s UI
VI_WIDTH Number No The width of the device screen, defaults to 1280
VI_HEIGHT Number No The height of the device screen, defaults to 720
Usage example:

Create the iFrame:


var self = this;
var vpaidFrame = document.createElement('iframe'), vpaidAdUnit;
vpaidFrame.id = 'viAd';
vpaidFrame.frameBorder = 0;
vpaidFrame.scrolling = 'no';
vpaidFrame.style.display = 'none';
vpaidFrame.onload = function() {
    var vpaidLoader = vpaidFrame.contentWindow.document.createElement('script');
    vpaidLoader.src = 'http://c.vi-serve.com/viadstv/viFrame.min.js';
    vpaidLoader.onload = function() {
        vpaidAdUnit = vpaidFrame.contentWindow.getVPAIDAd();
        self.vpaidAdUnit = vpaidAdUnit;
    };
    vpaidFrame.contentWindow.document.body.appendChild(vpaidLoader);
};
document.body.appendChild(vpaidFrame);

Subscribe to events:


vpaidAdUnit.subscribe(function() {
    // Pause and hide the main video stream
    // ...
 
    // Start the ad
    vpaidAdUnit.startAd();     
}, 'AdLoaded');
 
vpaidAdUnit.subscribe(function() {
    // Resume and show the main video stream
    // ...
}, 'AdStopped');
 
vpaidAdUnit.subscribe(function(msg) {
    // Handle errors
    // ...
}, 'AdError');

Create an ad:


var environmentVars = {
    slot            : container,  // the DIV that contains the VIDEO element
    videoSlot       : video,      // the VIDEO element
    VI_APP_ID       : appId,      // your app id
    VI_APP_VER      : appVer,     // your app version
    VI_PLACEMENT_ID : placementId // the id of the placement to be loaded
};
vpaidAdUnit.initAd(1280, 720, 'normal', 600, {}, environmentVars);