DCR & DTVR Browser Adobe Launch Extension

Engineering Portal / Digital / DCR & DTVR / DCR & DTVR Browser Adobe Launch Extension

Adobe Launch Extensions

Adobe Launch Extensions are building blocks for mobile application development that reside on Adobe Servers for client utilization.

Nielsen provides three Adobe Launch Extensions that can be integrated to an html page containing any number of video players. It allows clients to add the reporting functionality to their site by putting several lines of JavaScript code into the page.

• BDSK Adobe Launch Extension
• IMA Adobe Launch Extension
• VJS Adobe Launch Extension

Extension Installation and Configuration

Nielsen has developed Extensions to simplify adding Nielsen measurement into your video stream. The first step is to create and publish a property which is outlined in the Getting Started Guide.

Install the Extension

Nielsen provides three Adobe Launch Extensions that can be integrated to an html page containing any number of video players. It allows clients to add the reporting functionality to their site by putting several lines of JavaScript code into the page.

BSDK extension

BSDK extension integrates the Nielsen BSDK, initializes BSDK instances that can be used by any other extension or from the client’s page directly.

VJS (VideoJS) extension

VJS extension subscribes to standard media events fired by VideoJS player, processes data provided by the user and taken from player, and calls BSDK API (trackevent).

IMA extension

IMA extension subscribes to events fired by the IMA plugin, processes data provided by the user and taken from IMA, and calls BSDK API (trackEvent).

Build the Extension

After the Extension is configured, it can be “built” under the “library” on the Publishing page with other “libraries”.

Add a New library

Select to add a new library

Set the name, chose Environment (Production, Staging, Development):

Save and Build

Add all changed resources. When you get the Extension configured, it will appear in the list of changed resources. Select the Latest revision and press “Select & Create a New Revision” button:

Confirm

Once built, it will appear in the list of Development libraries:

Multi-instance support

The user’s page can contain several players. The user creates BSDK, VJS and IMA extension instances for each player. They should be bound by any string identifier, e.g. a player name. This value must be set in "sdk_instance_name" field of “ext_opt” object for all extensions to bind them.

Prerequisites

Before you begin, ensure that you have an Appid. This is a Unique ID assigned to the player/site and configured by product. If you do not have an AppID , please review the OnBoarding Guide.

BDSK Adobe Launch Extension

BSDK extension integrates the Nielsen BSDK, initializes BSDK instances that can be used by any other extension or from the client’s page directly. Users can communicate with the extension in two ways – either by calling functions exposed by the extension or by using events.

The following events and API calls are supported:

Event	API Function	Description
"nls-sdk-get-info"	window.NSDKAPI.getInfo	requests BSDK extension to provide the extension version information
"nls-sdk-init-instance"	window.NSDKAPI.initInstance	requests BSDK extension to initialize a new SDK instance
"nls-sdk-trackevent"	window.NSDKAPI.trackEvent	sends data for trackEvent function of the SDK

Event based API

The extension listens to the following custom events:

"nls-sdk-get-info"

Format of input object is the following:

{ detail:
    {
        callback: function(obj) { /* Do something */}
    }
}

All parameters and supported values are described below.

Parameter	Description	Required	Values
callback	Function that is called by the extension to provide output data	Yes	Function

"nls-sdk-init-instance"

Format of input object is the following:

{ detail:
    {
        sdk_instance_name: <name>,
        // other parameters,
        callback: function(obj) { /* Do something */}
    }
}

All parameters and supported values are described below.

Parameter	Description	Required	Values	Example
sdk_instance_name	Name of the BSDK instance. It's used to bind BSDK and other extensions. If it's not provided, the extension generates the name. It can be obtained in the callback function.	No	string	"sdk_instance_name": "myPlayer1"
debug	Debug flag. If set to "DEBUG", the extension prints debug messages to the browser console.	No	string	"debug": "DEBUG"
apid	APID that is used in Browser SDK	Yes	string	"apid": "PXXXXXXXX-XXXX-"
opt_params	Optional parameters that are passed to initialization function of Browser SDK	No	object	"opt_params": { "apn": "myApn", "sfcode": "code1", "nol_sdkDebug": "DEBUG" }
callback	Function that is called by the extension to provide output data	No	function	"callback": function (ret) { var name = ret.sdk_instance_name; }
fnMessage			function	"fnMessage": function (msg) { if (msg) console.log(msg); }

"nls-sdk-trackevent"

Format of input object is the following:

{ detail:
    {
        sdk_instance_name: <name>,
                obj: { /* data */ }
    }
}

All parameters and supported values are described below.

