Difference between revisions of "DCR & DTVR Browser Adobe Launch Extension"

From Engineering Client Portal

Line 157: Line 157:
 
</syntaxhighlight>||
 
</syntaxhighlight>||
 
|}
 
|}
Examples.
+
 
 +
=== Examples ===
 +
'''How to get version information of SDK extension'''
 +
 
 +
<syntaxhighlight lang="Javascript">
 +
var ev = new CustomEvent("nls-sdk-get-info", {"detail":
 +
{
 +
    callback: function (obj) {
 +
        var sdkInfo = obj.extinfo;
 +
    }
 +
}
 +
});
 +
document.dispatchEvent(ev);
 +
</syntaxhighlight>
 +
 
 +
 
 +
'''How to create an instance of SDK extension'''
 +
 
 +
<syntaxhighlight lang="Javascript">
 +
var ev = new CustomEvent("nls-sdk-init-instance", {"detail":
 +
  {
 +
    "sdk_instance_name": "myPlayer1",
 +
    "debug": "DEBUG",
 +
    "apid": "PXXXXXXXX-XXXX-",
 +
    "opt_params":
 +
      {
 +
        "apn": "myApn",
 +
        "sfcode": "code1",
 +
        "nol_sdkDebug": "DEBUG"
 +
      },
 +
    "callback": function (ret) {
 +
      var name = ret.sdk_instance_name;
 +
    }
 +
  }
 +
});
 +
document.dispatchEvent(ev);
 +
</syntaxhighlight>
 +
 
 +
 
 +
'''How to send trackEvent'''
 +
 
 +
<syntaxhighlight lang="Javascript">
 +
