Difference between revisions of "DCR & DTVR Browser Adobe Launch Extension"
From Engineering Client Portal
(50 intermediate revisions by 2 users not shown) | |||
Line 2: | Line 2: | ||
[[Category:Digital]] | [[Category:Digital]] | ||
__NOTOC__ | __NOTOC__ | ||
− | = Adobe Launch Extensions = | + | = Adobe Launch Extensions for Video = |
Adobe Launch Extensions are building blocks for mobile application development that reside on Adobe Servers for client utilization. | 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. | 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 | + | * [[#BDSK_Adobe_Launch_Extension|BDSK Adobe Launch Extension]] |
− | * IMA Adobe Launch Extension | + | * [[#IMA_Adobe_Launch_Extension|IMA Adobe Launch Extension]] |
− | * VJS Adobe Launch Extension | + | * [[#VJS_Adobe_Launch_Extension|VJS Adobe Launch Extension]] |
= Extension Installation and Configuration = | = 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 [https://developer.adobelaunch.com/guides/extensions/getting-started/#create-a-development-property Getting Started Guide]. | 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 [https://developer.adobelaunch.com/guides/extensions/getting-started/#create-a-development-property Getting Started Guide]. | ||
== Install the Extension== | == Install the Extension== | ||
− | + | When you sign in to the Launch you’ll see the Properties screen first. A property is a container for the tags that you want to deploy and it can be used on one or many sites. Click New Property and enter a name. You will now be able to add an extension. | |
[[File:Browser1.jpg|icon]] | [[File:Browser1.jpg|icon]] | ||
Line 22: | Line 21: | ||
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). | 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=== | ||
− | 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). | + | IMA extension subscribes to events fired by the IMA Ad 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”. | After the Extension is configured, it can be “built” under the “library” on the Publishing page with other “libraries”. | ||
Line 44: | Line 43: | ||
[[File:Browser6.jpg|icon]] | [[File:Browser6.jpg|icon]] | ||
+ | |||
==Multi-instance support== | ==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. | 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 == | == Prerequisites == | ||
Before you begin, ensure that you have an '''Appid.''' This is a Unique ID assigned to the player/site and configured by product. | 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 [[Digital_Measurement_Onboarding_Adobe| | + | If you do not have an AppID, please review the [[Digital_Measurement_Onboarding_Adobe|Onboarding Guide.]] |
= BDSK Adobe Launch Extension = | = 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 | + | 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 API's exposed by the extension or by using events. |
The following events and API calls are supported: | The following events and API calls are supported: | ||
Line 63: | Line 63: | ||
||"nls-sdk-trackevent"|| window.NSDKAPI.trackEvent|| sends data for trackEvent function of the SDK|| | ||"nls-sdk-trackevent"|| window.NSDKAPI.trackEvent|| sends data for trackEvent function of the SDK|| | ||
|} | |} | ||
− | + | [[File:Adobe-Browser-3.png|icon]] | |
==Event based API== | ==Event based API== | ||
The extension listens to the following custom events: | The extension listens to the following custom events: | ||
Line 82: | Line 82: | ||
||<code>callback</code> ||Function that is called by the extension to provide output data || Yes || Function || | ||<code>callback</code> ||Function that is called by the extension to provide output data || Yes || Function || | ||
|} | |} | ||
+ | ==== Examples ==== | ||
+ | <syntaxhighlight lang="Javascript"> | ||
+ | var ev = new CustomEvent("nls-sdk-get-info", {"detail": | ||
+ | { | ||
+ | callback: function (obj) { | ||
+ | var sdkInfo = obj.extinfo; | ||
+ | } | ||
+ | } | ||
+ | }); | ||
+ | document.dispatchEvent(ev); | ||
+ | </syntaxhighlight> | ||
=== "nls-sdk-init-instance" === | === "nls-sdk-init-instance" === | ||
Line 99: | Line 110: | ||
!Parameter!! Description !! Required !! Values !! Example !! | !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 ||<syntaxhighlight lang="Javascript">"sdk_instance_name": "myPlayer1"</syntaxhighlight>|| | + | ||sdk_instance_name||Name of the BSDK instance. It's used to bind <br> BSDK and other extensions. If it's not <br> provided, the extension generates the name. <br> It can be obtained in the callback function.|| No ||string ||<syntaxhighlight lang="Javascript">"sdk_instance_name": "myPlayer1"</syntaxhighlight>|| |
|- | |- | ||
− | ||debug||Debug flag. If set to "DEBUG", the extension prints debug messages to the browser console. || No ||string ||<syntaxhighlight lang="Javascript">"debug": "DEBUG"</syntaxhighlight>|| | + | ||debug||Debug flag. If set to "DEBUG", the extension prints <br> debug messages to the browser console. || No ||string ||<syntaxhighlight lang="Javascript">"debug": "DEBUG"</syntaxhighlight>|| |
|- | |- | ||
− | ||apid||APID that is used in Browser SDK|| Yes|| string|| <syntaxhighlight lang="Javascript">"apid": "PXXXXXXXX-XXXX-"</syntaxhighlight>|| | + | ||apid||APID that is used in Browser SDK|| Yes|| string|| <syntaxhighlight lang="Javascript">"apid": "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"</syntaxhighlight>|| |
|- | |- | ||
− | ||opt_params||Optional parameters that are passed to initialization function of Browser SDK || No ||object ||<syntaxhighlight lang="Javascript">"opt_params": | + | ||opt_params||Optional parameters that are passed to <br> initialization function of Browser SDK || No ||object ||<syntaxhighlight lang="Javascript">"opt_params": |
{ | { | ||
"apn": "myApn", | "apn": "myApn", | ||
Line 112: | Line 123: | ||
}</syntaxhighlight>|| | }</syntaxhighlight>|| | ||
|- | |- | ||
− | ||callback||Function that is called by the extension to provide output data|| No || function ||<syntaxhighlight lang="Javascript">"callback": function (ret) { | + | ||callback||Function that is called by the extension <br> to provide output data|| No || function ||<syntaxhighlight lang="Javascript">"callback": function (ret) { |
var name = ret.sdk_instance_name; | var name = ret.sdk_instance_name; | ||
}</syntaxhighlight>|| | }</syntaxhighlight>|| | ||
− | |||
− | |||
− | |||
− | |||
− | |||
|} | |} | ||
+ | ==== Example ==== | ||
+ | <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> | ||
+ | |||
=== "nls-sdk-trackevent" === | === "nls-sdk-trackevent" === | ||
Line 138: | Line 165: | ||
!Parameter!! Description !! Required !! Values !! Example !! | !Parameter!! Description !! Required !! Values !! Example !! | ||
|- | |- | ||
− | ||sdk_instance_name||Name of the BSDK instance that should receive the data. ||Yes|| string|| <syntaxhighlight lang="Javascript">"sdk_instance_name": "myPlayer1"</syntaxhighlight>|| | + | ||sdk_instance_name||Name of the BSDK instance that should<br> receive the data. ||Yes|| string|| <syntaxhighlight lang="Javascript">"sdk_instance_name": "myPlayer1"</syntaxhighlight>|| |
|- | |- | ||
− | ||obj||Object containing data that | + | ||obj||Object containing data that is passed <br> to trackEvent function of Browser SDK|| Yes ||string ||<syntaxhighlight lang="Javascript">"obj": { |
"event": 'playhead', | "event": 'playhead', | ||
"type": 'static', | "type": 'static', | ||
Line 151: | Line 178: | ||
}}</syntaxhighlight>|| | }}</syntaxhighlight>|| | ||
|- | |- | ||
− | ||callback||Function that is called by the extension to provide the result value. It's true if success.|| ||function ||<syntaxhighlight lang="Javascript">"callback": function (ret) { | + | ||callback||Function that is called by the extension <br> to provide the result value. It's true if success.|| ||function ||<syntaxhighlight lang="Javascript">"callback": function (ret) { |
var result = ret.result; | var result = ret.result; | ||
} | } | ||
</syntaxhighlight>|| | </syntaxhighlight>|| | ||
|} | |} | ||
− | + | ==== Example ==== | |
+ | <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,<br> Unix timestamp or id3 payload, OTT information to the SDK. | ||
+ | |- | ||
+ | |'''pause'''|| | ||
+ | This event should be used when | ||
+ | content playback is paused. <br> (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. |
− | = | ||
− | |||
− | |||
− | |||
− | <syntaxhighlight lang=" | + | 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> | </syntaxhighlight> | ||
− | |||
− | |||
− | |||
− | |||
− | + | |DTVR= | |
− | <syntaxhighlight lang=" | + | === 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> | </syntaxhighlight> | ||
− | + | }} | |
− | + | ||
− | + | = IMA Adobe Launch Extension = | |
− | + | IMA extension subscribes to ad related events fired by IMA plugin, processes data provided by the user and taken from IMA, and calls BSDK API (trackevent). | |
− | + | ||
− | + | Events that are used in IMA extension: | |
+ | <syntaxhighlight lang="Javascript"> | ||
+ | google.ima.AdEvent.Type.ALL_ADS_COMPLETED, | ||
+ | google.ima.AdEvent.Type.COMPLETE, | ||
+ | google.ima.AdEvent.Type.FIRST_QUARTILE, | ||
+ | google.ima.AdEvent.Type.MIDPOINT, | ||
+ | google.ima.AdEvent.Type.PAUSED, | ||
+ | google.ima.AdEvent.Type.STARTED, | ||
+ | google.ima.AdEvent.Type.THIRD_QUARTILE, | ||
+ | google.ima.AdEvent.Type.SKIPPED, | ||
+ | google.ima.AdEvent.Type.DURATION_CHANGE</syntaxhighlight> | ||
+ | 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: | |
− | + | {| class="wikitable" | |
− | + | !Event!! API Function !! Sender/Caller !! Description !! | |
− | + | |- | |
+ | ||<syntaxhighlight lang="Javascript">"nls-ima-get-info"</syntaxhighlight>|| window.NIMAAPI.getInfo. ||User|| requests IMA extension to provide the extension version information|| | ||
+ | |- | ||
+ | ||<syntaxhighlight lang="Javascript">"nls-ima-init-instance"</syntaxhighlight>|| window.NIMAAPI.initInstance. ||User|| requests IMA extension to initialize a new <br> IMA extension instance for the player|| | ||
+ | |- | ||
+ | ||<syntaxhighlight lang="Javascript">"nls-ima-get-data"</syntaxhighlight>|| ||Extension|| requests IMA extension to provide the extension version information|| | ||
+ | |- | ||
+ | ||<syntaxhighlight lang="Javascript">"nls-ima-set-data"</syntaxhighlight>|| ||User|| requests IMA extension to provide the extension version information|| | ||
+ | |- | ||
+ | ||<syntaxhighlight lang="Javascript">"nls-msg"</syntaxhighlight>|| ||Extension|| requests IMA extension to provide the extension version information|| | ||
+ | |- | ||
+ | |} | ||
− | |||
− | + | === "nls-ima-get-info" === | |
− | + | Format of input object is the following: | |
+ | <syntaxhighlight lang="Javascript"> | ||
+ | { detail: | ||
+ | { | ||
+ | callback: function(obj) { /* Do something */} | ||
+ | } | ||
+ | } | ||
+ | </syntaxhighlight> | ||
+ | All parameters and supported values are described below. | ||
+ | {| class="wikitable" | ||
+ | !Parameter!! Description !! Required !! Values !! Example | ||
+ | |- | ||
+ | ||<code>callback</code> ||Function that is called by the <br>extension to provide output data || Yes || Function ||<syntaxhighlight lang="Javascript"> "callback": function (ret) { | ||
+ | var name = ret.ima_instance_name; | ||
+ | }</syntaxhighlight> | ||
+ | |} | ||
− | + | === "nls-ima-init-instance" === | |
− | + | Format of input object is the following: | |
− | |||
− | |||
− | = | + | <syntaxhighlight lang="Javascript"> |
− | + | { detail: | |
+ | { | ||
+ | sdk_instance_name: <name>, | ||
+ | // other parameters, | ||
+ | callback: function(obj) { /* Do something */} | ||
+ | } | ||
+ | } | ||
+ | </syntaxhighlight> | ||
+ | All parameters and supported values are described below. | ||
{| class="wikitable" | {| class="wikitable" | ||
+ | !Parameter!! Description !! Required !! Values !! Example !! | ||
|- | |- | ||
− | + | ||<syntaxhighlight lang="Javascript">sdk_instance_name</syntaxhighlight>||Name of the BSDK instance that should<br> receive the data. ||Yes|| string|| <syntaxhighlight lang="Javascript">"sdk_instance_name": "myPlayer1"</syntaxhighlight>|| | |
|- | |- | ||
− | | | + | ||<syntaxhighlight lang="Javascript">debug</syntaxhighlight>||Debug flag. If set to "DEBUG", the extension prints <br> debug messages to the browser console.|| ||string ||<syntaxhighlight lang="Javascript">"debug": "DEBUG" |
+ | </syntaxhighlight>|| | ||
|- | |- | ||
− | | | + | ||<syntaxhighlight lang="Javascript">playerId</syntaxhighlight> || Id of the video element || Yes || string || <syntaxhighlight lang="Javascript">"playerId": "myPlayer1"</syntaxhighlight>|| |
|- | |- | ||
− | |nls- | + | ||<syntaxhighlight lang="Javascript">callback</syntaxhighlight>||Function that is called by the extension <br> to provide output data.|| ||function ||<syntaxhighlight lang="Javascript">"callback": function (ret) { |
+ | var result = ret.ima_instance_name; | ||
+ | } | ||
+ | </syntaxhighlight>|| | ||
+ | |} | ||
+ | |||
+ | === "nls-ima-set-data" === | ||
+ | Format of input object is the following: | ||
+ | <syntaxhighlight lang="Javascript"> | ||
+ | { detail: | ||
+ | { | ||
+ | playerId: <player element id>, | ||
+ | custom_fields: { /* data */ } | ||
+ | } | ||
+ | } | ||
+ | </syntaxhighlight> | ||
+ | All parameters and supported values are described below. | ||
+ | {| class="wikitable" | ||
+ | !Parameter!! Description !! Required !! Values !! Example | ||
+ | |- | ||
+ | ||<syntaxhighlight lang="Javascript">playerId</syntaxhighlight> || Id of the video element provided <br> in event "nls-ima-get-data" || Yes || string || <syntaxhighlight lang="Javascript">"playerId": "playerid"</syntaxhighlight>|| | ||
|- | |- | ||
− | | | + | ||<code>custom_fields</code> ||Custom fields like Custom fields like [[#Handling_JSON_Metadata|assetid]] || Yes || string ||<syntaxhighlight lang="Javascript"> "custom_fields": { |
+ | "assetid": 'myAssetId1' | ||
+ | }</syntaxhighlight> | ||
|} | |} | ||
− | |||
− | <syntaxhighlight lang=" | + | === "nls-ima-get-data" === |
− | + | Format of input object is the following: | |
− | + | <syntaxhighlight lang="Javascript"> | |
− | / | + | eventObject.detail.playerId |
− | + | </syntaxhighlight> | |
− | + | ||
− | + | ||
− | + | All parameters and supported values are described below. | |
− | / | + | {| class="wikitable" |
− | + | !Parameter!! Description !! Required !! Values !! Example | |
− | + | |- | |
− | var ev = new CustomEvent("nls- | + | ||<code>playerId</code> ||Id of the video element playing the video. <br>This id must be copied to the object that will be <br> provided in event "nls-ima-set-data" || Yes || string ||<syntaxhighlight lang="Javascript"> eventObject.detail.playerId</syntaxhighlight> |
+ | |} | ||
+ | |||
+ | === Examples === | ||
+ | '''How to get version information of IMA extension''' | ||
+ | |||
+ | <syntaxhighlight lang="Javascript"> | ||
+ | var ev = new CustomEvent("nls-ima-get-info", {"detail": | ||
+ | { | ||
+ | callback: function (obj) { | ||
+ | var imaInfo = obj.extinfo; | ||
+ | } | ||
+ | } | ||
+ | }); | ||
document.dispatchEvent(ev); | document.dispatchEvent(ev); | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | |||
+ | '''How to create an instance of IMA extension''' | ||
+ | |||
+ | <syntaxhighlight lang="Javascript"> | ||
+ | var ev = new CustomEvent("nls-ima-init-instance", {"detail": | ||
+ | { | ||
+ | "sdk_instance_name": "myPlayer1", | ||
+ | "debug": "DEBUG", | ||
+ | "playerId": "myPlayer1", | ||
+ | "callback": function (ret) { | ||
+ | console.log("IMA is ready"); | ||
+ | } | ||
+ | } | ||
}); | }); | ||
− | // | + | document.dispatchEvent(ev); |
− | // | + | </syntaxhighlight> |
− | var ev = new CustomEvent("nls- | + | |
− | { | + | |
− | + | '''How to provide custom fields''' | |
+ | |||
+ | <syntaxhighlight lang="Javascript"> | ||
+ | function fnCustomDataAdRequest(detail) { | ||
+ | var adId = detail.id; | ||
+ | // id - is an identifier of the ad that is currently playing. | ||
+ | var custom_fields = {}; | ||
+ | // search for the info of the ad (currently playing ad) | ||
+ | custom_fields.assetid = "myAssetId"; | ||
+ | return custom_fields; | ||
+ | } | ||
+ | document.addEventListener("nls-ima-get-data", function (event) { | ||
+ | var customData = null; | ||
+ | if (event) { | ||
+ | var detail = event.detail; | ||
+ | var plId = detail.playerId; | ||
+ | // We must provide playerId as the event originator | ||
+ | // Instead, we can copy the whole detail object back to the extension | ||
+ | customData = fnCustomDataAdRequest(detail); | ||
+ | } | ||
+ | if (customData) { | ||
+ | var ev = new CustomEvent("nls-ima-set-data", { | ||
+ | "detail": | ||
+ | { | ||
+ | playerId: plId, | ||
+ | custom_fields: customData | ||
+ | } | ||
+ | }); | ||
+ | document.dispatchEvent(ev); | ||
+ | } | ||
+ | }); | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | = VJS Adobe Launch Extension = | ||
+ | VideoJS (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). | ||
+ | |||
+ | Standard media events that are used in VJS extension: | ||
+ | <syntaxhighlight lang="Javascript"> | ||
+ | loadstart | ||
+ | timeupdate | ||
+ | ended | ||
+ | loadeddata | ||
+ | play | ||
+ | playing | ||
+ | stop | ||
+ | durationchange | ||
+ | </syntaxhighlight> | ||
+ | The extension handles id3 tag related events as well. | ||
+ | |||
+ | 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: | ||
+ | {| class="wikitable" | ||
+ | !Event!! API Function !! Sender/Caller !! Description !! | ||
+ | |- | ||
+ | ||<syntaxhighlight lang="Javascript">"nls-vjs-get-info"</syntaxhighlight>|| window.NVJSAPI.getInfo ||User|| requests JVS extension to provide the <br> extension version information|| | ||
+ | |- | ||
+ | ||<syntaxhighlight lang="Javascript">"nls-vjs-init-instance"</syntaxhighlight>|| window.NVJSAPI.initInstance ||User|| requests JVS extension to initialize a new <br> IMA extension instance for the player|| | ||
+ | |- | ||
+ | ||<syntaxhighlight lang="Javascript">"nls-vjs-get-data"</syntaxhighlight>|| ||Extension|| requests the user to provide custom data for the video|| | ||
+ | |- | ||
+ | ||<syntaxhighlight lang="Javascript">"nls-vjs-set-data"</syntaxhighlight>|| ||User||provides custom data to the extension|| | ||
+ | |- | ||
+ | ||<syntaxhighlight lang="Javascript">"nls-msg"</syntaxhighlight>|| ||Extension|| sends error or any other message|| | ||
+ | |- | ||
+ | |} | ||
− | + | === "nls-vjs-get-info" === | |
− | " | + | Format of input object is the following: |
− | " | + | <syntaxhighlight lang="Javascript"> |
− | + | { detail: | |
− | { | + | { |
− | + | callback: function(obj) { /* Do something */} | |
− | + | } | |
− | |||
} | } | ||
− | + | </syntaxhighlight> | |
− | callback: function (ret) { | + | |
− | var | + | |
− | + | All parameters and supported values are described below. | |
− | { | + | {| class="wikitable" |
− | + | !Parameter!! Description !! Required !! Values !! Example | |
− | + | |- | |
− | + | ||<code>callback</code> ||Function that is called by the <br>extension to provide output data || Yes || Function ||<syntaxhighlight lang="Javascript"> "callback": function (ret) { | |
− | + | var name = ret.vjs_instance_name; | |
− | // | + | }</syntaxhighlight> |
+ | |} | ||
+ | |||
+ | === "nls-vjs-init-instance" === | ||
+ | Format of input object is the following: | ||
+ | |||
+ | <syntaxhighlight lang="Javascript"> | ||
+ | { detail: | ||
+ | { | ||
+ | sdk_instance_name: <name>, | ||
+ | // other parameters, | ||
+ | callback: function(obj) { /* Do something */} | ||
+ | } | ||
} | } | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | All parameters and supported values are described below. | ||
+ | |||
+ | |||
+ | {| class="wikitable" | ||
+ | !Parameter!! Description !! Required !! Values !! Example !! | ||
+ | |- | ||
+ | ||<syntaxhighlight lang="Javascript">sdk_instance_name</syntaxhighlight>||Name of the BSDK instance that should<br> receive the data. ||Yes|| string|| <syntaxhighlight lang="Javascript">"sdk_instance_name": "myPlayer1"</syntaxhighlight>|| | ||
+ | |- | ||
+ | ||<syntaxhighlight lang="Javascript">debug</syntaxhighlight>||Debug flag. If set to "DEBUG", the extension prints <br> debug messages to the browser console.|| ||string ||<syntaxhighlight lang="Javascript">"debug": "DEBUG" | ||
+ | }}</syntaxhighlight>|| | ||
+ | |- | ||
+ | ||<syntaxhighlight lang="Javascript">playerId</syntaxhighlight> || Id of the video element || Yes || string || <syntaxhighlight lang="Javascript">"playerId": "myPlayer1"</syntaxhighlight>|| | ||
+ | |- | ||
+ | ||<syntaxhighlight lang="Javascript">callback</syntaxhighlight>||Function that is called by the extension <br> to provide output data.|| ||function ||<syntaxhighlight lang="Javascript">"callback": function (ret) { | ||
+ | var result = ret.vjs_instance_name; | ||
} | } | ||
+ | </syntaxhighlight>|| | ||
+ | |} | ||
+ | |||
+ | === "nls-vjs-set-data" === | ||
+ | Format of input object is the following: | ||
+ | <syntaxhighlight lang="Javascript"> | ||
+ | { detail: | ||
+ | { | ||
+ | playerId: <player element id>, | ||
+ | custom_fields: { /* data */ } | ||
+ | } | ||
+ | } | ||
+ | </syntaxhighlight> | ||
+ | All parameters and supported values are described below. | ||
+ | |||
+ | |||
+ | {| class="wikitable" | ||
+ | !Parameter!! Description !! Required !! Values !! Example | ||
+ | |- | ||
+ | ||<syntaxhighlight lang="Javascript">playerId</syntaxhighlight> || Id of the video element provided <br> in event "nls-vjs-get-data" || Yes || string || <syntaxhighlight lang="Javascript">"playerId": "playerid"</syntaxhighlight>|| | ||
+ | |- | ||
+ | ||<code>custom_fields</code> ||Custom fields like [[#Handling_JSON_Metadata|assetid]] || Yes || string ||<syntaxhighlight lang="Javascript"> "custom_fields": { | ||
+ | "assetid": 'myAssetId1', | ||
+ | "segA": 'NNh777' | ||
+ | }</syntaxhighlight> | ||
+ | |} | ||
+ | |||
+ | === "nls-vjs-get-data" === | ||
+ | Format of input object is the following: | ||
+ | <syntaxhighlight lang="Javascript"> | ||
+ | eventObject.detail.playerId | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | |||
+ | All parameters and supported values are described below. | ||
+ | {| class="wikitable" | ||
+ | !Parameter!! Description !! Required !! Values !! Example | ||
+ | |- | ||
+ | ||<code>playerId</code> ||Id of the video element playing the video. <br>This id must be copied to the object that will be <br> provided in event "nls-vjs-set-data" || Yes || string ||<syntaxhighlight lang="Javascript"> eventObject.detail.playerId</syntaxhighlight> | ||
+ | |} | ||
+ | === Examples === | ||
+ | '''How to get version information of VJS extension''' | ||
+ | |||
+ | <syntaxhighlight lang="Javascript"> | ||
+ | var ev = new CustomEvent("nls-vjs-get-info", {"detail": | ||
+ | { | ||
+ | callback: function (obj) { | ||
+ | var vjsInfo = obj.extinfo; | ||
+ | } | ||
+ | } | ||
+ | }); | ||
+ | document.dispatchEvent(ev); | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | |||
+ | '''How to create an instance of VJS extension''' | ||
+ | |||
+ | <syntaxhighlight lang="Javascript"> | ||
+ | var ev = new CustomEvent("nls-vjs-init-instance", {"detail": | ||
+ | { | ||
+ | "sdk_instance_name": "myPlayer1", | ||
+ | "debug": "DEBUG", | ||
+ | "playerId": "myPlayer1", | ||
+ | "callback": function (ret) { | ||
+ | console.log("VJS is ready"); | ||
+ | // Init Player here... | ||
+ | } | ||
+ | } | ||
}); | }); | ||
− | |||
document.dispatchEvent(ev); | document.dispatchEvent(ev); | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | |||
+ | '''How to provide custom fields''' | ||
+ | |||
+ | <syntaxhighlight lang="Javascript"> | ||
+ | function fnCustomDataContentRequest(detail) { | ||
+ | var currentSrc = detail.currentSrc; | ||
+ | // currentSrc - is the path to the stream that is currently playing | ||
+ | var custom_fields = {}; | ||
+ | // search for the info of the currentSrc (currently playing stream) | ||
+ | custom_fields.assetid = "myAssetId"; | ||
+ | return custom_fields; | ||
} | } | ||
+ | document.addEventListener("nls-vjs-get-data", function (event) { | ||
+ | var customData = null; | ||
+ | if (event) { | ||
+ | var detail = event.detail; | ||
+ | var plId = detail.playerId; | ||
+ | // We must provide playerId as the event originator | ||
+ | // Instead, we can copy the whole detail object back to the extension | ||
+ | customData = fnCustomDataContentRequest(detail); | ||
+ | } | ||
+ | if (customData) { | ||
+ | var ev = new CustomEvent("nls-vjs-set-data", { | ||
+ | "detail": | ||
+ | { | ||
+ | playerId: plId, | ||
+ | custom_fields: customData | ||
+ | } | ||
+ | }); | ||
+ | document.dispatchEvent(ev); | ||
+ | } | ||
+ | }); | ||
+ | </syntaxhighlight> | ||
+ | |||
+ | = 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: | ||
− | } | + | <syntaxhighlight lang="javascript"> |
+ | <script src="//assets.adobedtm.com/launch-XXXXXX-development.min.js"></script> | ||
+ | </syntaxhighlight> | ||
+ | === Initialize Instance === | ||
+ | Inside <body> tag: | ||
+ | <syntaxhighlight lang="javascript"> | ||
+ | // 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": | ||
+ | { | ||
+ | "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"); | console.log("USER: Sending nls-sdk-init-instance"); | ||
document.dispatchEvent(ev); | document.dispatchEvent(ev); | ||
− | + | ||
− | // Add the following before </body | + | // Add the following before </body |
− | |||
<script>_satellite.pageBottom();</script> | <script>_satellite.pageBottom();</script> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | |||
− |
Latest revision as of 20:47, 21 February 2019
Engineering Portal Digital DCR & DTVR DCR & DTVR Browser Adobe Launch Extension
Adobe Launch Extensions for Video
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.
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
When you sign in to the Launch you’ll see the Properties screen first. A property is a container for the tags that you want to deploy and it can be used on one or many sites. Click New Property and enter a name. You will now be able to add an extension.
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 Ad 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 API's 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 |
Examples
var ev = new CustomEvent("nls-sdk-get-info", {"detail":
{
callback: function (obj) {
var sdkInfo = obj.extinfo;
}
}
});
document.dispatchEvent(ev);
"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-XXXX-XXXX-XXXXXXXXXXXX"
|
|
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;
}
|
Example
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);
"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;
}
|
Example
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, |
pause |
This event should be used when
content playback is paused. |
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 |
|
"event":"playhead"
|
type | Determines the metadata object
that should be used for crediting. |
|
"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):
Position value is playhead:
|
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 |
|
"event":"playhead"
|
type | Determines the metadata object that should be used for crediting. |
|
"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:
Position value is playhead:
|
id3Data | Nielsen ID3 payload | String
|
|
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 |
|
"event":"playhead"
|
type | Determines the metadata object that should be used for crediting. |
|
"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:
Position value is playhead:
|
id3Data | Nielsen ID3 payload | Object
|
|
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
IMA extension subscribes to ad related events fired by IMA plugin, processes data provided by the user and taken from IMA, and calls BSDK API (trackevent).
Events that are used in IMA extension:
google.ima.AdEvent.Type.ALL_ADS_COMPLETED,
google.ima.AdEvent.Type.COMPLETE,
google.ima.AdEvent.Type.FIRST_QUARTILE,
google.ima.AdEvent.Type.MIDPOINT,
google.ima.AdEvent.Type.PAUSED,
google.ima.AdEvent.Type.STARTED,
google.ima.AdEvent.Type.THIRD_QUARTILE,
google.ima.AdEvent.Type.SKIPPED,
google.ima.AdEvent.Type.DURATION_CHANGE
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 | Sender/Caller | Description | |
---|---|---|---|---|
"nls-ima-get-info"
|
window.NIMAAPI.getInfo. | User | requests IMA extension to provide the extension version information | |
"nls-ima-init-instance"
|
window.NIMAAPI.initInstance. | User | requests IMA extension to initialize a new IMA extension instance for the player |
|
"nls-ima-get-data"
|
Extension | requests IMA extension to provide the extension version information | ||
"nls-ima-set-data"
|
User | requests IMA extension to provide the extension version information | ||
"nls-msg"
|
Extension | requests IMA extension to provide the extension version information |
"nls-ima-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 | Example |
---|---|---|---|---|
callback |
Function that is called by the extension to provide output data |
Yes | Function | "callback": function (ret) {
var name = ret.ima_instance_name;
}
|
"nls-ima-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 that should receive the data. |
Yes | string | "sdk_instance_name": "myPlayer1"
|
|
debug
|
Debug flag. If set to "DEBUG", the extension prints debug messages to the browser console. |
string | "debug": "DEBUG"
|
||
playerId
|
Id of the video element | Yes | string | "playerId": "myPlayer1"
|
|
callback
|
Function that is called by the extension to provide output data. |
function | "callback": function (ret) {
var result = ret.ima_instance_name;
}
|
"nls-ima-set-data"
Format of input object is the following:
{ detail:
{
playerId: <player element id>,
custom_fields: { /* data */ }
}
}
All parameters and supported values are described below.
Parameter | Description | Required | Values | Example | |
---|---|---|---|---|---|
playerId
|
Id of the video element provided in event "nls-ima-get-data" |
Yes | string | "playerId": "playerid"
|
|
custom_fields |
Custom fields like Custom fields like assetid | Yes | string | "custom_fields": {
"assetid": 'myAssetId1'
}
|
"nls-ima-get-data"
Format of input object is the following:
eventObject.detail.playerId
All parameters and supported values are described below.
Parameter | Description | Required | Values | Example |
---|---|---|---|---|
playerId |
Id of the video element playing the video. This id must be copied to the object that will be provided in event "nls-ima-set-data" |
Yes | string | eventObject.detail.playerId
|
Examples
How to get version information of IMA extension
var ev = new CustomEvent("nls-ima-get-info", {"detail":
{
callback: function (obj) {
var imaInfo = obj.extinfo;
}
}
});
document.dispatchEvent(ev);
How to create an instance of IMA extension
var ev = new CustomEvent("nls-ima-init-instance", {"detail":
{
"sdk_instance_name": "myPlayer1",
"debug": "DEBUG",
"playerId": "myPlayer1",
"callback": function (ret) {
console.log("IMA is ready");
}
}
});
document.dispatchEvent(ev);
How to provide custom fields
function fnCustomDataAdRequest(detail) {
var adId = detail.id;
// id - is an identifier of the ad that is currently playing.
var custom_fields = {};
// search for the info of the ad (currently playing ad)
custom_fields.assetid = "myAssetId";
return custom_fields;
}
document.addEventListener("nls-ima-get-data", function (event) {
var customData = null;
if (event) {
var detail = event.detail;
var plId = detail.playerId;
// We must provide playerId as the event originator
// Instead, we can copy the whole detail object back to the extension
customData = fnCustomDataAdRequest(detail);
}
if (customData) {
var ev = new CustomEvent("nls-ima-set-data", {
"detail":
{
playerId: plId,
custom_fields: customData
}
});
document.dispatchEvent(ev);
}
});
VJS Adobe Launch Extension
VideoJS (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).
Standard media events that are used in VJS extension:
loadstart
timeupdate
ended
loadeddata
play
playing
stop
durationchange
The extension handles id3 tag related events as well.
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 | Sender/Caller | Description | |
---|---|---|---|---|
"nls-vjs-get-info"
|
window.NVJSAPI.getInfo | User | requests JVS extension to provide the extension version information |
|
"nls-vjs-init-instance"
|
window.NVJSAPI.initInstance | User | requests JVS extension to initialize a new IMA extension instance for the player |
|
"nls-vjs-get-data"
|
Extension | requests the user to provide custom data for the video | ||
"nls-vjs-set-data"
|
User | provides custom data to the extension | ||
"nls-msg"
|
Extension | sends error or any other message |
"nls-vjs-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 | Example |
---|---|---|---|---|
callback |
Function that is called by the extension to provide output data |
Yes | Function | "callback": function (ret) {
var name = ret.vjs_instance_name;
}
|
"nls-vjs-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 that should receive the data. |
Yes | string | "sdk_instance_name": "myPlayer1"
|
|
debug
|
Debug flag. If set to "DEBUG", the extension prints debug messages to the browser console. |
string | "debug": "DEBUG"
}}
|
||
playerId
|
Id of the video element | Yes | string | "playerId": "myPlayer1"
|
|
callback
|
Function that is called by the extension to provide output data. |
function | "callback": function (ret) {
var result = ret.vjs_instance_name;
}
|
"nls-vjs-set-data"
Format of input object is the following:
{ detail:
{
playerId: <player element id>,
custom_fields: { /* data */ }
}
}
All parameters and supported values are described below.
Parameter | Description | Required | Values | Example | |
---|---|---|---|---|---|
playerId
|
Id of the video element provided in event "nls-vjs-get-data" |
Yes | string | "playerId": "playerid"
|
|
custom_fields |
Custom fields like assetid | Yes | string | "custom_fields": {
"assetid": 'myAssetId1',
"segA": 'NNh777'
}
|
"nls-vjs-get-data"
Format of input object is the following:
eventObject.detail.playerId
All parameters and supported values are described below.
Parameter | Description | Required | Values | Example |
---|---|---|---|---|
playerId |
Id of the video element playing the video. This id must be copied to the object that will be provided in event "nls-vjs-set-data" |
Yes | string | eventObject.detail.playerId
|
Examples
How to get version information of VJS extension
var ev = new CustomEvent("nls-vjs-get-info", {"detail":
{
callback: function (obj) {
var vjsInfo = obj.extinfo;
}
}
});
document.dispatchEvent(ev);
How to create an instance of VJS extension
var ev = new CustomEvent("nls-vjs-init-instance", {"detail":
{
"sdk_instance_name": "myPlayer1",
"debug": "DEBUG",
"playerId": "myPlayer1",
"callback": function (ret) {
console.log("VJS is ready");
// Init Player here...
}
}
});
document.dispatchEvent(ev);
How to provide custom fields
function fnCustomDataContentRequest(detail) {
var currentSrc = detail.currentSrc;
// currentSrc - is the path to the stream that is currently playing
var custom_fields = {};
// search for the info of the currentSrc (currently playing stream)
custom_fields.assetid = "myAssetId";
return custom_fields;
}
document.addEventListener("nls-vjs-get-data", function (event) {
var customData = null;
if (event) {
var detail = event.detail;
var plId = detail.playerId;
// We must provide playerId as the event originator
// Instead, we can copy the whole detail object back to the extension
customData = fnCustomDataContentRequest(detail);
}
if (customData) {
var ev = new CustomEvent("nls-vjs-set-data", {
"detail":
{
playerId: plId,
custom_fields: customData
}
});
document.dispatchEvent(ev);
}
});
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
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":
{
"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>