Parameter	Description	Required	Values	Example
sdk_instance_name	Name of the BSDK instance that should receive the data.	Yes	string	"sdk_instance_name": "myPlayer1"
obj	Object containing data that is passed to trackEvent function of Browser SDK	Yes	string	"obj": { "event": 'playhead', "type": 'static', "playheadPosition": '1', "metadata": { "static": { "type": 'static', "assetid": 'AID885-9984' } }}
callback	Function that is called by the extension to provide the result value. It's true if success.		function	"callback": function (ret) { var result = ret.result; }

Examples.

Implementation Methods

There are two ways to communicate with extensions. Users can use events or call the extension methods directly.

Event Implementation Method

The first step is to include the following Inside the <head> tag:

<script src="//assets.adobedtm.com/launch-XXXXXX-development.min.js"></script>

Initialize Instance

1. Create Video Player (Don't init at this stage yet)
2. Request VJS extension information

# Initialize BSDK Instance
<syntaxhighlight lang="javascript">
var ev = new CustomEvent("nls-sdk-init-instance", {
            "detail": {
                "sdk_instance_name": playerId,
                "debug": "DEBUG",
                "apid": sdkPluginParams.apid,
                "opt_params": {
                    "nol_override": {
                        "nol_playerv": videoVersion,
                        "nol_plugv": plugv
                    },
                    "apn": sdkPluginParams.apn,
                    "sfcode": sdkPluginParams.sfcode,
                    "nol_sdkDebug": sdkPluginParams.nol_sdkDebug
                },

1. Initialize IMA Instance 'nls-ima-init-instance'
2. Initialize VJS Instance 'nls-vjs-init-instance'
3. Initialize Player (Load playlist, ads)
4. Fire Media event 'loadstart'
5. Event 'nls-vjs-get-data'
6. Event 'nls-vjs-set-data'

1. When the video starts loading, the video player fires standard “loadstart” media event. The VJS extension sends "nls-vjs-get-data" event with the currentSrc (unique data describing the video stream) and the player identifier that must be returned with the user’s response.
2. The user responds with the event "nls-vjs-set-data" providing the custom content metadata to the VJS extension.
3. VJS extension listens to "nls-vjs-set-data" event. The custom data will be used when sending data to BSDK.
4. VJS extension listens to all necessary standard media events (loadeddata, play, pause, timeupdate, ended, etc.) and handles data appropriately.

These media events are being queued until the extension receives the custom data from the user. When the custom data arrives, the metadata in the queue is updated with the custom data received. The extension then flushes the queued data to the BSDK. The extension buffers the events within 5 seconds max

All extensions use event "nls-msg" to send error or any other messages to the user User subscribes to "nls-vjs-get-data" event.

- User sends "nls-sdk-init-instance" with the SDK instance name, SDK options and a callback function. - User sends "nls-vjs-init-instance" with the SDK instance name, VJS extension options and a callback function. - User sends "nls-ima-init-instance" with the SDK instance name, IMA extension options and a callback function. BSDK extension. In the "nls-sdk-init-instance" event handler:

Event Description

The extensions use the following events to communicate with the user’s page and between each other:

Event	Sender	Receiver	Description
nls-sdk-get-info	Client-defined	No	"Nielsen Sample App"
nls-sdk-init-instance	Client-defined	No	"1.0.2"
nls-sdk-trackevent
sfcode	Nielsen collection facility to which the SDK should connect.

Inside <body> tag:

// create player with id specified in video tag
// ....
// Add listener. You can use the following code as a template.
document.addEventListener("nls-vjs-get-data", function (event) {
var customData = {};
var detail = event.detail;
var plId = detail.playerId;
// We must provide playerId field back to the event originator in "nls-vjs-set-data"
var currentSrc = detail.currentSrc;
if (currentSrc === “/path/file.mp4”) customData.assetid = "SeaHorseID";
var ev = new CustomEvent("nls-vjs-set-data", {"detail": { playerId: plId, custom_fields: customData } });
document.dispatchEvent(ev);
});
//
// Initialize BSDK and VJS extensions. You can use the following code as a template.
var ev = new CustomEvent("nls-sdk-init-instance", {"detail":
{
ext_opt:

{
"sdk_instance_name": "inst_" + playerId,
"apid": APID,
"opt_params":
{
"apn": APN,
"sfcode": SFCODE,
"nol_sdkDebug": "DEBUG"
}
},
callback: function (ret) {
var sdk_instance_name = ret. sdk_instance_name;
var ev = new CustomEvent("nls-vjs-init-instance", {"detail":
{
"playerId": playerId,
"sdk_instance_name": sdk_instance_name,
"callback": function (ret) {
console.log("USER: VJS is ready");
// initialize player (set playlist, ads);
}
}
});
console.log("USER: Sending nls-vjs-init-instance");
document.dispatchEvent(ev);
}

}
});
console.log("USER: Sending nls-sdk-init-instance");
document.dispatchEvent(ev);

// Add the following before </body>

<script>_satellite.pageBottom();</script>