var ev = new CustomEvent("nls-sdk-trackevent", {"detail":
 +
  {
 +
  "sdk_instance_name": "myPlayer1",
 +
  "obj": {
 +
      "event": 'playhead',
 +
      "type": 'static',
 +
      "playheadPosition": '1',
 +
      "metadata": {
 +
        "static": {
 +
            "type": 'static',
 +
            "assetid": 'AID885-9984'
 +
        }
 +
    }
 +
  }
 +
});
 +
document.dispatchEvent(ev);
 +
</syntaxhighlight>
 +
 
 +
== Tracking the SDK Event ==
 +
=== Event Types ===
 +
The following event types are supported:
 +
{| class="wikitable"
 +
!Key
 +
!Description
 +
|-
 +
|'''playhead'''||
 +
It is used to pass content, ad or static metadata, the current playhead value, Unix timestamp or id3 payload, OTT information to the SDK.
 +
|-
 +
|'''pause'''||
 +
This event should be used to in the following cases:
 +
application enters background,
 +
any application interruptions,
 +
content playback is paused.  (Pause is detected by SDK automatically only if the time gap between commands exceeds 30 minutes.)
 +
|-
 +
|'''complete'''||
 +
It is called when session is completed or ends.
 +
|-
 +
|'''adStop'''||
 +
This event should be called at the end of each ad and is required when advertisements have the same assetId.
 +
|}
 +
<br>
 +
 
 +
=== Handling JSON Metadata ===
 +
Parameter “data” is a JSON object with many key-value pairs that holds all information required by SDK.
 +
 
 +
Format of input object is the following:
 +
<syntaxhighlight lang="json">
 +
{
 +
"event": <event identifier>,
 +
"type": <type of metadata>,
 +
"metadata":{
 +
  "content": <content metadata object>,
 +
  "ad": <ad metadata object>,
 +
  "static": <static metadata object>
 +
},
 +
"playheadPosition":<playhead value | Unix Timestamp>,
 +
"id3Data": <id3 payload>,
 +
}
 +
</syntaxhighlight>
 +
<br>
 +
{{DCRDTVRTabs
 +
|DCR=
 +
=== Digital Content Ratings===
 +
<table>
 +
<tr>
 +
<th>  Parameter
 +
</th>
 +
<th> <b>Description</b>
 +
</th>
 +
<th> <b>Supported values</b>
 +
</th>
 +
<th> <b>Example</b>
 +
</th></tr>
 +
<tr>
 +
<td> <b>event</b>
 +
</td>
 +
<td> Event identifier
 +
</td>
 +
<td>
 +
<p><code> String:
 +
playhead,pause,complete,
 +
adStop</code>
 +
</p>
 +
</td>
 +
<td><syntaxhighlight lang="swift">"event":"playhead"</syntaxhighlight>
 +
</td></tr>
 +
<tr>
 +
<td> <b>type</b>
 +
</td>
 +
<td> Determines the metadata object
 +
that should be used for crediting.
 +
</td>
 +
<td>
 +
<p><code> String:<br />
 +
content,
 +
ad,
 +
static</code>
 +
</p>
 +
</td>
 +
<td><syntaxhighlight lang="swift">"type":"content"</syntaxhighlight>
 +
</td></tr>
 +
<tr>
 +
<td> <b>metadata</b>
 +
</td>
 +
<td> Object that holds metadata values of specific types<br />
 +
<p><span style="color:blue"> Detailed in tables below</span>
 +
</p>
 +
</td>
 +
<td> <code>Object</code>
 +
</td>
 +
<td><syntaxhighlight lang="swift">
 +
"metadata":{
 +
  "content": <content metadata object>,
 +
  "ad": <ad metadata object>,
 +
  "static": <static metadata object>
 +
},
 +
</syntaxhighlight>
 +
</td></tr>
 +
<tr>
 +
<td> <b>playheadPosition</b>
 +
</td>
 +
<td> Playhead value as reported by video player.  <br> Unix timestamp (seconds since Jan-01-1970 UTC) for live video.
 +
</td>
 +
<td> <code>String</code>
 +
</td>
 +
<td>
 +
<p>Position value is Unix timestamp (live):
 +
<code>
 +
"playheadPosition":"1542797780"</code>
 +
</p><p>Position value is playhead:
 +
<code>
 +
"playheadPosition":"10"</code>
 +
</p>
 +
</td></tr>
 +
</table>
 +
=== Content Metadata ===
 +
Content metadata sent for every playheadposition update.
 +
<table>
 +
<tr>
 +
<th> Keys </th>
 +
<th> Description </th>
 +
<th> Example </th>
 +
<th> Required
 +
</th></tr>
 +
<tr>
 +
<td>'''assetName''' </td>
 +
<td> name of program (100 character limit) </td>
 +
<td> <code>"MyTest789"</code> </td>
 +
<td> Yes
 +
</td></tr>
 +
<tr>
 +
<td> '''assetid''' </td>
 +
<td> unique ID assigned to asset </td>
 +
<td> custom </td>
 +
<td> Yes
 +
</td></tr>
 +
<tr>
 +
<td> '''length''' </td>
 +
<td> length of content in seconds </td>
 +
<td> <code>seconds</code> (0 for live stream or unknown) </td>
 +
<td> Yes
 +
</td></tr>
 +
<tr>
 +
<td> '''program''' </td>
 +
<td>name of program (100 character limit) </td>
 +
<td> custom </td>
 +
<td> Yes
 +
</td></tr>
 +
<tr>
 +
<td> '''segB''' </td>
 +
<td> custom segment B ¹</td>
 +
<td> custom </td>
 +
<td>
 +
</td></tr>
 +
<tr>
 +
<td> '''segC''' </td>
 +
<td> custom segment C ¹</td>
 +
<td> custom </td>
 +
<td>
 +
</td></tr>
 +
<tr>
 +
<td> '''title''' </td>
 +
<td>name of program (100 character limit) </td>
 +
<td> custom </td>
 +
<td> Yes
 +
</td></tr>
 +
<tr>
 +
<td>'''type'''</td>
 +
<td><code>'content', 'ad', 'static'</code></td>
 +
<td> <code> 'content'</code> </td>
 +
<td> Yes
 +
</td></tr>
 +
<tr>
 +
<td>'''section''' </td>
 +
<td> Unique Value assigned to page/site section </td>
 +
<td> HomePage </td>
 +
<td> Yes
 +
</td></tr>
 +
<tr>
 +
<td> '''airdate''' </td>
 +
<td> the airdate in the linear TV ² </td>
 +
<td> YYYYMMDD HH24:MI:SS </td>
 +
<td> Yes
 +
</td></tr>
 +
<tr>
 +
<td> '''isfullepisode''' </td>
 +
<td> full episode flag </td>
 +
<td> <code>"y"</code>- full episode, <code>"n"</code>- non full episode </td>
 +
<td> Yes
 +
</td></tr>
 +
<tr>
 +
<td> '''crossId1''' </td>
 +
<td> standard episode ID </td>
 +
<td> custom </td>
 +
<td> ✓
 +
</td></tr>
 +
<tr>
 +
<td> '''crossId2 '''</td>
 +
<td> content originator (only required for distributors) </td>
 +
<td> Nielsen provided </td>
 +
<td>
 +
</td></tr>
 +
<tr>
 +
<td> <b>adloadtype</b>
 +
</td>
 +
<td> linear vs dynamic ad model
 +
</td>
 +
<td> 1=Linear
 +
2=Dynamic Ads
 +
</td>
 +
<td>custom
 +
</td></tr>
 +
</table>
 +
¹ '''Custom segments''' (segB and segC) can be used to aggregate video and/or static content within a single Brand to receive more granular reports within a brand.<br>
 +
² Acceptable '''Air Date''' Formats:
 +
<syntaxhighlight lang="json">
 +
YYYYMMDD HH24:MI:SS
 +
YYYYMMDDHH24MISS
 +
YYYY-MM-DDTHH:MI:SS
 +
YYYY-MM-DDHH:MI:SS
 +
YYYYMMDDHH:MI:SS
 +
MM-DD-YYYY
 +
YYYYMMDD HH:MI:SS
 +
</syntaxhighlight>
 +
<br>
 +
For USA all times should be EST, for all other countries Local Time.
 +
Below is a sample event for DCR. If no ad or static values, these can be left as blank/null.
 +
<syntaxhighlight lang="json">
 +
{
 +
"event": "playhead",
 +
"type": "content",
 +
"metadata": {
 +
  "content":{
 +
    "assetName":"Big Buck Bunny",
 +
    "assetid":"B66473",
 +
    "length":"3600",
 +
    "program":"MyProgram",
 +
    "segB":"CustomSegmentValueB",
 +
    "segC":"segmentC",
 +
    "title":"S2,E3",
 +
    "type":"content",
 +
    "section":"cloudApi_app",
 +
    "airdate":"20180120 10:00:00",
 +
    "isfullepisode":"y",
 +
    "crossId1":"Standard Episode ID",
 +
    "crossId2" :"Content Originator",
 +
    "adloadtype":"2"},
 +
"ad": {},
 +
"static": {}
 +
},
 +
"playheadPosition": "",
 +
}
 +
</syntaxhighlight>
 +
 
 +
|DTVR=
 +
=== Digital TV Ratings info ===
 +
<table>
 +
<tr>
 +
<th>  Parameter
 +
</th>
 +
<th> <b>Description</b>
 +
</th>
 +
<th> <b>Supported values</b>
 +
</th>
 +
<th> <b>Example</b>
 +
</th></tr>
 +
<tr>
 +
<td> <b>event</b>
 +
</td>
 +
<td> Event identifier
 +
</td>
 +
<td>
 +
<p><code> String:
 +
playhead,pause,complete,
 +
adStop</code>
 +
</p>
 +
</td>
 +
<td><syntaxhighlight lang="swift">"event":"playhead"</syntaxhighlight>
 +
</td></tr>
 +
<tr>
 +
<td> <b>type</b>
 +
</td>
 +
<td> Determines the metadata object that should be used for crediting.
 +
</td>
 +
<td>
 +
<p><code> String:<br />
 +
content,
 +
ad,
 +
static</code>
 +
</p>
 +
</td>
 +
<td><syntaxhighlight lang="swift">"type":"content"</syntaxhighlight>
 +
</td></tr>
 +
<tr>
 +
<td> <b>adModel</b>
 +
</td>
 +
<td> linear vs dynamic ad model
 +
</td>
 +
<td> 1=Linear
 +
2=Dynamic Ads
 +
</td>
 +
<td>custom
 +
</td></tr>
 +
<tr>
 +
<td> <b>channelName</b>
 +
</td>
 +
<td> Any string representing the.channel/stream
 +
</td>
 +
<td> <code>Object</code>
 +
</td>
 +
<td>custom
 +
</td></tr>
 +
<tr>
 +
<td> <b>playheadPosition</b>
 +
</td>
 +
<td> Playhead value or Unix timestamp (seconds since Jan-01-1970 UTC)
 +
</td>
 +
<td> <code>String</code>
 +
</td>
 +
<td>
 +
<p>Position value is Unix timestamp:
 +
<code>
 +
"playheadPosition":"1542797780"</code>
 +
</p><p>Position value is playhead:
 +
<code>
 +
"playheadPosition":"10"</code>
 +
</p>
 +
</td></tr>
 +
<tr>
 +
<td> <b>id3Data</b>
 +
</td>
 +
<td> Nielsen ID3 payload
 +
</td>
 +
<td> <code>String</code>
 +
</td>
 +
<td>
 +
<p><code>
 +
"id3Data": "www.nielsen.com/065H2g6E7ZyQ5UdmMAbbpg
 +
==/_EMc37zfVgq_8KB7baUYfg==/ADQCAmgV1Xyvnynyg60
 +
kZO_Ejkcn2KLSrTzyJpZZ-QeRn8GpMGTWI7-HrEKzghxyzC
 +
yBEoIDv2kA2g1QJmeYOl5GnwfrLDVK2bNLTbQxr1z9VBfxa
 +
hBcQP5tqbjhyMzdVqrMKuvvJO1jhtSXa9AroChb11ZUnG1W
 +
VJx2O4M=/33648/22847/00"</code>
 +
</p>
 +
<tr>
 +
 
 +
</td></tr>
 +
</table>
 +
Below is a sample event for DTVR.  If no ad or static values, these can be left as blank/null.
 +
<syntaxhighlight lang="json">
 +
{
 +
"event": "playhead",
 +
"type": "content",
 +
"metadata": {
 +
  "content":{
 +
    "adModel":"1",
 +
    "channelname":"channel1"
 +
  },
 +
"ad": {},
 +
"static": {}
 +
},
 +
"playheadPosition": "",
 +
"id3Data": "www.nielsen.com/065H2g6E7ZyQ5UdmMAbbpg==/_
 +
EMc37zfVgq_8KB7baUYfg==/ADQCAmgV1Xyvnynyg60kZO_Ejkcn
 +
2KLSrTzyJpZZ-QeRn8GpMGTWI7-HrEKzghxyzCyBEoIDv2kA2g1Q
 +
JmeYOl5GnwfrLDVK2bNLTbQxr1z9VBfxahBcQP5tqbjhyMzdVqrMK
 +
uvvJO1jhtSXa9AroChb11ZUnG1WVJx2O4M=/33648/22847/00"
 +
}
 +
</syntaxhighlight>
 +
|DCRDTVR=
 +
=== Applies to DCR and DTVR ===
 +
<table>
 +
<tr>
 +
<th>  Parameter
 +
</th>
 +
<th> <b>Description</b>
 +
</th>
 +
<th> <b>Supported values</b>
 +
</th>
 +
<th> <b>Example</b>
 +
</th></tr>
 +
<tr>
 +
<td> <b>event</b>
 +
</td>
 +
<td> Event identifier
 +
</td>
 +
<td>
 +
<p><code> String:
 +
playhead,
 +
pause,
 +
complete,
 +
adStop</code>
 +
</p>
 +
</td>
 +
<td><syntaxhighlight lang="swift">"event":"playhead"</syntaxhighlight>
 +
</td></tr>
 +
<tr>
 +
<td> <b>type</b>
 +
</td>
 +
<td> Determines the metadata object that should be used for crediting.
 +
</td>
 +
<td>
 +
<p><code> String:<br />
 +
content,
 +
ad,
 +
static</code>
 +
</p>
 +
</td>
 +
<td><syntaxhighlight lang="swift">"type":"content"</syntaxhighlight>
 +
</td></tr>
 +
<tr>
 +
<td> <b>metadata</b>
 +
</td>
 +
<td> Object that holds metadata values of specific types<br />
 +
<p><span style="color:blue"> Detailed in tables below</span>
 +
</p>
 +
</td>
 +
<td> <code>Object</code>
 +
</td>
 +
<td><syntaxhighlight lang="swift">
 +
"metadata":{
 +
  "content": <content metadata object>,
 +
  "ad": <ad metadata object>,
 +
  "static": <static metadata object>
 +
},
 +
</syntaxhighlight>
 +
</td></tr>
 +
<tr>
 +
<td> <b>playheadPosition</b>
 +
</td>
 +
<td> Playhead value or Unix timestamp (seconds since Jan-01-1970 UTC)
 +
</td>
 +
<td> <code>String</code>
 +
</td>
 +
<td>
 +
<p>Position value is Unix timestamp:
 +
<code>
 +
"playheadPosition":"1501225191747"</code>
 +
</p><p>Position value is playhead:
 +
<code>
 +
"playheadPosition":"10"</code>
 +
</p>
 +
</td></tr>
 +
<tr>
 +
<td> <b>id3Data</b>
 +
</td>
 +
<td> Nielsen ID3 payload
 +
</td>
 +
<td> <code>Object</code>
 +
</td>
 +
<td>
 +
<p><code>
 +
"id3Data": "www.nielsen.com/065H2g6E7ZyQ5UdmMAbbpg
 +
==/_EMc37zfVgq_8KB7baUYfg==/ADQCAmgV1Xyvnynyg60
 +
kZO_Ejkcn2KLSrTzyJpZZ-QeRn8GpMGTWI7-HrEKzghxyzC
 +
yBEoIDv2kA2g1QJmeYOl5GnwfrLDVK2bNLTbQxr1z9VBfxa
 +
hBcQP5tqbjhyMzdVqrMKuvvJO1jhtSXa9AroChb11ZUnG1W
 +
VJx2O4M=/33648/22847/00"</code>
 +
</p>
 +
</td></tr>
 +
<tr>
 +
<td> <b>ottData</b>
 +
</td>
 +
<td> Object that holds OTT information
 +
</td>
 +
<td> <code>Object</code>
 +
</td>
 +
<td><syntaxhighlight lang="swift">
 +
"ottData": {
 +
  "ottStatus": 1,
 +
  "ottType": casting,
 +
  "ottDevice": chromecast,
 +
  "ottDeviceID": 1234
 +
}
 +
</syntaxhighlight>
 +
</td></tr>
 +
</table>
 +
=== Content Metadata ===
 +
Content metadata sent for every playheadposition update.
 +
<table>
 +
<tr>
 +
<th> Keys </th>
 +
<th> Description </th>
 +
<th> Example </th>
 +
<th> Required
 +
</th></tr>
 +
<tr>
 +
<td> '''length''' </td>
 +
<td> length of content in seconds </td>
 +
<td> <code>seconds</code> (0 for live stream) </td>
 +
<td> Yes
 +
</td></tr>
 +
<tr>
 +
<td>'''type'''</td>
 +
<td><code>"content", "ad", "static"</code></td>
 +
<td> <code> "content"</code> </td>
 +
<td> Yes
 +
</td></tr>
 +
<tr>
 +
<td> <b>adModel</b>
 +
</td>
 +
<td> linear vs dynamic ad model
 +
</td>
 +
<td> 1=Linear
 +
2=Dynamic Ads
 +
</td>
 +
<td>custom
 +
</td></tr>
 +
<tr>
 +
<td> <b>adloadtype</b>
 +
</td>
 +
<td> DCR Ad Model
 +
</td>
 +
<td> 1=Linear
 +
2=Dynamic Ads
 +
</td>
 +
<td>custom
 +
</td></tr>
 +
</table>
 +
+ '''Custom segments''' (segB and segC) can be used to aggregate video and/or static content within a single Brand to receive more granular reports within a brand.<br>
 +
++ Acceptable '''Air Date''' Formats:
 +
<syntaxhighlight lang="json">
 +
YYYYMMDD HH24:MI:SS
 +
YYYYMMDDHH24MISS
 +
YYYY-MM-DDTHH:MI:SS
 +
YYYY-MM-DDHH:MI:SS
 +
YYYYMMDDHH:MI:SS
 +
MM-DD-YYYY
 +
YYYYMMDD HH:MI:SS
 +
</syntaxhighlight>
 +
<br>
 +
Below is a sample event for DCR/DTVR joint integration. If no ad or static values, these can be left as blank/null.
 +
<syntaxhighlight lang="json">
 +
{
 +
"event": "playhead",
 +
"type": "content",
 +
"metadata": {
 +
  "content":{
 +
    "type":"content",
 +
    "length":"0",
 +
    "adModel":"1",
 +
    "adloadtype":"1"},
 +
  "ad": {},
 +
  "static": {}
 +
},
 +
"playheadPosition": "",
 +
"id3Data": "www.nielsen.com/065H2g6E7ZyQ5UdmMAbbpg==/_
 +
EMc37zfVgq_8KB7baUYfg==/ADQCAmgV1Xyvnynyg60kZO_Ejkcn
 +
2KLSrTzyJpZZ-QeRn8GpMGTWI7-HrEKzghxyzCyBEoIDv2kA2g1Q
 +
JmeYOl5GnwfrLDVK2bNLTbQxr1z9VBfxahBcQP5tqbjhyMzdVqrMK
 +
uvvJO1jhtSXa9AroChb11ZUnG1WVJx2O4M=/33648/22847/00"
 +
}
 +
</syntaxhighlight>
 +
}}
  
 
= IMA Adobe Launch Extension =
 
= IMA Adobe Launch Extension =

Revision as of 06:32, 25 January 2019

Engineering Portal breadcrumbArrow.png Digital breadcrumbArrow.png DCR & DTVR breadcrumbArrow.png 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. icon

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

icon

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

icon

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: icon

Confirm

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

icon

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

How to get version information of SDK extension

var ev = new CustomEvent("nls-sdk-get-info", {"detail":
 {
     callback: function (obj) {
         var sdkInfo = obj.extinfo;
     }
 }
});
document.dispatchEvent(ev);


How to create an instance of SDK extension

var ev = new CustomEvent("nls-sdk-init-instance", {"detail":
  {
    "sdk_instance_name": "myPlayer1",
    "debug": "DEBUG",
    "apid": "PXXXXXXXX-XXXX-",
    "opt_params":
       {
         "apn": "myApn",
         "sfcode": "code1",
         "nol_sdkDebug": "DEBUG"
       },
    "callback": function (ret) {
       var name = ret.sdk_instance_name;
    }
  }
});
document.dispatchEvent(ev);


How to send trackEvent

var ev = new CustomEvent("nls-sdk-trackevent", {"detail":
  {
   "sdk_instance_name": "myPlayer1",
   "obj": {
      "event": 'playhead',
      "type": 'static',
      "playheadPosition": '1',
      "metadata": {
         "static": {
            "type": 'static',
            "assetid": 'AID885-9984'
         }
    }
  }
});
document.dispatchEvent(ev);

Tracking the SDK Event

Event Types

The following event types are supported:

Key Description
playhead

It is used to pass content, ad or static metadata, the current playhead value, Unix timestamp or id3 payload, OTT information to the SDK.

pause

This event should be used to in the following cases: application enters background, any application interruptions, content playback is paused. (Pause is detected by SDK automatically only if the time gap between commands exceeds 30 minutes.)

complete

It is called when session is completed or ends.

adStop

This event should be called at the end of each ad and is required when advertisements have the same assetId.


Handling JSON Metadata

Parameter “data” is a JSON object with many key-value pairs that holds all information required by SDK.

Format of input object is the following:

{ 
 "event": <event identifier>,
 "type": <type of metadata>,
 "metadata":{ 
   "content": <content metadata object>,
   "ad": <ad metadata object>,
   "static": <static metadata object>
 },
 "playheadPosition":<playhead value | Unix Timestamp>,
 "id3Data": <id3 payload>,
}


DCR

Digital Content Ratings

Parameter Description Supported values Example
event Event identifier

String: playhead,pause,complete, adStop

"event":"playhead"
type Determines the metadata object

that should be used for crediting.

String:
content, ad, static

"type":"content"
metadata Object that holds metadata values of specific types

Detailed in tables below

Object
"metadata":{ 
   "content": <content metadata object>,
   "ad": <ad metadata object>,
   "static": <static metadata object>
 },
playheadPosition Playhead value as reported by video player.
Unix timestamp (seconds since Jan-01-1970 UTC) for live video.
String

Position value is Unix timestamp (live): "playheadPosition":"1542797780"

Position value is playhead:

"playheadPosition":"10"

Content Metadata

Content metadata sent for every playheadposition update.

Keys Description Example Required
assetName name of program (100 character limit) "MyTest789" Yes
assetid unique ID assigned to asset custom Yes
length length of content in seconds seconds (0 for live stream or unknown) Yes
program name of program (100 character limit) custom Yes
segB custom segment B ¹ custom
segC custom segment C ¹ custom
title name of program (100 character limit) custom Yes
type 'content', 'ad', 'static' 'content' Yes
section Unique Value assigned to page/site section HomePage Yes
airdate the airdate in the linear TV ² YYYYMMDD HH24:MI:SS Yes
isfullepisode full episode flag "y"- full episode, "n"- non full episode Yes
crossId1 standard episode ID custom
crossId2 content originator (only required for distributors) Nielsen provided
adloadtype linear vs dynamic ad model 1=Linear

2=Dynamic Ads

custom

¹ Custom segments (segB and segC) can be used to aggregate video and/or static content within a single Brand to receive more granular reports within a brand.
² Acceptable Air Date Formats:

YYYYMMDD HH24:MI:SS
YYYYMMDDHH24MISS
YYYY-MM-DDTHH:MI:SS
YYYY-MM-DDHH:MI:SS 
YYYYMMDDHH:MI:SS
MM-DD-YYYY
YYYYMMDD HH:MI:SS


For USA all times should be EST, for all other countries Local Time. Below is a sample event for DCR. If no ad or static values, these can be left as blank/null.

{ 
"event": "playhead",
"type": "content",
"metadata": { 
  "content":{
    "assetName":"Big Buck Bunny",
    "assetid":"B66473",
    "length":"3600",
    "program":"MyProgram",
    "segB":"CustomSegmentValueB",
    "segC":"segmentC",
    "title":"S2,E3",
    "type":"content",
    "section":"cloudApi_app",
    "airdate":"20180120 10:00:00",
    "isfullepisode":"y",
    "crossId1":"Standard Episode ID",
    "crossId2" :"Content Originator",
    "adloadtype":"2"},
"ad": {},
"static": {}
},
"playheadPosition": "",
}

DTVR

Digital TV Ratings info

Parameter Description Supported values Example
event Event identifier

String: playhead,pause,complete, adStop

"event":"playhead"
type Determines the metadata object that should be used for crediting.

String:
content, ad, static

"type":"content"
adModel linear vs dynamic ad model 1=Linear

2=Dynamic Ads

custom
channelName Any string representing the.channel/stream Object custom
playheadPosition Playhead value or Unix timestamp (seconds since Jan-01-1970 UTC) String

Position value is Unix timestamp: "playheadPosition":"1542797780"

Position value is playhead:

"playheadPosition":"10"

id3Data Nielsen ID3 payload String

"id3Data": "www.nielsen.com/065H2g6E7ZyQ5UdmMAbbpg ==/_EMc37zfVgq_8KB7baUYfg==/ADQCAmgV1Xyvnynyg60 kZO_Ejkcn2KLSrTzyJpZZ-QeRn8GpMGTWI7-HrEKzghxyzC yBEoIDv2kA2g1QJmeYOl5GnwfrLDVK2bNLTbQxr1z9VBfxa hBcQP5tqbjhyMzdVqrMKuvvJO1jhtSXa9AroChb11ZUnG1W VJx2O4M=/33648/22847/00"

Below is a sample event for DTVR. If no ad or static values, these can be left as blank/null.

{ 
"event": "playhead",
"type": "content",
"metadata": { 
  "content":{
    "adModel":"1",
    "channelname":"channel1"
  },
"ad": {},
"static": {}
},
"playheadPosition": "",
"id3Data": "www.nielsen.com/065H2g6E7ZyQ5UdmMAbbpg==/_
EMc37zfVgq_8KB7baUYfg==/ADQCAmgV1Xyvnynyg60kZO_Ejkcn
2KLSrTzyJpZZ-QeRn8GpMGTWI7-HrEKzghxyzCyBEoIDv2kA2g1Q
JmeYOl5GnwfrLDVK2bNLTbQxr1z9VBfxahBcQP5tqbjhyMzdVqrMK
uvvJO1jhtSXa9AroChb11ZUnG1WVJx2O4M=/33648/22847/00"
}

DCR & DTVR

Applies to DCR and DTVR

Parameter Description Supported values Example
event Event identifier

String: playhead, pause, complete, adStop

"event":"playhead"
type Determines the metadata object that should be used for crediting.

String:
content, ad, static

"type":"content"
metadata Object that holds metadata values of specific types

Detailed in tables below

Object
"metadata":{ 
   "content": <content metadata object>,
   "ad": <ad metadata object>,
   "static": <static metadata object>
 },
playheadPosition Playhead value or Unix timestamp (seconds since Jan-01-1970 UTC) String

Position value is Unix timestamp: "playheadPosition":"1501225191747"

Position value is playhead:

"playheadPosition":"10"

id3Data Nielsen ID3 payload Object

"id3Data": "www.nielsen.com/065H2g6E7ZyQ5UdmMAbbpg ==/_EMc37zfVgq_8KB7baUYfg==/ADQCAmgV1Xyvnynyg60 kZO_Ejkcn2KLSrTzyJpZZ-QeRn8GpMGTWI7-HrEKzghxyzC yBEoIDv2kA2g1QJmeYOl5GnwfrLDVK2bNLTbQxr1z9VBfxa hBcQP5tqbjhyMzdVqrMKuvvJO1jhtSXa9AroChb11ZUnG1W VJx2O4M=/33648/22847/00"

ottData Object that holds OTT information Object
"ottData": {
   "ottStatus": 1,
   "ottType": casting,
   "ottDevice": chromecast,
   "ottDeviceID": 1234
}

Content Metadata

Content metadata sent for every playheadposition update.

Keys Description Example Required
length length of content in seconds seconds (0 for live stream) Yes
type "content", "ad", "static" "content" Yes
adModel linear vs dynamic ad model 1=Linear

2=Dynamic Ads

custom
adloadtype DCR Ad Model 1=Linear

2=Dynamic Ads

custom

+ Custom segments (segB and segC) can be used to aggregate video and/or static content within a single Brand to receive more granular reports within a brand.
++ Acceptable Air Date Formats:

YYYYMMDD HH24:MI:SS
YYYYMMDDHH24MISS
YYYY-MM-DDTHH:MI:SS
YYYY-MM-DDHH:MI:SS 
YYYYMMDDHH:MI:SS
MM-DD-YYYY
YYYYMMDD HH:MI:SS


Below is a sample event for DCR/DTVR joint integration. If no ad or static values, these can be left as blank/null.

{ 
"event": "playhead",
"type": "content",
"metadata": { 
  "content":{
    "type":"content",
    "length":"0",
    "adModel":"1",
    "adloadtype":"1"},
  "ad": {},
  "static": {}
},
"playheadPosition": "",
"id3Data": "www.nielsen.com/065H2g6E7ZyQ5UdmMAbbpg==/_
EMc37zfVgq_8KB7baUYfg==/ADQCAmgV1Xyvnynyg60kZO_Ejkcn
2KLSrTzyJpZZ-QeRn8GpMGTWI7-HrEKzghxyzCyBEoIDv2kA2g1Q
JmeYOl5GnwfrLDVK2bNLTbQxr1z9VBfxahBcQP5tqbjhyMzdVqrMK
uvvJO1jhtSXa9AroChb11ZUnG1WVJx2O4M=/33648/22847/00"
}

IMA Adobe Launch Extension

VJS Adobe Launch Extension

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>

Direct API Implementation Method