smartClientCore - Advertisement Add-On

Implementation Guideline

Applies to: HTML5 Custom Video Player
Last Modified on 2020-01-23T12:47:13.430Z

A JavaScript library (further referenced as add-on) to extend HTML5 video solutions. Aside of supporting the IAB video advertising standards (VAST, VPAID), it adds complex sequencing capabilities (Opener, Closer, Bumper, Sponsored Ads), includes mechanism for waterfalling, helps bypassing ad-blockers with ad-reinsertion and is fully compliant with SpotX' video advertising eco-system and its connected vendor networks.

Table of contents

• Implementation
  • Player Prerequisites
  • Installing
  • Safeguarding the Video Player
  • Basic Initialization
• Setup
  • Global Configuration
  • Sequential Configuration
• Facade and Video Player Interface
• Static API
  • Methods
  • Properties
• Plugin API
• Events
  • EVENT list
• Error Codes
• Glossar

Implementation

Player Prerequisites

Certainly your HTML page already includes a HTML5 Video Player. Otherwise you should take this step first. Next steps assume that your content videos run smoothly and fulfill the following preconditions:

• remove existing build-in ads setup

Example: Video Player configuration Object
===============================================================
--- config.js
+++ config.js

     advertising: {
-        schedule: {
-            'pre-roll-ad': {
-                offset: 'pre',
-                tag: 'https://adserver.com/tag?type=vast3xml'
-            }
-        }
     }

Installing

The add-on is provided as a JavaScript file smartclientcore.min.js. This file must be included once by putting the following HTML one-liner next to the Video Player source files.

Example: Player page scripts
===============================================================
--- page.html
+++ page.html

     <script src="js/videoplayer.js"></script>
+    <script src="js/smartclientcore.min.js"></script>

Safeguarding the Video Player

In order to avoid unexpected calls to the player API, it is not only recommended but mandatory to safeguard the player API with your own facade (proxy). The facade interface has to match with the Facade and Video Player Interface.

Using the facade has two main reasons:

• provide a generic player interface the plugin can safely talk to
• capture and validate requests made by this add-on towards the player API

For your reference the smartClientCore package contains a file FacadeBase.js that can be extended by your custom player facade.

Example: MyPlayerFacade.js - Step 1: Build your own Facade
===============================================================
import {FacadeBase} from './FacadeBase';

const FACADE_VERSION = '2.0';

export class MyPlayerFacade extends FacadeBase {
    constructor(playerReference = {}) {
        super(playerReference);
    }
}

Basic Initialization

Example: main.js - Step 2: Connect with the add-on
===============================================================
import {MyPlayerFacade} from './MyPlayerFacade';

// Let's assume the page uses a HTML5 VideoElement, though `myplayer` can be any other Video Player
let myplayer = document.querySelector('video#player');
let adPlugin = null;

let playerProxy = new MyPlayerFacade(myplayer);

let globalAdConfig = smartclientcore.SCHEMA.create(smartclientcore.SCHEMA.GLOBAL_CONFIG);
globalAdConfig.debug = true; // enable debug output to the browser console

smartclientcore.connect(playerProxy).setup(globalAdConfig).then(api => {
    adPlugin = api;

    /**
    * You are ready to request your first ads
    * this is also a good point to subscribe to ad events
    */    
    smartclientcore.EVENTS.forEach(eventType => {
        adPlugin.addEventListener(eventType, (event) => { /* do something */ });
    });

}, failure => {
    console.log("Error: ", failure);
});

Glossar

adSlot
adBreak