Integrating the Equativ Video Plugin for HTML5 players

Overview

The integration of Equativ's Video Plugin is a quick and simple 3 step process:

1. Import the Library on your page.
2. Define your targeting data (site, page, format, keyword targeting).
3. Register the Video Plugin, so that the Equativ script knows where it can display ads.

The steps mentioned above are mandatory; make sure you have gone through all of them.

Optionally, you can also set a custom configuration for the Video Plugin, manage ad rules, change the Video Plugin language, set content data, set callback functions and define callbacks for VAST events.

Import the Library

The Equativ Video Plugin Library contains all the logic of the video solution. It makes the requests to the ad server, parses the responses, manages ad breaks and all the tracking for reporting. Caution is advised, since each Equativ customer has a dedicated version of the library.

During the integration process, the technical account manager will send you your domain and your network ID.

Please add the following to your page’s head section:

		<script type="text/javascript" src="http://r.sascdn.com/video/config.js?nwid=<YOUR_NETWORK_ID>"></script>

<script type="text/javascript" src="http://r.sascdn.com/video/controller.js?nwid=<YOUR_NETWORK_ID>"></script>

			

Make sure you replace <YOUR_NETWORK_ID> by your own network ID.

This will automatically include Equativ's library in your web page. The next step is to Define Equativ Data.

Define Equativ Data

The Equativ Data object is the equivalent to the variables defined when setting up display ad serving tags. It tells the Video Plugin what to request (site, page, format, keywords).

All of these values should be defined in a sasVideoData object (property adData). You can define different values for each instance of player.

The adData object should contain the following keys:

Warning: This step should be done before registering the player.

				// Equativ variables
var sasVideoData= {
	id: "playerId",
	adData: {
		sas_siteid: '44928',
		sas_pageid: '322652',
		sas_pagename: 'linear',
		sas_target: '',
		sas_format_linears: '20180',
		sas_format_overlays: '19582'
	}
};
				

You are now ready to register Video Plugin.

The video plugin is capable of requesting banner ad when pausing the main video content. The corresponding configuration keys must be set in the dedicated banner object of sasVideoData. See here for more information

Register Video Plugin

After adding the js library on your page and defining the Equativ Data, you need to register all players where you want to display ads by calling this method:

					sas.video.register(sasVideoData);
			

Here, sasVideoData is an object with defined Equativ data and plugin settings. By calling this method, you will instantiate a new “javascript controller” which is responsible for loading, parsing and displaying the ads.

Note: Preferably, register the player when it has already been created. Otherwise, the javascript library will be looping until the DOM element is found to start processing.

With defined Equativ Data, the integration code should look as follows:

			var sasVideoData= {
	id: 'myContainer',
	adData: {
		sas_siteid: '44928',
		sas_pageid: '322652',
		sas_pagename: 'linear',
		sas_target: '',
		sas_format_linears: '20180,20316,20317',
		sas_format_overlays: '19582'
	}
};
sas.video.register(sasVideoData);
			

After this last mandatory step, you should be able to see some ads on your player.

If you are interested in more advanced features, check these optional settings:

• Define custom configuration
• Define AdRules
• Set your language
• Set content data
• Add callbacks functions
• Add VAST callbacks

User identification

This part of the configuration allows you to set up uid and eids.

The publisher can provide a 1st-party user identification value in the user.uid parameter.
Note that this is different from the uids parameter in the eid object.

eids stands for extended IDs in the AdCOM 1.0 specification of the IAB (used in OpenRTB 3.0). With this configuration, multiple user identifiers from the page can be passed to the plugin which appends them to the ad call. The eid object is an array of objects with properties:

sas.video.register({
	id: 'myContainer',
	adData:	{ ... }, 
	user: {
		uid: 'user-identification-string',
		eids: [{
			source: 'id5-sync.com',
			uids: [{
				id: 'ID5-abc123',
				atype: 1
			}]
		},{
			source: 'criteo.com',
			uids: [{
				id: '1234',
				atype: 1
			}]
		},{
			source: 'digitru.st',
			uids: [{
				id: 'abcd',
				atype: 1
			}]
		}]
	}
});
		

Add callback functions

You can define one or multiple javascript callback functions that will be executed at a specific time. Some callbacks have a callback parameter. Callbacks should be defined in a sasVideoData object (property callbacks).

// Define your callback function 
var adBreakBeginCallback = function(someCallbackParameter){
	// Do something here
}
var adBreakEndCallback = function(someCallbackParameter){
	// Do something here
}
// Add your callback to the config object
sas.video.register({
	id: 'myContainer',
	adData:	{ ... },
	callbacks : {
		adBreakBegin: adBreakBeginCallback,
		adBreakEnd: adBreakEndCallback
	},
	...
});

// Remove it when it is no longer required
sas.video.removeCallback('adBreakBegin', adBreakBeginCallback);
sas.video.removeCallback('adBreakEnd', adBreakEndCallback);
			

The following table lists the callback keys, the moments when callbacks added to the callback keys are triggered, and the callback parameters.

Add VAST callbacks

For an insertion, you can define javascript callback functions that will be executed at specific VAST tracking events.

The VAST tracking events are available in the VAST 4.0 specifications.
The IAB has defined keys for each event: "start", "firstQuartile", "midpoint", "thirdQuartile", "complete", "mute", "unmute", "pause", etc.

In Manage, go to the Creatives tab of your insertion. In the Customized script field, you can define functions that will be called when Equativ tracks the according VAST events. They should be placed in a script tag and their name should follow this pattern "[tracking-key]InsertionCallback"

When the ad is over, these functions will be removed from the page.