Difference between revisions of "Digital Measurement Browser Simplified API"

From Engineering Client Portal

(Replaced content with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}} Category:Digital == Overview == The Nielsen SDK is one of multiple framework SD...")
(Tag: Replaced)
Line 6: Line 6:
 
*Application launch events and how long app was running
 
*Application launch events and how long app was running
 
*Time of viewing a sub section / page in the application.
 
*Time of viewing a sub section / page in the application.
== Prerequisites ==
 
To start using the Simplified API for Browser, you will need an '''Appid.'''  This is a Unique ID assigned to the player/site and configured by product.
 
If you do not have an AppID , please contact our SDK sales support team.
 
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.
 
  
== Simplified API ==
+
Please select [[DCR_Video_Browser_SDK|The Browser Implementation Guide]] for more detailed information on implementation.
As part of making the SDK more user friendly and reduce the number of app integration touch points, Nielsen has designed a simple interface to pass metadata to the sdk while reducing the number of API calls.  The new <code> trackevent() </code> API has been implemented as a wrapper for the existing SDK and will be responsible for handling new API calls, performing validation, and translation of new API calls to the existing Nielsen App SDK API methods.  Applications which are already integrated with the existing SDK API, are unaffected by this new API.
 
[[File:SimplifiedAPI_vs_StandardAPI_New.jpg|2048px|link=http://engineeringportal.nielsen.com/w/images/9/91/SimplifiedAPI_vs_StandardAPI_New.jpg]]
 
[http://engineeringportal.nielsen.com/w/images/9/91/SimplifiedAPI_vs_StandardAPI_New.jpg Click here to zoom in on image]
 
 
 
== Manages the order of metadata (ad vs content and playheads) ==
 
Existing API has a number of methods used for reporting player and application state changes to the SDK. Order of calls is important for the SDK in the existing API. In the new enhanced API all these calls will be replaced with one API call that will get one dictionary object with many key-value pairs, where any value could be another complex dictionary object. All the data provided in the existing API in separate calls will be provided in one single call. SDK will analyse the data received in the dictionary object, compare it with the data received previously and generate a sequence of calls for the existing API.
 
== Everything passed via trackevent() ==
 
The New API method supports the following event types:
 
{| 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 passed when the
 
content playback is paused. 
 
|-
 
|'''complete'''||
 
It is called when session is completed or ends.
 
|-
 
|'''adStop'''||
 
Should be called at the end of each ad. This event type is required to handle the case when advertisements could not be distinguished, as its assetId is the same.
 
|}
 
 
 
__TOC__
 
 
 
== Prerequisites ==
 
To get started, an App ID is needed. The App ID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration.
 
<syntaxhighlight lang="javascript">'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'</syntaxhighlight>
 
 
 
== Configure SDK ==
 
There are two steps required for configuring the SDK:
 
* Add Static Queue Snippet
 
* Create SDK Instance
 
=== Add Static Queue Snippet ===
 
Add the following script tag to the website:
 
<syntaxhighlight lang="javascript">
 
<script type = "text/javascript" >
 
  /***************** Static Queue Snippet *********************/
 
  ! function(t, n) {
 
    t[n] = t[n] || {
 
      nlsQ: function(e, c, o, r, s, i) {
 
        return s = t.document,
 
          r = s.createElement("script"),
 
          r.async = 1,
 
          r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + c + "&ns=" + n, i = s.getElementsByTagName("script")[0], i.parentNode.insertBefore(r, i),
 
          t[n][c] = t[n][c] || {
 
            g: o || {},
 
            ggPM: function(e, o, r, s, i) {
 
              (t[n][c].q = t[n][c].q || []).push([e, o, r, s, i])
 
            },
 
            trackEvent: function(e) {
 
              (t[n][c].te = t[n][c].te || []).push(e)
 
            }
 
          }, t[n][c]
 
      }
 
    }
 
  }(window, "NOLBUNDLE");
 
</script>
 
</syntaxhighlight>
 
 
 
The static queue snippet allows the SDK APIs to be called while the actual SDK and configuration file are still being downloaded. As the queue can capture all API calls before the download completes, there is no wait time. Once the SDK is available, the API calls will transition from directing to the queue to the SDK seamlessly.
 
 
 
===Create SDK Instance===
 
To initialize the SDK, create an SDK instance by making the initialization call:
 
 
 
==== Initialization API Call ====
 
<syntaxhighlight lang="javascript">
 
NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug", optout: "false"})
 
</syntaxhighlight>
 
<br>
 
When creating an instance, pass the following values: (<code>nol_sdkDebug</code> and <code>optout</code> are optional)
 
{| class="wikitable"
 
|-
 
! Parameter !! Description !! Values
 
|-
 
| apid || Unique ID assigned to player/site || 'PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
 
|-
 
|instanceName || Name of SDK instance || "any string value"
 
|-
 
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing || "{nol_sdkDebug: "debug"})"
 
|-
 
|optout || OptOut global parameter (Optional Parameter) || <code>1/0</code> or <code>true/false</code>
 
|}
 
 
 
==== Example SDK Initialization ====
 
When the initialization call is made, a unique static configuration file, <apid>.js, will be downloaded based on the apid and will be cached on the user’s browser.
 
 
 
Once the configuration is downloaded, the SDK itself will be downloaded and initialized. All SDK modules are included in one file: “nlsSDK600.bundle.min.js”.
 
 
 
More information on OptOut Parameter under [[DCR Video Browser Bundled SDK#Privacy_and_Opt-Out|Privacy and Opt-Out.]]
 
 
 
=== Example SDK Configuration ===
 
 
 
The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:
 
<syntaxhighlight lang="javascript">
 
<script type = "text/javascript" >
 
  /***************** Static Queue Snippet *********************/
 
  ! function(t, n) {
 
    t[n] = t[n] || {
 
      nlsQ: function(e, c, o, r, s, i) {
 
        return s = t.document,
 
          r = s.createElement("script"),
 
          r.async = 1,
 
          r.src = ("http:" === t.location.protocol ? "http:" : "https:") + "//cdn-gl.imrworldwide.com/conf/" + e + ".js#name=" + c + "&ns=" + n, i = s.getElementsByTagName("script")[0], i.parentNode.insertBefore(r, i),
 
          t[n][c] = t[n][c] || {
 
            g: o || {},
 
            ggPM: function(e, o, r, s, i) {
 
              (t[n][c].q = t[n][c].q || []).push([e, o, r, s, i])
 
            },
 
            trackEvent: function(e) {
 
              (t[n][c].te = t[n][c].te || []).push(e)
 
            }
 
          }, t[n][c]
 
      }
 
    }
 
  }(window, "NOLBUNDLE");
 
 
 
  // Created SDK Instance
 
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {
 
  nol_sdkDebug: "debug",
 
  optout: "false"
 
});
 
</script></syntaxhighlight>
 
 
 
== Simplified API Syntax ==
 
The existing API has a number of methods used for reporting player and application state changes to the SDK. The order of calls is important for the SDK in the existing API. In the new simplified API, all these calls will be replaced with one API call that will get one dictionary object with many key-value pairs, where any value could be another complex dictionary object. All the data provided in the older API in separate calls will be provided in one single call.
 
 
Main API call for the new NielsenEventTracker API:
 
<br/>
 
<syntaxhighlight lang="java"> nSdkInstance.trackEvent({metadata})
 
</syntaxhighlight>
 
 
 
=== 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 (seconds since Jan-1-1970 UTC) >,
 
"id3Data": <id3 payload>,
 
}
 
</syntaxhighlight>
 
<br>
 
=== Event Types ===
 
The New API method supports the following event types:
 
{| 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 when
 
content playback is paused. <br > (Pause is detected by SDK automatically when the time gap between commands is more than 30 minutes.)
 
|-
 
|'''complete'''||
 
It is called when session is completed or ends.
 
|-
 
|'''adStop'''||
 
Should be called at the end of each ad. This event type is required to handle the case when advertisements could not be distinguished, as its assetId is the same.
 
|}
 
<br>
 
DCR and DTVR require various levels of data.  Please select the TAB of the product you are interested in reviewing.
 
{{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 in seconds or Unix timestamp
 
</td>
 
<td> <code>String</code>
 
</td>
 
<td>
 
<p>Position value is Unix timestamp:
 
<code>
 
"playheadPosition":"1543437655"</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> '''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) </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> '''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> '''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> Gracenote ID or Enterprise ID </td>
 
<td> custom </td>
 
<td> Yes
 
</td></tr>
 
<tr>
 
<td> '''crossId2 '''</td>
 
<td> content originator or network (only required for distributors) </td>
 
<td> custom </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>
 
++ 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":{
 
    "assetid":"B66473",
 
    "length":"3600",
 
    "program":"MyProgram",
 
    "title":"S2,E3",
 
    "type":"content",
 
    "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 in seconds or Unix timestamp
 
</td>
 
<td> <code>String</code>
 
</td>
 
<td>
 
<p>Position value is Unix timestamp:
 
<code>
 
"playheadPosition":"1543437655"</code>
 
</p><p>Position value is playhead:
 
<code>
 
"playheadPosition":"10"</code>
 
</p>
 
</td></tr>
 
<tr>
 
<td> <b>id3Data</b>
 
</td>
 
<td> Nielsen ID3 payload string
 
</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>
 
<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 in seconds or Unix timestamp
 
</td>
 
<td> <code>String</code>
 
</td>
 
<td>
 
<p>Position value is Unix timestamp:
 
<code>
 
"playheadPosition":"1543437655"</code>
 
</p><p>Position value is playhead:
 
<code>
 
"playheadPosition":"10"</code>
 
</p>
 
</td></tr>
 
<tr>
 
<td> <b>id3Data</b>
 
</td>
 
<td> Nielsen ID3 payload string
 
</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,
 
ottDeviceName:Google ChromeCast,
 
ottDeviceID:1234,
 
ottDeviceModel:ChromeCast,
 
ottDeviceVersion:1.0.0
 
}
 
</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> '''assetid''' </td>
 
<td> unique asset ID for DCR; can be set to "0" for DTVR </td>
 
<td> <code>EP732481</code> </td>
 
<td> Yes
 
</td></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>
 
++ 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",
 
    "assetid":"0",
 
    "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>
 
}}
 
 
 
=== Ad Metadata ===
 
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
 
<br/>
 
{| class="wikitable"
 
|-
 
! Keys !! Description !! Values !! Example
 
|-
 
| assetid || unique ID assigned to ad || custom <br>(no [[Special Characters]]) || <code>'AD1234'</code>
 
|-
 
| title || unique name assigned to ad || custom ||<code>'ADtitle'</code>
 
|-
 
|adldx || Ad Index (*See Note below*) || custom || <code> "66478364" </code>
 
|-
 
| type || type of ad || 'preroll', 'midroll', or 'postroll' || <code>'preroll'</code>
 
|-
 
|length || length of ad || In Seconds ||<code> '20' </code>
 
|}
 
=== Ad Metadata Sample ===
 
<syntaxhighlight lang="json">
 
{
 
  "ad": {
 
    "assetid":"AD12345",
 
    "title":"ADTestTitle",
 
    "adldx":"1",
 
    "type":"preroll",
 
    "length":"20"
 
  },
 
}
 
</syntaxhighlight>
 
=== Managing Ads ===
 
If there is an Ad block within the playing content (such as a midroll) you need to:
 
* Reset the playhead position to 0 for each ad.
 
* Call the '''adStop''' event at the end of each ad or increment the adldx
 
 
 
The Simplified API will can automatically detect the change from ad to content, or even ad to ad if the assetID changes; however, there could be situations where the same ad is played back to back.  You can either increment/change the '''adldx value''', and/or call adStop at the end of each Ad.
 
 
 
Sometimes it is not possible for integrators to provide different assetId value for individual ads in a sequence of ads. Taking this into account the Nielsen Simplified API will support a new parameter for ad metadata: '''adIdx.''' This parameter is just an index of an individual ad in a sequence of ads. Once the next ad is started the '''adIdx''' parameter should be changed and provided as part of ad metadata.
 
 
 
<syntaxhighlight lang="swift">
 
            // Example of passing both values
 
            self.data.updateValue("adStop", forKey: "event")
 
            self.data.updateValue("223", forKey: "adldx")
 
            self.nielsenEventTracker.trackEvent(data)
 
</syntaxhighlight>
 
=== Static Metadata ===
 
The values passed through the Nielsen keys will determine the breakouts that are seen in reporting. The custom segments (A, B & C) will roll into the sub-brand. To not use custom segments A, B and C, do not pass any value in these keys.
 
<br/>
 
{| class="wikitable"
 
|-
 
! Key !! Description !! Data Type !! Value !! Required?
 
|-
 
| assetid || Unique ID for each article || dynamic || custom <br>(no [[Special Characters]]) || Yes
 
|-
 
| section || Section of each site which is limited to 25 unique values<br> (e.g. section value should be first level in page URL: website.com/section).  || dynamic || custom || Yes
 
|-
 
| segA || custom segment for reporting: Limit to 25 unique values across custom segments<br> (segA + segB + segC) || dynamic || custom || No
 
|-
 
| segB || custom segment for reporting: Limit to 25 unique values across custom segments<br> (segA + segB + segC) || dynamic || custom || No
 
|-
 
| segC || custom segment for reporting: Limit to 25 unique values across custom segments<br> (segA + segB + segC) || dynamic || custom || No
 
|}
 
 
 
'''Aggregation Limits'''
 
There are limits on the number of unique values that can be aggregated on in reporting. The specific limitations by key are:
 
{| class="wikitable"
 
|-
 
! Key !! Aggregation Limit
 
|-
 
| section || maximum of 25 unique values (section <= 25)
 
|-
 
| segA || Maximum number of unique values allowed across segA, segB, and segC is 25 (segA + segB + segC<= 25)
 
|-
 
| segB || Maximum number of unique values allowed across segA, segB, and segC is 25 (segA + segB + segC<= 25)
 
|-
 
| segC || Maximum number of unique values allowed across segA, segB, and segC is 25 (segA + segB + segC<= 25)
 
|}
 
 
 
=== Static Metadata Sample ===
 
<syntaxhighlight lang="json">
 
// Sample input Object for static metadata
 
// Since only recording static data, playheadposition = ""
 
{
 
  "metadata": {
 
      "content": {},
 
      "ad": {},
 
      "static": {
 
        "type":"static",
 
        "assetid":"Static1",
 
        "section":"Page",
 
        "segA":"S07E04:NBC",
 
        "segB":"teams",
 
        "segC":"Atlanta",
 
        "crossId1":"Reference"
 
      }
 
  },
 
  "event": "playhead",
 
  "type": "static",
 
  "playheadPosition": "",
 
}
 
</syntaxhighlight>
 
=== Json Examples ===
 
[https://engineeringportal.nielsen.com/docs/Digital_Measurement_Simplified_API_Supplements Addtional JSON input object examples.]
 
{{Template:Browser_Privacy_and_Opt-Out}}
 
 
 
== Going Live ==
 
After the integration has been certified, users will need to make a couple of updates to the initialization call to ensure that player will be measured properly.
 
Disable debug logging by deleting {nol_sdkDebug: 'DEBUG'} from initialization call.
 
Example Production Initialization Call
 
 
 
<syntaxhighlight lang="javascript">
 
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", { optout: "false"});
 
</syntaxhighlight>
 
 
 
== Sample Code ==
 
This code is for example purposes only to demonstrate a very simple video implementation, with a single preroll and single content block.
 
<syntaxhighlight lang=javascript>
 
<script >
 
  // Setup videojs sample player
 
  var nielsenid = document.getElementById("my-sdkplayer");
 
var coolPlayer = videojs('my-sdkplayer', {
 
  controls: true,
 
  autoplay: true,
 
  preload: 'auto',
 
});
 
var prevPos = null;
 
 
 
coolPlayer.preroll({
 
  src: {
 
    src: "assets/CleaningCrew.mp4",
 
    type: "video/mp4"
 
  },
 
  href: "http://videojs.com",
 
  adsOptions: {
 
    debug: true
 
  }
 
});
 
 
 
videojs('my-sdkplayer').ready(function() {
 
  // EXAMPLE: Start playing the video.
 
 
 
  coolPlayer.play();
 
  var obj = {
 
    event: 'playhead', // playhead,pause,complete,adstop
 
    type: 'content',
 
    playheadPosition: '0',
 
    metadata: {
 
      content: {
 
        type: 'content',
 
        assetid: 'VID98-2B88',
 
        program: 'Put a programname here ',
 
        title: 'S01E02',
 
        length: '180',
 
        airdate: '20190101 10:01:00',
 
        isfullepisode: 'y',
 
        crossId1: 'Standard Episode ID',
 
        crossID2: 'Content Originator',
 
        adloadtype: '2'
 
      },
 
      ad: {},
 
      static: {}
 
    }
 
  };
 
 
 
    coolPlayer.on('timeupdate', function() {
 
        var getcurrentTime = coolPlayer.currentTime();
 
        var intPlayedTime = parseInt(getcurrentTime, 10);
 
        if (intPlayedTime > 0 && intPlayedTime !== prevPos && !coolPlayer.scrubbing()) {
 
            // check for playhead change so it's only called once per second
 
            console.log('PLAYHEAD EVENT **************************************************************');
 
            console.log(Math.round(getcurrentTime));
 
            obj.event = 'playhead';
 
            obj.type = 'content';
 
            obj.metadata.ad = {};
 
            prevPos = intPlayedTime;
 
            obj.playheadPosition = Math.round(getcurrentTime);
 
            nSdkInstance.trackEvent(obj);
 
    }
 
  });
 
 
 
  this.on('adstart', function() {
 
    console.log('ADSTART EVENT **************************************************************');
 
    obj.type = 'ad';
 
    obj.metadata.ad = {
 
      type: 'preroll',
 
      assetid: 'AD9455',
 
      adldx: '1',
 
      program: 'Cant Skip Campaign',
 
      title: 'Cleaning Crew',
 
      length: '36',
 
    };
 
    nSdkInstance.trackEvent(obj);
 
  });
 
 
 
  this.on('contentresumed', function() {
 
    console.log('CONTENT RESUMED EVENT **************************************************************');
 
    obj.type = 'content';
 
    obj.event = 'playhead';
 
    obj.metadata.ad = {};
 
    nSdkInstance.trackEvent(obj);
 
  });
 
 
 
  this.on('pause', function() {
 
    console.log('PAUSE EVENT **************************************************************');
 
    obj.event = 'pause';
 
    obj.playheadPosition = Math.round(coolPlayer.currentTime());
 
    nSdkInstance.trackEvent(obj);
 
  });
 
 
 
  this.on('adtimeupdate', function() {
 
    var getcurrentTime = coolPlayer.currentTime();
 
    var intPlayedTime = parseInt(getcurrentTime, 10);
 
    if (intPlayedTime > 0 && intPlayedTime !== prevPos) {
 
      // check for playhead change so it's only called once per second
 
      console.log('AD PLAYHEAD EVENT **************************************************************');
 
      console.log(Math.round(getcurrentTime));
 
      prevPos = intPlayedTime;
 
      obj.playheadPosition = Math.round(getcurrentTime);
 
      nSdkInstance.trackEvent(obj);
 
    };
 
  });
 
 
 
  this.on('adend', function() {
 
    console.log('AD STOP EVENT **************************************************************');
 
    obj.event = 'adstop';
 
    nSdkInstance.trackEvent(obj);
 
  });
 
 
 
  this.on('ended', function() {
 
    console.log('COMPLETE EVENT **************************************************************');
 
    obj.event = 'complete';
 
    nSdkInstance.trackEvent(obj);
 
  });
 
});
 
 
 
</script>
 
</syntaxhighlight>
 

Revision as of 19:53, 28 September 2021

Engineering Portal breadcrumbArrow.png Digital breadcrumbArrow.png DCR & DTVR breadcrumbArrow.png Digital Measurement Browser Simplified API

Overview

The Nielsen SDK is one of multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc. The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like Digital in TV Ratings, Digital Content Ratings (DCR & DTVR), and Digital Ad Ratings (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:

  • Application launch events and how long app was running
  • Time of viewing a sub section / page in the application.

Please select The Browser Implementation Guide for more detailed information on implementation.