Engineering Client Portal - User contributions [en]

DCR Video & Static Roku Cloud API

2018-03-22T02:12:32Z

RyanCarlson: sandbox

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR) measurement on your Roku Apps.
*For other OTT Apps, please see [[DCR Video & Static Cloud API]]
*For Mobile Apps, please see [[DCR Video & Static Mobile Cloud API]]

==Prerequisites==
To get started, you will need a Nielsen App ID. The App ID is a unique ID assigned to your app. This will be provided to you upon starting the integration.

<syntaxhighlight lang="javascript">XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

==Integration==
We will cover the steps for constructing the Cloud API Calls.

===Request Overview===

====URL Structure====

The Cloud API Calls are HTTP GET Requests with the URL structure:

<syntaxhighlight lang="javascript">[endpoint]/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

The URL includes the following components:

*<code>[endpoint]</code>: location of data collection environment
*<code>[appid]</code>: provided App ID
*<code>[sessionID]</code>: unique value for each user session
*<code>[payload]</code>: metadata and events

====Endpoint====

There are endpoints for testing and production:

*Testing: <code>https://sandbox-cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

During testing, all calls should be pointed to the testing endpoint. Once your application has been certified, the URL should be updated to point to the Cloud API production endpoint.

====URL Example====
As you move through the integration steps, you can reference the below URL structure with the expanded payload:

<syntaxhighlight lang="javascript">
https://sandbox-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"static": [static_metadata],
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [UTC]
}
</syntaxhighlight>

===Create Session ID===
A unique Session ID must be created upon app launch and provided in the URL. This will allow measurement to occur for the entire duration that a user is within the app.

The session ID must be passed with every request and must remain consistent throughout each individual session.

===Example Roku Sample Code Provided Below:===
<syntaxhighlight lang="javascript">sessionTime = createObject("roDateTime")</syntaxhighlight>

<syntaxhighlight lang="javascript">sessionID = (sessionTime.asSeconds()).tostr()+(sessionTime.getMilliseconds()).tostr()</syntaxhighlight>

Upon exiting the app, the session will need to be terminated using the delete event. Sessions will automatically expire after 30 minutes of cloud inactivity.

===Define URL Structure===
Define the URL structure using your provided <code>[appid]</code> and a unique <code>[sessionID]</code>.

<syntaxhighlight lang="javascript">https://sandbox-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

===Configure Payload===

All Cloud API requests must contain the following payload data:

*''devInfo'': device and app info
*''metadata'': asset metadata
*''event metadata'': type of event

The payload can be passed through key-values using the Nielsen reserved keys. The specific keys and descriptions are highlighted in the tables included in this section.

'''Payload Example'''

The example below should be referenced when following the steps for configuring the request payload.

<syntaxhighlight lang="javascript">
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"apn": "AppName",
"encdata": "encdata=v1.key.RokuAES256CBC00.iv3x2EV0BpHH9AbZK%2FnBWWRhZbj7pD%3D...",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2", //ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}
</syntaxhighlight>

=====Configure Payload: devInfo=====
An object <code>"devInfo"</code> will need to be created to capture App and Device information.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apn || app name || custom || Yes
|-
| apv || app build version || custom || Yes
|-
| uoo || device opt-out status || <code>"true"</code> or <code>"false"</code> || Yes
|-
| Example || Example || Example || Yes
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"encdata": "encdata=v1.key.RokuAES256CB...",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},
</syntaxhighlight>
==== 3.2 Configure Payload: metadata ====
Asset metadata can be passed through <code>"metadata"</code>. There are two asset types: <code>"content"</code> for video and <code>"ad"</code> for ads. The metadata received for each asset is used for classification and reporting.

You will need to set up <code>"metadata"</code> objects for <code>"content"</code> and <code>"ad"</code> with the required Nielsen keys as shown in the sample code below.

===== Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>"content"</code> || Yes
|-
| assetid || unique ID assigned to asset || custom || Yes
|-
| program ||name of program (25 character limit) || custom || Yes
|-
| title ||name of program (25 character limit) || custom || Yes
|-
| length || length of content in seconds || <code>seconds</code> (86400 for live stream) || Yes
|-
| segB || custom segment B || custom ||
|-
| segC || custom segment C || custom ||
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH24:MI:SS || Yes
|-
| isfullepisode || full episode flag || <code>"y"</code>- full episode, <code>"n"</code>- non full episode || Yes
|-
| crossId1 || standard episode ID || custom || Yes
|-
| crossId2 || content originator (only required for distributors) || Nielsen ||
|-
| adloadtype || type of ad load:
<code>"1"</code> Linear – matches TV ad load

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|-
| hasAds || ads indicator
<code>"1"</code>: ads included

<code>"0"</code>: ads not included
|| <code>"1"</code> or <code>"0"</code> || Yes
|-
| progen || program genre abbreviation - see [[DCR OTT Genre List]] for accepted values || <code>"CV"</code> for Comedy Variety || Yes
|}

'''Example Content Object'''
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "VIDEO-ID123",
"isfullepisode": "y",
"program": "Program Name",
"title": "Episode Title S3 - EP1",
"length": "1800",
"segB": "Custom Segment B",
"segC": "Custom Segment C",
"crossId1": "Standard Episode ID",
"crossId2": "Content Originator ID",
"airdate": "20161013 20:00:00",
"adloadtype": "2",
"hasAds": "1",
"progen": "CV"
}</syntaxhighlight>

===== Ad Metadata =====
The ad metadata should be passed for each individual ad.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || <code>"preroll"</code>, <code>"midroll"</code>, or <code>"postroll"</code> || Yes
|-
| assetid || unique ID assigned to ad || custom || Yes
|}

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "AD-ID123"
}
</syntaxhighlight>

=== Configure Payload: Events ===

The last part of the payload is for enabling events so content is measured correctly when viewed. The events and required parameters are included below.

==== Event Types ====

The available events are:
{| class="wikitable"
|-
! Event !! Description
|-
| <code>"playhead"</code> || Playhead position in seconds. Must be passed as a whole number every 10 seconds. The final playhead position should also be sent before an asset has changed to properly capture full duration. Playhead is used to handle pause and scrubbing. When content is paused, stop passing playhead position.
|-
| <code>"complete"</code> || The complete event must be sent when the content has completed full playback. Before calling the complete event, a final playhead update with the final position is required to be sent to receive full duration credit.
|-
| <code>"delete"</code> || The delete event must be sent when the session is completed, or terminated. After 30 minutes of inactivity, the session will expire. All creditable duration will be summarized for all asset types when delete occurs (content and ads).
|}

===== Event Parameters =====

The following parameters need to be passed when calling events:

{| class="wikitable"
|-
! Parameter !! Description !! Value !! Required
|-
| <code>"event"</code> || event type || <code>"playhead"</code>, <code>"complete"</code>, or <code>"delete"</code> || Yes
|-
| <code>"position"</code> || creditable position || playhead position in seconds or UTC timestamp in seconds for livestream || Yes
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || Yes
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || Yes
|}

===== Example Event =====
You can call events by passing values in the required parameters:

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"metadata": {
"static": [static metadata],
"content": [content metadata],
"ad": [ad metadata]
},
// Event Parameters
"event": [event], // event name
"position": [playheadPosition], //position in seconds
"type": [asset type], // values are "content" or "ad"
"utc": "1472760000000" //unix timestamp in milliseconds
}
</syntaxhighlight>

'''Note:''' The full payload including "devInfo" and "metadata" must be populated in each event request.

===Example Image Request===

In order to execute Cloud API calls, image requests will need to be established for each event.

===Playhead Image Request Example Code===

<syntaxhighlight lang="javascript">
playheadRequest = CreateObject("roUrlTransfer")
sendUrl = sessionUrl+playheadRequest.Escape(playheadPayload)
playheadRequest.SetUrl(sendUrl)
xport=CreateObject("RoMessagePort")
playheadRequest.setport(xport)
aa3 = {}
aa3["Connection"] = "keep-alive"
aa3["Content-type"] = "image/gif"
playheadRequest.SetHeaders(aa3)
playheadRequest.setRequest("GET")
</syntaxhighlight>

===== Sample Event Lifecycle =====
The sample event lifecycle can be used as a reference for identifying the order for calling events and values to pass.

<syntaxhighlight lang="javascript">
// Start of Session: session ID created when App is opened

// Preroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472760000000"}

// Midroll
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content resumes at 15 minutes
Content Playhead {"event": "playhead", "position": "900", "type": "content", "utc": "1472760000000"}

// Content completes at 30 minutes
Complete {"event": "complete", "position": "1800", "type": "content", "utc": "1472760000000"}

// Postroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472760000000"}
</syntaxhighlight>

'''Sample Event Lifecycle - Detailed Storyline'''
This detailed event sequence provides additional insight for the correct events to call when handling certain playback scenarios.
<syntaxhighlight lang='javascript'>// SESSION STARTS
// Start of Session: session ID created when App is opened

// PREROLL
// Preroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Preroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "15", "type": "ad", "utc": "1472761500000"}

// CONTENT
// Content Start - Start new content streams with a position of "0" incrementing the position every 10 seconds.
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472761500000"}

// Content Stop Before Ad Break - Send a playhead update including the current content positon before an Ad break.
Content Playhead {"event": "playhead", "position": "299", "type": "content", "utc": "1472787400000"}

// MIDROLL
// Midroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472787500000"}

// Midroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "60", "type": "ad", "utc": "1472793500000"}

// CONTENT
// Content resumes at 5 minutes - Send playhead update with the current resumed position, and begin incrimenting the positon every 10 seconds.
Content Playhead {"event": "playhead", "position": "300", "type": "content", "utc": "1472799500000"}

// Content completes at 10:12 - Make sure to send in the playhead event with the final content position before sending the complete event.
Final Content Playhead {"event": "playhead", "position": "612", "type": "content", "utc": "1472830700000"}

Complete {"event": "complete", "position": "612", "type": "content", "utc": "1472830800000"}

// POSTROLL
// Postroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472830900000"}

// Postroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "45", "type": "ad", "utc": "1472835300000"}

// SESSION ENDS

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472835400000"} </syntaxhighlight>

=====Handling Playhead=====
Calling <code>"playhead"</code> is critical for accurate duration crediting. You can reference the below guidance to determine the correct playhead position to pass depending on the playback scenario.

'''Playhead: General'''
* Playhead position must start at 0 for each new asset, and be passed at least every 10 seconds.
* Final postion must be sent at the end of content or an ad

'''Playhead: Ads'''
* The final position must be sent when switching from content to ad, or ad to content.
* Each ad playhead position should be 0 at ad start.
* For Ad Pods, playhead must be called, and reset to 0 for each individual ad.
* The last content position before an Ad should be sent before switching to Ads.
* When content has resumed following an ad break, the playhead position update must continue where the previous content segment left off.

'''Playhead: User Actions'''
* Upon user scrubbing, the current position must be sent before a user scrubs, and the new position should be sent where the user lands, and begin sending in the 10 second updates thereafter.
* On pause, send the current position and then discontinue sending playhead event updates.
* If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

===== Interruption Scenarios =====

As part of configuring events, you will need to handle all possible interruption scenarios such as:

*Wi-Fi OFF / ON
*App going Background / Foreground (Video players only, not for Audio players)
*App Crash or Exit

When playback is interrupted, the app needs to send delete immediately.

Once playback resumes, a new session will need to be created with a unique session ID. All of the required metadata and events will need to be sent.

'''Note:''' The session will automatically timeout after 30 minutes of inactivity.

=== Example Request ===

Now that we walked through the Cloud API integration steps, your requests should have the following components: Session ID, App ID, and Payload. You can reference the example below when your reviewing your integration.

<syntaxhighlight lang="javascript">
// 1. Create Session ID
sessionTime = createObject("roDateTime")
sessionID = (sessionTime.asSeconds()).tostr()+(sessionTime.getMilliseconds()).tostr()

// 2. Define URL Structure with App ID and Session ID
sessionURL = https://sandbox-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"encdata": "encdata=v1.key.RokuAES256CB...",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2", // ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}

// Append payload to URL
sendUrl = sessionUrl.Escape(payload)
</syntaxhighlight>

==== Enable Debug Logging ====

Now that you have set up the Cloud API requests, you can enable debug logging to validate your integration. Enabling debug logging is required for Nielsen certification.

==== GET Request ====

Display GET Request to console using a name to identify each event (e.g. playhead).

<syntaxhighlight lang="javascript">
print "Playhead Event " + sendUrl
</syntaxhighlight>

==== Payload ====

Output payload to identify required metadata and events.

<syntaxhighlight lang="javascript">
print "Event Payload "+ playheadPayload + modSeq%.tostr()
</syntaxhighlight>

==== HTTP Response Code ====

Confirm request was completed by viewing HTTP response code.

<syntaxhighlight lang="javascript">
httpCode = GetResponseCode()
print "Response Code " +httpCode.tostr()
</syntaxhighlight>

You can reference the HTTP Response Code table when reviewing your requests:

{| class="wikitable"
|-
! Status Code !! Status Text !! Description
|-
| <code>200</code> || OK || request received
|-
| <code>403</code> || Forbidden || invalid App ID
|-
| <code>404</code> || Not Found || JSON issue
|}

== Opt-Out ==

Your app must provide a means for the user to Opt-Out, or Opt-In to Nielsen Measurement. This can be implemented in two steps:

==== Step 1: Nielsen Privacy Policy & Roku Channel Disclosure ====

In your application, you must display the Nielsen privacy policy, which instructs users on how to opt out and opt in to Nielsen measurements. This text is usually displayed in an application's "Settings" or "About" screens.

<blockquote>
'''''ABOUT NIELSEN MEASUREMENT'''''

Television and the way we watch it have come a long way since Nielsen began measuring TV audiences in 1950. Today, the ability to watch our favorite shows at any time and on multiple devices amplifies the need for exceptionally adept and flexible audience measurement capabilities.

Consumers are changing with the times, and the same goes for us. As technology continues to evolve and media companies try new ways to attract viewers, understanding what consumers are watching — and what they're watching on — is more important than ever. Today, viewing video is a personal and mobile experience — anytime and anywhere. Our capabilities provide relevant metrics that are necessary to inform successful marketing and programming and drive continued growth. As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. While our digital measurement products are not used to identify you in any way, they help us and our clients measure and analyze how consumers engage with media across online, mobile and emerging technologies, and offer insights into consumer behavior.

'''''YOUR CHOICES'''''

Nielsen believes that you should have a choice about whether to contribute to our research and insights. To opt out, or opt into Nielsen measurement please choose the appropriate "Limit Ad Tracking" setting on your device. If you have this app on more than one device, you will need to opt out of this app on each device. To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.
</blockquote>

In addition, on your Roku Channel description, you should add the following disclosure:

<blockquote>
This app features Nielsen's proprietary measurement software which will allow you to contribute to market research, like Nielsen's TV Ratings. Please see http://www.nielsen.com/digitalprivacy for more information.
</blockquote>

==== Step 2: Use "Limit Ad Tracking" setting to set User Opt Out ====

Depending on the user's selection for the "Limit Ad Tracking" device setting, you should set the Cloud API <code>"uoo"</code> parameter accordingly. Roku provides an API called [https://sdkdocs.roku.com/display/sdkdoc/ifDeviceInfo#ifDeviceInfo-IsAdIdTrackingDisabled()asBoolean IsAdIdTrackingDisabled()] to check the user's limit ad tracking setting.

{| class="wikitable"
|-
! uoo Key !! Description !! Values
|-
| uoo || Device is Opted-In to Nielsen Measurement || <code>"false"</code>
|-
| uoo || Device is Opted-Out of Nielsen Measurement || <code>"true"</code>
|}

The <code>"uoo"</code> parameter is located in the <code>"devInfo"</code> JSON object, which will be sent in every Cloud API event (playhead, complete, & delete).

===== devInfo Opt-In JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Roku Sample App",
"apv": "1",
"encdata": "encdata=v1.key.RokuAES256CB...",
"uoo": "false"
},
</syntaxhighlight>

===== devInfo Opt-Out JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Roku Sample App",
"apv": "1",
"encdata": "", //Encdata must be blank when a user elects to Opt-Out.
"uoo": "true"
},
</syntaxhighlight>

Your application should check the Limit Ad Tracking setting on each app start, and/or periodically, to ensure the user's ad tracking selection is reflected in the Nielsen opt-out setting in your app.

*In addition, you will need to ensure that the encdata field is populated with a blank value if a user has elected to Opt-Out.

== Testing ==
Before providing an app build to Nielsen for testing, it is important to run validation checks once you have enabled debug logging.

=== Payload Validation ===

Ensure that all of the required payload data is populating while testing several videos. The following areas are critical to measurement:
*devInfo
*Asset metadata for both content, and ads
*Events
*Opt-Out status

=== Player Events ===
Review event calls:

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset.
*Final playhead position is sent on content, or ad before switching between assets.
*Content metadata remains constant throughout an episode, or clip play.
*Ad metadata is populated appropriately for each individual ad.
*Playhead position update resumes for content after an ad break, and resets to 0 for each individual ad.
*For scrubbing, last current position should be sent while scrubbing occurs, and the new position should also be sent where the user scrubs to.
*Exiting a stream early should execute the last current position in a playhead update to receive accurate duration.
*Upon pause, the current position should be sent, and playhead updates should stop incrementing until resume play occurs.

==== complete ====
*Check that the complete event executes upon content complete after the final playhead update is sent.
*Do not execute the complete event for ads

==== delete ====
*Check to see that the delete event occurs upon app exit

==== GET Request Format ====
*Ensure that the event payloads are formatted in JSON
*Check to see that each of the Cloud API GET requests are properly encoded.

==== HTTP Response ====
*Make sure that each of the Cloud API Get requests are received by the Nielsen Cloud API properly through use of the HTTP Response Code outputs enabled in console.

==== Opt-Out ====
*Test the "uoo" key gets populated accurately for both Opt-In and Opt-Out selections based on the device's "Limit Ad Tracking" setting.
*Test that the encdata field is populated with a blank value if a user has elected to Opt-Out. For Example: "encdata": "",

== Go Live ==
After your integration has been certified, you will need to: Change Endpoint and Disable Logging.

'''Change Endpoint:''' You will need to update to the production endpoint:

*Testing: <code>https://sandbox-cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

Your production URL structure should now be:
<code>https://cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</code>

'''Disable Logging:''' You can now disable debug logging.

DCR Video & Static Mobile Cloud API

2018-03-22T02:10:22Z

RyanCarlson: sandbox

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR) measurement on your mobile apps.
*For Roku Apps, please see [[DCR Video & Static Roku Cloud API]]
*For OTT Devices, please see [[DCR Video & Static Cloud API]]

==Prerequisites==
To get started, you will need a Nielsen App ID. The App ID is a unique ID assigned to your app. This will be provided to you upon starting the integration.

<syntaxhighlight lang="javascript">XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

==Integration==
We will cover the steps for constructing the Cloud API Calls.

===Request Overview===

====URL Structure====

The Cloud API Calls are HTTP GET Requests with the URL structure:

<syntaxhighlight lang="javascript">[endpoint]/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

The URL includes the following components:

*<code>[endpoint]</code>: location of data collection environment
*<code>[appid]</code>: provided App ID
*<code>[sessionID]</code>: unique value for each user session
*<code>[payload]</code>: metadata and events

====Endpoint====

There are endpoints for testing and production:

*Testing: <code>https://sandbox-cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

During testing, all calls should be pointed to the testing endpoint. We will review the update to the production endpoint during the Go Live section of this guide.

====URL Example====
As you move through the integration steps, you can reference the below URL structure with the expanded payload:

<syntaxhighlight lang="javascript">
https://sandbox-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"static": [static_metadata],
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [UTC]
}
</syntaxhighlight>

===Create Session ID===
A unique Session ID must be created upon app launch and provided in the URL. This will allow measurement to occur for the entire duration that a user is within the app.

The session ID must be a GUID that is passed with every request and remain consistent throughout each individual session. You can use an existing ID, a random number, or date.now() as shown in the recommended sample code below:

<syntaxhighlight lang="javascript">sessionID = Date.now()+String(Math.random()*1000000 >> 0);</syntaxhighlight>

Upon exiting the app, the session will need to be terminated using the delete event. Sessions will automatically expire after 30 minutes of cloud inactivity.

===Define URL Structure===
Define the URL structure using your provided <code>[appid]</code> and a unique <code>[sessionID]</code>.

<syntaxhighlight lang="javascript">https://sandbox-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

===Configure Payload===

All Cloud API requests must contain the following payload data:

*''devInfo'': device and app info
*''metadata'': asset metadata
*''event metadata'': type of event

The payload can be passed through key-values using the Nielsen reserved keys. The specific keys and descriptions are highlighted in the tables included in this section.

'''Payload Example'''

The example below should be referenced when following the steps for configuring the request payload.

<syntaxhighlight lang="javascript">
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2" //ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}
</syntaxhighlight>

=====Configure Payload: devInfo=====
An object <code>"devInfo"</code> will need to be created to capture App and Device information.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| devId || unique ID to identify user (e.g. Advertising ID, Roku Device ID) || custom || Yes
|-
| apn || app name || custom || Yes
|-
| apv || app build version || custom || Yes
|-
| uoo || device opt-out status || <code>"true"</code> or <code>"false"</code> || Yes
|-
|}

On mobile devices you will need to pass the IDFA/Ad ID as part of the devId parameter. Please see the section below regarding Opt Out and the IDFA/Ad ID.

===== Accessing the IDFA on iOS =====

Accessing the ID For Advertisers (IDFA) uses OS level API calls. In order to do this, you must first import the following header file:
<syntaxhighlight lang="objective-c">#import <AdSupport/ASIdentifierManager.h></syntaxhighlight>

Then to receive the IDFA as a NSString, use similar code to the following:
<syntaxhighlight lang="objective-c">NSString *idfaString = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];</syntaxhighlight>
You can read more about ASIdentifierManager on Apple's [https://developer.apple.com/reference/adsupport/asidentifiermanager| developer website].

===== Accessing the Ad ID on Android =====

Accessing the Google Ad ID uses OS level API calls. In order to do this, you must first import Google Play Services. Then to receive the Ad ID, use the AdvertisingIdClient class as such:
<syntaxhighlight lang="java">public static AdvertisingIdClient.Info getAdvertisingIdInfo (Context context)</syntaxhighlight>

You can read more about the AdvertisingIdClient class on Google's [https://developers.google.com/android/reference/com/google/android/gms/ads/identifier/AdvertisingIdClient| developer website].

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},
</syntaxhighlight>

==== 3.2 Configure Payload: metadata ====
Asset metadata can be passed through <code>"metadata"</code>. There are two asset types: <code>"content"</code> for video and <code>"ad"</code> for ads. The metadata received for each asset is used for classification and reporting.

You will need to set up <code>"metadata"</code> objects for <code>"content"</code> and <code>"ad"</code> with the required Nielsen keys as shown in the sample code below.

===== Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>"content"</code> || Yes
|-
| assetid || unique ID assigned to asset || custom || Yes
|-
| program ||name of program (25 character limit) || custom || Yes
|-
| title ||name of program (25 character limit) || custom || Yes
|-
| length || length of content in seconds || <code>seconds</code> (86400 for live stream) || Yes
|-
| segB || custom segment B || custom ||
|-
| segC || custom segment C || custom ||
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH24:MI:SS || Yes
|-
| isfullepisode || full episode flag || <code>"y"</code>- full episode, <code>"n"</code>- non full episode || Yes
|-
| crossId1 || standard episode ID || custom || Yes
|-
| crossId2 || content originator (only required for distributors) || Nielsen ||
|-
| adloadtype || type of ad load:
<code>"1"</code> Linear – matches TV ad load

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|-
| hasAds || ads indicator
<code>"1"</code>: ads included

<code>"0"</code>: ads not included
|| <code>"1"</code> or <code>"0"</code> || Yes
|-
| progen || program genre abbreviation - see [[DCR OTT Genre List]] for accepted values || <code>"CV"</code> for Comedy Variety || Yes
|}

'''Example Content Object'''
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "VIDEO-ID123",
"isfullepisode": "y",
"program": "Program Name",
"title": "Episode Title S3 - EP1",
"length": "1800",
"segB": "Custom Segment B",
"segC": "Custom Segment C",
"crossId1": "Standard Episode ID",
"crossId2": "Content Originator ID",
"airdate": "20161013 20:00:00",
"adloadtype": "2",
"hasAds": "1",
"progen": "CV"
}</syntaxhighlight>

===== Ad Metadata =====
The ad metadata should be passed for each individual ad.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || <code>"preroll"</code>, <code>"midroll"</code>, or <code>"postroll"</code> || Yes
|-
| assetid || unique ID assigned to ad || custom || Yes
|}

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "AD-ID123"
}
</syntaxhighlight>

=== Configure Payload: Events ===

The last part of the payload is for enabling events so content is measured correctly when viewed. The events and required parameters are included below.

==== Event Types ====

The available events are:
{| class="wikitable"
|-
! Event !! Description
|-
| <code>"playhead"</code> || Playhead position in seconds. Must be passed as a whole number every 10 seconds. The final playhead position should also be sent before an asset has changed to properly capture full duration. Playhead is used to handle pause and scrubbing. When content is paused, stop passing playhead position.
|-
| <code>"complete"</code> || Complete event must be sent when the content has completed full playback.Before calling the complete event, a final playhead update with the final position is required to be sent to receive full duration credit.
|-
| <code>"delete"</code> || The delete event must be sent when the session is completed, or terminated. After 30 minutes of inactivity, the session will expire. All creditable duration will be summarized for all asset types when delete occurs (content and ads).
|}

===== Event Parameters =====

The following parameters need to be passed when calling events:

{| class="wikitable"
|-
! Parameter !! Description !! Value !! Required
|-
| <code>"event"</code> || event type || <code>"playhead"</code>, <code>"complete"</code>, or <code>"delete"</code> || Yes
|-
| <code>"position"</code> || creditable position || playhead position in seconds or UTC timestamp in seconds for livestream || Yes
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || Yes
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || Yes
|}

===== Example Event =====
You can call events by passing values in the required parameters:

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"metadata": {
"static": [static metadata],
"content": [content metadata],
"ad": [ad metadata]
},
// Event Parameters
"event": [event], // event name
"position": [playheadPosition], //position in seconds
"type": [asset type], // values are "content" or "ad"
"utc": "1472760000000" //unix timestamp in milliseconds
}
</syntaxhighlight>

'''Note:''' The full payload including "devInfo" and "metadata" must be populated in each event request.

===== Sample Event Lifecycle =====
The sample event lifecycle can be used as a reference for identifying the order for calling events and values to pass.

<syntaxhighlight lang="javascript">
// Start of Session: session ID created when App is opened

// Preroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472760000000"}

// Midroll
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content resumes at 15 minutes
Content Playhead {"event": "playhead", "position": "900", "type": "content", "utc": "1472760000000"}

// Content completes at 30 minutes
Complete {"event": "complete", "position": "1800", "type": "content", "utc": "1472760000000"}

// Postroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472760000000"}
</syntaxhighlight>

'''Sample Event Lifecycle - Detailed Storyline'''
This detailed event sequence provides additional insight for the correct events to call when handling certain playback scenarios.
<syntaxhighlight lang='javascript'>// SESSION STARTS
// Start of Session: session ID created when App is opened

// PREROLL
// Preroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Preroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "15", "type": "ad", "utc": "1472761500000"}

// CONTENT
// Content Start - Start new content streams with a position of "0" incrementing the position every 10 seconds.
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472761500000"}

// Content Stop Before Ad Break - Send a playhead update including the current content positon before an Ad break.
Content Playhead {"event": "playhead", "position": "299", "type": "content", "utc": "1472787400000"}

// MIDROLL
// Midroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472787500000"}

// Midroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "60", "type": "ad", "utc": "1472793500000"}

// CONTENT
// Content resumes at 5 minutes - Send playhead update with the current resumed position, and begin incrimenting the positon every 10 seconds.
Content Playhead {"event": "playhead", "position": "300", "type": "content", "utc": "1472799500000"}

// Content completes at 10:12 - Make sure to send in the playhead event with the final content position before sending the complete event.
Final Content Playhead {"event": "playhead", "position": "612", "type": "content", "utc": "1472830700000"}

Complete {"event": "complete", "position": "612", "type": "content", "utc": "1472830800000"}

// POSTROLL
// Postroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472830900000"}

// Postroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "45", "type": "ad", "utc": "1472835300000"}

// SESSION ENDS

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472835400000"} </syntaxhighlight>

=====Handling Playhead=====
Calling <code>"playhead"</code> is critical for accurate duration crediting. You can reference the below guidance to determine the correct playhead position to pass depending on the playback scenario.

'''Playhead: General'''
* Playhead position must start at 0 for each new asset, and be passed at least every 10 seconds.
* Final postion must be sent at the end of content or an ad

'''Playhead: Ads'''
* The final position must be sent when switching from content to ad, or ad to content.
* Each ad playhead position should be 0 at ad start.
* For Ad Pods, playhead must be called, and reset to 0 for each individual ad.
* The last content position before an Ad should be sent before switching to Ads.
* When content has resumed following an ad break, the playhead position update must continue where the previous content segment left off.

'''Playhead: User Actions'''
* Upon user scrubbing, the current position must be sent before a user scrubs, and the new position should be sent where the user lands, and begin sending in the 10 second updates thereafter.
* On pause, send the current position and then discontinue sending playhead event updates.
* If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

===== Interruption Scenarios =====

As part of configuring events, you will need to handle all possible interruption scenarios such as:

*Pause / Play
*Network Loss (Wi-Fi / Airplane Mode / Cellular)
*Wi-Fi OFF / ON
*Call Interrupt (SIM or Third party Skype / Hangout call)
*Alarm Interrupt
*Content Buffering
*Device Lock / Unlock (Video players only, not for Audio players)
*App going Background / Foreground (Video players only, not for Audio players)
*App Crash or Exit
*Channel / Station Change Scenario
*Unplugging of headphone

When playback is temporarily interrupted (e.g. pause, content buffering), the app needs to send the last known playhead position.

*If an app is sent to background for more than 5 minutes, please create a new session ID. Otherwise, use the same session ID as before.
*If loss of Internet occurs, please queue the API calls that would have been made. Once Internet connectivity is regained, please spool off the API calls in order of first generated (Note: if doing so, please use the UTC time in milliseconds)

When playback is permanently interrupted, the app needs to send delete immediately.
*If an app crashes, please create a new session ID. No delete call will be necessary as the previous session will timeout.

Once playback resumes after delete occurs, a new session will need to be created with a unique session ID. All of the required metadata and events will need to be sent.

'''Note:''' The session will automatically timeout after 30 minutes of inactivity.

=== Example Request ===

Now that we walked through the Cloud API integration steps, your requests should have the following components: Session ID, App ID, and Payload. You can reference the example below when your reviewing your integration.

<syntaxhighlight lang="javascript">
// 1. Create Session ID
sessionID = Date.now()+String(Math.random()*1000000 >> 0); // Must be GUID for each viewing session

// 2. Define URL Structure with App ID and Session ID
sessionURL = https://sandbox-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2", // ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}

// Append payload to URL
var image = new Image()
image.onerror = function() {
// wait and send again
}
(new Image).src = sessionURL+encodeURI(JSON.stringify(payload));
</syntaxhighlight>

==== Enable Debug Logging ====

Now that you have set up the Cloud API requests, you can enable debug logging to validate your integration. Enabling debug logging is required for Nielsen certification.

==== GET Request ====

Display GET Request to console using a name to identify each event (e.g. playhead).

<syntaxhighlight lang="javascript">
console.log("Event", image);
</syntaxhighlight>

==== Payload ====

Output payload to identify required metadata and events.

<syntaxhighlight lang="javascript">
console.log("Event Payload", payload);
</syntaxhighlight>

==== HTTP Response Code ====

Confirm request was completed by viewing HTTP response code.

<syntaxhighlight lang="javascript">
code = msg.GetResponseCode();
console.log("Response Code", code);
</syntaxhighlight>

You can reference the HTTP Response Code table when reviewing your requests:

{| class="wikitable"
|-
! Status Code !! Status Text !! Description
|-
| <code>200</code> || OK || request received
|-
| <code>403</code> || Forbidden || invalid App ID
|-
| <code>404</code> || Not Found || JSON issue
|}

== Opt-Out ==
Your app must provide a means for the user to Opt-Out, or Opt-In to Nielsen Measurement. The Opt-Out requirement can be fulfilled by creating an Opt-Out/Opt-In button, toggle switch, or slider within the app "Settings", or "About" section to allow the user selection. If you have the ability to render text within the Opt-Out screen, it is recommended to add the Privacy Information included below.

[[File:Nielsen Opt-Out.png|link=]]

You will need to store the User Opt-Out (uoo) status, so that it can be retrieved and populated in the <code>"devInfo"</code> metadata which will be sent in every Cloud API event (playhead, complete, & delete).

*In addition, you will need to ensure that the devId field is a blank value if a user has elected to Opt-Out

*If the device offers "Limit Ad Tracking" or "Opt-Out" device settings, you must set uoo=true, and also ensure that the devId is set to a blank value if the user elects to enable this setting.

{| class="wikitable"
|-
! uoo Key !! Description !! Values
|-
| uoo || Device is Opted-In to Nielsen Measurement (Recommended Default Setting) || <code>"false"</code>
|-
| uoo || Device is Opted-Out of Nielsen Measurement || <code>"true"</code>
|}

===== devInfo Opt-In JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Roku Sample App",
"apv": "1",
"devId": "7be25cf9-8c40-5cc2-871e-19bf41940288",
"uoo": "false"
},
</syntaxhighlight>

===== devInfo Opt-Out JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Roku Sample App",
"apv": "1",
"devId": "", //devId must be blank when a user elects to Opt-Out.
"uoo": "true"
},
</syntaxhighlight>

===== Privacy Information Template To Include In Opt-Out Screen =====

<blockquote>
'''''ABOUT NIELSEN MEASUREMENT'''''

Television and the way we watch it have come a long way since Nielsen began measuring TV audiences in 1950. Today, the ability to watch our favorite shows at any time and on multiple devices amplifies the need for exceptionally adept and flexible audience measurement capabilities.

Consumers are changing with the times, and the same goes for us. As technology continues to evolve and media companies try new ways to attract viewers, understanding what consumers are watching — and what they're watching on — is more important than ever. Today, viewing video is a personal and mobile experience — anytime and anywhere. Our capabilities provide relevant metrics that are necessary to inform successful marketing and programming and drive continued growth. As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. While our digital measurement products are not used to identify you in any way, they help us and our clients measure and analyze how consumers engage with media across online, mobile and emerging technologies, and offer insights into consumer behavior.

'''''YOUR CHOICES'''''

Nielsen believes that you should have a choice about whether to contribute to our research and insights. To opt out, or opt into Nielsen measurement please make the appropriate selection within the app. If you have this app on more than one device, you will need to opt out of this app on each device. To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

'''''Disclosure Template'''''

Additionally, you must update the App description information from the App Distribution Store with the Nielsen Measurement disclosure below:

This app features Nielsen's proprietary measurement software which will allow you to contribute to market research, like Nielsen's TV Ratings. Please see http://www.nielsen.com/digitalprivacy for more information.
</blockquote>

== Testing ==
Before providing an app build to Nielsen for testing, it is important to run validation checks once you have enabled debug logging.

=== Payload Validation ===

Ensure that all of the required payload data is populating while testing several videos. The following areas are critical to measurement:
*devInfo
*Asset metadata for both content, and ads
*Events
*Opt-Out status

=== Player Events ===
Review event calls:

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset.
*Final playhead position is sent on content, or ad before switching between assets.
*Content metadata remains constant throughout an episode, or clip play.
*Ad metadata is populated appropriately for each individual ad.
*Playhead position update resumes for content after an ad break, and resets to 0 for each individual ad.
*For scrubbing, last current position should be sent while scrubbing occurs, and the new position should also be sent where the user scrubs to.
*Exiting a stream early should execute the last current position in a playhead update to receive accurate duration.
*Upon pause, the current position should be sent, and playhead updates should stop incrementing until resume play occurs.

==== complete ====
*Check that the complete event executes upon content complete after the final playhead update is sent
*Do not execute the complete event for ads

==== delete ====
*Check to see that the delete event occurs upon app exit

==== GET Request Format ====
*Ensure that the event payloads are formatted in JSON
*Check to see that each of the Cloud API GET requests are properly encoded

==== HTTP Response ====
*Make sure that each of the Cloud API Get requests are received by the Nielsen Cloud API properly through use of the HTTP Response Code outputs enabled in console.

==== Opt-Out ====
*Test the "uoo" key gets populated accurately for both Opt-In and Opt-Out selections by validating the Cloud API events called after the user Opt-Out/Opt-In selection.
*Test that the devId field is populated with a blank value if a user has elected to Opt-Out. For example: "devId": "",
*If the device supports "Limit Ad Tracking" or has device "Opt-Out" settings, test that uoo=true, and that devId is set to a blank value if enabled in the device settings.

== Go Live ==
After your integration has been certified, you will need to: Change Endpoint and Disable Logging.

'''Change Endpoint:''' You will need to update to the production endpoint:

*Testing: <code>https://sandbox-cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

Your production URL structure should now be:
<code>https://cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</code>

'''Disable Logging:''' You can now disable debug logging

DCR Video & Static Cloud API

2018-03-22T02:08:18Z

RyanCarlson: sandbox

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR) measurement on your over-the-top (OTT) Apps.
*For Roku Apps, please see [[DCR Video & Static Roku Cloud API]]
*For Mobile Apps, please see [[DCR Video & Static Mobile Cloud API]]

==Prerequisites==
To get started, you will need a Nielsen App ID. The App ID is a unique ID assigned to your app. This will be provided to you upon starting the integration.

<syntaxhighlight lang="javascript">XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

==Integration==
We will cover the steps for constructing the Cloud API Calls.

===Request Overview===

====URL Structure====

The Cloud API Calls are HTTP GET Requests with the URL structure:

<syntaxhighlight lang="javascript">[endpoint]/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

The URL includes the following components:

*<code>[endpoint]</code>: location of data collection environment
*<code>[appid]</code>: provided App ID
*<code>[sessionID]</code>: unique value for each user session
*<code>[payload]</code>: metadata and events

====Endpoint====

There are endpoints for testing and production:

*Testing: <code>https://sandbox-cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

During testing, all calls should be pointed to the testing endpoint. We will review the update to the production endpoint during the Go Live section of this guide.

====URL Example====
As you move through the integration steps, you can reference the below URL structure with the expanded payload:

<syntaxhighlight lang="javascript">
https://sandbox-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"static": [static_metadata],
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [UTC]
}
</syntaxhighlight>

===Create Session ID===
A unique Session ID must be created upon app launch and provided in the URL. This will allow measurement to occur for the entire duration that a user is within the app.

The session ID must be a GUID that is passed with every request and remain consistent throughout each individual session. You can use an existing ID, a random number, or date.now() as shown in the recommended sample code below:

<syntaxhighlight lang="javascript">sessionID = Date.now()+String(Math.random()*1000000 >> 0);</syntaxhighlight>

Upon exiting the app, the session will need to be terminated using the delete event. Sessions will automatically expire after 30 minutes of cloud inactivity.

===Define URL Structure===
Define the URL structure using your provided <code>[appid]</code> and a unique <code>[sessionID]</code>.

<syntaxhighlight lang="javascript">https://sandbox-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

===Configure Payload===

All Cloud API requests must contain the following payload data:

*''devInfo'': device and app info
*''metadata'': asset metadata
*''event metadata'': type of event

The payload can be passed through key-values using the Nielsen reserved keys. The specific keys and descriptions are highlighted in the tables included in this section.

'''Payload Example'''

The example below should be referenced when following the steps for configuring the request payload.

<syntaxhighlight lang="javascript">
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2" //ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}
</syntaxhighlight>

=====Configure Payload: devInfo=====
An object <code>"devInfo"</code> will need to be created to capture App and Device information.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| devId || unique ID to identify user (e.g. Advertising ID, Roku Device ID) || custom || Yes
|-
| apn || app name || custom || Yes
|-
| apv || app build version || custom || Yes
|-
| uoo || device opt-out status || <code>"true"</code> or <code>"false"</code> || Yes
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},
</syntaxhighlight>

==== 3.2 Configure Payload: metadata ====
Asset metadata can be passed through <code>"metadata"</code>. There are two asset types: <code>"content"</code> for video and <code>"ad"</code> for ads. The metadata received for each asset is used for classification and reporting.

You will need to set up <code>"metadata"</code> objects for <code>"content"</code> and <code>"ad"</code> with the required Nielsen keys as shown in the sample code below.

===== Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>"content"</code> || Yes
|-
| assetid || unique ID assigned to asset || custom || Yes
|-
| program ||name of program (25 character limit) || custom || Yes
|-
| title ||name of program (25 character limit) || custom || Yes
|-
| length || length of content in seconds || <code>seconds</code> (86400 for live stream) || Yes
|-
| segB || custom segment B || custom ||
|-
| segC || custom segment C || custom ||
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH24:MI:SS || Yes
|-
| isfullepisode || full episode flag || <code>"y"</code>- full episode, <code>"n"</code>- non full episode || Yes
|-
| crossId1 || standard episode ID || custom || Yes
|-
| crossId2 || content originator (only required for distributors) || Nielsen ||
|-
| adloadtype || type of ad load:
<code>"1"</code> Linear – matches TV ad load

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|-
| hasAds || ads indicator
<code>"1"</code>: ads included

<code>"0"</code>: ads not included
|| <code>"1"</code> or <code>"0"</code> || Yes
|-
| progen || Genre (required only for non-TV originated content). See [[DCR OTT Genre List]] for accepted values || <code>"CV"</code> for Comedy Variety || Required for non-TV originated content
|}

'''Example Content Object'''
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "VIDEO-ID123",
"isfullepisode": "y",
"program": "Program Name",
"title": "Episode Title S3 - EP1",
"length": "1800",
"segB": "Custom Segment B",
"segC": "Custom Segment C",
"crossId1": "Standard Episode ID",
"crossId2": "Content Originator ID",
"airdate": "20161013 20:00:00",
"adloadtype": "2",
"hasAds": "1",
"progen": "CV"
}</syntaxhighlight>

===== Ad Metadata =====
The ad metadata should be passed for each individual ad.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || <code>"preroll"</code>, <code>"midroll"</code>, or <code>"postroll"</code> || Yes
|-
| assetid || unique ID assigned to ad || custom || Yes
|}

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "AD-ID123"
}
</syntaxhighlight>

=== Configure Payload: Events ===

The last part of the payload is for enabling events so content is measured correctly when viewed. The events and required parameters are included below.

==== Event Types ====

The available events are:
{| class="wikitable"
|-
! Event !! Description
|-
| <code>"playhead"</code> || Playhead position in seconds. Must be passed as a whole number every 10 seconds. The final playhead position should also be sent before an asset has changed to properly capture full duration. Playhead is used to handle pause and scrubbing. When content is paused, stop passing playhead position.
|-
| <code>"complete"</code> || Complete event must be sent when the content has completed full playback or if a user has initiated a Stop. Before calling the complete event, a final playhead update with the final position is required to be sent to receive full duration credit. Complete does not need to be called if a user transitions videos (e.g. channel change or selecting a new VOD asset) before the video completes.
|-
| <code>"delete"</code> || The delete event should be sent when the application is exited and the viewing session is completed. After 30 minutes of inactivity, the session will expire automatically. All creditable duration will be summarized for all asset types when delete occurs (content and ads). Note that the delete event may not be feasible on certain platforms that do not offer the necessary callbacks to trigger this event.
|}

===== Event Parameters =====

The following parameters need to be passed when calling events:

{| class="wikitable"
|-
! Parameter !! Description !! Value !! Required
|-
| <code>"event"</code> || event type || <code>"playhead"</code>, <code>"complete"</code>, or <code>"delete"</code> || Yes
|-
| <code>"position"</code> || creditable position || playhead position in seconds or UTC timestamp in seconds for livestream || Yes
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || Yes
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || Yes
|}

===== Example Event =====
You can call events by passing values in the required parameters:

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"metadata": {
"static": [static metadata],
"content": [content metadata],
"ad": [ad metadata]
},
// Event Parameters
"event": [event], // event name
"position": [playheadPosition], //position in seconds
"type": [asset type], // values are "content" or "ad"
"utc": "1472760000000" //unix timestamp in milliseconds
}
</syntaxhighlight>

'''Note:''' The full payload including "devInfo" and "metadata" must be populated in each event request.

===== Sample Event Lifecycle =====
The sample event lifecycle can be used as a reference for identifying the order for calling events and values to pass.

<syntaxhighlight lang="javascript">
// Start of Session: session ID created when App is opened

// Preroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472760000000"}

// Midroll
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content resumes at 15 minutes
Content Playhead {"event": "playhead", "position": "900", "type": "content", "utc": "1472760000000"}

// Content completes at 30 minutes
Complete {"event": "complete", "position": "1800", "type": "content", "utc": "1472760000000"}

// Postroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472760000000"}
</syntaxhighlight>

'''Sample Event Lifecycle - Detailed Storyline'''
This detailed event sequence provides additional insight for the correct events to call when handling certain playback scenarios.
<syntaxhighlight lang='javascript'>// SESSION STARTS
// Start of Session: session ID created when App is opened

// PREROLL
// Preroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Preroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "15", "type": "ad", "utc": "1472761500000"}

// CONTENT
// Content Start - Start new content streams with a position of "0" incrementing the position every 10 seconds.
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472761500000"}

// Content Stop Before Ad Break - Send a playhead update including the current content positon before an Ad break.
Content Playhead {"event": "playhead", "position": "299", "type": "content", "utc": "1472787400000"}

// MIDROLL
// Midroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472787500000"}

// Midroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "60", "type": "ad", "utc": "1472793500000"}

// CONTENT
// Content resumes at 5 minutes - Send playhead update with the current resumed position, and begin incrimenting the positon every 10 seconds.
Content Playhead {"event": "playhead", "position": "300", "type": "content", "utc": "1472799500000"}

// Content completes at 10:12 - Make sure to send in the playhead event with the final content position before sending the complete event.
Final Content Playhead {"event": "playhead", "position": "612", "type": "content", "utc": "1472830700000"}

Complete {"event": "complete", "position": "612", "type": "content", "utc": "1472830800000"}

// POSTROLL
// Postroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472830900000"}

// Postroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "45", "type": "ad", "utc": "1472835300000"}

// SESSION ENDS

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472835400000"} </syntaxhighlight>

=====Handling Playhead=====
Calling <code>"playhead"</code> is critical for accurate duration crediting. You can reference the below guidance to determine the correct playhead position to pass depending on the playback scenario.

'''Playhead: General'''
* Playhead position must start at 0 for each new asset, and be passed at least every 10 seconds.
* Final postion must be sent at the end of content or an ad

'''Playhead: Ads'''
* The final position must be sent when switching from content to ad, or ad to content.
* Each ad playhead position should be 0 at ad start.
* For Ad Pods, playhead must be called, and reset to 0 for each individual ad.
* The last content position before an Ad should be sent before switching to Ads.
* When content has resumed following an ad break, the playhead position update must continue where the previous content segment left off.

'''Playhead: User Actions'''
* Upon user scrubbing, the current position must be sent before a user scrubs, and the new position should be sent where the user lands, and begin sending in the 10 second updates thereafter.
* On pause, send the current position and then discontinue sending playhead event updates.
* If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

===== Interruption Scenarios =====

As part of configuring events, you will need to handle all possible interruption scenarios such as:

*Wi-Fi OFF / ON
*App going Background / Foreground (Video players only, not for Audio players)
*App Crash or Exit

When playback is interrupted, the app needs to send delete immediately.

Once playback resumes, a new session will need to be created with a unique session ID. All of the required metadata and events will need to be sent.

'''Note:''' The session will automatically timeout after 30 minutes of inactivity.

=== Example Request ===

Now that we walked through the Cloud API integration steps, your requests should have the following components: Session ID, App ID, and Payload. You can reference the example below when your reviewing your integration.

<syntaxhighlight lang="javascript">
// 1. Create Session ID
sessionID = Date.now()+String(Math.random()*1000000 >> 0); // Must be GUID for each viewing session

// 2. Define URL Structure with App ID and Session ID
sessionURL = https://sandbox-cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2", // ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}

// Append payload to URL
var image = new Image()
image.onerror = function() {
// wait and send again
}
(new Image).src = sessionURL+encodeURI(JSON.stringify(payload));
</syntaxhighlight>

==== Enable Debug Logging ====

Now that you have set up the Cloud API requests, you can enable debug logging to validate your integration. Enabling debug logging is required for Nielsen certification.

==== GET Request ====

Display GET Request to console using a name to identify each event (e.g. playhead).

<syntaxhighlight lang="javascript">
console.log("Event", image);
</syntaxhighlight>

==== Payload ====

Output payload to identify required metadata and events.

<syntaxhighlight lang="javascript">
console.log("Event Payload", payload);
</syntaxhighlight>

==== HTTP Response Code ====

Confirm request was completed by viewing HTTP response code.

<syntaxhighlight lang="javascript">
code = msg.GetResponseCode();
console.log("Response Code", code);
</syntaxhighlight>

You can reference the HTTP Response Code table when reviewing your requests:

{| class="wikitable"
|-
! Status Code !! Status Text !! Description
|-
| <code>200</code> || OK || request received
|-
| <code>403</code> || Forbidden || invalid App ID
|-
| <code>404</code> || Not Found || JSON issue
|}

== Opt-Out ==
Your app must provide a means for the user to Opt-Out, or Opt-In to Nielsen Measurement. This requirement can be fulfilled by checking the device OS for the user's setting of "Limit Ad Tracking" or similar option. If the device offers "Limit Ad Tracking" settings, you must set uoo=true or uoo=false depending on the user's privacy setting. Also, ensure that the devId is set to a blank value if the user elects to opt-out.

If the device does not have OS-level "Do Not Track" settings, you can implement opt-out by creating an Opt-Out/Opt-In button, toggle switch, or slider within the app "Settings", or "About" section to allow the user selection. If you have the ability to render text within the Opt-Out screen, it is recommended to add the Privacy Information included below.

[[File:Nielsen Opt-Out.png|link=]]

You will need to store the User Opt-Out (uoo) status, so that it can be retrieved and populated in the <code>"devInfo"</code> metadata which will be sent in every Cloud API event (playhead, complete, & delete).

{| class="wikitable"
|-
! uoo Key !! Description !! Values
|-
| uoo || Device is Opted-In to Nielsen Measurement (Recommended Default Setting) || <code>"false"</code>
|-
| uoo || Device is Opted-Out of Nielsen Measurement || <code>"true"</code>
|}

===== devInfo Opt-In JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Roku Sample App",
"apv": "1",
"devId": "7be25cf9-8c40-5cc2-871e-19bf41940288",
"uoo": "false"
},
</syntaxhighlight>

===== devInfo Opt-Out JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Roku Sample App",
"apv": "1",
"devId": "", //devId must be blank when a user elects to Opt-Out.
"uoo": "true"
},
</syntaxhighlight>

===== Privacy Information Template To Include In Opt-Out Screen =====

<blockquote>
'''''ABOUT NIELSEN MEASUREMENT'''''

Television and the way we watch it have come a long way since Nielsen began measuring TV audiences in 1950. Today, the ability to watch our favorite shows at any time and on multiple devices amplifies the need for exceptionally adept and flexible audience measurement capabilities.

Consumers are changing with the times, and the same goes for us. As technology continues to evolve and media companies try new ways to attract viewers, understanding what consumers are watching — and what they're watching on — is more important than ever. Today, viewing video is a personal and mobile experience — anytime and anywhere. Our capabilities provide relevant metrics that are necessary to inform successful marketing and programming and drive continued growth. As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. While our digital measurement products are not used to identify you in any way, they help us and our clients measure and analyze how consumers engage with media across online, mobile and emerging technologies, and offer insights into consumer behavior.

'''''YOUR CHOICES'''''

Nielsen believes that you should have a choice about whether to contribute to our research and insights. To opt out, or opt into Nielsen measurement please toggle your "Limit Ad Tracking" (or similar setting) on your device. If you have this app on more than one device, you will need to opt out of this app on each device. To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

'''''Disclosure Template'''''

Additionally, you must update the App description information from the App Distribution Store with the Nielsen Measurement disclosure below:

This app features Nielsen's proprietary measurement software which will allow you to contribute to market research, like Nielsen's TV Ratings. Please see http://www.nielsen.com/digitalprivacy for more information.
</blockquote>

== Testing ==
Before providing an app build to Nielsen for testing, it is important to run validation checks once you have enabled debug logging.

=== Payload Validation ===

Ensure that all of the required payload data is populating while testing several videos. The following areas are critical to measurement:
*devInfo
*Asset metadata for both content, and ads
*Events
*Opt-Out status

=== Player Events ===
Review event calls:

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset.
*Final playhead position is sent on content, or ad before switching between assets.
*Content metadata remains constant throughout an episode, or clip play.
*Ad metadata is populated appropriately for each individual ad.
*Playhead position update resumes for content after an ad break, and resets to 0 for each individual ad.
*For scrubbing, last current position should be sent while scrubbing occurs, and the new position should also be sent where the user scrubs to.
*Exiting a stream early should execute the last current position in a playhead update to receive accurate duration.
*Upon pause, the current position should be sent, and playhead updates should stop incrementing until resume play occurs.

==== complete ====
*Check that the complete event executes upon content complete after the final playhead update is sent
*Do not execute the complete event for ads

==== delete ====
*Check to see that the delete event occurs upon app exit, if the platform has the necessary exit callback events.

==== GET Request Format ====
*Ensure that the event payloads are formatted in JSON
*Check to see that each of the Cloud API GET requests are properly encoded

==== HTTP Response ====
*Make sure that each of the Cloud API Get requests are received by the Nielsen Cloud API properly through use of the HTTP Response Code outputs enabled in console.

==== Opt-Out ====
*Test the "uoo" key gets populated accurately for both Opt-In and Opt-Out selections by validating the Cloud API events called after the user Opt-Out/Opt-In selection.
*Test that the devId field is populated with a blank value if a user has elected to Opt-Out. For example: "devId": "",
*If the device supports "Limit Ad Tracking" or has device "Opt-Out" settings, test that uoo=true, and that devId is set to a blank value if enabled in the device settings.

== Go Live ==
After your integration has been certified, you will need to: Change Endpoint and Disable Logging.

'''Change Endpoint:''' You will need to update to the production endpoint:

*Testing: <code>https://sandbox-cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

Your production URL structure should now be:
<code>https://cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</code>

'''Disable Logging:''' You can now disable debug logging

DCR Video & Static Cloud API

2018-03-22T02:07:08Z

RyanCarlson: sandbox

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR) measurement on your over-the-top (OTT) Apps.
*For Roku Apps, please see [[DCR Video & Static Roku Cloud API]]
*For Mobile Apps, please see [[DCR Video & Static Mobile Cloud API]]

==Prerequisites==
To get started, you will need a Nielsen App ID. The App ID is a unique ID assigned to your app. This will be provided to you upon starting the integration.

<syntaxhighlight lang="javascript">XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

==Integration==
We will cover the steps for constructing the Cloud API Calls.

===Request Overview===

====URL Structure====

The Cloud API Calls are HTTP GET Requests with the URL structure:

<syntaxhighlight lang="javascript">[endpoint]/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

The URL includes the following components:

*<code>[endpoint]</code>: location of data collection environment
*<code>[appid]</code>: provided App ID
*<code>[sessionID]</code>: unique value for each user session
*<code>[payload]</code>: metadata and events

====Endpoint====

There are endpoints for testing and production:

*Testing: <code>https://sandbox-cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

During testing, all calls should be pointed to the testing endpoint. We will review the update to the production endpoint during the Go Live section of this guide.

====URL Example====
As you move through the integration steps, you can reference the below URL structure with the expanded payload:

<syntaxhighlight lang="javascript">
http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"static": [static_metadata],
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [UTC]
}
</syntaxhighlight>

===Create Session ID===
A unique Session ID must be created upon app launch and provided in the URL. This will allow measurement to occur for the entire duration that a user is within the app.

The session ID must be a GUID that is passed with every request and remain consistent throughout each individual session. You can use an existing ID, a random number, or date.now() as shown in the recommended sample code below:

<syntaxhighlight lang="javascript">sessionID = Date.now()+String(Math.random()*1000000 >> 0);</syntaxhighlight>

Upon exiting the app, the session will need to be terminated using the delete event. Sessions will automatically expire after 30 minutes of cloud inactivity.

===Define URL Structure===
Define the URL structure using your provided <code>[appid]</code> and a unique <code>[sessionID]</code>.

<syntaxhighlight lang="javascript">http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

===Configure Payload===

All Cloud API requests must contain the following payload data:

*''devInfo'': device and app info
*''metadata'': asset metadata
*''event metadata'': type of event

The payload can be passed through key-values using the Nielsen reserved keys. The specific keys and descriptions are highlighted in the tables included in this section.

'''Payload Example'''

The example below should be referenced when following the steps for configuring the request payload.

<syntaxhighlight lang="javascript">
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2" //ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}
</syntaxhighlight>

=====Configure Payload: devInfo=====
An object <code>"devInfo"</code> will need to be created to capture App and Device information.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| devId || unique ID to identify user (e.g. Advertising ID, Roku Device ID) || custom || Yes
|-
| apn || app name || custom || Yes
|-
| apv || app build version || custom || Yes
|-
| uoo || device opt-out status || <code>"true"</code> or <code>"false"</code> || Yes
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},
</syntaxhighlight>

==== 3.2 Configure Payload: metadata ====
Asset metadata can be passed through <code>"metadata"</code>. There are two asset types: <code>"content"</code> for video and <code>"ad"</code> for ads. The metadata received for each asset is used for classification and reporting.

You will need to set up <code>"metadata"</code> objects for <code>"content"</code> and <code>"ad"</code> with the required Nielsen keys as shown in the sample code below.

===== Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>"content"</code> || Yes
|-
| assetid || unique ID assigned to asset || custom || Yes
|-
| program ||name of program (25 character limit) || custom || Yes
|-
| title ||name of program (25 character limit) || custom || Yes
|-
| length || length of content in seconds || <code>seconds</code> (86400 for live stream) || Yes
|-
| segB || custom segment B || custom ||
|-
| segC || custom segment C || custom ||
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH24:MI:SS || Yes
|-
| isfullepisode || full episode flag || <code>"y"</code>- full episode, <code>"n"</code>- non full episode || Yes
|-
| crossId1 || standard episode ID || custom || Yes
|-
| crossId2 || content originator (only required for distributors) || Nielsen ||
|-
| adloadtype || type of ad load:
<code>"1"</code> Linear – matches TV ad load

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|-
| hasAds || ads indicator
<code>"1"</code>: ads included

<code>"0"</code>: ads not included
|| <code>"1"</code> or <code>"0"</code> || Yes
|-
| progen || Genre (required only for non-TV originated content). See [[DCR OTT Genre List]] for accepted values || <code>"CV"</code> for Comedy Variety || Required for non-TV originated content
|}

'''Example Content Object'''
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "VIDEO-ID123",
"isfullepisode": "y",
"program": "Program Name",
"title": "Episode Title S3 - EP1",
"length": "1800",
"segB": "Custom Segment B",
"segC": "Custom Segment C",
"crossId1": "Standard Episode ID",
"crossId2": "Content Originator ID",
"airdate": "20161013 20:00:00",
"adloadtype": "2",
"hasAds": "1",
"progen": "CV"
}</syntaxhighlight>

===== Ad Metadata =====
The ad metadata should be passed for each individual ad.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || <code>"preroll"</code>, <code>"midroll"</code>, or <code>"postroll"</code> || Yes
|-
| assetid || unique ID assigned to ad || custom || Yes
|}

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "AD-ID123"
}
</syntaxhighlight>

=== Configure Payload: Events ===

The last part of the payload is for enabling events so content is measured correctly when viewed. The events and required parameters are included below.

==== Event Types ====

The available events are:
{| class="wikitable"
|-
! Event !! Description
|-
| <code>"playhead"</code> || Playhead position in seconds. Must be passed as a whole number every 10 seconds. The final playhead position should also be sent before an asset has changed to properly capture full duration. Playhead is used to handle pause and scrubbing. When content is paused, stop passing playhead position.
|-
| <code>"complete"</code> || Complete event must be sent when the content has completed full playback or if a user has initiated a Stop. Before calling the complete event, a final playhead update with the final position is required to be sent to receive full duration credit. Complete does not need to be called if a user transitions videos (e.g. channel change or selecting a new VOD asset) before the video completes.
|-
| <code>"delete"</code> || The delete event should be sent when the application is exited and the viewing session is completed. After 30 minutes of inactivity, the session will expire automatically. All creditable duration will be summarized for all asset types when delete occurs (content and ads). Note that the delete event may not be feasible on certain platforms that do not offer the necessary callbacks to trigger this event.
|}

===== Event Parameters =====

The following parameters need to be passed when calling events:

{| class="wikitable"
|-
! Parameter !! Description !! Value !! Required
|-
| <code>"event"</code> || event type || <code>"playhead"</code>, <code>"complete"</code>, or <code>"delete"</code> || Yes
|-
| <code>"position"</code> || creditable position || playhead position in seconds or UTC timestamp in seconds for livestream || Yes
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || Yes
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || Yes
|}

===== Example Event =====
You can call events by passing values in the required parameters:

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"metadata": {
"static": [static metadata],
"content": [content metadata],
"ad": [ad metadata]
},
// Event Parameters
"event": [event], // event name
"position": [playheadPosition], //position in seconds
"type": [asset type], // values are "content" or "ad"
"utc": "1472760000000" //unix timestamp in milliseconds
}
</syntaxhighlight>

'''Note:''' The full payload including "devInfo" and "metadata" must be populated in each event request.

===== Sample Event Lifecycle =====
The sample event lifecycle can be used as a reference for identifying the order for calling events and values to pass.

<syntaxhighlight lang="javascript">
// Start of Session: session ID created when App is opened

// Preroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472760000000"}

// Midroll
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content resumes at 15 minutes
Content Playhead {"event": "playhead", "position": "900", "type": "content", "utc": "1472760000000"}

// Content completes at 30 minutes
Complete {"event": "complete", "position": "1800", "type": "content", "utc": "1472760000000"}

// Postroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472760000000"}
</syntaxhighlight>

'''Sample Event Lifecycle - Detailed Storyline'''
This detailed event sequence provides additional insight for the correct events to call when handling certain playback scenarios.
<syntaxhighlight lang='javascript'>// SESSION STARTS
// Start of Session: session ID created when App is opened

// PREROLL
// Preroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Preroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "15", "type": "ad", "utc": "1472761500000"}

// CONTENT
// Content Start - Start new content streams with a position of "0" incrementing the position every 10 seconds.
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472761500000"}

// Content Stop Before Ad Break - Send a playhead update including the current content positon before an Ad break.
Content Playhead {"event": "playhead", "position": "299", "type": "content", "utc": "1472787400000"}

// MIDROLL
// Midroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472787500000"}

// Midroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "60", "type": "ad", "utc": "1472793500000"}

// CONTENT
// Content resumes at 5 minutes - Send playhead update with the current resumed position, and begin incrimenting the positon every 10 seconds.
Content Playhead {"event": "playhead", "position": "300", "type": "content", "utc": "1472799500000"}

// Content completes at 10:12 - Make sure to send in the playhead event with the final content position before sending the complete event.
Final Content Playhead {"event": "playhead", "position": "612", "type": "content", "utc": "1472830700000"}

Complete {"event": "complete", "position": "612", "type": "content", "utc": "1472830800000"}

// POSTROLL
// Postroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472830900000"}

// Postroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "45", "type": "ad", "utc": "1472835300000"}

// SESSION ENDS

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472835400000"} </syntaxhighlight>

=====Handling Playhead=====
Calling <code>"playhead"</code> is critical for accurate duration crediting. You can reference the below guidance to determine the correct playhead position to pass depending on the playback scenario.

'''Playhead: General'''
* Playhead position must start at 0 for each new asset, and be passed at least every 10 seconds.
* Final postion must be sent at the end of content or an ad

'''Playhead: Ads'''
* The final position must be sent when switching from content to ad, or ad to content.
* Each ad playhead position should be 0 at ad start.
* For Ad Pods, playhead must be called, and reset to 0 for each individual ad.
* The last content position before an Ad should be sent before switching to Ads.
* When content has resumed following an ad break, the playhead position update must continue where the previous content segment left off.

'''Playhead: User Actions'''
* Upon user scrubbing, the current position must be sent before a user scrubs, and the new position should be sent where the user lands, and begin sending in the 10 second updates thereafter.
* On pause, send the current position and then discontinue sending playhead event updates.
* If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

===== Interruption Scenarios =====

As part of configuring events, you will need to handle all possible interruption scenarios such as:

*Wi-Fi OFF / ON
*App going Background / Foreground (Video players only, not for Audio players)
*App Crash or Exit

When playback is interrupted, the app needs to send delete immediately.

Once playback resumes, a new session will need to be created with a unique session ID. All of the required metadata and events will need to be sent.

'''Note:''' The session will automatically timeout after 30 minutes of inactivity.

=== Example Request ===

Now that we walked through the Cloud API integration steps, your requests should have the following components: Session ID, App ID, and Payload. You can reference the example below when your reviewing your integration.

<syntaxhighlight lang="javascript">
// 1. Create Session ID
sessionID = Date.now()+String(Math.random()*1000000 >> 0); // Must be GUID for each viewing session

// 2. Define URL Structure with App ID and Session ID
sessionURL = http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2", // ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}

// Append payload to URL
var image = new Image()
image.onerror = function() {
// wait and send again
}
(new Image).src = sessionURL+encodeURI(JSON.stringify(payload));
</syntaxhighlight>

==== Enable Debug Logging ====

Now that you have set up the Cloud API requests, you can enable debug logging to validate your integration. Enabling debug logging is required for Nielsen certification.

==== GET Request ====

Display GET Request to console using a name to identify each event (e.g. playhead).

<syntaxhighlight lang="javascript">
console.log("Event", image);
</syntaxhighlight>

==== Payload ====

Output payload to identify required metadata and events.

<syntaxhighlight lang="javascript">
console.log("Event Payload", payload);
</syntaxhighlight>

==== HTTP Response Code ====

Confirm request was completed by viewing HTTP response code.

<syntaxhighlight lang="javascript">
code = msg.GetResponseCode();
console.log("Response Code", code);
</syntaxhighlight>

You can reference the HTTP Response Code table when reviewing your requests:

{| class="wikitable"
|-
! Status Code !! Status Text !! Description
|-
| <code>200</code> || OK || request received
|-
| <code>403</code> || Forbidden || invalid App ID
|-
| <code>404</code> || Not Found || JSON issue
|}

== Opt-Out ==
Your app must provide a means for the user to Opt-Out, or Opt-In to Nielsen Measurement. This requirement can be fulfilled by checking the device OS for the user's setting of "Limit Ad Tracking" or similar option. If the device offers "Limit Ad Tracking" settings, you must set uoo=true or uoo=false depending on the user's privacy setting. Also, ensure that the devId is set to a blank value if the user elects to opt-out.

If the device does not have OS-level "Do Not Track" settings, you can implement opt-out by creating an Opt-Out/Opt-In button, toggle switch, or slider within the app "Settings", or "About" section to allow the user selection. If you have the ability to render text within the Opt-Out screen, it is recommended to add the Privacy Information included below.

[[File:Nielsen Opt-Out.png|link=]]

You will need to store the User Opt-Out (uoo) status, so that it can be retrieved and populated in the <code>"devInfo"</code> metadata which will be sent in every Cloud API event (playhead, complete, & delete).

{| class="wikitable"
|-
! uoo Key !! Description !! Values
|-
| uoo || Device is Opted-In to Nielsen Measurement (Recommended Default Setting) || <code>"false"</code>
|-
| uoo || Device is Opted-Out of Nielsen Measurement || <code>"true"</code>
|}

===== devInfo Opt-In JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Roku Sample App",
"apv": "1",
"devId": "7be25cf9-8c40-5cc2-871e-19bf41940288",
"uoo": "false"
},
</syntaxhighlight>

===== devInfo Opt-Out JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Roku Sample App",
"apv": "1",
"devId": "", //devId must be blank when a user elects to Opt-Out.
"uoo": "true"
},
</syntaxhighlight>

===== Privacy Information Template To Include In Opt-Out Screen =====

<blockquote>
'''''ABOUT NIELSEN MEASUREMENT'''''

Television and the way we watch it have come a long way since Nielsen began measuring TV audiences in 1950. Today, the ability to watch our favorite shows at any time and on multiple devices amplifies the need for exceptionally adept and flexible audience measurement capabilities.

Consumers are changing with the times, and the same goes for us. As technology continues to evolve and media companies try new ways to attract viewers, understanding what consumers are watching — and what they're watching on — is more important than ever. Today, viewing video is a personal and mobile experience — anytime and anywhere. Our capabilities provide relevant metrics that are necessary to inform successful marketing and programming and drive continued growth. As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. While our digital measurement products are not used to identify you in any way, they help us and our clients measure and analyze how consumers engage with media across online, mobile and emerging technologies, and offer insights into consumer behavior.

'''''YOUR CHOICES'''''

Nielsen believes that you should have a choice about whether to contribute to our research and insights. To opt out, or opt into Nielsen measurement please toggle your "Limit Ad Tracking" (or similar setting) on your device. If you have this app on more than one device, you will need to opt out of this app on each device. To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

'''''Disclosure Template'''''

Additionally, you must update the App description information from the App Distribution Store with the Nielsen Measurement disclosure below:

This app features Nielsen's proprietary measurement software which will allow you to contribute to market research, like Nielsen's TV Ratings. Please see http://www.nielsen.com/digitalprivacy for more information.
</blockquote>

== Testing ==
Before providing an app build to Nielsen for testing, it is important to run validation checks once you have enabled debug logging.

=== Payload Validation ===

Ensure that all of the required payload data is populating while testing several videos. The following areas are critical to measurement:
*devInfo
*Asset metadata for both content, and ads
*Events
*Opt-Out status

=== Player Events ===
Review event calls:

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset.
*Final playhead position is sent on content, or ad before switching between assets.
*Content metadata remains constant throughout an episode, or clip play.
*Ad metadata is populated appropriately for each individual ad.
*Playhead position update resumes for content after an ad break, and resets to 0 for each individual ad.
*For scrubbing, last current position should be sent while scrubbing occurs, and the new position should also be sent where the user scrubs to.
*Exiting a stream early should execute the last current position in a playhead update to receive accurate duration.
*Upon pause, the current position should be sent, and playhead updates should stop incrementing until resume play occurs.

==== complete ====
*Check that the complete event executes upon content complete after the final playhead update is sent
*Do not execute the complete event for ads

==== delete ====
*Check to see that the delete event occurs upon app exit, if the platform has the necessary exit callback events.

==== GET Request Format ====
*Ensure that the event payloads are formatted in JSON
*Check to see that each of the Cloud API GET requests are properly encoded

==== HTTP Response ====
*Make sure that each of the Cloud API Get requests are received by the Nielsen Cloud API properly through use of the HTTP Response Code outputs enabled in console.

==== Opt-Out ====
*Test the "uoo" key gets populated accurately for both Opt-In and Opt-Out selections by validating the Cloud API events called after the user Opt-Out/Opt-In selection.
*Test that the devId field is populated with a blank value if a user has elected to Opt-Out. For example: "devId": "",
*If the device supports "Limit Ad Tracking" or has device "Opt-Out" settings, test that uoo=true, and that devId is set to a blank value if enabled in the device settings.

== Go Live ==
After your integration has been certified, you will need to: Change Endpoint and Disable Logging.

'''Change Endpoint:''' You will need to update to the production endpoint:

*Testing: <code>http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

Your production URL structure should now be:
<code>https://cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</code>

'''Disable Logging:''' You can now disable debug logging

DTVR Browser SDK

2017-11-08T22:11:35Z

RyanCarlson: adModel

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Prerequisites ==
To start using the Browser SDK, the following details are required:
* '''App ID (apid):''' Unique ID assigned to the player/site and configured by product.
* '''sfcode:''' Location of collection environment. Please set the sfcode to “dcr“.
If you do not have any of these pre-requisites or if you have any questions, please contact our SDK sales support team.

== Configure SDK ==
There are two steps required for configuring your SDK: 1. Add Static Queue Snippet and 2. Create SDK Instance.

== Add Static Queue Snippet ==
Add the following script tag to your website:

<syntaxhighlight lang="javascript">
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, 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=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(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. Since the queue is able to 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, you will need to create an SDK instance by making the initialization call:

<syntaxhighlight lang="javascript">
NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})
</syntaxhighlight>
<br />
When creating your instance, you will need to pass three parameter values. The available parameters are listed in the table below:

{| class="wikitable"
|-
! Parameters !! Description !! Value !! Required? (Y/N)
|-
| apid || UniqueID assigned to player/site.
|| "XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX" || Yes
|-
| instanceName || User-defined string value for describing the player/site. || Client specified || Yes
|-
| sfcode || Location of collection environment. All traffic should be directed to "dcr". || dcr || Yes
|-
| nol_sdkDebug:"debug" || Enables Debug Mode which allows output to be viewed in console. || "{nol_sdkDebug: "debug"}" || No
|}

== Example SDK Initialization ==
<syntaxhighlight lang="javascript">
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {nol_sdkDebug: "debug"});
</syntaxhighlight>

When the initialization call is made, a unique static configuration file, <apid>.js, will be downloaded based on your apid and 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".

=== Example SDK Initialization ===
Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, 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=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

=== Create Metadata Objects ===
<br />
There are two types of asset metadata:
<br />
*content: identify video
*ad: identify each ad
<br />
The metadata received for each asset is used for classification and reporting.
<br />
Metadata can be passed through key-values using the Nielsen reserved keys. User will need to set up content and ad objects with the required Nielsen keys as shown in the sample code below.
<br />

== Content Metadata ==
<br />
Content metadata should remain constant throughout the completion of an episode or live stream.
<br />
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| type || type of asset || "content" || ✓
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
| adModel || linear vs dynamic ad model || * 1) - Linear – matches TV ad load * 2) Dynamic – Dynamic Ad Insertion (DAI) || ✓
|-
|}
<br/>
'''Example Content Object'''
<syntaxhighlight lang="javascript"> var contentMetadataObject =
{
type: 'content',
channelName: 'Live Player',
adModel: '1'
};</syntaxhighlight>

=== Ad Metadata Object ===
<br/>
The ad metadata should be passed for each individual ad, if ads are available during or before the stream begins.
<br/>
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}
<br/>
'''Example Ad Object'''
<br/>
<syntaxhighlight lang="javascript"> var adMetadataObject =
{
assetid: 'AD-1',
type: 'preroll'
};</syntaxhighlight>

=== SDK Events ===
<br/>
{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each asset to pass type, channelName, and adModel.
|-
| 'sendID3' || Used to send the ID3 tag payload retrieved from the stream || Needs to be called at the beginning of playback
||
|-
| 'end' || playhead position in seconds || Call when the current video asset completes playback or when a stream is interrupted. <br/>
Example: At the end of the content stream, if the user switches to another piece of content, when the browser is refreshed or closed.
|}

== Configure and fire API calls ==
<br />
The syntax for firing events is:
<syntaxhighlight lang="javascript"> nSdkInstance.ggPM("event", parameter object);</syntaxhighlight>
<br />
Event is passed in parameter 1 and the argument is passed in parameter 2.

=== Configure API calls - loadMetadata ===
<br />
Use [[loadMetadata (Browser)]] to pass the metadata object. The data must be passed as a JSON string.
<br />
<syntaxhighlight lang="javascript">nSdkInstance.ggPM("loadMetadata", metadataObject);</syntaxhighlight>

=== Configure API calls - sendID3 ===
<br />
Use [[sendID3 (Browser)]] to send ID3 payload of the HLS content being played. This will allow the ID3 payload to be sent every time an ID3 packet is received (approximately, once in every 10 seconds).
<br />
<syntaxhighlight lang="javascript">nSdkInstance.ggPM("sendID3", ID3_Object);</syntaxhighlight>
<br />
==== Sample ID3 tags ====
<br />
<syntaxhighlight>
www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</syntaxhighlight>
<br />
<syntaxhighlight>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</syntaxhighlight>
<br />
<code>ID3_Object</code> is the container to pass the retrieved ID3 tag from the streaming. The player should look for 'PRIV' ID3 tags and send 'owner' field (which typically starts from "www.nielsen.com") through this API. Refer to [[Browser SDK API Reference#Retrieving ID3 Tags|Browser SDK API Reference - Retrieving ID3 Tags]] for more information.
<br />
<br />
Refer to [[Browser SDK API Reference#Retrieving ID3 Tags|Browser SDK API Reference - Retrieving ID3 Tags]] section to know more details.

=== Configure API calls - end ===
<br />
Call [[end (Browser)]] only at the end of playback, or if the stream is interrupted.
<syntaxhighlight lang="javascript">nSdkInstance.ggPM("end", UTC_Timestamp);</syntaxhighlight>

== SDK DTVR Event Sequence ==
<br/>
The sample event lifecycle can be used as a reference for identifying the order for calling events.
<br/>
<syntaxhighlight lang="javascript"> // START OF STREAM
nSdkInstance.ggPM('loadMetadata', contentMetadataObject);
nSdkInstance.ggPM('sendID3', ID3_Payload);

//Upon completion of a stream, or upon an interruption scenario call 'end' and pass the UTC timestamp

nSdkInstance.ggPM('end', UTC_TIMESTAMP);

</syntaxhighlight>

== Nielsen Opt-Out ==
<br />
The site must provide a means for the user to opt-out of, or opt back into, Nielsen Measurement. A user can opt-out if they would prefer not to participate in any Nielsen online measurement research. To implement the opt-out option, include the following two items in your privacy policy.
<br />
*A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings).
*A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.
<br />
On the Nielsen Digital Measurement Privacy Policy page, users can click Choices to read more detailed information about the measurement software, learn about their options with regard to Nielsen measurement, and, if they do not want to participate in Nielsen online measurement, click a link to receive an opt-out cookie.
<br />
<br>
The following paragraph is a template for an opt-out statement.
<br />
<syntaxhighlight lang="javascript">
The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices, please see the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.
</syntaxhighlight>
<br />

===Opt Back In===
<br />
Once users have opted-out, they can choose to opt back into Nielsen Measurement at anytime by selecting the opt back in link on the Nielsen Digital Privacy Policy page. When a user selects the link, their opt-out cookie will be deleted and they will be able to be measured.
<br />

== Going Live ==
Once the DCR Tracking Code is added to Instant Articles, Nielsen will validate the implementation. Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
# '''App ID''': Ensure that correct <apid> is used during initialization<syntaxhighlight lang="javascript">'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'</syntaxhighlight>
# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");</syntaxhighlight>

DTVR Browser SDK

2017-11-08T22:11:12Z

RyanCarlson: adModel

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Prerequisites ==
To start using the Browser SDK, the following details are required:
* '''App ID (apid):''' Unique ID assigned to the player/site and configured by product.
* '''sfcode:''' Location of collection environment. Please set the sfcode to “dcr“.
If you do not have any of these pre-requisites or if you have any questions, please contact our SDK sales support team.

== Configure SDK ==
There are two steps required for configuring your SDK: 1. Add Static Queue Snippet and 2. Create SDK Instance.

== Add Static Queue Snippet ==
Add the following script tag to your website:

<syntaxhighlight lang="javascript">
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, 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=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(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. Since the queue is able to 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, you will need to create an SDK instance by making the initialization call:

<syntaxhighlight lang="javascript">
NOLBUNDLE.nlsQ("<apid>", "<instanceName>",{nol_sdkDebug: "debug"})
</syntaxhighlight>
<br />
When creating your instance, you will need to pass three parameter values. The available parameters are listed in the table below:

{| class="wikitable"
|-
! Parameters !! Description !! Value !! Required? (Y/N)
|-
| apid || UniqueID assigned to player/site.
|| "XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX" || Yes
|-
| instanceName || User-defined string value for describing the player/site. || Client specified || Yes
|-
| sfcode || Location of collection environment. All traffic should be directed to "dcr". || dcr || Yes
|-
| nol_sdkDebug:"debug" || Enables Debug Mode which allows output to be viewed in console. || "{nol_sdkDebug: "debug"}" || No
|}

== Example SDK Initialization ==
<syntaxhighlight lang="javascript">
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {nol_sdkDebug: "debug"});
</syntaxhighlight>

When the initialization call is made, a unique static configuration file, <apid>.js, will be downloaded based on your apid and 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".

=== Example SDK Initialization ===
Your configuration should include the Static Queue Snippet and an SDK Instance for your unique App ID as shown in the example:

<syntaxhighlight lang="javascript">

//Add Static Queue Snippet
<script>
! function(t, n) {
t[n] = t[n] || {
nlsQ: function(e, o, c, 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=" + o + "&ns=" + n,
i = s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r, i),
t[n][o] = t[n][o] || {
g: c || {},
ggPM: function(e, c, r, s, i) {
(t[n][o].q = t[n][o].q || []).push([e, c, r, s, i])
}
}, t[n][o]
}
}
}
(window, "NOLBUNDLE");

//Create SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

=== Create Metadata Objects ===
<br />
There are two types of asset metadata:
<br />
*content: identify video
*ad: identify each ad
<br />
The metadata received for each asset is used for classification and reporting.
<br />
Metadata can be passed through key-values using the Nielsen reserved keys. User will need to set up content and ad objects with the required Nielsen keys as shown in the sample code below.
<br />

== Content Metadata ==
<br />
Content metadata should remain constant throughout the completion of an episode or live stream.
<br />
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| type || type of asset || "content" || ✓
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
| adModel || linear vs dynamic ad model || * 1) - Linear – matches TV ad load * 2) Dynamic – Dynamic Ad Insertion (DAI) || ✓
|-
|}
<br/>
'''Example Content Object'''
<syntaxhighlight lang="javascript"> var contentMetadataObject =
{
type: 'content',
channelName: 'Live Player',
adModel: '1'
};</syntaxhighlight>

=== Ad Metadata Object ===
<br/>
The ad metadata should be passed for each individual ad, if ads are available during or before the stream begins.
<br/>
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}
<br/>
'''Example Ad Object'''
<br/>
<syntaxhighlight lang="javascript"> var adMetadataObject =
{
assetid: 'AD-1',
type: 'preroll'
};</syntaxhighlight>

=== SDK Events ===
<br/>
{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each asset to pass type, channelName, and adloadtype.
|-
| 'sendID3' || Used to send the ID3 tag payload retrieved from the stream || Needs to be called at the beginning of playback
||
|-
| 'end' || playhead position in seconds || Call when the current video asset completes playback or when a stream is interrupted. <br/>
Example: At the end of the content stream, if the user switches to another piece of content, when the browser is refreshed or closed.
|}

== Configure and fire API calls ==
<br />
The syntax for firing events is:
<syntaxhighlight lang="javascript"> nSdkInstance.ggPM("event", parameter object);</syntaxhighlight>
<br />
Event is passed in parameter 1 and the argument is passed in parameter 2.

=== Configure API calls - loadMetadata ===
<br />
Use [[loadMetadata (Browser)]] to pass the metadata object. The data must be passed as a JSON string.
<br />
<syntaxhighlight lang="javascript">nSdkInstance.ggPM("loadMetadata", metadataObject);</syntaxhighlight>

=== Configure API calls - sendID3 ===
<br />
Use [[sendID3 (Browser)]] to send ID3 payload of the HLS content being played. This will allow the ID3 payload to be sent every time an ID3 packet is received (approximately, once in every 10 seconds).
<br />
<syntaxhighlight lang="javascript">nSdkInstance.ggPM("sendID3", ID3_Object);</syntaxhighlight>
<br />
==== Sample ID3 tags ====
<br />
<syntaxhighlight>
www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_<wbr />JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00</syntaxhighlight>
<br />
<syntaxhighlight>www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGhe<wbr />Fi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8<wbr />QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00</syntaxhighlight>
<br />
<code>ID3_Object</code> is the container to pass the retrieved ID3 tag from the streaming. The player should look for 'PRIV' ID3 tags and send 'owner' field (which typically starts from "www.nielsen.com") through this API. Refer to [[Browser SDK API Reference#Retrieving ID3 Tags|Browser SDK API Reference - Retrieving ID3 Tags]] for more information.
<br />
<br />
Refer to [[Browser SDK API Reference#Retrieving ID3 Tags|Browser SDK API Reference - Retrieving ID3 Tags]] section to know more details.

=== Configure API calls - end ===
<br />
Call [[end (Browser)]] only at the end of playback, or if the stream is interrupted.
<syntaxhighlight lang="javascript">nSdkInstance.ggPM("end", UTC_Timestamp);</syntaxhighlight>

== SDK DTVR Event Sequence ==
<br/>
The sample event lifecycle can be used as a reference for identifying the order for calling events.
<br/>
<syntaxhighlight lang="javascript"> // START OF STREAM
nSdkInstance.ggPM('loadMetadata', contentMetadataObject);
nSdkInstance.ggPM('sendID3', ID3_Payload);

//Upon completion of a stream, or upon an interruption scenario call 'end' and pass the UTC timestamp

nSdkInstance.ggPM('end', UTC_TIMESTAMP);

</syntaxhighlight>

== Nielsen Opt-Out ==
<br />
The site must provide a means for the user to opt-out of, or opt back into, Nielsen Measurement. A user can opt-out if they would prefer not to participate in any Nielsen online measurement research. To implement the opt-out option, include the following two items in your privacy policy.
<br />
*A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings).
*A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.
<br />
On the Nielsen Digital Measurement Privacy Policy page, users can click Choices to read more detailed information about the measurement software, learn about their options with regard to Nielsen measurement, and, if they do not want to participate in Nielsen online measurement, click a link to receive an opt-out cookie.
<br />
<br>
The following paragraph is a template for an opt-out statement.
<br />
<syntaxhighlight lang="javascript">
The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices, please see the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.
</syntaxhighlight>
<br />

===Opt Back In===
<br />
Once users have opted-out, they can choose to opt back into Nielsen Measurement at anytime by selecting the opt back in link on the Nielsen Digital Privacy Policy page. When a user selects the link, their opt-out cookie will be deleted and they will be able to be measured.
<br />

== Going Live ==
Once the DCR Tracking Code is added to Instant Articles, Nielsen will validate the implementation. Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
# '''App ID''': Ensure that correct <apid> is used during initialization<syntaxhighlight lang="javascript">'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'</syntaxhighlight>
# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");</syntaxhighlight>

DTVR Android SDK

2017-11-08T22:10:00Z

RyanCarlson: adModel

DTVR Android SDK

2017-11-08T22:09:38Z

RyanCarlson: adModel

DCR Video Android SDK

2017-11-08T22:06:50Z

RyanCarlson: adloadtype

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Prerequisites ==
To start using the App SDK, the following details are required:
* '''App ID (appid):''' Unique ID assigned to the player/site and configured by product.
* '''sfcode:''' Unique identifier for the environment that the SDK should point to.
* '''Nielsen SDK''' and '''Sample Player''': A part of the downloaded package
If you do not have any of these pre-requisites or if you have any questions, please contact our SDK sales support team.
Refer to [[Digital Measurement Onboarding]] guide for more information on how to get a Nielsen App SDK and appid.

== Import Library ==
Refer to [[Android SDK API Reference#Setting Up Development Environment|Android SDK API Reference - Setting Up Development Environment]] for information on importing libraries.
* The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues.
<blockquote>Note: The latest version of App SDK contains only ''appsdk.jar'' file and does not feature any native shared libraries like ''libAppSdk.so''.</blockquote>

== Initialize SDK ==
Initialize App SDK as soon as the application is launched. Refer to [[Android SDK API Reference#Initialization|Android SDK API Reference - Initialization]] for details on initializing an AppSDK object and the parameters required.

== Configure API calls ==
=== play ===
Use [[play()]] to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player.

=== loadMetadata ===
Use [[loadMetadata()]] to pass 'content' and 'ad' [[Digital Measurement Metadata]]. The CMS data must be passed as a JSON object.
<syntaxhighlight lang="java"> loadMetadata(JSONObject jsonMetadata);</syntaxhighlight>
Refer to [[Digital Measurement Metadata]] section for the list of parameters to be passed in the JSON string.
<blockquote>Note: The [[loadMetadata()]] call after the first [[play()]] call must have 'content' details ("type": "content"). This call should occur before any preroll ad starts playing.</blockquote>

=== setPlayheadPosition (Content) ===
Use [[setPlayheadPosition()]] to pass the position of the playhead while the content is being played.
<syntaxhighlight lang="java"> public AppSdk setPlayheadPosition(long position)</syntaxhighlight>

{| class="wikitable"
|-
! # !! Key !! Description !! Values !! Required? (Y/N) !! Example
|-
| 1 || Live** || UTC of the live content || Client-defined || Yes || Seconds since 1970
|-
| 2 || Video On Demand (VOD)** || Position taken from beginning of the content in seconds. || Client-defined || Yes || Current player position from beginning of the content.
|}
<nowiki>**</nowiki>Only one of these parameters is mandatory
<blockquote>Note: If playhead is not available from audio / video measurement, allow the app to start a timer (1-5 seconds) and send playhead position to SDK based on the timer event. Once the actual playhead is available, let the app send the proper playhead position. This allows the SDK to calculate and provide a closer value for duration.</blockquote>

'''Buffering state'''
* Do not supply playhead position while the content is being buffered.
* If the content is in buffering state continuously for more than 30 seconds, call the [[stop | stop()]] API.

'''Live Content'''
<syntaxhighlight lang="java"> Calendar c = Calendar.getInstance();
long pos = (c.getTimeInMillis()/ 1000);
if (mAppSdk != null)
{
mAppSdk.setPlayheadPosition(pos);
}</syntaxhighlight>

'''On-demand Content'''
<syntaxhighlight lang="java"> long pos = mPlayer.videoPosition() / 1000;
if (mAppSdk != null)
{
mAppSdk.setPlayheadPosition(pos);
}</syntaxhighlight>

=== setPlayheadPosition (Ad) ===
Use [[setPlayheadPosition()]] to pass the position of the playhead while the advertisement is being played.
<syntaxhighlight lang="java"> public AppSdk setPlayheadPosition(long position)</syntaxhighlight>

{| class="wikitable"
|-
! Key !! Description !! Values !! Required? (Y/N) !! Example
|-
| Ad || Position taken from beginning of the ad in seconds || Client-defined || Yes || Seconds since start of the ad
|}

'''Ad Content'''
<syntaxhighlight lang="java"> long pos = mAdPlayer.videoPosition() / 1000;
if (mAppSdk != null)
{
mAppSdk.setPlayheadPosition(pos);
}</syntaxhighlight>
<blockquote>Note: The playhead positions for ad and content should be maintained separately.</blockquote>

=== stop ===
Call [[stop | stop()]] only at the end of ad and when the stream playback is stopped by a user or an interruption from another event. Common events are; network loss, power / standby, incoming call, alarm, etc. Call [[stop | stop()]] only when buffering continues for 30 seconds (not when it starts). Call [[loadMetadata()]] and [[setPlayheadPosition()]] when a previously stopped stream resumes. Call [[play | play()]] when starting playback of a new stream.

=== end ===
Call [[end()]] only at the end of playback.

=== API Call sequence ===
==== Use Case 1: Content has no Advertisements ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
"segB": "CustomSegmentValueB",
"segC": "CustomSegmentValueC",
"crossId1": "Reference11",
"crossId2": "Reference22",
"isfullepisode": "y",
"airdate": "20161013 20:00:00",
"adloadtype": "2",
"progen":"GV"
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause / stop.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelName); </code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Advertisements ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad=123"
}</syntaxhighlight>
<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / stop / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelName); </code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="3" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after the content is paused (ad starts)
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="3" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| <code>mAppSdk.stop();</code> || // Always call stop irrespective of postroll is followed or not
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Handling Foreground and Background states of App ==
There are two ways of handling the foreground and background states of the client application.
* Let App SDK handle the app states information (foreground / background) and use it, as necessary. See [[#New_devices_.28Android_4.0_and_later_versions.29]] for more information.
* Capture app states through the application and trigger the corresponding API ([[appInForeground()]] or [[appInBackground()]]) upon every change of state. This allows Nielsen App SDK to know the app state. See [[#Older_devices_.28Android_4.0_or_earlier_versions.29]] for more information.

=== New devices (Android 4.0 and later versions) ===
'''Add ''application'' tag to Manifest XML file'''
When client's app supports only new devices (Android 4.0 and above) and the client has not implemented a custom Application class for some other purpose,
* Add the following entry (application tag) into the Manifest XML file to use SDK's state detection feature.
<syntaxhighlight lang="java"> <application android:name="com.nielsen.app.sdk.AppSdkApplication"></syntaxhighlight>
This is the custom Application class where the whole background detection implementation is done.
<blockquote>Note: No new permissions are required to change the properties in Manifest XML file.</blockquote>

=== Older devices (Android 4.0 or earlier versions) ===
Identify the change of state through the application and call the respective API ([[appInForeground()]] or [[appInBackground()]]) upon every change of state (foreground / background). The SDK will use this information to pass the app launch times, etc. to Collection facility.
<syntaxhighlight lang="java"> AppLaunchMeasurementManager.appInForeground(getApplicationContext());
AppLaunchMeasurementManager.appInBackground(getApplicationContext());</syntaxhighlight>

== Interruptions during playback ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call [[stop()]] immediately (except when content is buffering) and withhold sending playhead position.
* Start sending pings – [[loadMetadata()]] and [[setPlayheadPosition()]] for the new viewing session, once the playback resumes.
Please see the [[Digital Measurement FAQ]] for more details

== Nielsen Measurement Opt-Out Implementation ==
As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. Our digital measurement products are not used to identify the consumer in any way, but they help us and our clients measure and analyze how consumers engage with media across online, mobile and emerging technologies, and offer insights into consumer behavior.
* When the app user wants to opt in or opt out of Nielsen measurement, a new dynamic page (with content string obtained from [[userOptOutURLString()]]) should be displayed.
* Use [[getOptOutStatus()]] to retrieve the device's Opt-Out status.
* This Opt-out page should be displayed in a webview (within the app) and not in any external browser.
* Capture the user's selection in this page and pass it to the SDK through [[userOptOut()]] for Nielsen to save the user's preference.
* For more details, refer to [[Android SDK API Reference#Android Opt-Out Implementation|Android SDK API Reference - Android Opt-Out Implementation]] and Nielsen Digital Privacy.

== Pre-Certification Checklists ==
After the application is ready to be sent for Nielsen Certification, please go through the Pre-Certification Checklist and ensure the app behaves as expected, before submitting to Nielsen.

== Testing an Implementation - App ==
See [[Digital Measurement Testing]].

DCR Video iOS SDK

2017-11-08T22:05:45Z

RyanCarlson: adloadtype

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Prerequisites ==
To start using the App SDK, the following details are required:
* '''App ID (appid):''' Unique ID assigned to the player/site and configured by product.
* '''sfcode:''' Unique identifier for the environment that the SDK should point to.
* '''Nielsen SDK''' and '''Sample Player''': A part of the downloaded package
If you do not have any of these pre-requisites or if you have any questions, 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.

== Import Library ==
Refer to [[iOS SDK API Reference#Importing Frameworks|iOS SDK API Reference - Importing Frameworks]] for information on importing libraries.
* The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues.

== Initialize SDK ==
Initialize App SDK as soon as the application is launched. Refer to [[iOS SDK API Reference#Initialization|iOS SDK API Reference - Initialization]] for details on initializing an AppSDK object and the parameters required.

== Configure API calls ==
=== play ===
Use [[play]] to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player.

=== loadMetadata ===
Use [[loadMetadata]] to pass 'content' and 'ad' [[Digital Measurement Metadata]]. The CMS data must be passed as a JSON object.
<syntaxhighlight lang="objective-c"> – (void) loadMetadata :(id)metadata;</syntaxhighlight>
Refer to [[loadMetadata]] for the list of parameters to be passed in the JSON object.
<blockquote>'''Note:''' The [[loadMetadata]] call after the first [[play]] call must have ‘content’ details ("type": "content"). This call should occur before any preroll ad starts playing.</blockquote>

=== playheadPosition (Content) ===
Use [[playheadPosition]] to pass the position of the playhead while the content is being played.
<syntaxhighlight lang="objective-c"> – (void) playheadPosition: (long long) playheadPos</syntaxhighlight>
{| class="wikitable"
|-
! # !! Key !! Description !! Values !! Required? (Y/N) !! Example
|-
| 1 || Live** || UTC of the live content || Client-defined || Yes || Seconds since 1970
|-
| 2 || Video On Demand (VOD)** || Position taken from beginning of the content in seconds. || Client-defined || Yes || Current player position from beginning of the content.
|}
<nowiki>**</nowiki>''Only one of these parameters is mandatory''
<blockquote>'''Note:''' If playhead is not available from audio / video measurement, allow the app to start a timer (1-5 seconds) and send playhead position to SDK based on the timer event. Once the actual playhead is available, let the app send the proper playhead position. This allows the SDK to calculate and provide a closer value for duration.</blockquote>

'''Buffering state'''
* Do not supply playhead position while the content is being buffered.
* If the content is in buffering state continuously for more than 30 seconds, call [[stop]] API.

'''Live Content'''
<syntaxhighlight lang="objective-c"> long long pos = [[NSDate date] timeIntervalSince1970];
[nAppApiObject playheadPosition:pos];</syntaxhighlight>

'''On-demand Content'''
<syntaxhighlight lang="objective-c"> CMTime curTime=[player currentTime];
long pos=CMTimeGetSeconds(curTime);
[nAppApiObject playheadPosition:pos];</syntaxhighlight>

=== playheadPosition (Ad) ===
Use [[playheadPosition]] to pass the position of the playhead while the advertisement is being played.
<syntaxhighlight lang="objective-c"> – (void) playheadPosition: (long long) playheadPos</syntaxhighlight>

{| class="wikitable"
|-
! Key !! Description !! Values !! Required? (Y/N) !! Example
|-
| Ad || Position taken from beginning of the ad in seconds || Client-defined || Yes || Seconds since tart of the ad
|}

'''Ad Content'''
<syntaxhighlight lang="objective-c"> CMTime curTime=[adplayer currentTime];
long pos=CMTimeGetSeconds(curTime);
[nAppApiObject playheadPosition:pos];</syntaxhighlight>
<blockquote>'''Note:''' The playhead positions for ad and content should be maintained separately.</blockquote>

=== stop ===
[[stop]] must be called on the following events:
* At the end of ad
* In case of interruptions during playback like flight mode, Wi-Fi toggle, etc.

Call [[loadMetadata]] and [[playheadPosition]] when the stream resumes.

Call [[play]] when starting the new stream.

=== end ===
[[end]] must be called on the following events:
*End of playback
*Channel change

=== API Call sequence ===
==== Use Case 1: Content has no Advertisements ====
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.

Call [[play]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
"segB": "CustomSegmentValueB",
"segC": "CustomSegmentValueC",
"crossId1": "Reference11",
"crossId2": "Reference22",
"isfullepisode": "y",
"airdate": "20161013 20:00:00",
"adloadtype": "2",
"progen":"GV"
}</syntaxhighlight>
Call [[playheadPosition]] every one second until a pause / stop.

{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>[nielsenMeter play: channelName];</code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>[nielsenMeter loadMetadata: contentMetadataObject];</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>[nielsenMeter playheadPosition: position];</code> || // playheadPosition is position of the playhead while the content is being played
|-
| End of Stream || <code>[nielsenMeter end];</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Advertisements ====
Call [[play]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad=123"
}</syntaxhighlight>
<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[playheadPosition]] every one second until a pause / stop / another ''loadMetadata'' is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata]].

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>[nielsenMeter play: channelName];</code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>[nielsenMeter loadMetadata: contentMetadataObject];</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>[nielsenMeter loadMetadata: prerollMetadataObject];</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>[nielsenMeter playheadPosition: position];</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>[nielsenMeter stop];</code> || // Call stop after preroll occurs
|-
| rowspan="3" | Content || <code>[nielsenMeter loadMetadata: contentMetadataObject];</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>[nielsenMeter playheadPosition: position];</code> || // position is position of the playhead while the content is being played
|-
| <code>[nielsenMeter stop];</code> || // Call stop after the content is paused (ad starts)
|-
| rowspan="3" | Midroll || <code>[nielsenMeter loadMetadata: midrollMetadataObject];</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>[nielsenMeter playheadPosition: position];</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>[nielsenMeter stop];</code> || // Call stop after midroll occurs
|-
| rowspan="3" | Content (End of stream) || <code>[nielsenMeter loadMetadata: contentMetadataObject];</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>[nielsenMeter playheadPosition: position];</code> || // position is position of the playhead while the content is being played
|-
| <code>[nielsenMeter end];</code> || // Called at the end of content
|-
| rowspan="3" | Postroll || <code>[nielsenMeter loadMetadata: postrollMetadataObject];</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>[nielsenMeter playheadPosition: position];</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>[nielsenMeter stop];</code> || // Call stop after postroll occurs
|}

<blockquote>'''Note:''' Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Interruptions during playback ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call [[stop]] immediately (except when content is buffering) and withhold sending playhead position.
* Start sending pings – [[loadMetadata]] and [[playheadPosition]] for the new viewing session, once the playback resumes.
Please see the [[Digital Measurement FAQ]] for more details

== Nielsen Measurement Opt-Out Implementation ==
As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. Our digital measurement products are not used to identify the consumer in any way, but they help us and our clients measure and analyze how consumers engage with media across online, mobile and emerging technologies, and offer insights into consumer behavior.
* When the app user wants to opt in or opt out of Nielsen measurement, a new dynamic page (with content string obtained from [[optOutURL]]) should be displayed.
* Use [[optOutStatus]] to retrieve the device’s Opt-Out status.
* This Opt-out page should be displayed in a webview (within the app) and not in any external browser.
* (For SDK Version 5.1.1.17 or below) Capture the user’s selection in this page and pass it to the SDK through [[userOptOut]] for Nielsen to save the user’s preference.
* (For SDK Version 5.1.1.18 or above) Opt-out is controlled by the Limit Ad Tracking setting on the user's device. There is no need to capture any user selection on the opt-out page.


== Pre-Certification Checklists ==
After the application is ready to be sent for Nielsen Certification, please go through the [[Digital Pre-Certification Checklist App SDK]] and ensure the app behaves as expected, before submitting to Nielsen.

== Testing an Implementation - App ==
See [[Digital Measurement Testing]].

DCR Video Browser SDK

2017-11-08T22:04:34Z

RyanCarlson: adloadtype

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== 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="html">
apid: "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
</syntaxhighlight>

== Configure SDK ==
There are two steps required for configuring the SDK:
*Add Static Queue Snippet
*Create SDK Instance

=== Static Queue Snippet ===
Add the following script tag to the website:
<syntaxhighlight lang="javascript">
<script>
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}

(window,"NOLBUNDLE");

var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");

</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"})
</syntaxhighlight>

When creating an instance, pass the following three values:
{| 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"})"
|}

==== Example SDK Initialization ====
<syntaxhighlight lang="javascript">
var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {nol_sdkDebug: "debug"});
</syntaxhighlight>

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”.

=== 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="html"><script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","myPlayerName", {clientid: "it-123456", vcid: "c01", nol_sdkDebug: "debug"});
</script></syntaxhighlight>

=== Create Metadata Objects ===
There are two types of asset metadata:
*content: identify video
*ad: identify each ad

The metadata received for each asset is used for classification and reporting.

Metadata can be passed through key-values using the Nielsen reserved keys. User will need to set up content and ad objects with the required Nielsen keys as shown in the sample code below.

==== Content Metadata ====
Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| clientid ||
parent ID – value is automatically populated through provided App ID.<br/>
In order to override the brand configured to the App ID, pass parent <br/>
value here and the sub-brand ID associated to that brand in the subbrand <br/>
key (e.g. multiple brands in App)
||
Nielsen provided
||
|-
| vcid || sub-brand ID – value is automatically populated through provided<br/>
App ID. In order to override the sub-brand configured to the App ID, value can <br/>
be passed here (e.g. multiple sub-brands in App)
||
Nielsen provided
||
|-
| type || type of asset || "content" || ✓
|-
| assetid || unique ID assigned to asset || custom || ✓
|-
| program || name of program (25 character limit) || custom || ✓
|-
| title || episode title (40 character limit) || custom || ✓
|-
| length || length of content in seconds || seconds (86400 for live stream)|| ✓
|-
| mediaURL || URL location of the content being streamed || custom || ✓
|-
| segB || custom segment B || custom ||
|-
| segC || custom segment C || custom ||
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH:MI:SS || ✓
|-
| isfullepisode || full episode flag ||
*"y"– full episode
*"n"– non full episode
||
✓
|-
| crossId1 || standard episode ID || custom || ✓
|-
| crossId2 || content originator (only required for distributors) || Nielsen provided ||
|-
|adloadtype || type of ad load:
* 1) - Linear – matches TV ad load
* 2) Dynamic – Dynamic Ad Insertion (DAI)
||
*"1" – content with linear ads
*"2" – content with dynamic ads
||
✓
|}

==== Example Content Object ====
<syntaxhighlight lang="javascript">
var contentMetadataObject =
{
type: 'content',
assetid: 'VID123-123456',
program: 'program name',
title: 'episode title',
length: 'length in seconds',
mediaURL: 'http://www.site.com/videoAsset',
segB: 'custom segment B',
segC: 'custom segment C',
airdate: 'YYYYMMDD HH:MI:SS',
isfullepisode: 'y',
crossId1: 'Standard Episode ID',
crossId2: 'Content Originator',
adloadtype: '2'
};
</syntaxhighlight>

=== Ad Metadata Object ===
The ad metadata should be passed for each individual ad.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}

==== Example Ad Object ====
<syntaxhighlight lang="javascript">
var adMetadataObject =
{
assetid: 'AD-1',
type: 'preroll'
};
</syntaxhighlight>
<br/>
<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

==== Call Nielsen APIs ====
The method for calling events is ggPM().

<syntaxhighlight lang="javascript">
nSdkInstance.ggPM('event', parameter, ...);
</syntaxhighlight>

== Interrupt Scenarios ==

=== Pause Event ===
The setPlayheadPostion event is used for handling pause. To indicate pause, stop passing the playhead position to the SDK. Once the content resumes, begin sending the playhead again with the correct playhead value.

=== Other Interrupt Scenarios ===
The following possible browser interruption scenarios must be handled:

* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button

There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. midroll vs. content).

<syntaxhighlight lang="javascript">
window.addEventListener('beforeunload', function(event)
{
// Only inside a midroll indicate <stop> for the ad
nSdkInstance.ggPM('stop', playheadPosition);

// Indicate <end> and <stop> for the content
nSdkInstance.ggPM('end', playheadPosition);
nSdkInstance.ggPM('stop', playheadPosition);
});
</syntaxhighlight>

<blockquote>'''Note:''' User may need to add code to support specific browser versions (e.g. older versions of Internet Explorer).</blockquote>

=== SDK Events ===
{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each asset
|-
| 'setPlayheadPosition' || playhead position as integer<br/>
VOD: || current position in seconds <br/>
Live: current UTC timestamp <br/>
Note: 'setPlayheadPosition' has to be called every second
||
Pass playhead position every second during playback
|-
| 'stop' || playhead position || Call when content or ads complete playing and pass playhead position
|-
| 'end' || playhead position in seconds || Call when the current video asset completes playback and pass the playhead position. <br/>
Example: At the end of the content stream, if the user switches to another piece of content, when the browser is refreshed or closed.
|}

== SDK Playhead Event Sequence ==
The sample event lifecycle can be used as a reference for identifying the order for calling events.

<syntaxhighlight lang="javascript">
// START OF STREAM
nSdkInstance.ggPM('loadMetadata', contentMetadataObject);

// PREROLL
nSdkInstance.ggPM('loadMetadata', prerollMetadataObject);
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
//
// pass playhead every second
//
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
nSdkInstance.ggPM('stop', playheadPosition);

// CONTENT
nSdkInstance.ggPM('loadMetadata', contentMetadataObject);
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
//
// pass playhead every second
//
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
nSdkInstance.ggPM('stop', playheadPosition);

// MIDROLL
nSdkInstance.ggPM('loadMetadata', midrollMetadataObject);
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
//
// pass playhead every second
//
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
nSdkInstance.ggPM('stop', playheadPosition);

// CONTENT
nSdkInstance.ggPM('loadMetadata', contentMetadataObject);
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
//
// pass playhead every second
//
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
nSdkInstance.ggPM('end', playheadPosition);

// POSTROLL
nSdkInstance.ggPM('loadmetadata', postrollMetadataObject);
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
//
// pass playhead every second
//
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
nSdkInstance.ggPM('stop', playheadPosition);
</syntaxhighlight>
<blockquote>
* 'setPlayheadPosition' is used for calculating duration and must be passed every second. The final playhead position must be sent for the current asset being played before calling 'stop', 'end', or 'loadmetadata'.

* For Ad Pods, events must be called for each individual Ad. Each Ad playhead position should begin at ‘0’ when ad starts.

* When content has resumed following an ad break, the playhead position update must continue where previous content segment left off. The playhead position should be passed as a rounded number with no decimals.
</blockquote>

== Nielsen Opt-Out ==
The site must provide a means for the user to opt-out of, or opt back into, Nielsen Measurement. A user can opt-out if they would prefer not to participate in any Nielsen online measurement research. To implement the opt-out option, include the following two items in your privacy policy.
*A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings).
*A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

On the Nielsen Digital Measurement Privacy Policy page, users can click Choices to read more detailed information about the measurement software, learn about their options with regard to Nielsen measurement, and, if they do not want to participate in Nielsen online measurement, click a link to receive an opt-out cookie.

The following paragraph is a template for an opt-out statement.
<blockquote>
The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.
</blockquote>

=== Opt Back In ===
Once users have opted-out, they can choose to opt back into Nielsen Measurement at anytime by selecting the opt back in link on the Nielsen Digital Privacy Policy page. When a user selects the link, their opt-out cookie will be deleted and they will be able to be measured.

=== 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("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");
</syntaxhighlight>

DCR Video Browser SDK

2017-11-08T22:04:11Z

RyanCarlson: adloadtype

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== 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="html">
apid: "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
</syntaxhighlight>

== Configure SDK ==
There are two steps required for configuring the SDK:
*Add Static Queue Snippet
*Create SDK Instance

=== Static Queue Snippet ===
Add the following script tag to the website:
<syntaxhighlight lang="javascript">
<script>
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}

(window,"NOLBUNDLE");

var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");

</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"})
</syntaxhighlight>

When creating an instance, pass the following three values:
{| 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"})"
|}

==== Example SDK Initialization ====
<syntaxhighlight lang="javascript">
var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {nol_sdkDebug: "debug"});
</syntaxhighlight>

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”.

=== 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="html"><script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","myPlayerName", {clientid: "it-123456", vcid: "c01", nol_sdkDebug: "debug"});
</script></syntaxhighlight>

=== Create Metadata Objects ===
There are two types of asset metadata:
*content: identify video
*ad: identify each ad

The metadata received for each asset is used for classification and reporting.

Metadata can be passed through key-values using the Nielsen reserved keys. User will need to set up content and ad objects with the required Nielsen keys as shown in the sample code below.

==== Content Metadata ====
Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| clientid ||
parent ID – value is automatically populated through provided App ID.<br/>
In order to override the brand configured to the App ID, pass parent <br/>
value here and the sub-brand ID associated to that brand in the subbrand <br/>
key (e.g. multiple brands in App)
||
Nielsen provided
||
|-
| vcid || sub-brand ID – value is automatically populated through provided<br/>
App ID. In order to override the sub-brand configured to the App ID, value can <br/>
be passed here (e.g. multiple sub-brands in App)
||
Nielsen provided
||
|-
| type || type of asset || "content" || ✓
|-
| assetid || unique ID assigned to asset || custom || ✓
|-
| program || name of program (25 character limit) || custom || ✓
|-
| title || episode title (40 character limit) || custom || ✓
|-
| length || length of content in seconds || seconds (86400 for live stream)|| ✓
|-
| mediaURL || URL location of the content being streamed || custom || ✓
|-
| segB || custom segment B || custom ||
|-
| segC || custom segment C || custom ||
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH:MI:SS || ✓
|-
| isfullepisode || full episode flag ||
*"y"– full episode
*"n"– non full episode
||
✓
|-
| crossId1 || standard episode ID || custom || ✓
|-
| crossId2 || content originator (only required for distributors) || Nielsen provided ||
|-
|adloadtype || type of ad load:
* 1) - Linear – matches TV ad load
* 2) Dynamic – Dynamic Ad Insertion (DAI)
||
*"1" – content with linear ads
*"2" – content with dynamic ads
||
✓
|}

==== Example Content Object ====
<syntaxhighlight lang="javascript">
var contentMetadataObject =
{
type: 'content',
assetid: 'VID123-123456',
program: 'program name',
title: 'episode title',
length: 'length in seconds',
mediaURL: 'http://www.site.com/videoAsset',
segB: 'custom segment B',
segC: 'custom segment C',
airdate: 'YYYYMMDD HH:MI:SS',
isfullepisode: 'y',
crossId1: 'Standard Episode ID',
crossId2: 'Content Originator',
admodel: '2'
};
</syntaxhighlight>

=== Ad Metadata Object ===
The ad metadata should be passed for each individual ad.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}

==== Example Ad Object ====
<syntaxhighlight lang="javascript">
var adMetadataObject =
{
assetid: 'AD-1',
type: 'preroll'
};
</syntaxhighlight>
<br/>
<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

==== Call Nielsen APIs ====
The method for calling events is ggPM().

<syntaxhighlight lang="javascript">
nSdkInstance.ggPM('event', parameter, ...);
</syntaxhighlight>

== Interrupt Scenarios ==

=== Pause Event ===
The setPlayheadPostion event is used for handling pause. To indicate pause, stop passing the playhead position to the SDK. Once the content resumes, begin sending the playhead again with the correct playhead value.

=== Other Interrupt Scenarios ===
The following possible browser interruption scenarios must be handled:

* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button

There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. midroll vs. content).

<syntaxhighlight lang="javascript">
window.addEventListener('beforeunload', function(event)
{
// Only inside a midroll indicate <stop> for the ad
nSdkInstance.ggPM('stop', playheadPosition);

// Indicate <end> and <stop> for the content
nSdkInstance.ggPM('end', playheadPosition);
nSdkInstance.ggPM('stop', playheadPosition);
});
</syntaxhighlight>

<blockquote>'''Note:''' User may need to add code to support specific browser versions (e.g. older versions of Internet Explorer).</blockquote>

=== SDK Events ===
{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each asset
|-
| 'setPlayheadPosition' || playhead position as integer<br/>
VOD: || current position in seconds <br/>
Live: current UTC timestamp <br/>
Note: 'setPlayheadPosition' has to be called every second
||
Pass playhead position every second during playback
|-
| 'stop' || playhead position || Call when content or ads complete playing and pass playhead position
|-
| 'end' || playhead position in seconds || Call when the current video asset completes playback and pass the playhead position. <br/>
Example: At the end of the content stream, if the user switches to another piece of content, when the browser is refreshed or closed.
|}

== SDK Playhead Event Sequence ==
The sample event lifecycle can be used as a reference for identifying the order for calling events.

<syntaxhighlight lang="javascript">
// START OF STREAM
nSdkInstance.ggPM('loadMetadata', contentMetadataObject);

// PREROLL
nSdkInstance.ggPM('loadMetadata', prerollMetadataObject);
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
//
// pass playhead every second
//
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
nSdkInstance.ggPM('stop', playheadPosition);

// CONTENT
nSdkInstance.ggPM('loadMetadata', contentMetadataObject);
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
//
// pass playhead every second
//
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
nSdkInstance.ggPM('stop', playheadPosition);

// MIDROLL
nSdkInstance.ggPM('loadMetadata', midrollMetadataObject);
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
//
// pass playhead every second
//
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
nSdkInstance.ggPM('stop', playheadPosition);

// CONTENT
nSdkInstance.ggPM('loadMetadata', contentMetadataObject);
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
//
// pass playhead every second
//
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
nSdkInstance.ggPM('end', playheadPosition);

// POSTROLL
nSdkInstance.ggPM('loadmetadata', postrollMetadataObject);
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
//
// pass playhead every second
//
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
nSdkInstance.ggPM('stop', playheadPosition);
</syntaxhighlight>
<blockquote>
* 'setPlayheadPosition' is used for calculating duration and must be passed every second. The final playhead position must be sent for the current asset being played before calling 'stop', 'end', or 'loadmetadata'.

* For Ad Pods, events must be called for each individual Ad. Each Ad playhead position should begin at ‘0’ when ad starts.

* When content has resumed following an ad break, the playhead position update must continue where previous content segment left off. The playhead position should be passed as a rounded number with no decimals.
</blockquote>

== Nielsen Opt-Out ==
The site must provide a means for the user to opt-out of, or opt back into, Nielsen Measurement. A user can opt-out if they would prefer not to participate in any Nielsen online measurement research. To implement the opt-out option, include the following two items in your privacy policy.
*A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings).
*A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

On the Nielsen Digital Measurement Privacy Policy page, users can click Choices to read more detailed information about the measurement software, learn about their options with regard to Nielsen measurement, and, if they do not want to participate in Nielsen online measurement, click a link to receive an opt-out cookie.

The following paragraph is a template for an opt-out statement.
<blockquote>
The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.
</blockquote>

=== Opt Back In ===
Once users have opted-out, they can choose to opt back into Nielsen Measurement at anytime by selecting the opt back in link on the Nielsen Digital Privacy Policy page. When a user selects the link, their opt-out cookie will be deleted and they will be able to be measured.

=== 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("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");
</syntaxhighlight>

DCR Static VHL

2017-10-04T19:00:38Z

RyanCarlson: debug

DCR Static VHL

2017-10-04T18:56:44Z

RyanCarlson: update

DCR Static VHL

2017-10-04T18:48:52Z

RyanCarlson: update

DCR Static VHL

2017-10-04T18:47:03Z

RyanCarlson: updated

DCR Static VHL

2017-10-04T18:46:42Z

RyanCarlson: deleted

DCR Static VHL

2017-10-04T18:46:00Z

RyanCarlson: <br>

DCR Static VHL

2017-10-04T18:45:31Z

RyanCarlson: global

DCR Static VHL

2017-10-04T18:44:48Z

RyanCarlson: <br>

DCR Static VHL

2017-10-04T18:44:35Z

RyanCarlson: DCR

DCR Static VHL

2017-10-04T18:44:07Z

RyanCarlson: update

DCR Static VHL

2017-10-04T18:43:39Z

RyanCarlson: VHL

DCR Static VHL

2017-10-04T18:41:45Z

RyanCarlson: infinite scroll

DCR Static VHL

2017-10-04T18:40:34Z

RyanCarlson: br

DCR Static VHL

2017-10-04T18:40:11Z

RyanCarlson: init

DCR Static VHL

2017-10-04T18:37:25Z

RyanCarlson:

DCR Static VHL

2017-10-04T18:36:54Z

RyanCarlson: update

DCR Static VHL

2017-10-04T18:33:57Z

RyanCarlson: d

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== 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>

== Implementation Steps ==
=== Add Tracking Code ===
The Adobe DCR Tracking Code must be added to each page.
<syntaxhighlight lang="javascript">
<script src="script/lib/VideoHeartbeat.min.js"></script>

// A second SDK instance must be created specifically for static, if video measurement is also enabled on the same page.
var i = NOLSDK.getInstance('mynewinstance');

//The Required Nielsen Global Parameters Must Be Established
var _nolggGlobalParams = {
apid: "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX",
sfcode: "dcr",
nsdkv: "511",
apn: "Static-VHL",
nol_sdkDebug: "DEBUG"
};

//You Can Now Initialize The SDK
i.ggInitialize(_nolggGlobalParams);

// Create Content Metadata Object
var nielsenMetadata = {
type: 'static',
assetid: '', // *DYNAMIC METADATA*: unique ID for each article **REQUIRED**
section: '', // *DYNAMIC METADATA*: section of site **REQUIRED**
segA: '', // *DYNAMIC METADATA*: custom segment
segB: '', // *DYNAMIC METADATA*: custom segment
segC: '' // *DYNAMIC METADATA*: custom segment
};

// Event 'staticstart' Call
i.ggPM("staticstart", nielsenMetadata);
</script></syntaxhighlight>

==== Tracking Code Components ====
The tracking code includes
* Adobe VHL Library JS
* Create SDK Instance
* Setup Global Parameters
* SDK Initialization
* Content Metadata
* staticstart Event

'''Static Queue Snippet'''

The Adobe VHL Library 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.
<syntaxhighlight lang="javascript">
<script src="script/lib/VideoHeartbeat.min.js"></script>

'''SDK Initialization'''

While creating an SDK instance, initialize the SDK by calling:

'''Initialization API Call'''

<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX", "",{nol_sdkDebug: "debug"})</syntaxhighlight>

When the initialization call is made, a unique static config file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and cached by the client-side browser(s).

Once the static config file is downloaded, the SDK will be fully downloaded and initialized. All SDK modules are included in one file:
"nlsSDK600.bundle.min.js".

'''Content Metadata'''

Metadata can be passed through key-values using the Nielsen reserved keys. The tracking code includes the Nielsen reserved keys and placeholder values.

Pass dynamic metadata for the keys with the <code><metadataPlaceholder></code> value (e.g. <code>section: ''</code>).

'''staticstart Event'''

There is only one event call required:
<syntaxhighlight lang="javascript">nSdkInstance.ggPM("staticstart", nielsenMetadata);</syntaxhighlight>

The content metadata object is passed as a parameter when calling 'staticstart' event . To know more about configuring metadata refer [[Bundled_SDK_-_Static#Configure_Metadata|Step 3]].

=== Pass App ID in Initialization Call ===
Pass the unique App ID in the first parameter of the initialization call, <code><apid></code>.

'''Example SDK Initialization'''

<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX", "nlsnInstance", {nol_sdkDebug: "debug"});</syntaxhighlight>

The initialization call has three parameters:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site. || <code>PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX</code>
|-
| instanceName || Name of SDK instance || Any string value
|-
| nol_sdkDebug: "debug" || Enables Nielsen console logging. Only required for testing || <code>{nol_sdkDebug: "debug"}</code>
|}

Update <code><apid></code> with the AppID provided. Refer to the [[#Going_Live|Going Live]] section to know about updating the AppID to production after testing is completed.

=== Configure Metadata ===
Map the Nielsen keys to variables so that the content metadata is dynamically updated.

The Nielsen reserved keys are:
{| class="wikitable"
|-
! Key !! Description !! Data Type !! Value !! Required?
|-
| type || asset type || fixed || <code>'static'</code> || Yes
|-
| assetid || Unique ID for each article || dynamic || custom || Yes
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values || dynamic || custom || Yes
|-
| segA || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segB || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segC || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || fixed || custom || No
|}

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.

'''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)
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of, or opt back into, Nielsen Measurement. A user can opt-out if they would prefer not to participate in any Nielsen online measurement research. To implement the opt-out option, include the following two items in your privacy policy
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy
On the Nielsen Digital Measurement Privacy Policy page, users can click Choices to read more detailed information about the measurement software, learn about their options with regard to Nielsen measurement, and, if they do not want to participate in Nielsen online measurement, click a link to receive an opt-out cookie.

The following paragraph is a template for an opt-out statement, the properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

'''Opt Back In'''

Once users have opted-out, they can choose to opt back into Nielsen Measurement at anytime by selecting the opt back in link on the Nielsen Digital Privacy Policy page. When a user selects the link, their opt-out cookie will be deleted and they will be able to be measured.

== Infinite Scrolling ==

<code>onPaginate</code> will refire the view ping with the existing/original metadata.

<source lang="javascript">nSdkInstance.ggPM("onPaginate", scrolloffset);</source>
<br>
{|
!width="23%"| Parameter
!width="19%"| Description
|-
| event
| <code>onPaginate</code>
|-
| scrolloffset
| The <code>scrolloffset</code> value should be the y-scroll position:
|}

=== onPaginate ===

<code>onPageinate</code> is a slightly modified version of <code>staticstart</code> to enable tracking of user’s focus in pages with continuous scrolling. <code>onPaginate</code> event provides the same behavior as <code>staticstart</code> keeping it local to only clients who wish to implement continuous scrolling. (Note: This event <code>onPaginate</code> will not reset the page duration timer.)

* The maximum number of static View pings allowed per session is ‘1’. This is enforced via the <code>nol_maxPingCount</code> parameter in the tag and the cadence of impression.
* When an <code>onPaginate</code> event is called at the end of section / a focus shift (within the same page), this filter will reset the current ping count to ‘0’ for the static View ping. This change of value will cause a new View ping when the Browser SDK receives the next <code>staticPosition</code> event (at the section end). This sequence continues through the end of scrolling or till the close of static page session.

[[File:StaticPageEvent35.jpg|center|link=]]

== Going Live ==
Once the DCR Tracking Code is added to Instant Articles, Nielsen will validate the implementation. Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
# '''App ID''': Ensure that correct <apid> is used during initialization<syntaxhighlight lang="javascript">'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'</syntaxhighlight>
# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");</syntaxhighlight>

DCR Static VHL

2017-10-04T18:33:21Z

RyanCarlson: .

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== 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>

== Implementation Steps ==
=== Add Tracking Code ===
The Adobe DCR Tracking Code must be added to each page.
<syntaxhighlight lang="javascript">
<script src="script/lib/VideoHeartbeat.min.js"></script>

// A second SDK instance must be created specifically for static, if video measurement is also enabled on the same page.
var i = NOLSDK.getInstance('mynewinstance');

//The Required Nielsen Global Parameters Must Be Established
var _nolggGlobalParams = {
apid: "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX",
sfcode: "dcr",
nsdkv: "511",
apn:"Static-VHL",
nol_sdkDebug:"DEBUG"
};

//You Can Now Initialize The SDK
i.ggInitialize(_nolggGlobalParams);

// Create Content Metadata Object
var nielsenMetadata = {
type: 'static',
assetid: '', // *DYNAMIC METADATA*: unique ID for each article **REQUIRED**
section: '', // *DYNAMIC METADATA*: section of site **REQUIRED**
segA: '', // *DYNAMIC METADATA*: custom segment
segB: '', // *DYNAMIC METADATA*: custom segment
segC: '' // *DYNAMIC METADATA*: custom segment
};

// Event 'staticstart' Call
i.ggPM("staticstart", nielsenMetadata);
</script></syntaxhighlight>

==== Tracking Code Components ====
The tracking code includes
* Adobe VHL Library JS
* Create SDK Instance
* Setup Global Parameters
* SDK Initialization
* Content Metadata
* staticstart Event

'''Static Queue Snippet'''

The Adobe VHL Library 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.
<syntaxhighlight lang="javascript">
<script src="script/lib/VideoHeartbeat.min.js"></script>

'''SDK Initialization'''

While creating an SDK instance, initialize the SDK by calling:

'''Initialization API Call'''

<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX", "",{nol_sdkDebug: "debug"})</syntaxhighlight>

When the initialization call is made, a unique static config file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and cached by the client-side browser(s).

Once the static config file is downloaded, the SDK will be fully downloaded and initialized. All SDK modules are included in one file:
"nlsSDK600.bundle.min.js".

'''Content Metadata'''

Metadata can be passed through key-values using the Nielsen reserved keys. The tracking code includes the Nielsen reserved keys and placeholder values.

Pass dynamic metadata for the keys with the <code><metadataPlaceholder></code> value (e.g. <code>section: ''</code>).

'''staticstart Event'''

There is only one event call required:
<syntaxhighlight lang="javascript">nSdkInstance.ggPM("staticstart", nielsenMetadata);</syntaxhighlight>

The content metadata object is passed as a parameter when calling 'staticstart' event . To know more about configuring metadata refer [[Bundled_SDK_-_Static#Configure_Metadata|Step 3]].

=== Pass App ID in Initialization Call ===
Pass the unique App ID in the first parameter of the initialization call, <code><apid></code>.

'''Example SDK Initialization'''

<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX", "nlsnInstance", {nol_sdkDebug: "debug"});</syntaxhighlight>

The initialization call has three parameters:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site. || <code>PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX</code>
|-
| instanceName || Name of SDK instance || Any string value
|-
| nol_sdkDebug: "debug" || Enables Nielsen console logging. Only required for testing || <code>{nol_sdkDebug: "debug"}</code>
|}

Update <code><apid></code> with the AppID provided. Refer to the [[#Going_Live|Going Live]] section to know about updating the AppID to production after testing is completed.

=== Configure Metadata ===
Map the Nielsen keys to variables so that the content metadata is dynamically updated.

The Nielsen reserved keys are:
{| class="wikitable"
|-
! Key !! Description !! Data Type !! Value !! Required?
|-
| type || asset type || fixed || <code>'static'</code> || Yes
|-
| assetid || Unique ID for each article || dynamic || custom || Yes
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values || dynamic || custom || Yes
|-
| segA || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segB || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segC || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || fixed || custom || No
|}

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.

'''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)
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of, or opt back into, Nielsen Measurement. A user can opt-out if they would prefer not to participate in any Nielsen online measurement research. To implement the opt-out option, include the following two items in your privacy policy
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy
On the Nielsen Digital Measurement Privacy Policy page, users can click Choices to read more detailed information about the measurement software, learn about their options with regard to Nielsen measurement, and, if they do not want to participate in Nielsen online measurement, click a link to receive an opt-out cookie.

The following paragraph is a template for an opt-out statement, the properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

'''Opt Back In'''

Once users have opted-out, they can choose to opt back into Nielsen Measurement at anytime by selecting the opt back in link on the Nielsen Digital Privacy Policy page. When a user selects the link, their opt-out cookie will be deleted and they will be able to be measured.

== Infinite Scrolling ==

<code>onPaginate</code> will refire the view ping with the existing/original metadata.

<source lang="javascript">nSdkInstance.ggPM("onPaginate", scrolloffset);</source>
<br>
{|
!width="23%"| Parameter
!width="19%"| Description
|-
| event
| <code>onPaginate</code>
|-
| scrolloffset
| The <code>scrolloffset</code> value should be the y-scroll position:
|}

=== onPaginate ===

<code>onPageinate</code> is a slightly modified version of <code>staticstart</code> to enable tracking of user’s focus in pages with continuous scrolling. <code>onPaginate</code> event provides the same behavior as <code>staticstart</code> keeping it local to only clients who wish to implement continuous scrolling. (Note: This event <code>onPaginate</code> will not reset the page duration timer.)

* The maximum number of static View pings allowed per session is ‘1’. This is enforced via the <code>nol_maxPingCount</code> parameter in the tag and the cadence of impression.
* When an <code>onPaginate</code> event is called at the end of section / a focus shift (within the same page), this filter will reset the current ping count to ‘0’ for the static View ping. This change of value will cause a new View ping when the Browser SDK receives the next <code>staticPosition</code> event (at the section end). This sequence continues through the end of scrolling or till the close of static page session.

[[File:StaticPageEvent35.jpg|center|link=]]

== Going Live ==
Once the DCR Tracking Code is added to Instant Articles, Nielsen will validate the implementation. Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
# '''App ID''': Ensure that correct <apid> is used during initialization<syntaxhighlight lang="javascript">'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'</syntaxhighlight>
# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");</syntaxhighlight>

DCR Static VHL

2017-10-04T18:32:54Z

RyanCarlson: script

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== 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>

== Implementation Steps ==
=== Add Tracking Code ===
The Adobe DCR Tracking Code must be added to each page.
<syntaxhighlight lang="javascript">
<script src="script/lib/VideoHeartbeat.min.js"></script>

// A second SDK instance must be created specifically for static if video measurement is also enabled on the same page
var i = NOLSDK.getInstance('mynewinstance');

//The Required Nielsen Global Parameters Must Be Established
var _nolggGlobalParams = {
apid: "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX",
sfcode: "dcr",
nsdkv: "511",
apn:"Static-VHL",
nol_sdkDebug:"DEBUG"
};

//You Can Now Initialize The SDK
i.ggInitialize(_nolggGlobalParams);

// Create Content Metadata Object
var nielsenMetadata = {
type: 'static',
assetid: '', // *DYNAMIC METADATA*: unique ID for each article **REQUIRED**
section: '', // *DYNAMIC METADATA*: section of site **REQUIRED**
segA: '', // *DYNAMIC METADATA*: custom segment
segB: '', // *DYNAMIC METADATA*: custom segment
segC: '' // *DYNAMIC METADATA*: custom segment
};

// Event 'staticstart' Call
i.ggPM("staticstart", nielsenMetadata);
</script></syntaxhighlight>

==== Tracking Code Components ====
The tracking code includes
* Adobe VHL Library JS
* Create SDK Instance
* Setup Global Parameters
* SDK Initialization
* Content Metadata
* staticstart Event

'''Static Queue Snippet'''

The Adobe VHL Library 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.
<syntaxhighlight lang="javascript">
<script src="script/lib/VideoHeartbeat.min.js"></script>

'''SDK Initialization'''

While creating an SDK instance, initialize the SDK by calling:

'''Initialization API Call'''

<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX", "",{nol_sdkDebug: "debug"})</syntaxhighlight>

When the initialization call is made, a unique static config file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and cached by the client-side browser(s).

Once the static config file is downloaded, the SDK will be fully downloaded and initialized. All SDK modules are included in one file:
"nlsSDK600.bundle.min.js".

'''Content Metadata'''

Metadata can be passed through key-values using the Nielsen reserved keys. The tracking code includes the Nielsen reserved keys and placeholder values.

Pass dynamic metadata for the keys with the <code><metadataPlaceholder></code> value (e.g. <code>section: ''</code>).

'''staticstart Event'''

There is only one event call required:
<syntaxhighlight lang="javascript">nSdkInstance.ggPM("staticstart", nielsenMetadata);</syntaxhighlight>

The content metadata object is passed as a parameter when calling 'staticstart' event . To know more about configuring metadata refer [[Bundled_SDK_-_Static#Configure_Metadata|Step 3]].

=== Pass App ID in Initialization Call ===
Pass the unique App ID in the first parameter of the initialization call, <code><apid></code>.

'''Example SDK Initialization'''

<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX", "nlsnInstance", {nol_sdkDebug: "debug"});</syntaxhighlight>

The initialization call has three parameters:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site. || <code>PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX</code>
|-
| instanceName || Name of SDK instance || Any string value
|-
| nol_sdkDebug: "debug" || Enables Nielsen console logging. Only required for testing || <code>{nol_sdkDebug: "debug"}</code>
|}

Update <code><apid></code> with the AppID provided. Refer to the [[#Going_Live|Going Live]] section to know about updating the AppID to production after testing is completed.

=== Configure Metadata ===
Map the Nielsen keys to variables so that the content metadata is dynamically updated.

The Nielsen reserved keys are:
{| class="wikitable"
|-
! Key !! Description !! Data Type !! Value !! Required?
|-
| type || asset type || fixed || <code>'static'</code> || Yes
|-
| assetid || Unique ID for each article || dynamic || custom || Yes
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values || dynamic || custom || Yes
|-
| segA || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segB || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segC || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || fixed || custom || No
|}

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.

'''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)
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of, or opt back into, Nielsen Measurement. A user can opt-out if they would prefer not to participate in any Nielsen online measurement research. To implement the opt-out option, include the following two items in your privacy policy
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy
On the Nielsen Digital Measurement Privacy Policy page, users can click Choices to read more detailed information about the measurement software, learn about their options with regard to Nielsen measurement, and, if they do not want to participate in Nielsen online measurement, click a link to receive an opt-out cookie.

The following paragraph is a template for an opt-out statement, the properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

'''Opt Back In'''

Once users have opted-out, they can choose to opt back into Nielsen Measurement at anytime by selecting the opt back in link on the Nielsen Digital Privacy Policy page. When a user selects the link, their opt-out cookie will be deleted and they will be able to be measured.

== Infinite Scrolling ==

<code>onPaginate</code> will refire the view ping with the existing/original metadata.

<source lang="javascript">nSdkInstance.ggPM("onPaginate", scrolloffset);</source>
<br>
{|
!width="23%"| Parameter
!width="19%"| Description
|-
| event
| <code>onPaginate</code>
|-
| scrolloffset
| The <code>scrolloffset</code> value should be the y-scroll position:
|}

=== onPaginate ===

<code>onPageinate</code> is a slightly modified version of <code>staticstart</code> to enable tracking of user’s focus in pages with continuous scrolling. <code>onPaginate</code> event provides the same behavior as <code>staticstart</code> keeping it local to only clients who wish to implement continuous scrolling. (Note: This event <code>onPaginate</code> will not reset the page duration timer.)

* The maximum number of static View pings allowed per session is ‘1’. This is enforced via the <code>nol_maxPingCount</code> parameter in the tag and the cadence of impression.
* When an <code>onPaginate</code> event is called at the end of section / a focus shift (within the same page), this filter will reset the current ping count to ‘0’ for the static View ping. This change of value will cause a new View ping when the Browser SDK receives the next <code>staticPosition</code> event (at the section end). This sequence continues through the end of scrolling or till the close of static page session.

[[File:StaticPageEvent35.jpg|center|link=]]

== Going Live ==
Once the DCR Tracking Code is added to Instant Articles, Nielsen will validate the implementation. Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
# '''App ID''': Ensure that correct <apid> is used during initialization<syntaxhighlight lang="javascript">'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'</syntaxhighlight>
# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");</syntaxhighlight>

DCR Static VHL

2017-10-04T18:32:31Z

RyanCarlson: Updating VHL Guide

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== 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>

== Implementation Steps ==
=== Add Tracking Code ===
The Adobe DCR Tracking Code must be added to each page.
<syntaxhighlight lang="javascript"><script>
<script src="script/lib/VideoHeartbeat.min.js"></script>

// A second SDK instance must be created specifically for static if video measurement is also enabled on the same page
var i = NOLSDK.getInstance('mynewinstance');

//The Required Nielsen Global Parameters Must Be Established
var _nolggGlobalParams = {
apid: "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX",
sfcode: "dcr",
nsdkv: "511",
apn:"Static-VHL",
nol_sdkDebug:"DEBUG"
};

//You Can Now Initialize The SDK
i.ggInitialize(_nolggGlobalParams);

// Create Content Metadata Object
var nielsenMetadata = {
type: 'static',
assetid: '', // *DYNAMIC METADATA*: unique ID for each article **REQUIRED**
section: '', // *DYNAMIC METADATA*: section of site **REQUIRED**
segA: '', // *DYNAMIC METADATA*: custom segment
segB: '', // *DYNAMIC METADATA*: custom segment
segC: '' // *DYNAMIC METADATA*: custom segment
};

// Event 'staticstart' Call
i.ggPM("staticstart", nielsenMetadata);
</script></syntaxhighlight>

==== Tracking Code Components ====
The tracking code includes
* Adobe VHL Library JS
* Create SDK Instance
* Setup Global Parameters
* SDK Initialization
* Content Metadata
* staticstart Event

'''Static Queue Snippet'''

The Adobe VHL Library 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.
<syntaxhighlight lang="javascript">
<script src="script/lib/VideoHeartbeat.min.js"></script>

'''SDK Initialization'''

While creating an SDK instance, initialize the SDK by calling:

'''Initialization API Call'''

<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX", "",{nol_sdkDebug: "debug"})</syntaxhighlight>

When the initialization call is made, a unique static config file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and cached by the client-side browser(s).

Once the static config file is downloaded, the SDK will be fully downloaded and initialized. All SDK modules are included in one file:
"nlsSDK600.bundle.min.js".

'''Content Metadata'''

Metadata can be passed through key-values using the Nielsen reserved keys. The tracking code includes the Nielsen reserved keys and placeholder values.

Pass dynamic metadata for the keys with the <code><metadataPlaceholder></code> value (e.g. <code>section: ''</code>).

'''staticstart Event'''

There is only one event call required:
<syntaxhighlight lang="javascript">nSdkInstance.ggPM("staticstart", nielsenMetadata);</syntaxhighlight>

The content metadata object is passed as a parameter when calling 'staticstart' event . To know more about configuring metadata refer [[Bundled_SDK_-_Static#Configure_Metadata|Step 3]].

=== Pass App ID in Initialization Call ===
Pass the unique App ID in the first parameter of the initialization call, <code><apid></code>.

'''Example SDK Initialization'''

<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX", "nlsnInstance", {nol_sdkDebug: "debug"});</syntaxhighlight>

The initialization call has three parameters:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site. || <code>PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX</code>
|-
| instanceName || Name of SDK instance || Any string value
|-
| nol_sdkDebug: "debug" || Enables Nielsen console logging. Only required for testing || <code>{nol_sdkDebug: "debug"}</code>
|}

Update <code><apid></code> with the AppID provided. Refer to the [[#Going_Live|Going Live]] section to know about updating the AppID to production after testing is completed.

=== Configure Metadata ===
Map the Nielsen keys to variables so that the content metadata is dynamically updated.

The Nielsen reserved keys are:
{| class="wikitable"
|-
! Key !! Description !! Data Type !! Value !! Required?
|-
| type || asset type || fixed || <code>'static'</code> || Yes
|-
| assetid || Unique ID for each article || dynamic || custom || Yes
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values || dynamic || custom || Yes
|-
| segA || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segB || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segC || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || fixed || custom || No
|}

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.

'''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)
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of, or opt back into, Nielsen Measurement. A user can opt-out if they would prefer not to participate in any Nielsen online measurement research. To implement the opt-out option, include the following two items in your privacy policy
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy
On the Nielsen Digital Measurement Privacy Policy page, users can click Choices to read more detailed information about the measurement software, learn about their options with regard to Nielsen measurement, and, if they do not want to participate in Nielsen online measurement, click a link to receive an opt-out cookie.

The following paragraph is a template for an opt-out statement, the properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

'''Opt Back In'''

Once users have opted-out, they can choose to opt back into Nielsen Measurement at anytime by selecting the opt back in link on the Nielsen Digital Privacy Policy page. When a user selects the link, their opt-out cookie will be deleted and they will be able to be measured.

== Infinite Scrolling ==

<code>onPaginate</code> will refire the view ping with the existing/original metadata.

<source lang="javascript">nSdkInstance.ggPM("onPaginate", scrolloffset);</source>
<br>
{|
!width="23%"| Parameter
!width="19%"| Description
|-
| event
| <code>onPaginate</code>
|-
| scrolloffset
| The <code>scrolloffset</code> value should be the y-scroll position:
|}

=== onPaginate ===

<code>onPageinate</code> is a slightly modified version of <code>staticstart</code> to enable tracking of user’s focus in pages with continuous scrolling. <code>onPaginate</code> event provides the same behavior as <code>staticstart</code> keeping it local to only clients who wish to implement continuous scrolling. (Note: This event <code>onPaginate</code> will not reset the page duration timer.)

* The maximum number of static View pings allowed per session is ‘1’. This is enforced via the <code>nol_maxPingCount</code> parameter in the tag and the cadence of impression.
* When an <code>onPaginate</code> event is called at the end of section / a focus shift (within the same page), this filter will reset the current ping count to ‘0’ for the static View ping. This change of value will cause a new View ping when the Browser SDK receives the next <code>staticPosition</code> event (at the section end). This sequence continues through the end of scrolling or till the close of static page session.

[[File:StaticPageEvent35.jpg|center|link=]]

== Going Live ==
Once the DCR Tracking Code is added to Instant Articles, Nielsen will validate the implementation. Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
# '''App ID''': Ensure that correct <apid> is used during initialization<syntaxhighlight lang="javascript">'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'</syntaxhighlight>
# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");</syntaxhighlight>

DCR Static VHL

2017-10-04T18:17:24Z

RyanCarlson: VHL Static Page

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

'''Prior Version Guide:''' [[DCR Static Browser SDK (5.1.1)|5.1.1]]

== 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>

== Implementation Steps ==
=== Add Tracking Code ===
The Nielsen DCR Tracking Code must be added to each page.
<syntaxhighlight lang="javascript"><script>
// Static Queue Snippet
!function(t,n){t[n]=t[n]||{nlsQ:function(e,o,c,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="+o+"&ns="+n,i=s.getElementsByTagName("script")[0],i.parentNode.insertBefore(r,i),t[n][o]=t[n][o]||{g:c||{},ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]}}}(window,"NOLBUNDLE");

// SDK Initialization
var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});

// Content Metadata
var nielsenMetadata = {
type: 'static',
assetid: '', // *DYNAMIC METADATA*: unique ID for each article **REQUIRED**
section: '', // *DYNAMIC METADATA*: section of site **REQUIRED**
segA: '', // *DYNAMIC METADATA*: custom segment
segB: '', // *DYNAMIC METADATA*: custom segment
segC: '' // *DYNAMIC METADATA*: custom segment
};

// Event 'staticstart' Call
nSdkInstance.ggPM("staticstart", nielsenMetadata);
</script></syntaxhighlight>

==== Tracking Code Components ====
The tracking code includes
* Static Queue Snippet
* SDK Initialization
* Content Metadata
* staticstart Event

'''Static Queue Snippet'''

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.
<syntaxhighlight lang="javascript">
!function(t,n){t[n]=t[n]||
{
nlsQ:function(e,o,c,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="+o+"&ns="+n,i=s.getElementsByTagName("script")[0],i.parentNode.insertBefore(r,i),
t[o]=t[o]||{g:c,ggPM:function(n,e,c,r,s){(t[o].q=t[o].q||[]).push([n,e,c,r,s])}},t[o]}
}
}
(window,"NOLBUNDLE");</syntaxhighlight>

'''SDK Initialization'''

While creating an SDK instance, initialize the SDK by calling:

'''Initialization API Call'''

<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX", "",{nol_sdkDebug: "debug"})</syntaxhighlight>

When the initialization call is made, a unique static config file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and cached by the client-side browser(s).

Once the static config file is downloaded, the SDK will be fully downloaded and initialized. All SDK modules are included in one file:
"nlsSDK600.bundle.min.js".

'''Content Metadata'''

Metadata can be passed through key-values using the Nielsen reserved keys. The tracking code includes the Nielsen reserved keys and placeholder values.

Pass dynamic metadata for the keys with the <code><metadataPlaceholder></code> value (e.g. <code>section: ''</code>).

'''staticstart Event'''

There is only one event call required:
<syntaxhighlight lang="javascript">nSdkInstance.ggPM("staticstart", nielsenMetadata);</syntaxhighlight>

The content metadata object is passed as a parameter when calling 'staticstart' event . To know more about configuring metadata refer [[Bundled_SDK_-_Static#Configure_Metadata|Step 3]].

=== Pass App ID in Initialization Call ===
Pass the unique App ID in the first parameter of the initialization call, <code><apid></code>.

'''Example SDK Initialization'''

<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX", "nlsnInstance", {nol_sdkDebug: "debug"});</syntaxhighlight>

The initialization call has three parameters:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site. || <code>PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX</code>
|-
| instanceName || Name of SDK instance || Any string value
|-
| nol_sdkDebug: "debug" || Enables Nielsen console logging. Only required for testing || <code>{nol_sdkDebug: "debug"}</code>
|}

Update <code><apid></code> with the AppID provided. Refer to the [[#Going_Live|Going Live]] section to know about updating the AppID to production after testing is completed.

=== Configure Metadata ===
Map the Nielsen keys to variables so that the content metadata is dynamically updated.

The Nielsen reserved keys are:
{| class="wikitable"
|-
! Key !! Description !! Data Type !! Value !! Required?
|-
| type || asset type || fixed || <code>'static'</code> || Yes
|-
| assetid || Unique ID for each article || dynamic || custom || Yes
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values || dynamic || custom || Yes
|-
| segA || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segB || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || dynamic || custom || No
|-
| segC || custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) || fixed || custom || No
|}

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.

'''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)
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of, or opt back into, Nielsen Measurement. A user can opt-out if they would prefer not to participate in any Nielsen online measurement research. To implement the opt-out option, include the following two items in your privacy policy
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy
On the Nielsen Digital Measurement Privacy Policy page, users can click Choices to read more detailed information about the measurement software, learn about their options with regard to Nielsen measurement, and, if they do not want to participate in Nielsen online measurement, click a link to receive an opt-out cookie.

The following paragraph is a template for an opt-out statement, the properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

'''Opt Back In'''

Once users have opted-out, they can choose to opt back into Nielsen Measurement at anytime by selecting the opt back in link on the Nielsen Digital Privacy Policy page. When a user selects the link, their opt-out cookie will be deleted and they will be able to be measured.

== Infinite Scrolling ==

<code>onPaginate</code> will refire the view ping with the existing/original metadata.

<source lang="javascript">nSdkInstance.ggPM("onPaginate", scrolloffset);</source>
<br>
{|
!width="23%"| Parameter
!width="19%"| Description
|-
| event
| <code>onPaginate</code>
|-
| scrolloffset
| The <code>scrolloffset</code> value should be the y-scroll position:
|}

=== onPaginate ===

<code>onPageinate</code> is a slightly modified version of <code>staticstart</code> to enable tracking of user’s focus in pages with continuous scrolling. <code>onPaginate</code> event provides the same behavior as <code>staticstart</code> keeping it local to only clients who wish to implement continuous scrolling. (Note: This event <code>onPaginate</code> will not reset the page duration timer.)

* The maximum number of static View pings allowed per session is ‘1’. This is enforced via the <code>nol_maxPingCount</code> parameter in the tag and the cadence of impression.
* When an <code>onPaginate</code> event is called at the end of section / a focus shift (within the same page), this filter will reset the current ping count to ‘0’ for the static View ping. This change of value will cause a new View ping when the Browser SDK receives the next <code>staticPosition</code> event (at the section end). This sequence continues through the end of scrolling or till the close of static page session.

[[File:StaticPageEvent35.jpg|center|link=]]

== Going Live ==
Once the DCR Tracking Code is added to Instant Articles, Nielsen will validate the implementation. Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
# '''App ID''': Ensure that correct <apid> is used during initialization<syntaxhighlight lang="javascript">'PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'</syntaxhighlight>
# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");</syntaxhighlight>

DCR Video Browser SDK

2017-10-02T18:09:51Z

RyanCarlson: added stop() call

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== 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="html">
apid: "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
</syntaxhighlight>

== Configure SDK ==
There are two steps required for configuring the SDK:
*Add Static Queue Snippet
*Create SDK Instance

=== Static Queue Snippet ===
Add the following script tag to the website:
<syntaxhighlight lang="javascript">
<script>
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}

(window,"NOLBUNDLE");

var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");

</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"})
</syntaxhighlight>

When creating an instance, pass the following three values:
{| 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"})"
|}

==== Example SDK Initialization ====
<syntaxhighlight lang="javascript">
var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX", "nlsnInstance", {nol_sdkDebug: "debug"});
</syntaxhighlight>

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”.

==== 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">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||{nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[o]=t[o]||{g:c,ggPM:function(n,e,c,r,s){(t[o].q=t[o].q||[]).push([n,e,c,r,s])}},
t[o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

=== Create Metadata Objects ===
There are two types of asset metadata:
*content: identify video
*ad: identify each ad

The metadata received for each asset is used for classification and reporting.

Metadata can be passed through key-values using the Nielsen reserved keys. User will need to set up content and ad objects with the required Nielsen keys as shown in the sample code below.

==== Content Metadata ====
Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| clientid ||
parent ID – value is automatically populated through provided App ID.<br/>
In order to override the brand configured to the App ID, pass parent <br/>
value here and the sub-brand ID associated to that brand in the subbrand <br/>
key (e.g. multiple brands in App)
||
Nielsen provided
||
|-
| vcid || sub-brand ID – value is automatically populated through provided<br/>
App ID. In order to override the sub-brand configured to the App ID, value can <br/>
be passed here (e.g. multiple sub-brands in App)
||
Nielsen provided
||
|-
| type || type of asset || "content" || ✓
|-
| assetid || unique ID assigned to asset || custom || ✓
|-
| program || name of program (25 character limit) || custom || ✓
|-
| title || episode title (40 character limit) || custom || ✓
|-
| length || length of content in seconds || seconds 86400 for live stream)|| ✓
|-
| mediaURL || URL location of the content being streamed || custom || ✓
|-
| segB || custom segment B || custom ||
|-
| segC || custom segment C || custom ||
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH:MI:SS || ✓
|-
| isfullepisode || full episode flag ||
*"y"– full episode
*"n"– non full episode
||
✓
|-
| crossId1 || standard episode ID || custom || ✓
|-
| crossId2 || content originator (only required for distributors) || Nielsen provided ||
|-
|adloadtype || type of ad load:
* 1) - Linear – matches TV ad load
* 2) Dynamic – Dynamic Ad Insertion (DAI)
||
*"1" – content with linear ads
*"2" – content with dynamic ads
||
✓
|}

==== Example Content Object ====
<syntaxhighlight lang="javascript">
var contentMetadataObject =
{
type: 'content',
assetid: 'VID123-123456',
program: 'program name',
title: 'episode title',
length: 'length in seconds',
mediaURL: 'http://www.site.com/videoAsset',
segB: 'custom segment B',
segC: 'custom segment C',
airdate: 'YYYYMMDD HH:MI:SS',
isfullepisode: 'y',
crossId1: 'Standard Episode ID',
crossId2: 'Content Originator',
adloadtype: '2'
};
</syntaxhighlight>

=== Ad Metadata Object ===
The ad metadata should be passed for each individual ad.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}

==== Example Ad Object ====
<syntaxhighlight lang="javascript">
var adMetadataObject =
{
assetid: 'AD-1',
type: 'preroll'
};
</syntaxhighlight>
<br/>
<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

==== Call Nielsen APIs ====
The method for calling events is ggPM().

<syntaxhighlight lang="javascript">
nSdkInstance.ggPM('event', parameter, ...);
</syntaxhighlight>

== Interrupt Scenarios ==

=== Pause Event ===
The setPlayheadPostion event is used for handling pause. To indicate pause, stop passing the playhead position to the SDK. Once the content resumes, begin sending the playhead again with the correct playhead value.

=== Other Interrupt Scenarios ===
The following possible browser interruption scenarios must be handled:

* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button

There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. midroll vs. content).

<syntaxhighlight lang="javascript">
window.addEventListener('beforeunload', function(event)
{
// Only inside a midroll indicate <stop> for the ad
nSdkInstance.ggPM('stop', playheadPosition);

// Indicate <end> and <stop> for the content
nSdkInstance.ggPM('end', playheadPosition);
nSdkInstance.ggPM('stop', playheadPosition);
});
</syntaxhighlight>

<blockquote>'''Note:''' User may need to add code to support specific browser versions (e.g. older versions of Internet Explorer).</blockquote>

=== SDK Events ===
{| class="wikitable"
|-
! Event !! Parameter !! Description
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each asset
|-
| 'setPlayheadPosition' || playhead position as integer<br/>
VOD: || current position in seconds <br/>
Live: current UTC timestamp <br/>
Note: 'setPlayheadPosition' has to be called every second
||
Pass playhead position every second during playback
|-
| 'stop' || playhead position || Call when content or ads complete playing and pass playhead position
|-
| 'end' || playhead position in seconds || Call when the current video asset completes playback and pass the playhead position. <br/>
Example: At the end of the content stream, if the user switches to another piece of content, when the browser is refreshed or closed.
|}

== SDK Playhead Event Sequence ==
The sample event lifecycle can be used as a reference for identifying the order for calling events.

<syntaxhighlight lang="javascript">
// START OF STREAM
nSdkInstance.ggPM('loadMetadata', contentMetadataObject);

// PREROLL
nSdkInstance.ggPM('loadMetadata', prerollMetadataObject);
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
//
// pass playhead every second
//
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
nSdkInstance.ggPM('stop', playheadPosition);

// CONTENT
nSdkInstance.ggPM('loadMetadata', contentMetadataObject);
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
//
// pass playhead every second
//
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
nSdkInstance.ggPM('stop', playheadPosition);

// MIDROLL
nSdkInstance.ggPM('loadMetadata', midrollMetadataObject);
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
//
// pass playhead every second
//
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
nSdkInstance.ggPM('stop', playheadPosition);

// CONTENT
nSdkInstance.ggPM('loadMetadata', contentMetadataObject);
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
//
// pass playhead every second
//
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
nSdkInstance.ggPM('end', playheadPosition);

// POSTROLL
nSdkInstance.ggPM('loadmetadata', postrollMetadataObject);
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
//
// pass playhead every second
//
nSdkInstance.ggPM('setPlayheadPosition', playheadPosition);
nSdkInstance.ggPM('stop', playheadPosition);
</syntaxhighlight>
<blockquote>
* 'setPlayheadPosition' is used for calculating duration and must be passed every second. The final playhead position must be sent for the current asset being played before calling 'stop', 'end', or 'loadmetadata'.

* For Ad Pods, events must be called for each individual Ad. Each Ad playhead position should begin at ‘0’ when ad starts.

* When content has resumed following an ad break, the playhead position update must continue where previous content segment left off. The playhead position should be passed as a rounded number with no decimals.
</blockquote>

== Nielsen Opt-Out ==
The site must provide a means for the user to opt-out of, or opt back into, Nielsen Measurement. A user can opt-out if they would prefer not to participate in any Nielsen online measurement research. To implement the opt-out option, include the following two items in your privacy policy.
*A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings).
*A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

On the Nielsen Digital Measurement Privacy Policy page, users can click Choices to read more detailed information about the measurement software, learn about their options with regard to Nielsen measurement, and, if they do not want to participate in Nielsen online measurement, click a link to receive an opt-out cookie.

The following paragraph is a template for an opt-out statement.
<blockquote>
The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.
</blockquote>

=== Opt Back In ===
Once users have opted-out, they can choose to opt back into Nielsen Measurement at anytime by selecting the opt back in link on the Nielsen Digital Privacy Policy page. When a user selects the link, their opt-out cookie will be deleted and they will be able to be measured.

=== 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("PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance");
</syntaxhighlight>

Digital Pre-Certification Checklist Browser SDK

2017-09-28T22:54:32Z

RyanCarlson: '

== Pre-Certification Checklist - VOD with Ads ==
Before starting the certification process, please verify the following steps have been completed.
* Your Client Service representative should have already discussed a reporting hierarchy with you -- along with a Parent, Brand, and Sub-brand/Channel
* Your Technical Account Manager should have:
** provided you with an APID
** informed you of our Opt-Out requirement to be included in your Privacy Policy section of your site
** informed you to add the Static Queue Snippit on each page you wish to enable video measurement
** informed you that the apid, 'instanceName', and ‘nol_sdkDebug’ : ‘DEBUG’ should be present in the SDK initialization

== Initialization ==
The first step in the Certification process is to ensure that the Nielsen SDK is initializing on page load, and that the global metadata values are present.
{| class="wikitable"
|-
! Keys !! Value
|-
| apid || <code>PXXXXX-XXXXXX-XXXXX-XXXXX</code>
|-
| instanceName || <code>'nlsnInstance'</code>
|-
| nol_sdkDebug || <code>debug</code>
|}

'''Browser SDK Queue Snippit & Initialization Example'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
<script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||{nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[o]=t[o]||{g:c,ggPM:function(n,e,c,r,s){(t[o].q=t[o].q||[]).push([n,e,c,r,s])}},
t[o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

== Test Cases ==
The following lists the test cases along with the Expected results:
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| SDK Initialized || <code>apid</code> || Correct APID ||
|-
| || <code>instanceName</code> || SDK Instance Name ||
|-
| || <code>nol_sdkDebug</code> || <code>'DEBUG'</code> ||
|}

=== loadMetadata() - Content ===
* Called at beginning of content, or when resuming content from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== loadMetadata() - ad ===
* Called at beginning of ad, or when resuming ad from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>assetid</code> || <code>"ad_2201343201"</code> || (any non-empty value) ||
|-
| || <code>type</code> || <code>"midroll"</code> || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> || Example
|}

=== setPlayheadPosition() - Preroll ad ===
* Track current position of playhead
* Starts at 0 at the beginning of ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Ad ||
|}

=== loadMetadata() - Content ===
* Test is to validate Content metadata is the same as original metadata passed during initial loadMetadata call.
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== setPlayheadPosition() - Content ===
* Track current position of playhead
* Starts at 0 at the beginning of content
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second, and starts at 0 ||
|-
| <code>stop()</code> || Called at the end of each asset before transition ie. content to ad, ad to content, ad to ad ||
|}

=== stop() ===
* Should Be Called:
* Before each transition from ad to content, content to ad, or ad to ad
* Upon pause
* When playback is interrupted (connection lost, user exits video or page)

=== end() ===
* Reached the end of content
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>end</code> || Called once content has completed fully ||
|}

== Interruptions ==
* All interruptions to playback of content or ads should trigger a call to stop(). Once the interruption is over, loadMetadata() with the same metadata should be called, followed by playheadPosition resuming from where it left off.

* Interruptions include:
** user-induced pause
** screen turned off
** refresh page
** internet connection lost (n.b. cached playback plays as normal until it expires)
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| user-induced pause || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| screen turned off || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| internet connection lost || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| content paused || <code>playheadPosition</code> is not passed ||
|-
| resume content || <code>loadMetadata()</code> is called for content ||
|-
| || <code>loadMetadata()</code> is the same as original ||
|-
| || <code>playheadPosition</code> continues from resumed position ||
|}

'''Expected SDK behavior for all interruptions:'''
# interruption triggers stop() call
# when content resumes, loadMetadata() is called with the same metadata that was playing previously (ad or content)
# playheadPosition() resumes from the same position before the interruption

'''Example session:'''
* 5 minutes of content played, call interruption, content resumes until end of 15 min video

== Scrubbing ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| Scrub Backward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub Forward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub to end || final playhead position is passed ||
|-
| || end event called at completion of content playback ||
|-
| Scrub past midroll || Playhead for content stops ||
|}

== Midroll & Postroll Ads ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>loadMetadata()</code> || Called for each Ad ||
|-
| || Required Metadata is accurate ||
|-
| <code>playheadPosition</code> || Passed every second ||
|-
| <code>stop()</code> || called for each ad ||
|-
| <code>loadMetadata()</code>, <code>playheadPosition</code>, <code>stop()</code> || correct sequence for each ad ||
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of or opt back into Nielsen measurement. Include the following two items in the site’s Privacy Policy:
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy

The following paragraph is a template for an opt-out statement
Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

Digital Pre-Certification Checklist Browser SDK

2017-09-28T22:51:19Z

RyanCarlson: sdpfojidsf\

== Pre-Certification Checklist - VOD with Ads ==
Before starting the certification process, please verify the following steps have been completed.
* Your Client Service representative should have already discussed a reporting hierarchy with you -- along with a Parent, Brand, and Sub-brand/Channel
* Your Technical Account Manager should have:
** provided you with an APID
** informed you of our Opt-Out requirement to be included in your Privacy Policy section of your site
** informed you to add the Static Queue Snippit on each page you wish to enable video measurement
** informed you that the apid, 'instanceName', and ‘nol_sdkDebug’ : ‘DEBUG’ should be present in the SDK initialization

== Initialization ==
The first step in the Certification process is to ensure that the Nielsen SDK is initializing on page load, and that the global metadata values are present.
{| class="wikitable"
|-
! Keys !! Value
|-
| apid || <code>PXXXXX-XXXXXX-XXXXX-XXXXX</code>
|-
| instanceName || <code>'nlsnInstance'</code>
|-
| nol_sdkDebug || <code>debug</code>
|}

'''Browser SDK Queue Snippit & Initialization Example'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
<script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||{nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[o]=t[o]||{g:c,ggPM:function(n,e,c,r,s){(t[o].q=t[o].q||[]).push([n,e,c,r,s])}},
t[o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

== Test Cases ==
The following lists the test cases along with the Expected results:
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| SDK Initialized || <code>apid</code> || Correct APID ||
|-
| || <code>instanceName</code> || SDK Instance Name ||
|-
| || <code>nol_sdkDebug</code> || <code>'DEBUG</code> ||
|}

=== loadMetadata() - Content ===
* Called at beginning of content, or when resuming content from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== loadMetadata() - ad ===
* Called at beginning of ad, or when resuming ad from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>assetid</code> || <code>"ad_2201343201"</code> || (any non-empty value) ||
|-
| || <code>type</code> || <code>"midroll"</code> || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> || Example
|}

=== setPlayheadPosition() - Preroll ad ===
* Track current position of playhead
* Starts at 0 at the beginning of ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Ad ||
|}

=== loadMetadata() - Content ===
* Test is to validate Content metadata is the same as original metadata passed during initial loadMetadata call.
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== setPlayheadPosition() - Content ===
* Track current position of playhead
* Starts at 0 at the beginning of content
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second, and starts at 0 ||
|-
| <code>stop()</code> || Called at the end of each asset before transition ie. content to ad, ad to content, ad to ad ||
|}

=== stop() ===
* Should Be Called:
* Before each transition from ad to content, content to ad, or ad to ad
* Upon pause
* When playback is interrupted (connection lost, user exits video or page)

=== end() ===
* Reached the end of content
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>end</code> || Called once content has completed fully ||
|}

== Interruptions ==
* All interruptions to playback of content or ads should trigger a call to stop(). Once the interruption is over, loadMetadata() with the same metadata should be called, followed by playheadPosition resuming from where it left off.

* Interruptions include:
** user-induced pause
** screen turned off
** refresh page
** internet connection lost (n.b. cached playback plays as normal until it expires)
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| user-induced pause || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| screen turned off || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| internet connection lost || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| content paused || <code>playheadPosition</code> is not passed ||
|-
| resume content || <code>loadMetadata()</code> is called for content ||
|-
| || <code>loadMetadata()</code> is the same as original ||
|-
| || <code>playheadPosition</code> continues from resumed position ||
|}

'''Expected SDK behavior for all interruptions:'''
# interruption triggers stop() call
# when content resumes, loadMetadata() is called with the same metadata that was playing previously (ad or content)
# playheadPosition() resumes from the same position before the interruption

'''Example session:'''
* 5 minutes of content played, call interruption, content resumes until end of 15 min video

== Scrubbing ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| Scrub Backward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub Forward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub to end || final playhead position is passed ||
|-
| || end event called at completion of content playback ||
|-
| Scrub past midroll || Playhead for content stops ||
|}

== Midroll & Postroll Ads ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>loadMetadata()</code> || Called for each Ad ||
|-
| || Required Metadata is accurate ||
|-
| <code>playheadPosition</code> || Passed every second ||
|-
| <code>stop()</code> || called for each ad ||
|-
| <code>loadMetadata()</code>, <code>playheadPosition</code>, <code>stop()</code> || correct sequence for each ad ||
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of or opt back into Nielsen measurement. Include the following two items in the site’s Privacy Policy:
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy

The following paragraph is a template for an opt-out statement
Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

Digital Pre-Certification Checklist Browser SDK

2017-09-28T22:50:57Z

RyanCarlson: yes

== Pre-Certification Checklist - VOD with Ads ==
Before starting the certification process, please verify the following steps have been completed.
* Your Client Service representative should have already discussed a reporting hierarchy with you -- along with a Parent, Brand, and Sub-brand/Channel
* Your Technical Account Manager should have:
** provided you with an APID
** informed you of our Opt-Out requirement to be included in your Privacy Policy section of your site
** informed you to add the Static Queue Snippit on each page you wish to enable video measurement
** informed you that the apid, 'instanceName', and ‘nol_sdkDebug’ : ‘DEBUG’ should be present in the SDK initialization

== Initialization ==
The first step in the Certification process is to ensure that the Nielsen SDK is initializing on page load, and that the global metadata values are present.
{| class="wikitable"
|-
! Keys !! Value
|-
| apid || <code>PXXXXX-XXXXXX-XXXXX-XXXXX</code>
|-
| instanceName || <code>'nlsnInstance'</code>
|-
| nol_sdkDebug || <code>debug</code>
|}

'''Browser SDK Queue Snippit & Initialization Example'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
<script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||{nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[o]=t[o]||{g:c,ggPM:function(n,e,c,r,s){(t[o].q=t[o].q||[]).push([n,e,c,r,s])}},
t[o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

== Test Cases ==
The following lists the test cases along with the Expected results:
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| SDK Initialized || <code>apid</code> || Correct APID ||
|-
| || <code>instanceName</code> || SDK Instance Name ||
|-
| || <code>nol_sdkDebug</code> || <code>'DEBUG</code> ||
|}

=== loadMetadata() - Content ===
* Called at beginning of content, or when resuming content from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== loadMetadata() - ad ===
* Called at beginning of ad, or when resuming ad from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>assetid</code> || <code>"ad_2201343201"</code> || (any non-empty value) ||
|-
| || <code>type</code> || <code>"midroll"</code> || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> || Example
|}

=== setPlayheadPosition() - Preroll ad ===
* Track current position of playhead
* Starts at 0 at the beginning of ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Ad ||
|}

=== loadMetadata() - Content ===
* Test is to validate Content metadata is the same as original metadata passed during initial loadMetadata call.
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== setPlayheadPosition() - Content ===
* Track current position of playhead
* Starts at 0 at the beginning of content
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second, and starts at 0 ||
|-
| <code>stop()</code> || Called at the end of each asset before transition ie. content to ad, ad to content, ad to ad ||
|}

=== stop() ===
* Should Be Called:
* Before each transition from ad to content, content to ad, or ad to ad
* Upon pause
* When playback is interrupted (connection lost, user exits video or page)

=== end() ===
* Reached the end of content
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>end</code> || Called once content has completed fully ||
|}

== Interruptions ==
* All interruptions to playback of content or ads should trigger a call to stop(). Once the interruption is over, loadMetadata() with the same metadata should be called, followed by playheadPosition resuming from where it left off.

* Interruptions include:
** user-induced pause
** screen turned off
** refresh page
** internet connection lost (n.b. cached playback plays as normal until it expires)
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| user-induced pause || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| screen turned off || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| internet connection lost || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| content paused || <code>playheadPosition</code> is not passed ||
|-
| resume content || <code>loadMetadata()</code> is called for content ||
|-
| || <code>loadMetadataM</code> is the same as original ||
|-
| || <code>playheadPosition</code> continues from resumed position ||
|}

'''Expected SDK behavior for all interruptions:'''
# interruption triggers stop() call
# when content resumes, loadMetadata() is called with the same metadata that was playing previously (ad or content)
# playheadPosition() resumes from the same position before the interruption

'''Example session:'''
* 5 minutes of content played, call interruption, content resumes until end of 15 min video

== Scrubbing ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| Scrub Backward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub Forward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub to end || final playhead position is passed ||
|-
| || end event called at completion of content playback ||
|-
| Scrub past midroll || Playhead for content stops ||
|}

== Midroll & Postroll Ads ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>loadMetadata()</code> || Called for each Ad ||
|-
| || Required Metadata is accurate ||
|-
| <code>playheadPosition</code> || Passed every second ||
|-
| <code>stop()</code> || called for each ad ||
|-
| <code>loadMetadata()</code>, <code>playheadPosition</code>, <code>stop()</code> || correct sequence for each ad ||
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of or opt back into Nielsen measurement. Include the following two items in the site’s Privacy Policy:
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy

The following paragraph is a template for an opt-out statement
Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

Digital Pre-Certification Checklist Browser SDK

2017-09-28T22:50:17Z

RyanCarlson: stop

== Pre-Certification Checklist - VOD with Ads ==
Before starting the certification process, please verify the following steps have been completed.
* Your Client Service representative should have already discussed a reporting hierarchy with you -- along with a Parent, Brand, and Sub-brand/Channel
* Your Technical Account Manager should have:
** provided you with an APID
** informed you of our Opt-Out requirement to be included in your Privacy Policy section of your site
** informed you to add the Static Queue Snippit on each page you wish to enable video measurement
** informed you that the apid, 'instanceName', and ‘nol_sdkDebug’ : ‘DEBUG’ should be present in the SDK initialization

== Initialization ==
The first step in the Certification process is to ensure that the Nielsen SDK is initializing on page load, and that the global metadata values are present.
{| class="wikitable"
|-
! Keys !! Value
|-
| apid || <code>PXXXXX-XXXXXX-XXXXX-XXXXX</code>
|-
| instanceName || <code>'nlsnInstance'</code>
|-
| nol_sdkDebug || <code>debug</code>
|}

'''Browser SDK Queue Snippit & Initialization Example'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
<script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||{nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[o]=t[o]||{g:c,ggPM:function(n,e,c,r,s){(t[o].q=t[o].q||[]).push([n,e,c,r,s])}},
t[o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

== Test Cases ==
The following lists the test cases along with the Expected results:
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| SDK Initialized || <code>apid</code> || Correct APID ||
|-
| || <code>instanceName</code> || SDK Instance Name ||
|-
| || <code>nol_sdkDebug</code> || <code>'DEBUG</code> ||
|}

=== loadMetadata() - Content ===
* Called at beginning of content, or when resuming content from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== loadMetadata() - ad ===
* Called at beginning of ad, or when resuming ad from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>assetid</code> || <code>"ad_2201343201"</code> || (any non-empty value) ||
|-
| || <code>type</code> || <code>"midroll"</code> || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> || Example
|}

=== setPlayheadPosition() - Preroll ad ===
* Track current position of playhead
* Starts at 0 at the beginning of ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Ad ||
|}

=== loadMetadata() - Content ===
* Test is to validate Content metadata is the same as original metadata passed during initial loadMetadata call.
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== setPlayheadPosition() - Content ===
* Track current position of playhead
* Starts at 0 at the beginning of content
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second, and starts at 0 ||
|-
| <code>stop()</code> || Called at the end of each asset before transition ie. content to ad, ad to content, ad to ad ||
|}

=== stop() ===
* Should Be Called:
* Before each transition from ad to content, content to ad, or ad to ad
* Upon pause
* When playback is interrupted (connection lost, user exits video or page)

=== end() ===
* Reached the end of content
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>end</code> || Called once content has completed fully ||
|}

== Interruptions ==
* All interruptions to playback of content or ads should trigger a call to stop(). Once the interruption is over, loadMetadata() with the same metadata should be called, followed by playheadPosition resuming from where it left off.

* Interruptions include:
** user-induced pause
** screen turned off
** refresh page
** internet connection lost (n.b. cached playback plays as normal until it expires)
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| user-induced pause || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| screen turned off || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| app sent to background || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| headphones removed || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| alarm/call interruption || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| internet connection lost || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| content paused || <code>playheadPosition</code> is not passed ||
|-
| resume content || <code>loadMetadata()</code> is called for content ||
|-
| || <code>loadMetadataM</code> is the same as original ||
|-
| || <code>playheadPosition</code> continues from resumed position ||
|}

'''Expected SDK behavior for all interruptions:'''
# interruption triggers stop() call
# when content resumes, loadMetadata() is called with the same metadata that was playing previously (ad or content)
# playheadPosition() resumes from the same position before the interruption

'''Example session:'''
* 5 minutes of content played, call interruption, content resumes until end of 15 min video

== Scrubbing ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| Scrub Backward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub Forward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub to end || final playhead position is passed ||
|-
| || end event called at completion of content playback ||
|-
| Scrub past midroll || Playhead for content stops ||
|}

== Midroll & Postroll Ads ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>loadMetadata()</code> || Called for each Ad ||
|-
| || Required Metadata is accurate ||
|-
| <code>playheadPosition</code> || Passed every second ||
|-
| <code>stop()</code> || called for each ad ||
|-
| <code>loadMetadata()</code>, <code>playheadPosition</code>, <code>stop()</code> || correct sequence for each ad ||
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of or opt back into Nielsen measurement. Include the following two items in the site’s Privacy Policy:
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy

The following paragraph is a template for an opt-out statement
Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

Digital Pre-Certification Checklist Browser SDK

2017-09-28T22:48:30Z

RyanCarlson: end

== Pre-Certification Checklist - VOD with Ads ==
Before starting the certification process, please verify the following steps have been completed.
* Your Client Service representative should have already discussed a reporting hierarchy with you -- along with a Parent, Brand, and Sub-brand/Channel
* Your Technical Account Manager should have:
** provided you with an APID
** informed you of our Opt-Out requirement to be included in your Privacy Policy section of your site
** informed you to add the Static Queue Snippit on each page you wish to enable video measurement
** informed you that the apid, 'instanceName', and ‘nol_sdkDebug’ : ‘DEBUG’ should be present in the SDK initialization

== Initialization ==
The first step in the Certification process is to ensure that the Nielsen SDK is initializing on page load, and that the global metadata values are present.
{| class="wikitable"
|-
! Keys !! Value
|-
| apid || <code>PXXXXX-XXXXXX-XXXXX-XXXXX</code>
|-
| instanceName || <code>'nlsnInstance'</code>
|-
| nol_sdkDebug || <code>debug</code>
|}

'''Browser SDK Queue Snippit & Initialization Example'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
<script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||{nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[o]=t[o]||{g:c,ggPM:function(n,e,c,r,s){(t[o].q=t[o].q||[]).push([n,e,c,r,s])}},
t[o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

== Test Cases ==
The following lists the test cases along with the Expected results:
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| SDK Initialized || <code>apid</code> || Correct APID ||
|-
| || <code>instanceName</code> || SDK Instance Name ||
|-
| || <code>nol_sdkDebug</code> || <code>'DEBUG</code> ||
|}

=== loadMetadata() - Content ===
* Called at beginning of content, or when resuming content from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== loadMetadata() - ad ===
* Called at beginning of ad, or when resuming ad from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>assetid</code> || <code>"ad_2201343201"</code> || (any non-empty value) ||
|-
| || <code>type</code> || <code>"midroll"</code> || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> || Example
|}

=== setPlayheadPosition() - Preroll ad ===
* Track current position of playhead
* Starts at 0 at the beginning of ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Ad ||
|}

=== loadMetadata() - Content ===
* Test is to validate Content metadata is the same as original metadata passed during initial loadMetadata call.
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== setPlayheadPosition() - Content ===
* Track current position of playhead
* Starts at 0 at the beginning of content
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second, and starts at 0 ||
|-
| <code>stop()</code> || Called at the end of each asset before transition ie. content to ad, ad to content, ad to ad ||
|}

=== stop() ===
* Indicates one of the following:
* Playback of content or ad was interrupted
* Reached end of ad

=== end() ===
* Reached the end of content
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>end</code> || Called once content has completed fully ||
|}

== Interruptions ==
* All interruptions to playback of content or ads should trigger a call to stop(). Once the interruption is over, loadMetadata() with the same metadata should be called, followed by playheadPosition resuming from where it left off.

* Interruptions include:
** user-induced pause
** screen turned off
** refresh page
** internet connection lost (n.b. cached playback plays as normal until it expires)
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| user-induced pause || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| screen turned off || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| app sent to background || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| headphones removed || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| alarm/call interruption || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| internet connection lost || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| content paused || <code>playheadPosition</code> is not passed ||
|-
| resume content || <code>loadMetadata()</code> is called for content ||
|-
| || <code>loadMetadataM</code> is the same as original ||
|-
| || <code>playheadPosition</code> continues from resumed position ||
|}

'''Expected SDK behavior for all interruptions:'''
# interruption triggers stop() call
# when content resumes, loadMetadata() is called with the same metadata that was playing previously (ad or content)
# playheadPosition() resumes from the same position before the interruption

'''Example session:'''
* 5 minutes of content played, call interruption, content resumes until end of 15 min video

== Scrubbing ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| Scrub Backward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub Forward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub to end || final playhead position is passed ||
|-
| || end event called at completion of content playback ||
|-
| Scrub past midroll || Playhead for content stops ||
|}

== Midroll & Postroll Ads ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>loadMetadata()</code> || Called for each Ad ||
|-
| || Required Metadata is accurate ||
|-
| <code>playheadPosition</code> || Passed every second ||
|-
| <code>stop()</code> || called for each ad ||
|-
| <code>loadMetadata()</code>, <code>playheadPosition</code>, <code>stop()</code> || correct sequence for each ad ||
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of or opt back into Nielsen measurement. Include the following two items in the site’s Privacy Policy:
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy

The following paragraph is a template for an opt-out statement
Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

Digital Pre-Certification Checklist Browser SDK

2017-09-28T22:47:06Z

RyanCarlson: stop

== Pre-Certification Checklist - VOD with Ads ==
Before starting the certification process, please verify the following steps have been completed.
* Your Client Service representative should have already discussed a reporting hierarchy with you -- along with a Parent, Brand, and Sub-brand/Channel
* Your Technical Account Manager should have:
** provided you with an APID
** informed you of our Opt-Out requirement to be included in your Privacy Policy section of your site
** informed you to add the Static Queue Snippit on each page you wish to enable video measurement
** informed you that the apid, 'instanceName', and ‘nol_sdkDebug’ : ‘DEBUG’ should be present in the SDK initialization

== Initialization ==
The first step in the Certification process is to ensure that the Nielsen SDK is initializing on page load, and that the global metadata values are present.
{| class="wikitable"
|-
! Keys !! Value
|-
| apid || <code>PXXXXX-XXXXXX-XXXXX-XXXXX</code>
|-
| instanceName || <code>'nlsnInstance'</code>
|-
| nol_sdkDebug || <code>debug</code>
|}

'''Browser SDK Queue Snippit & Initialization Example'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
<script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||{nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[o]=t[o]||{g:c,ggPM:function(n,e,c,r,s){(t[o].q=t[o].q||[]).push([n,e,c,r,s])}},
t[o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

== Test Cases ==
The following lists the test cases along with the Expected results:
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| SDK Initialized || <code>apid</code> || Correct APID ||
|-
| || <code>instanceName</code> || SDK Instance Name ||
|-
| || <code>nol_sdkDebug</code> || <code>'DEBUG</code> ||
|}

=== loadMetadata() - Content ===
* Called at beginning of content, or when resuming content from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== loadMetadata() - ad ===
* Called at beginning of ad, or when resuming ad from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>assetid</code> || <code>"ad_2201343201"</code> || (any non-empty value) ||
|-
| || <code>type</code> || <code>"midroll"</code> || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> || Example
|}

=== setPlayheadPosition() - Preroll ad ===
* Track current position of playhead
* Starts at 0 at the beginning of ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Ad ||
|}

=== loadMetadata() - Content ===
* Test is to validate Content metadata is the same as original metadata passed during initial loadMetadata call.
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== setPlayheadPosition() - Content ===
* Track current position of playhead
* Starts at 0 at the beginning of content
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second, and starts at 0 ||
|-
| <code>stop()</code> || Called at the end of each asset before transition ie. content to ad, ad to content, ad to ad ||
|}

=== stop() ===
* Indicates one of the following:
* Playback of content or ad was interrupted
* Reached end of ad

=== end() ===
* Reached the end of content

== Interruptions ==
* All interruptions to playback of content or ads should trigger a call to stop(). Once the interruption is over, loadMetadata() with the same metadata should be called, followed by playheadPosition resuming from where it left off.

* Interruptions include:
** user-induced pause
** screen turned off
** refresh page
** internet connection lost (n.b. cached playback plays as normal until it expires)
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| user-induced pause || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| screen turned off || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| app sent to background || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| headphones removed || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| alarm/call interruption || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| internet connection lost || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| content paused || <code>playheadPosition</code> is not passed ||
|-
| resume content || <code>loadMetadata()</code> is called for content ||
|-
| || <code>loadMetadataM</code> is the same as original ||
|-
| || <code>playheadPosition</code> continues from resumed position ||
|}

'''Expected SDK behavior for all interruptions:'''
# interruption triggers stop() call
# when content resumes, loadMetadata() is called with the same metadata that was playing previously (ad or content)
# playheadPosition() resumes from the same position before the interruption

'''Example session:'''
* 5 minutes of content played, call interruption, content resumes until end of 15 min video

== Scrubbing ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| Scrub Backward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub Forward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub to end || final playhead position is passed ||
|-
| || end event called at completion of content playback ||
|-
| Scrub past midroll || Playhead for content stops ||
|}

== Midroll & Postroll Ads ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>loadMetadata()</code> || Called for each Ad ||
|-
| || Required Metadata is accurate ||
|-
| <code>playheadPosition</code> || Passed every second ||
|-
| <code>stop()</code> || called for each ad ||
|-
| <code>loadMetadata()</code>, <code>playheadPosition</code>, <code>stop()</code> || correct sequence for each ad ||
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of or opt back into Nielsen measurement. Include the following two items in the site’s Privacy Policy:
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy

The following paragraph is a template for an opt-out statement
Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

Digital Pre-Certification Checklist Browser SDK

2017-09-28T22:46:05Z

RyanCarlson: got rid of stuff

== Pre-Certification Checklist - VOD with Ads ==
Before starting the certification process, please verify the following steps have been completed.
* Your Client Service representative should have already discussed a reporting hierarchy with you -- along with a Parent, Brand, and Sub-brand/Channel
* Your Technical Account Manager should have:
** provided you with an APID
** informed you of our Opt-Out requirement to be included in your Privacy Policy section of your site
** informed you to add the Static Queue Snippit on each page you wish to enable video measurement
** informed you that the apid, 'instanceName', and ‘nol_sdkDebug’ : ‘DEBUG’ should be present in the SDK initialization

== Initialization ==
The first step in the Certification process is to ensure that the Nielsen SDK is initializing on page load, and that the global metadata values are present.
{| class="wikitable"
|-
! Keys !! Value
|-
| apid || <code>PXXXXX-XXXXXX-XXXXX-XXXXX</code>
|-
| instanceName || <code>'nlsnInstance'</code>
|-
| nol_sdkDebug || <code>debug</code>
|}

'''Browser SDK Queue Snippit & Initialization Example'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
<script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||{nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[o]=t[o]||{g:c,ggPM:function(n,e,c,r,s){(t[o].q=t[o].q||[]).push([n,e,c,r,s])}},
t[o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

== Test Cases ==
The following lists the test cases along with the Expected results:
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| SDK Initialized || <code>apid</code> || Correct APID ||
|-
| || <code>instanceName</code> || SDK Instance Name ||
|-
| || <code>nol_sdkDebug</code> || <code>'DEBUG</code> ||
|}

=== loadMetadata() - Content ===
* Called at beginning of content, or when resuming content from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== loadMetadata() - ad ===
* Called at beginning of ad, or when resuming ad from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>assetid</code> || <code>"ad_2201343201"</code> || (any non-empty value) ||
|-
| || <code>type</code> || <code>"midroll"</code> || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> || Example
|}

=== setPlayheadPosition() - Preroll ad ===
* Track current position of playhead
* Starts at 0 at the beginning of ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Ad ||
|}

=== loadMetadata() - Content ===
* Test is to validate Content metadata is the same as original metadata passed during initial loadMetadata call.
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== setPlayheadPosition() - Content ===
* Track current position of playhead
* Starts at 0 at the beginning of content
* Starts at 0 at the beginning of each ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of each asset before transition ie. content to ad, ad to content, ad to ad ||
|}

=== stop() ===
* Indicates one of the following:
* Playback of content or ad was interrupted
* Reached end of ad

=== end() ===
* Reached the end of content

== Interruptions ==
* All interruptions to playback of content or ads should trigger a call to stop(). Once the interruption is over, loadMetadata() with the same metadata should be called, followed by playheadPosition resuming from where it left off.

* Interruptions include:
** user-induced pause
** screen turned off
** refresh page
** internet connection lost (n.b. cached playback plays as normal until it expires)
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| user-induced pause || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| screen turned off || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| app sent to background || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| headphones removed || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| alarm/call interruption || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| internet connection lost || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| content paused || <code>playheadPosition</code> is not passed ||
|-
| resume content || <code>loadMetadata()</code> is called for content ||
|-
| || <code>loadMetadataM</code> is the same as original ||
|-
| || <code>playheadPosition</code> continues from resumed position ||
|}

'''Expected SDK behavior for all interruptions:'''
# interruption triggers stop() call
# when content resumes, loadMetadata() is called with the same metadata that was playing previously (ad or content)
# playheadPosition() resumes from the same position before the interruption

'''Example session:'''
* 5 minutes of content played, call interruption, content resumes until end of 15 min video

== Scrubbing ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| Scrub Backward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub Forward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub to end || final playhead position is passed ||
|-
| || end event called at completion of content playback ||
|-
| Scrub past midroll || Playhead for content stops ||
|}

== Midroll & Postroll Ads ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>loadMetadata()</code> || Called for each Ad ||
|-
| || Required Metadata is accurate ||
|-
| <code>playheadPosition</code> || Passed every second ||
|-
| <code>stop()</code> || called for each ad ||
|-
| <code>loadMetadata()</code>, <code>playheadPosition</code>, <code>stop()</code> || correct sequence for each ad ||
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of or opt back into Nielsen measurement. Include the following two items in the site’s Privacy Policy:
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy

The following paragraph is a template for an opt-out statement
Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

Digital Pre-Certification Checklist Browser SDK

2017-09-28T22:45:24Z

RyanCarlson: deleted things

== Pre-Certification Checklist - VOD with Ads ==
Before starting the certification process, please verify the following steps have been completed.
* Your Client Service representative should have already discussed a reporting hierarchy with you -- along with a Parent, Brand, and Sub-brand/Channel
* Your Technical Account Manager should have:
** provided you with an APID
** informed you of our Opt-Out requirement to be included in your Privacy Policy section of your site
** informed you to add the Static Queue Snippit on each page you wish to enable video measurement
** informed you that the apid, 'instanceName', and ‘nol_sdkDebug’ : ‘DEBUG’ should be present in the SDK initialization

== Initialization ==
The first step in the Certification process is to ensure that the Nielsen SDK is initializing on page load, and that the global metadata values are present.
{| class="wikitable"
|-
! Keys !! Value
|-
| apid || <code>PXXXXX-XXXXXX-XXXXX-XXXXX</code>
|-
| instanceName || <code>'nlsnInstance'</code>
|-
| nol_sdkDebug || <code>debug</code>
|}

'''Browser SDK Queue Snippit & Initialization Example'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
<script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||{nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[o]=t[o]||{g:c,ggPM:function(n,e,c,r,s){(t[o].q=t[o].q||[]).push([n,e,c,r,s])}},
t[o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

== Test Cases ==
The following lists the test cases along with the Expected results:
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| SDK Initialized || <code>apid</code> || Correct APID ||
|-
| || <code>instanceName</code> || SDK Instance Name ||
|-
| || <code>nol_sdkDebug</code> || <code>'DEBUG</code> ||
|}

=== loadMetadata() - Content ===
* Called at beginning of content, or when resuming content from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== loadMetadata() - ad ===
* Called at beginning of ad, or when resuming ad from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>assetid</code> || <code>"ad_2201343201"</code> || (any non-empty value) ||
|-
| || <code>type</code> || <code>"midroll"</code> || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> || Example
|}

=== setPlayheadPosition() - Preroll ad ===
* Track current position of playhead
* Starts at 0 at the beginning of ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Ad ||
|}

=== loadMetadata() - Content ===
* Test is to validate Content metadata is the same as original metadata passed during initial loadMetadata call.
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== setPlayheadPosition() - Content ===
* Track current position of playhead
* Starts at 0 at the beginning of content
* Starts at 0 at the beginning of each ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of each asset before transition ie. content to ad, ad to content, ad to ad ||
|}

=== stop() ===
* Indicates one of the following:
* Playback of content or ad was interrupted
* Reached end of ad

=== end() ===
* Reached the end of content

== Interruptions ==
* All interruptions to playback of content or ads should trigger a call to stop(). Once the interruption is over, loadMetadata() with the same metadata should be called, followed by playheadPosition resuming from where it left off.

* Interruptions include:
** user-induced pause
** screen turned off
** refresh page
** internet connection lost (n.b. cached playback plays as normal until it expires)
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| user-induced pause || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| screen turned off || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| app sent to background || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| headphones removed || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| alarm/call interruption || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| internet connection lost || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| content paused || <code>playheadPosition</code> is not passed ||
|-
| resume content || <code>loadMetadata()</code> is called for content ||
|-
| || <code>loadMetadataM</code> is the same as original ||
|-
| || <code>playheadPosition</code> continues from resumed position ||
|}

'''Expected SDK behavior for all interruptions:'''
# interruption triggers stop() call
# when content resumes, loadMetadata() is called with the same metadata that was playing previously (ad or content)
# playheadPosition() resumes from the same position before the interruption

'''Example session:'''
* 5 minutes of content played, call interruption, content resumes until end of 15 min video

== Scrubbing ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| Scrub Backward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub Forward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub to end || final playhead position is passed ||
|-
| || end event called at completion of content playback ||
|-
| Scrub past midroll || Playhead for content stops ||
|}

== Midroll & Postroll Ads ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>loadMetadata()</code> || Called for each Ad ||
|-
| || Required Metadata is accurate ||
|-
| <code>playheadPosition</code> || Passed every second ||
|-
| <code>stop()</code> || called for each ad ||
|-
| <code>loadMetadata()</code>, <code>playheadPosition</code>, <code>stop()</code> || correct sequence for each ad ||
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of or opt back into Nielsen measurement. Include the following two items in the site’s Privacy Policy:
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy

The following paragraph is a template for an opt-out statement
Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

Digital Pre-Certification Checklist Browser SDK

2017-09-28T22:43:44Z

RyanCarlson: dfgiojdfgjoi

== Pre-Certification Checklist - VOD with Ads ==
Before starting the certification process, please verify the following steps have been completed.
* Your Client Service representative should have already discussed a reporting hierarchy with you -- along with a Parent, Brand, and Sub-brand/Channel
* Your Technical Account Manager should have:
** provided you with an APID
** informed you of our Opt-Out requirement to be included in your Privacy Policy section of your site
** informed you to add the Static Queue Snippit on each page you wish to enable video measurement
** informed you that the apid, 'instanceName', and ‘nol_sdkDebug’ : ‘DEBUG’ should be present in the SDK initialization

== Initialization ==
The first step in the Certification process is to ensure that the Nielsen SDK is initializing on page load, and that the global metadata values are present.
{| class="wikitable"
|-
! Keys !! Value
|-
| apid || <code>PXXXXX-XXXXXX-XXXXX-XXXXX</code>
|-
| instanceName || <code>'nlsnInstance'</code>
|-
| nol_sdkDebug || <code>debug</code>
|}

'''Browser SDK Queue Snippit & Initialization Example'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
<script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||{nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[o]=t[o]||{g:c,ggPM:function(n,e,c,r,s){(t[o].q=t[o].q||[]).push([n,e,c,r,s])}},
t[o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

== Test Cases ==
The following lists the test cases along with the Expected results:
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| SDK Initialized || <code>apid</code> || Correct APID ||
|-
| || <code>instanceName</code> || SDK Instance Name ||
|-
| || <code>nol_sdkDebug</code> || <code>'DEBUG</code> ||
|}

=== play() ===
* The <code>play()</code> call is required only once per viewing session (until app is killed)
* Called just before playback commences for first piece of content
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| Play || <code>channelname</code> || Name of Channel ||
|}

=== loadMetadata() - Content ===
* Called at beginning of content, or when resuming content from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== loadMetadata() - ad ===
* Called at beginning of ad, or when resuming ad from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>assetid</code> || <code>"ad_2201343201"</code> || (any non-empty value) ||
|-
| || <code>type</code> || <code>"midroll"</code> || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> || Example
|}

=== setPlayheadPosition() - Preroll ad ===
* Track current position of playhead
* Starts at 0 at the beginning of ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Ad ||
|}

=== loadMetadata() - Content ===
* Test is to validate Content metadata is the same as original metadata passed during initial loadMetadata call.
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== setPlayheadPosition() - Content ===
* Track current position of playhead
* Starts at 0 at the beginning of content
* Starts at 0 at the beginning of each ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of each asset before transition ie. content to ad, ad to content, ad to ad ||
|}

=== stop() ===
* Indicates one of the following:
* Playback of content or ad was interrupted
* Reached end of ad

=== end() ===
* Reached the end of content

== Interruptions ==
* All interruptions to playback of content or ads should trigger a call to stop(). Once the interruption is over, loadMetadata() with the same metadata should be called, followed by playheadPosition resuming from where it left off.

* Interruptions include:
** user-induced pause
** screen turned off
** refresh page
** internet connection lost (n.b. cached playback plays as normal until it expires)
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| user-induced pause || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| screen turned off || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| app sent to background || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| headphones removed || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| alarm/call interruption || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| internet connection lost || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| content paused || <code>playheadPosition</code> is not passed ||
|-
| resume content || <code>loadMetadata()</code> is called for content ||
|-
| || <code>loadMetadataM</code> is the same as original ||
|-
| || <code>playheadPosition</code> continues from resumed position ||
|}

'''Expected SDK behavior for all interruptions:'''
# interruption triggers stop() call
# when content resumes, loadMetadata() is called with the same metadata that was playing previously (ad or content)
# playheadPosition() resumes from the same position before the interruption

'''Example session:'''
* 5 minutes of content played, call interruption, content resumes until end of 15 min video

== Scrubbing ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| Scrub Backward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub Forward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub to end || final playhead position is passed ||
|-
| || end event called at completion of content playback ||
|-
| Scrub past midroll || Playhead for content stops ||
|}

== Midroll & Postroll Ads ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>loadMetadata()</code> || Called for each Ad ||
|-
| || Required Metadata is accurate ||
|-
| <code>playheadPosition</code> || Passed every second ||
|-
| <code>stop()</code> || called for each ad ||
|-
| <code>loadMetadata()</code>, <code>playheadPosition</code>, <code>stop()</code> || correct sequence for each ad ||
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of or opt back into Nielsen measurement. Include the following two items in the site’s Privacy Policy:
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy

The following paragraph is a template for an opt-out statement
Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

Digital Pre-Certification Checklist Browser SDK

2017-09-28T22:40:14Z

RyanCarlson: stop

== Pre-Certification Checklist - VOD with Ads ==
Before starting the certification process, please verify the following steps have been completed.
* Your Client Service representative should have already discussed a reporting hierarchy with you -- along with a Parent, Brand, and Sub-brand/Channel
* Your Technical Account Manager should have:
** provided you with an APID
** informed you of our Opt-Out requirement to be included in your Privacy Policy section of your site
** informed you to add the Static Queue Snippit on each page you wish to enable video measurement
** informed you that the apid, 'instanceName', and ‘nol_sdkDebug’ : ‘DEBUG’ should be present in the SDK initialization

== Initialization ==
The first step in the Certification process is to ensure that the Nielsen SDK is initializing on page load, and that the global metadata values are present.
{| class="wikitable"
|-
! Keys !! Value
|-
| apid || <code>PXXXXX-XXXXXX-XXXXX-XXXXX</code>
|-
| instanceName || <code>'nlsnInstance'</code>
|-
| nol_sdkDebug || <code>debug</code>
|}

'''Browser SDK Queue Snippit & Initialization Example'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
<script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||{nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[o]=t[o]||{g:c,ggPM:function(n,e,c,r,s){(t[o].q=t[o].q||[]).push([n,e,c,r,s])}},
t[o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

== Test Cases ==
The following lists the test cases along with the Expected results:
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| SDK Initialized || <code>apid</code> || Correct APID ||
|-
| || <code>instanceName</code> || SDK Instance Name ||
|-
| || <code>nol_sdkDebug</code> || <code>'DEBUG</code> ||
|}

=== play() ===
* The <code>play()</code> call is required only once per viewing session (until app is killed)
* Called just before playback commences for first piece of content
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| Play || <code>channelname</code> || Name of Channel ||
|}

=== loadMetadata() - Content ===
* Called at beginning of content, or when resuming content from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== loadMetadata() - ad ===
* Called at beginning of ad, or when resuming ad from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>assetid</code> || <code>"ad_2201343201"</code> || (any non-empty value) ||
|-
| || <code>type</code> || <code>"midroll"</code> || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> || Example
|}

=== setPlayheadPosition() - Preroll ad ===
* Track current position of playhead
* Starts at 0 at the beginning of ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Ad ||
|}

=== loadMetadata() - Content ===
* Test is to validate Content metadata is the same as original metadata passed during initial loadMetadata call.
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== setPlayheadPosition() - Content ===
* Track current position of playhead
* Starts at 0 at the beginning of content
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Content ||
|}

=== stop() ===
* Indicates one of the following:
* Playback of content or ad was interrupted
* Reached end of ad

=== end() ===
* Reached the end of content

== Interruptions ==
* All interruptions to playback of content or ads should trigger a call to stop(). Once the interruption is over, loadMetadata() with the same metadata should be called, followed by playheadPosition resuming from where it left off.

* Interruptions include:
** user-induced pause
** screen turned off
** refresh page
** internet connection lost (n.b. cached playback plays as normal until it expires)
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| user-induced pause || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| screen turned off || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| app sent to background || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| headphones removed || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| alarm/call interruption || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| internet connection lost || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| content paused || <code>playheadPosition</code> is not passed ||
|-
| resume content || <code>loadMetadata()</code> is called for content ||
|-
| || <code>loadMetadataM</code> is the same as original ||
|-
| || <code>playheadPosition</code> continues from resumed position ||
|}

'''Expected SDK behavior for all interruptions:'''
# interruption triggers stop() call
# when content resumes, loadMetadata() is called with the same metadata that was playing previously (ad or content)
# playheadPosition() resumes from the same position before the interruption

'''Example session:'''
* 5 minutes of content played, call interruption, content resumes until end of 15 min video

== Scrubbing ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| Scrub Backward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub Forward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub to end || final playhead position is passed ||
|-
| || end event called at completion of content playback ||
|-
| Scrub past midroll || Playhead for content stops ||
|}

== Midroll & Postroll Ads ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>loadMetadata()</code> || Called for each Ad ||
|-
| || Required Metadata is accurate ||
|-
| <code>playheadPosition</code> || Passed every second ||
|-
| <code>stop()</code> || called for each ad ||
|-
| <code>loadMetadata()</code>, <code>playheadPosition</code>, <code>stop()</code> || correct sequence for each ad ||
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of or opt back into Nielsen measurement. Include the following two items in the site’s Privacy Policy:
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy

The following paragraph is a template for an opt-out statement
Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

Digital Pre-Certification Checklist Browser SDK

2017-09-28T22:39:59Z

RyanCarlson: updated

== Pre-Certification Checklist - VOD with Ads ==
Before starting the certification process, please verify the following steps have been completed.
* Your Client Service representative should have already discussed a reporting hierarchy with you -- along with a Parent, Brand, and Sub-brand/Channel
* Your Technical Account Manager should have:
** provided you with an APID
** informed you of our Opt-Out requirement to be included in your Privacy Policy section of your site
** informed you to add the Static Queue Snippit on each page you wish to enable video measurement
** informed you that the apid, 'instanceName', and ‘nol_sdkDebug’ : ‘DEBUG’ should be present in the SDK initialization

== Initialization ==
The first step in the Certification process is to ensure that the Nielsen SDK is initializing on page load, and that the global metadata values are present.
{| class="wikitable"
|-
! Keys !! Value
|-
| apid || <code>PXXXXX-XXXXXX-XXXXX-XXXXX</code>
|-
| instanceName || <code>'nlsnInstance'</code>
|-
| nol_sdkDebug || <code>debug</code>
|}

'''Browser SDK Queue Snippit & Initialization Example'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
<script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||{nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[o]=t[o]||{g:c,ggPM:function(n,e,c,r,s){(t[o].q=t[o].q||[]).push([n,e,c,r,s])}},
t[o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

== Test Cases ==
The following lists the test cases along with the Expected results:
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| SDK Initialized || <code>apid</code> || Correct APID ||
|-
| || <code>instanceName</code> || SDK Instance Name ||
|-
| || <code>nol_sdkDebug</code> || <code>'DEBUG</code> ||
|}

=== play() ===
* The <code>play()</code> call is required only once per viewing session (until app is killed)
* Called just before playback commences for first piece of content
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| Play || <code>channelname</code> || Name of Channel ||
|}

=== loadMetadata() - Content ===
* Called at beginning of content, or when resuming content from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== loadMetadata() - ad ===
* Called at beginning of ad, or when resuming ad from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>assetid</code> || <code>"ad_2201343201"</code> || (any non-empty value) ||
|-
| || <code>type</code> || <code>"midroll"</code> || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> || Example
|}

=== setPlayheadPosition() - Preroll ad ===
* Track current position of playhead
* Starts at 0 at the beginning of ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Ad ||
|}

=== loadMetadata() - Content ===
* Test is to validate Content metadata is the same as original metadata passed during initial loadMetadata call.
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== setPlayheadPosition() - Content ===
* Track current position of playhead
* Starts at 0 at the beginning of content
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Content ||
|}

=== stop() ===
* Indicates one of the following:
* Playback of content or ad was interrupted
* Reached end of ad (no parameters or metadata)

=== end() ===
* Reached the end of content

== Interruptions ==
* All interruptions to playback of content or ads should trigger a call to stop(). Once the interruption is over, loadMetadata() with the same metadata should be called, followed by playheadPosition resuming from where it left off.

* Interruptions include:
** user-induced pause
** screen turned off
** refresh page
** internet connection lost (n.b. cached playback plays as normal until it expires)
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| user-induced pause || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| screen turned off || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| app sent to background || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| headphones removed || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| alarm/call interruption || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| internet connection lost || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| content paused || <code>playheadPosition</code> is not passed ||
|-
| resume content || <code>loadMetadata()</code> is called for content ||
|-
| || <code>loadMetadataM</code> is the same as original ||
|-
| || <code>playheadPosition</code> continues from resumed position ||
|}

'''Expected SDK behavior for all interruptions:'''
# interruption triggers stop() call
# when content resumes, loadMetadata() is called with the same metadata that was playing previously (ad or content)
# playheadPosition() resumes from the same position before the interruption

'''Example session:'''
* 5 minutes of content played, call interruption, content resumes until end of 15 min video

== Scrubbing ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| Scrub Backward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub Forward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub to end || final playhead position is passed ||
|-
| || end event called at completion of content playback ||
|-
| Scrub past midroll || Playhead for content stops ||
|}

== Midroll & Postroll Ads ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>loadMetadata()</code> || Called for each Ad ||
|-
| || Required Metadata is accurate ||
|-
| <code>playheadPosition</code> || Passed every second ||
|-
| <code>stop()</code> || called for each ad ||
|-
| <code>loadMetadata()</code>, <code>playheadPosition</code>, <code>stop()</code> || correct sequence for each ad ||
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of or opt back into Nielsen measurement. Include the following two items in the site’s Privacy Policy:
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy

The following paragraph is a template for an opt-out statement
Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

Digital Pre-Certification Checklist Browser SDK

2017-09-28T22:39:00Z

RyanCarlson: deleted things

== Pre-Certification Checklist - VOD with Ads ==
Before starting the certification process, please verify the following steps have been completed.
* Your Client Service representative should have already discussed a reporting hierarchy with you -- along with a Parent, Brand, and Sub-brand/Channel
* Your Technical Account Manager should have:
** provided you with an APID
** informed you of our Opt-Out requirement to be included in your Privacy Policy section of your site
** informed you to add the Static Queue Snippit on each page you wish to enable video measurement
** informed you that the apid, 'instanceName', and ‘nol_sdkDebug’ : ‘DEBUG’ should be present in the SDK initialization

== Initialization ==
The first step in the Certification process is to ensure that the Nielsen SDK is initializing on page load, and that the global metadata values are present.
{| class="wikitable"
|-
! Keys !! Value
|-
| apid || <code>PXXXXX-XXXXXX-XXXXX-XXXXX</code>
|-
| instanceName || <code>'nlsnInstance'</code>
|-
| nol_sdkDebug || <code>debug</code>
|}

'''Browser SDK Queue Snippit & Initialization Example'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
<script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||{nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[o]=t[o]||{g:c,ggPM:function(n,e,c,r,s){(t[o].q=t[o].q||[]).push([n,e,c,r,s])}},
t[o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

== Test Cases ==
The following lists the test cases along with the Expected results:
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| SDK Initialized || <code>apid</code> || Correct APID ||
|-
| || <code>instanceName</code> || SDK Instance Name ||
|-
| || <code>nol_sdkDebug</code> || <code>'DEBUG</code> ||
|}

=== play() ===
* The <code>play()</code> call is required only once per viewing session (until app is killed)
* Called just before playback commences for first piece of content
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| Play || <code>channelname</code> || Name of Channel ||
|}

=== loadMetadata() - Content ===
* Called at beginning of content, or when resuming content from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== loadMetadata() - ad ===
* Called at beginning of ad, or when resuming ad from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>assetid</code> || <code>"ad_2201343201"</code> || (any non-empty value) ||
|-
| || <code>type</code> || <code>"midroll"</code> || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> || Example
|}

=== setPlayheadPosition() - Preroll ad ===
* Track current position of playhead
* Starts at 0 at the beginning of ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Ad ||
|}

=== loadMetadata() - Content ===
* Test is to validate Content metadata is the same as original metadata passed during initial loadMetadata call.
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== setPlayheadPosition() - Content ===
* Track current position of playhead
* Starts at 0 at the beginning of content
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Content ||
|}

=== stop() ===
* Indicates one of the following:
* Playback of content or ad was interrupted
* Reached end of ad (no parameters or metadata)

=== end() ===
* Reached the end of content (no parameters or metadata)

== Interruptions ==
* All interruptions to playback of content or ads should trigger a call to stop(). Once the interruption is over, loadMetadata() with the same metadata should be called, followed by playheadPosition resuming from where it left off.

* Interruptions include:
** user-induced pause
** screen turned off
** refresh page
** internet connection lost (n.b. cached playback plays as normal until it expires)
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| user-induced pause || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| screen turned off || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| app sent to background || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| headphones removed || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| alarm/call interruption || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| internet connection lost || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| content paused || <code>playheadPosition</code> is not passed ||
|-
| resume content || <code>loadMetadata()</code> is called for content ||
|-
| || <code>loadMetadataM</code> is the same as original ||
|-
| || <code>playheadPosition</code> continues from resumed position ||
|}

'''Expected SDK behavior for all interruptions:'''
# interruption triggers stop() call
# when content resumes, loadMetadata() is called with the same metadata that was playing previously (ad or content)
# playheadPosition() resumes from the same position before the interruption

'''Example session:'''
* 5 minutes of content played, call interruption, content resumes until end of 15 min video

== Scrubbing ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| Scrub Backward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub Forward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub to end || final playhead position is passed ||
|-
| || end event called at completion of content playback ||
|-
| Scrub past midroll || Playhead for content stops ||
|}

== Midroll & Postroll Ads ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>loadMetadata()</code> || Called for each Ad ||
|-
| || Required Metadata is accurate ||
|-
| <code>playheadPosition</code> || Passed every second ||
|-
| <code>stop()</code> || called for each ad ||
|-
| <code>loadMetadata()</code>, <code>playheadPosition</code>, <code>stop()</code> || correct sequence for each ad ||
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of or opt back into Nielsen measurement. Include the following two items in the site’s Privacy Policy:
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy

The following paragraph is a template for an opt-out statement
Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

Digital Pre-Certification Checklist Browser SDK

2017-09-28T22:38:30Z

RyanCarlson: updated things

== Pre-Certification Checklist - VOD with Ads ==
Before starting the certification process, please verify the following steps have been completed.
* Your Client Service representative should have already discussed a reporting hierarchy with you -- along with a Parent, Brand, and Sub-brand/Channel
* Your Technical Account Manager should have:
** provided you with an APID
** informed you of our Opt-Out requirement to be included in your Privacy Policy section of your site
** informed you to add the Static Queue Snippit on each page you wish to enable video measurement
** informed you that the apid, 'instanceName', and ‘nol_sdkDebug’ : ‘DEBUG’ should be present in the SDK initialization

== Initialization ==
The first step in the Certification process is to ensure that the Nielsen SDK is initializing on page load, and that the global metadata values are present.
{| class="wikitable"
|-
! Keys !! Value
|-
| apid || <code>PXXXXX-XXXXXX-XXXXX-XXXXX</code>
|-
| instanceName || <code>'nlsnInstance'</code>
|-
| nol_sdkDebug || <code>debug</code>
|}

'''Browser SDK Queue Snippit & Initialization Example'''
<syntaxhighlight lang="objective-c">NSDictionary* appInformation = @
<script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||{nlsQ:function(e,o,c,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="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[o]=t[o]||{g:c,ggPM:function(n,e,c,r,s){(t[o].q=t[o].q||[]).push([n,e,c,r,s])}},
t[o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","nlsnInstance", {nol_sdkDebug: "debug"});
</script>
</syntaxhighlight>

== Test Cases ==
The following lists the test cases along with the Expected results:
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| SDK Initialized || <code>apid</code> || Correct APID ||
|-
| || <code>instanceName</code> || SDK Instance Name ||
|-
| || <code>nol_sdkDebug</code> || <code>'DEBUG</code> ||
|}

=== play() ===
* The <code>play()</code> call is required only once per viewing session (until app is killed)
* Called just before playback commences for first piece of content
{| class="wikitable"
|-
! Test Case !! Param !! Expected Result !! Pass/Fail
|-
| Play || <code>channelname</code> || Name of Channel ||
|}

=== loadMetadata() - Content ===
* Called at beginning of content, or when resuming content from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== loadMetadata() - ad ===
* Called at beginning of ad, or when resuming ad from interruption
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>assetid</code> || <code>"ad_2201343201"</code> || (any non-empty value) ||
|-
| || <code>type</code> || <code>"midroll"</code> || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> || Example
|}

=== setPlayheadPosition() - Preroll ad ===
* Track current position of playhead
* Starts at 0 at the beginning of ad
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Ad ||
|}

=== loadMetadata() - Content ===
* Test is to validate Content metadata is the same as original metadata passed during initial loadMetadata call.
{| class="wikitable"
|-
! Test !! Param !! Example Value !! Accepted Values !! Pass/Fail
|-
| loadMetadata || <code>type</code> || <code>"content"</code> || <code>"content"</code> ||
|-
| || <code>assetid</code> || <code>"unique_id_500291"</code> || (unique per asset) ||
|-
| || <code>length</code> || <code>"600"</code> || length in seconds (int or float) ||
|-
| || <code>title</code> || <code>"Episode Title"</code> || (any non-empty value) ||
|-
| || <code>program</code> || <code>"Show Name"</code> || (any non-empty value) ||
|-
| || <code>segB</code> || <code>"Primetime"</code> || (any value), used for optional breakdown ||
|-
| || <code>segC</code> || <code>"Comedy"</code> || (any value), used for optional breakdown ||
|-
| || <code>crossId1</code> || <code>"EP018S9S290015"</code> || Gracenote ID ||
|-
| || <code>crossId2</code> || <code>"ABC"</code> || Network Name ||
|-
| || <code>isfullepisode</code> || <code>"y"</code> || (<code>"y"</code> or <code>"n"</code>) (<code>"Y"</code> or <code>"N"</code>) ||
|-
| || <code>airdate</code> || <code>"20160206 23:00:00</code> || <code>"YYYYMMDD[space]HH:MM:SS"</code> -- note: HH=24 hour time ||
|-
| || <code>adloadtype</code> || <code>"1"</code> || <code>"1"</code> for linear ads, <code>"2"</code> for DAI ||
|-
| || <code>hasAds</code> || <code>"1"</code> || <code>"0"</code> for no ads, <code>"1"</code> for has ads ||
|}

=== setPlayheadPosition() - Content ===
* Track current position of playhead
* Starts at 0 at the beginning of content
* Updated at least once per second
* Separate playhead position for ads and content, should accurately reflect current position in either ads or content
* Final playhead position for content must equal the length specified in loadMetadata(), followed by end() call
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>setPlayehadPosition</code> || Called every second ||
|-
| <code>stop()</code> || Called at the end of Content ||
|}

=== stop() ===
* Indicates one of the following:
* Playback of content or ad was interrupted
* Reached end of ad (no parameters or metadata)

=== end() ===
* Reached the end of content (no parameters or metadata)

== Interruptions ==
* All interruptions to playback of content or ads should trigger a call to stop(). Once the interruption is over, loadMetadata() with the same metadata should be called, followed by playheadPosition resuming from where it left off.

* Interruptions include:
** user-induced pause
** screen turned off
** refresh page
** internet connection lost (n.b. cached playback plays as normal until it expires)
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| user-induced pause || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| screen turned off || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| app sent to background || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| headphones removed || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| alarm/call interruption || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| internet connection lost || <code>stop()</code>, <code>loadMetadata()</code> & <code>playheadPosition</code> ||
|-
| content paused || <code>playheadPosition</code> is not passed ||
|-
| resume content || <code>loadMetadata()</code> is called for content ||
|-
| || <code>loadMetadataM</code> is the same as original ||
|-
| || <code>playheadPosition</code> continues from resumed position ||
|}

'''Expected SDK behavior for all interruptions:'''
# interruption triggers stop() call
# when content resumes, loadMetadata() is called with the same metadata that was playing previously (ad or content)
# playheadPosition() resumes from the same position before the interruption

'''Example session:'''
* 5 minutes of content played, call interruption, content resumes until end of 15 min video

== Scrubbing ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| Scrub Backward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub Forward || new playhead position is accurate ||
|-
| || new playhead continues from new position ||
|-
| Scrub to end || final playhead position is passed ||
|-
| || end event called at completion of content playback ||
|-
| Scrub past midroll || Playhead for content stops ||
|}

== Midroll & Postroll Ads ==
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>loadMetadata()</code> || Called for each Ad ||
|-
| || Required Metadata is accurate ||
|-
| <code>playheadPosition</code> || Passed every second ||
|-
| <code>stop()</code> || called for each ad ||
|-
| <code>loadMetadata()</code>, <code>playheadPosition</code>, <code>stop()</code> || correct sequence for each ad ||
|}

== Opt-Out ==
The site must provide a means for the user to opt-out of or opt back into Nielsen measurement. Include the following two items in the site’s Privacy Policy:
* A notice that the player includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings)
* A link to the Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy

The following paragraph is a template for an opt-out statement
Our properties may feature Nielsen proprietary measurement software, which will allow you to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, refer to Nielsen Digital Measurement Privacy Policy at http://www.nielsen.com/digitalprivacy.

== Opt-Out ==
Users must have access to "About Nielsen Measurement" page. User can click this page from app settings screen.
* URL to this web page should be called from SDK by invoking optOutURL and opened in 'WebView' / External browser.
* If the App SDK returns NULL as Opt-Out URL, handle the exception gracefully and retry later.
* To retrieve the current Opt-Out status of a device, use the optOutStatus method.
{| class="wikitable"
|-
! Test Case !! Test Condition !! Pass/Fail
|-
| <code>optOutView</code> || User can Opt-Out ||
|}

Sandbox

2017-09-28T19:48:23Z

RyanCarlson: pulling over iOS SDK template

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Prerequisites ==
To start using the App SDK, the following details are required:
* '''App ID (appid):''' Unique ID assigned to the player/site and configured by product.
* '''sfcode:''' Unique identifier for the environment that the SDK should point to.
* '''Nielsen SDK''' and '''Sample Player''': A part of the downloaded package
If you do not have any of these pre-requisites or if you have any questions, 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.

== Import Library ==
Refer to [[iOS SDK API Reference#Importing Frameworks|iOS SDK API Reference - Importing Frameworks]] for information on importing libraries.
* The latest version of App SDK allows instantiating multiple instances of App SDK object and can be used simultaneously without any issues.

== Initialize SDK ==
Initialize App SDK as soon as the application is launched. Refer to [[iOS SDK API Reference#Initialization|iOS SDK API Reference - Initialization]] for details on initializing an AppSDK object and the parameters required.

== Configure API calls ==
=== play ===
Use [[play]] to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player.

=== loadMetadata ===
Use [[loadMetadata]] to pass 'content' and 'ad' [[Digital Measurement Metadata]]. The CMS data must be passed as a JSON object.
<syntaxhighlight lang="objective-c"> – (void) loadMetadata :(id)metadata;</syntaxhighlight>
Refer to [[loadMetadata]] for the list of parameters to be passed in the JSON object.
<blockquote>'''Note:''' The [[loadMetadata]] call after the first [[play]] call must have ‘content’ details ("type": "content"). This call should occur before any preroll ad starts playing.</blockquote>

=== playheadPosition (Cotent) ===
Use [[playheadPosition]] to pass the position of the playhead while the content is being played.
<syntaxhighlight lang="objective-c"> – (void) playheadPosition: (long long) playheadPos</syntaxhighlight>
{| class="wikitable"
|-
! # !! Key !! Description !! Values !! Required? (Y/N) !! Example
|-
| 1 || Live** || UTC of the live content || Client-defined || Yes || Seconds since 1970
|-
| 2 || Video On Demand (VOD)** || Position taken from beginning of the content in seconds. || Client-defined || Yes || Current player position from beginning of the content.
|}
<nowiki>**</nowiki>''Only one of these parameters is mandatory''
<blockquote>'''Note:''' If playhead is not available from audio / video measurement, allow the app to start a timer (1-5 seconds) and send playhead position to SDK based on the timer event. Once the actual playhead is available, let the app send the proper playhead position. This allows the SDK to calculate and provide a closer value for duration.</blockquote>

'''Buffering state'''
* Do not supply playhead position while the content is being buffered.
* If the content is in buffering state continuously for more than 30 seconds, call [[stop]] API.

'''Live Content'''
<syntaxhighlight lang="objective-c"> long long pos = [[NSDate date] timeIntervalSince1970];
[nAppApiObject playheadPosition:pos];</syntaxhighlight>

'''On-demand Content'''
<syntaxhighlight lang="objective-c"> CMTime curTime=[player currentTime];
long pos=CMTimeGetSeconds(curTime);
[nAppApiObject playheadPosition:pos];</syntaxhighlight>

=== playheadPosition (Ad) ===
Use [[playheadPosition]] to pass the position of the playhead while the advertisement is being played.
<syntaxhighlight lang="objective-c"> – (void) playheadPosition: (long long) playheadPos</syntaxhighlight>

{| class="wikitable"
|-
! Key !! Description !! Values !! Required? (Y/N) !! Example
|-
| Ad || Position taken from beginning of the ad in seconds || Client-defined || Yes || Seconds since tart of the ad
|}

'''Ad Content'''
<syntaxhighlight lang="objective-c"> CMTime curTime=[adplayer currentTime];
long pos=CMTimeGetSeconds(curTime);
[nAppApiObject playheadPosition:pos];</syntaxhighlight>
<blockquote>'''Note:''' The playhead positions for ad and content should be maintained separately.</blockquote>

=== stop ===
Call [[stop]] only at the end of ad or in case of interruptions during playback like flight mode, Wi-Fi toggle, etc. Call [[loadMetadata]] and [[playheadPosition]] when the stream resumes. Call [[play]] when starting the new stream.

=== end ===
Call [[end]] only at the end of playback.

=== API Call sequence ===
==== Use Case 1: Content has no Advertisements ====
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.

Call [[play]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
"segB": "CustomSegmentValueB",
"segC": "CustomSegmentValueC",
"crossId1": "Reference11",
"crossId2": "Reference22",
"isfullepisode": "y",
"airdate": "20161013 20:00:00",
"adloadtype": "2"
}</syntaxhighlight>
Call [[playheadPosition]] every one second until a pause / stop.

{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>[nielsenMeter play: channelName];</code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>[nielsenMeter loadMetadata: contentMetadataObject];</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>[nielsenMeter playheadPosition: position];</code> || // playheadPosition is position of the playhead while the content is being played
|-
| End of Stream || <code>[nielsenMeter end];</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Advertisements ====
Call [[play]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetId_ad": "ad=123"
}</syntaxhighlight>
<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[playheadPosition]] every one second until a pause / stop / another ''loadMetadata'' is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata]].

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>[nielsenMeter play: channelName];</code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>[nielsenMeter loadMetadata: contentMetadataObject];</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>[nielsenMeter loadMetadata: prerollMetadataObject];</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>[nielsenMeter playheadPosition: position];</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>[nielsenMeter stop];</code> || // Call stop after preroll occurs
|-
| rowspan="3" | Content || <code>[nielsenMeter loadMetadata: contentMetadataObject];</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>[nielsenMeter playheadPosition: position];</code> || // position is position of the playhead while the content is being played
|-
| <code>[nielsenMeter stop];</code> || // Call stop after the content is paused (ad starts)
|-
| rowspan="3" | Midroll || <code>[nielsenMeter loadMetadata: midrollMetadataObject];</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>[nielsenMeter playheadPosition: position];</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>[nielsenMeter stop];</code> || // Call stop after midroll occurs
|-
| rowspan="3" | Content (End of stream) || <code>[nielsenMeter loadMetadata: contentMetadataObject];</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>[nielsenMeter playheadPosition: position];</code> || // position is position of the playhead while the content is being played
|-
| <code>[nielsenMeter end];</code> || // Called at the end of content
|-
| rowspan="3" | Postroll || <code>[nielsenMeter loadMetadata: postrollMetadataObject];</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>[nielsenMeter playheadPosition: position];</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>[nielsenMeter stop];</code> || // Call stop after postroll occurs
|}

<blockquote>'''Note:''' Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Interruptions during playback ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call [[stop]] immediately (except when content is buffering) and withhold sending playhead position.
* Start sending pings – [[loadMetadata]] and [[playheadPosition]] for the new viewing session, once the playback resumes.
Please see the [[Digital Measurement FAQ]] for more details

== Nielsen Measurement Opt-Out Implementation ==
As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. Our digital measurement products are not used to identify the consumer in any way, but they help us and our clients measure and analyze how consumers engage with media across online, mobile and emerging technologies, and offer insights into consumer behavior.
* When the app user wants to opt in or opt out of Nielsen measurement, a new dynamic page (with content string obtained from [[optOutURL]]) should be displayed.
* Use [[optOutStatus]] to retrieve the device’s Opt-Out status.
* This Opt-out page should be displayed in a webview (within the app) and not in any external browser.
* Capture the user’s selection in this page and pass it to the SDK through [[userOptOut]] for Nielsen to save the user’s preference.


== Pre-Certification Checklists ==
After the application is ready to be sent for Nielsen Certification, please go through the Pre-Certification Checklist and ensure the app behaves as expected, before submitting to Nielsen.

== Testing an Implementation - App ==
See [[Digital Measurement Testing]].

DCR Video & Static Roku Cloud API

2017-09-22T01:23:18Z

RyanCarlson: Opt OUt

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR) measurement on your Roku Apps.
*For other OTT Apps, please see [[DCR Video & Static Cloud API]]
*For Mobile Apps, please see [[DCR Video & Static Mobile Cloud API]]

==Prerequisites==
To get started, you will need a Nielsen App ID. The App ID is a unique ID assigned to your app. This will be provided to you upon starting the integration.

<syntaxhighlight lang="javascript">XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

==Integration==
We will cover the steps for constructing the Cloud API Calls.

===Request Overview===

====URL Structure====

The Cloud API Calls are HTTP GET Requests with the URL structure:

<syntaxhighlight lang="javascript">[endpoint]/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

The URL includes the following components:

*<code>[endpoint]</code>: location of data collection environment
*<code>[appid]</code>: provided App ID
*<code>[sessionID]</code>: unique value for each user session
*<code>[payload]</code>: metadata and events

====Endpoint====

There are endpoints for testing and production:

*Testing: <code>http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

During testing, all calls should be pointed to the testing endpoint. We will review the update to the production endpoint during the Go Live section of this guide.

====URL Example====
As you move through the integration steps, you can reference the below URL structure with the expanded payload:

<syntaxhighlight lang="javascript">
http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"static": [static_metadata],
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [UTC]
}
</syntaxhighlight>

===Create Session ID===
A unique Session ID must be created upon app launch and provided in the URL. This will allow measurement to occur for the entire duration that a user is within the app.

The session ID must be passed with every request and must remain consistent throughout each individual session.

===Example Roku Sample Code Provided Below:===
<syntaxhighlight lang="javascript">sessionTime = createObject("roDateTime")</syntaxhighlight>

<syntaxhighlight lang="javascript">sessionID = (sessionTime.asSeconds()).tostr()+(sessionTime.getMilliseconds()).tostr()</syntaxhighlight>

Upon exiting the app, the session will need to be terminated using the delete event. Sessions will automatically expire after 30 minutes of cloud inactivity.

===Define URL Structure===
Define the URL structure using your provided <code>[appid]</code> and a unique <code>[sessionID]</code>.

<syntaxhighlight lang="javascript">http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

===Configure Payload===

All Cloud API requests must contain the following payload data:

*''devInfo'': device and app info
*''metadata'': asset metadata
*''event metadata'': type of event

The payload can be passed through key-values using the Nielsen reserved keys. The specific keys and descriptions are highlighted in the tables included in this section.

'''Payload Example'''

The example below should be referenced when following the steps for configuring the request payload.

<syntaxhighlight lang="javascript">
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"apn": "AppName",
"encdata": "encdata=v1.key.RokuAES256CBC00.iv3x2EV0BpHH9AbZK%2FnBWWRhZbj7pD%3D...",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2", //ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}
</syntaxhighlight>

=====Configure Payload: devInfo=====
An object <code>"devInfo"</code> will need to be created to capture App and Device information.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| encdata || Nielsen - Roku ID for Advertisers || N-RIDA Payload || Yes
|-
| apn || app name || custom || Yes
|-
| apv || app build version || custom || Yes
|-
| uoo || device opt-out status || <code>"true"</code> or <code>"false"</code> || Yes
|-
| Example || Example || Example || Yes
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"encdata": "encdata=v1.key.RokuAES256CB...",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},
</syntaxhighlight>

===== Encdata (N-RIDA): Nielsen - Roku Identifier for Advertisers =====
The N-RIDA (Nielsen-Roku ID for Advertisers) is a proprietary advertising identifier that ties back to an individual Roku device, and allows Nielsen to attribute audience metrics. The N-RIDA is provided by Roku, and is pulled through the Roku <code>AdIface.GetNielsenContentData()</code> API.

The N-RIDA payload should be requested once per user session and populated in the <code>"encdata"</code> Nielsen key within the <code>"devInfo"</code> payload. Each Cloud API request throughout a user session should include the same N-RIDA payload. The N-RIDA should be established when a user launches the app, and it should be maintained until the user exits. A new N-RIDA payload should be requested when the user re-enters the app.

'''Prerequisites For Using The AdIface.GetNielsenContentData() Roku API'''

* Roku Ad Framework (RAF) must be implemented:
** <code>bs_libs_required=roku_ads_lib</code> must be included in the Roku manifest file.
** <code>Library "Roku_Ads.brs"</code> should be the first entry in your Roku main.brs file.
** <code>adIface = Roku_Ads()</code> allows you to access the Roku Ad Framework interface and must be called before utilizing RAF API's such as <code>AdIface.GetNielsenContentData()</code>
* For additional details for integrating the Roku Ad Framework (RAF) please refer to the link provided below:
** https://sdkdocs.roku.com/display/sdkdoc/Integrating+the+Roku+Advertising+Framework

===== Request N-RIDA for the devInfo Payload <code>encdata</code> parameter using AdIface.GetNielsenContentData() =====

'''Example Code For Configuring Encdata'''
<syntaxhighlight lang="java">// create a variable as a placeholder for the N-RIDA payload
n_Rida=AdIface.GetNielsenContentData()

// populate the encdata key in devInfo with the AdIface.GetNielsenContentData() retrun
"devInfo": {
"apn": "AppName",
"apv": "1.0",
"encdata": "n_Rida", //insert the AdIface.GetNielsenContentData() return within encdata
"uoo": "false"
}</syntaxhighlight>

<blockquote>'''Note''': When pulled and populated into the encdata key, the <code>AdIface.GetNielsenContentData()</code> return will be formatted similarly to the example below, and will include "encdata=" within the return along with the N-RIDA key.</blockquote>
<syntaxhighlight lang="json">"encdata":"encdata=v1.key.RokuAES256CBC00.iv.HSh88AM%2BG%2Fx57TZ%2BW5j5Fw%3D%3D..."</syntaxhighlight>

==== 3.2 Configure Payload: metadata ====
Asset metadata can be passed through <code>"metadata"</code>. There are two asset types: <code>"content"</code> for video and <code>"ad"</code> for ads. The metadata received for each asset is used for classification and reporting.

You will need to set up <code>"metadata"</code> objects for <code>"content"</code> and <code>"ad"</code> with the required Nielsen keys as shown in the sample code below.

===== Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>"content"</code> || Yes
|-
| assetid || unique ID assigned to asset || custom || Yes
|-
| program ||name of program (25 character limit) || custom || Yes
|-
| title ||name of program (25 character limit) || custom || Yes
|-
| length || length of content in seconds || <code>seconds</code> (86400 for live stream) || Yes
|-
| segB || custom segment B || custom ||
|-
| segC || custom segment C || custom ||
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH24:MI:SS || Yes
|-
| isfullepisode || full episode flag || <code>"y"</code>- full episode, <code>"n"</code>- non full episode || Yes
|-
| crossId1 || standard episode ID || custom || Yes
|-
| crossId2 || content originator (only required for distributors) || Nielsen ||
|-
| adloadtype || type of ad load:
<code>"1"</code> Linear – matches TV ad load

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|-
| hasAds || ads indicator
<code>"1"</code>: ads included

<code>"0"</code>: ads not included
|| <code>"1"</code> or <code>"0"</code> || Yes
|-
| progen || program genre abbreviation - see [[DCR OTT Genre List]] for accepted values || <code>"CV"</code> for Comedy Variety || Yes
|}

'''Example Content Object'''
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "VIDEO-ID123",
"isfullepisode": "y",
"program": "Program Name",
"title": "Episode Title S3 - EP1",
"length": "1800",
"segB": "Custom Segment B",
"segC": "Custom Segment C",
"crossId1": "Standard Episode ID",
"crossId2": "Content Originator ID",
"airdate": "20161013 20:00:00",
"adloadtype": "2",
"hasAds": "1",
"progen": "CV"
}</syntaxhighlight>

===== Ad Metadata =====
The ad metadata should be passed for each individual ad.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || <code>"preroll"</code>, <code>"midroll"</code>, or <code>"postroll"</code> || Yes
|-
| assetid || unique ID assigned to ad || custom || Yes
|}

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "AD-ID123"
}
</syntaxhighlight>

=== Configure Payload: Events ===

The last part of the payload is for enabling events so content is measured correctly when viewed. The events and required parameters are included below.

==== Event Types ====

The available events are:
{| class="wikitable"
|-
! Event !! Description
|-
| <code>"playhead"</code> || Playhead position in seconds. Must be passed as a whole number every 10 seconds. The final playhead position should also be sent before an asset has changed to properly capture full duration. Playhead is used to handle pause and scrubbing. When content is paused, stop passing playhead position.
|-
| <code>"complete"</code> || The complete event must be sent when the content has completed full playback. Before calling the complete event, a final playhead update with the final position is required to be sent to receive full duration credit.
|-
| <code>"delete"</code> || The delete event must be sent when the session is completed, or terminated. After 30 minutes of inactivity, the session will expire. All creditable duration will be summarized for all asset types when delete occurs (content and ads).
|}

===== Event Parameters =====

The following parameters need to be passed when calling events:

{| class="wikitable"
|-
! Parameter !! Description !! Value !! Required
|-
| <code>"event"</code> || event type || <code>"playhead"</code>, <code>"complete"</code>, or <code>"delete"</code> || Yes
|-
| <code>"position"</code> || creditable position || playhead position in seconds or UTC timestamp in seconds for livestream || Yes
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || Yes
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || Yes
|}

===== Example Event =====
You can call events by passing values in the required parameters:

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"metadata": {
"static": [static metadata],
"content": [content metadata],
"ad": [ad metadata]
},
// Event Parameters
"event": [event], // event name
"position": [playheadPosition], //position in seconds
"type": [asset type], // values are "content" or "ad"
"utc": "1472760000000" //unix timestamp in milliseconds
}
</syntaxhighlight>

'''Note:''' The full payload including "devInfo" and "metadata" must be populated in each event request.

===Example Image Request===

In order to execute Cloud API calls, image requests will need to be established for each event.

===Playhead Image Request Example Code===

<syntaxhighlight lang="javascript">
playheadRequest = CreateObject("roUrlTransfer")
sendUrl = sessionUrl+playheadRequest.Escape(playheadPayload)
playheadRequest.SetUrl(sendUrl)
xport=CreateObject("RoMessagePort")
playheadRequest.setport(xport)
aa3 = {}
aa3["Connection"] = "keep-alive"
aa3["Content-type"] = "image/gif"
playheadRequest.SetHeaders(aa3)
playheadRequest.setRequest("GET")
</syntaxhighlight>

===== Sample Event Lifecycle =====
The sample event lifecycle can be used as a reference for identifying the order for calling events and values to pass.

<syntaxhighlight lang="javascript">
// Start of Session: session ID created when App is opened

// Preroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472760000000"}

// Midroll
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content resumes at 15 minutes
Content Playhead {"event": "playhead", "position": "900", "type": "content", "utc": "1472760000000"}

// Content completes at 30 minutes
Complete {"event": "complete", "position": "1800", "type": "content", "utc": "1472760000000"}

// Postroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472760000000"}
</syntaxhighlight>

'''Sample Event Lifecycle - Detailed Storyline'''
This detailed event sequence provides additional insight for the correct events to call when handling certain playback scenarios.
<syntaxhighlight lang='javascript'>// SESSION STARTS
// Start of Session: session ID created when App is opened

// PREROLL
// Preroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Preroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "15", "type": "ad", "utc": "1472761500000"}

// CONTENT
// Content Start - Start new content streams with a position of "0" incrementing the position every 10 seconds.
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472761500000"}

// Content Stop Before Ad Break - Send a playhead update including the current content positon before an Ad break.
Content Playhead {"event": "playhead", "position": "299", "type": "content", "utc": "1472787400000"}

// MIDROLL
// Midroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472787500000"}

// Midroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "60", "type": "ad", "utc": "1472793500000"}

// CONTENT
// Content resumes at 5 minutes - Send playhead update with the current resumed position, and begin incrimenting the positon every 10 seconds.
Content Playhead {"event": "playhead", "position": "300", "type": "content", "utc": "1472799500000"}

// Content completes at 10:12 - Make sure to send in the playhead event with the final content position before sending the complete event.
Final Content Playhead {"event": "playhead", "position": "612", "type": "content", "utc": "1472830700000"}

Complete {"event": "complete", "position": "612", "type": "content", "utc": "1472830800000"}

// POSTROLL
// Postroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472830900000"}

// Postroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "45", "type": "ad", "utc": "1472835300000"}

// SESSION ENDS

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472835400000"} </syntaxhighlight>

=====Handling Playhead=====
Calling <code>"playhead"</code> is critical for accurate duration crediting. You can reference the below guidance to determine the correct playhead position to pass depending on the playback scenario.

'''Playhead: General'''
* Playhead position must start at 0 for each new asset, and be passed at least every 10 seconds.
* Final postion must be sent at the end of content or an ad

'''Playhead: Ads'''
* The final position must be sent when switching from content to ad, or ad to content.
* Each ad playhead position should be 0 at ad start.
* For Ad Pods, playhead must be called, and reset to 0 for each individual ad.
* The last content position before an Ad should be sent before switching to Ads.
* When content has resumed following an ad break, the playhead position update must continue where the previous content segment left off.

'''Playhead: User Actions'''
* Upon user scrubbing, the current position must be sent before a user scrubs, and the new position should be sent where the user lands, and begin sending in the 10 second updates thereafter.
* On pause, send the current position and then discontinue sending playhead event updates.
* If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

===== Interruption Scenarios =====

As part of configuring events, you will need to handle all possible interruption scenarios such as:

*Wi-Fi OFF / ON
*App going Background / Foreground (Video players only, not for Audio players)
*App Crash or Exit

When playback is interrupted, the app needs to send delete immediately.

Once playback resumes, a new session will need to be created with a unique session ID. All of the required metadata and events will need to be sent.

'''Note:''' The session will automatically timeout after 30 minutes of inactivity.

=== Example Request ===

Now that we walked through the Cloud API integration steps, your requests should have the following components: Session ID, App ID, and Payload. You can reference the example below when your reviewing your integration.

<syntaxhighlight lang="javascript">
// 1. Create Session ID
sessionTime = createObject("roDateTime")
sessionID = (sessionTime.asSeconds()).tostr()+(sessionTime.getMilliseconds()).tostr()

// 2. Define URL Structure with App ID and Session ID
sessionURL = http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"encdata": "encdata=v1.key.RokuAES256CB...",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2", // ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}

// Append payload to URL
sendUrl = sessionUrl.Escape(payload)
</syntaxhighlight>

==== Enable Debug Logging ====

Now that you have set up the Cloud API requests, you can enable debug logging to validate your integration. Enabling debug logging is required for Nielsen certification.

==== GET Request ====

Display GET Request to console using a name to identify each event (e.g. playhead).

<syntaxhighlight lang="javascript">
print "Playhead Event " + sendUrl
</syntaxhighlight>

==== Payload ====

Output payload to identify required metadata and events.

<syntaxhighlight lang="javascript">
print "Event Payload "+ playheadPayload + modSeq%.tostr()
</syntaxhighlight>

==== HTTP Response Code ====

Confirm request was completed by viewing HTTP response code.

<syntaxhighlight lang="javascript">
httpCode = GetResponseCode()
print "Response Code " +httpCode.tostr()
</syntaxhighlight>

You can reference the HTTP Response Code table when reviewing your requests:

{| class="wikitable"
|-
! Status Code !! Status Text !! Description
|-
| <code>200</code> || OK || request received
|-
| <code>403</code> || Forbidden || invalid App ID
|-
| <code>404</code> || Not Found || JSON issue
|}

== Opt-Out ==
Your app must provide a means for the user to Opt-Out, or Opt-In to Nielsen Measurement. The Opt-Out requirement can be fulfilled by creating an Opt-Out/Opt-In button, toggle switch, or slider within the app "Settings", or "About" section to allow the user selection. If you have the ability to render text within the Opt-Out screen, it is recommended to add the Privacy Information included below.

[[File:Nielsen Opt-Out.png|link=]]

You will need to store the User Opt-Out (uoo) status, so that it can be retrieved and populated in the <code>"devInfo"</code> metadata which will be sent in every Cloud API event (playhead, complete, & delete).

*In addition, you will need to ensure that the encdata field is populated with a blank value if a user has elected to Opt-Out.

*If the device offers "Limit Ad Tracking" or "Opt-Out" device settings, you must set uoo=true, and also ensure that the encdata is set to a blank value if the user elects to enable this setting.

{| class="wikitable"
|-
! uoo Key !! Description !! Values
|-
| uoo || Device is Opted-In to Nielsen Measurement (Recommended Default Setting) || <code>"false"</code>
|-
| uoo || Device is Opted-Out of Nielsen Measurement || <code>"true"</code>
|}

===== devInfo Opt-In JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Roku Sample App",
"apv": "1",
"encdata": "encdata=v1.key.RokuAES256CB...",
"uoo": "false"
},
</syntaxhighlight>

===== devInfo Opt-Out JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Roku Sample App",
"apv": "1",
"encdata": "", //Encdata must be blank when a user elects to Opt-Out.
"uoo": "true"
},
</syntaxhighlight>

===== Privacy Information Template To Include In Opt-Out Screen =====

<blockquote>
'''''ABOUT NIELSEN MEASUREMENT'''''

Television and the way we watch it have come a long way since Nielsen began measuring TV audiences in 1950. Today, the ability to watch our favorite shows at any time and on multiple devices amplifies the need for exceptionally adept and flexible audience measurement capabilities.

Consumers are changing with the times, and the same goes for us. As technology continues to evolve and media companies try new ways to attract viewers, understanding what consumers are watching — and what they're watching on — is more important than ever. Today, viewing video is a personal and mobile experience — anytime and anywhere. Our capabilities provide relevant metrics that are necessary to inform successful marketing and programming and drive continued growth. As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. While our digital measurement products are not used to identify you in any way, they help us and our clients measure and analyze how consumers engage with media across online, mobile and emerging technologies, and offer insights into consumer behavior.

'''''YOUR CHOICES'''''

Nielsen believes that you should have a choice about whether to contribute to our research and insights. To opt out, or opt into Nielsen measurement please make the appropriate selection within the app. If you have this app on more than one device, you will need to opt out of this app on each device. To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

'''''Disclosure Template'''''

Additionally, you must update the App description information from the App Distribution Store with the Nielsen Measurement disclosure below:

This app features Nielsen's proprietary measurement software which will allow you to contribute to market research, like Nielsen's TV Ratings. Please see http://www.nielsen.com/digitalprivacy for more information.
</blockquote>

== Testing ==
Before providing an app build to Nielsen for testing, it is important to run validation checks once you have enabled debug logging.

=== Payload Validation ===

Ensure that all of the required payload data is populating while testing several videos. The following areas are critical to measurement:
*devInfo
*Asset metadata for both content, and ads
*Events
*Opt-Out status

=== Player Events ===
Review event calls:

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset.
*Final playhead position is sent on content, or ad before switching between assets.
*Content metadata remains constant throughout an episode, or clip play.
*Ad metadata is populated appropriately for each individual ad.
*Playhead position update resumes for content after an ad break, and resets to 0 for each individual ad.
*For scrubbing, last current position should be sent while scrubbing occurs, and the new position should also be sent where the user scrubs to.
*Exiting a stream early should execute the last current position in a playhead update to receive accurate duration.
*Upon pause, the current position should be sent, and playhead updates should stop incrementing until resume play occurs.

==== complete ====
*Check that the complete event executes upon content complete after the final playhead update is sent.
*Do not execute the complete event for ads

==== delete ====
*Check to see that the delete event occurs upon app exit

==== GET Request Format ====
*Ensure that the event payloads are formatted in JSON
*Check to see that each of the Cloud API GET requests are properly encoded.

==== HTTP Response ====
*Make sure that each of the Cloud API Get requests are received by the Nielsen Cloud API properly through use of the HTTP Response Code outputs enabled in console.

==== Opt-Out ====
*Test the "uoo" key gets populated accurately for both Opt-In and Opt-Out selections by validating the Cloud API events called after the user Opt-Out/Opt-In selection.
*Test that the encdata field is populated with a blank value if a user has elected to Opt-Out. For Example: "encdata": "",
*If the device supports "Limit Ad Tracking" or has device "Opt-Out" settings, test that uoo=true, and that encdata is set to a blank value if enabled in the device settings.

== Go Live ==
After your integration has been certified, you will need to: Change Endpoint and Disable Logging.

'''Change Endpoint:''' You will need to update to the production endpoint:

*Testing: <code>http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

Your production URL structure should now be:
<code>https://cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</code>

'''Disable Logging:''' You can now disable debug logging.

DCR Video & Static Mobile Cloud API

2017-09-22T01:22:13Z

RyanCarlson: enabled

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|DCR & DTVR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR) measurement on your mobile apps.
*For Roku Apps, please see [[DCR Video & Static Roku Cloud API]]
*For Mobile Apps, please see [[DCR Video & Static Mobile Cloud API]]

==Prerequisites==
To get started, you will need a Nielsen App ID. The App ID is a unique ID assigned to your app. This will be provided to you upon starting the integration.

<syntaxhighlight lang="javascript">XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

==Integration==
We will cover the steps for constructing the Cloud API Calls.

===Request Overview===

====URL Structure====

The Cloud API Calls are HTTP GET Requests with the URL structure:

<syntaxhighlight lang="javascript">[endpoint]/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

The URL includes the following components:

*<code>[endpoint]</code>: location of data collection environment
*<code>[appid]</code>: provided App ID
*<code>[sessionID]</code>: unique value for each user session
*<code>[payload]</code>: metadata and events

====Endpoint====

There are endpoints for testing and production:

*Testing: <code>http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

During testing, all calls should be pointed to the testing endpoint. We will review the update to the production endpoint during the Go Live section of this guide.

====URL Example====
As you move through the integration steps, you can reference the below URL structure with the expanded payload:

<syntaxhighlight lang="javascript">
http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"static": [static_metadata],
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [UTC]
}
</syntaxhighlight>

===Create Session ID===
A unique Session ID must be created upon app launch and provided in the URL. This will allow measurement to occur for the entire duration that a user is within the app.

The session ID must be a GUID that is passed with every request and remain consistent throughout each individual session. You can use an existing ID, a random number, or date.now() as shown in the recommended sample code below:

<syntaxhighlight lang="javascript">sessionID = Date.now()+String(Math.random()*1000000 >> 0);</syntaxhighlight>

Upon exiting the app, the session will need to be terminated using the delete event. Sessions will automatically expire after 30 minutes of cloud inactivity.

===Define URL Structure===
Define the URL structure using your provided <code>[appid]</code> and a unique <code>[sessionID]</code>.

<syntaxhighlight lang="javascript">http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

===Configure Payload===

All Cloud API requests must contain the following payload data:

*''devInfo'': device and app info
*''metadata'': asset metadata
*''event metadata'': type of event

The payload can be passed through key-values using the Nielsen reserved keys. The specific keys and descriptions are highlighted in the tables included in this section.

'''Payload Example'''

The example below should be referenced when following the steps for configuring the request payload.

<syntaxhighlight lang="javascript">
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2" //ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}
</syntaxhighlight>

=====Configure Payload: devInfo=====
An object <code>"devInfo"</code> will need to be created to capture App and Device information.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| devId || unique ID to identify user (e.g. Advertising ID, Roku Device ID) || custom || Yes
|-
| apn || app name || custom || Yes
|-
| apv || app build version || custom || Yes
|-
| uoo || device opt-out status || <code>"true"</code> or <code>"false"</code> || Yes
|-
|}

On mobile devices you will need to pass the IDFA/Ad ID as part of the devId parameter. Please see the section below regarding Opt Out and the IDFA/Ad ID.

===== Accessing the IDFA on iOS =====

Accessing the ID For Advertisers (IDFA) uses OS level API calls. In order to do this, you must first import the following header file:
<syntaxhighlight lang="objective-c">#import <AdSupport/ASIdentifierManager.h></syntaxhighlight>

Then to receive the IDFA as a NSString, use similar code to the following:
<syntaxhighlight lang="objective-c">NSString *idfaString = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];</syntaxhighlight>
You can read more about ASIdentifierManager on Apple's [https://developer.apple.com/reference/adsupport/asidentifiermanager| developer website].

===== Accessing the Ad ID on Android =====

Accessing the Google Ad ID uses OS level API calls. In order to do this, you must first import Google Play Services. Then to receive the Ad ID, use the AdvertisingIdClient class as such:
<syntaxhighlight lang="java">public static AdvertisingIdClient.Info getAdvertisingIdInfo (Context context)</syntaxhighlight>

You can read more about the AdvertisingIdClient class on Google's [https://developers.google.com/android/reference/com/google/android/gms/ads/identifier/AdvertisingIdClient| developer website].

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},
</syntaxhighlight>

==== 3.2 Configure Payload: metadata ====
Asset metadata can be passed through <code>"metadata"</code>. There are two asset types: <code>"content"</code> for video and <code>"ad"</code> for ads. The metadata received for each asset is used for classification and reporting.

You will need to set up <code>"metadata"</code> objects for <code>"content"</code> and <code>"ad"</code> with the required Nielsen keys as shown in the sample code below.

===== Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>"content"</code> || Yes
|-
| assetid || unique ID assigned to asset || custom || Yes
|-
| program ||name of program (25 character limit) || custom || Yes
|-
| title ||name of program (25 character limit) || custom || Yes
|-
| length || length of content in seconds || <code>seconds</code> (86400 for live stream) || Yes
|-
| segB || custom segment B || custom ||
|-
| segC || custom segment C || custom ||
|-
| airdate || the airdate in the linear TV || YYYYMMDD HH24:MI:SS || Yes
|-
| isfullepisode || full episode flag || <code>"y"</code>- full episode, <code>"n"</code>- non full episode || Yes
|-
| crossId1 || standard episode ID || custom || Yes
|-
| crossId2 || content originator (only required for distributors) || Nielsen ||
|-
| adloadtype || type of ad load:
<code>"1"</code> Linear – matches TV ad load

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|-
| hasAds || ads indicator
<code>"1"</code>: ads included

<code>"0"</code>: ads not included
|| <code>"1"</code> or <code>"0"</code> || Yes
|-
| progen || program genre abbreviation - see [[DCR OTT Genre List]] for accepted values || <code>"CV"</code> for Comedy Variety || Yes
|}

'''Example Content Object'''
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "VIDEO-ID123",
"isfullepisode": "y",
"program": "Program Name",
"title": "Episode Title S3 - EP1",
"length": "1800",
"segB": "Custom Segment B",
"segC": "Custom Segment C",
"crossId1": "Standard Episode ID",
"crossId2": "Content Originator ID",
"airdate": "20161013 20:00:00",
"adloadtype": "2",
"hasAds": "1",
"progen": "CV"
}</syntaxhighlight>

===== Ad Metadata =====
The ad metadata should be passed for each individual ad.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || <code>"preroll"</code>, <code>"midroll"</code>, or <code>"postroll"</code> || Yes
|-
| assetid || unique ID assigned to ad || custom || Yes
|}

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "AD-ID123"
}
</syntaxhighlight>

=== Configure Payload: Events ===

The last part of the payload is for enabling events so content is measured correctly when viewed. The events and required parameters are included below.

==== Event Types ====

The available events are:
{| class="wikitable"
|-
! Event !! Description
|-
| <code>"playhead"</code> || Playhead position in seconds. Must be passed as a whole number every 10 seconds. The final playhead position should also be sent before an asset has changed to properly capture full duration. Playhead is used to handle pause and scrubbing. When content is paused, stop passing playhead position.
|-
| <code>"complete"</code> || Complete event must be sent when the content has completed full playback.Before calling the complete event, a final playhead update with the final position is required to be sent to receive full duration credit.
|-
| <code>"delete"</code> || The delete event must be sent when the session is completed, or terminated. After 30 minutes of inactivity, the session will expire. All creditable duration will be summarized for all asset types when delete occurs (content and ads).
|}

===== Event Parameters =====

The following parameters need to be passed when calling events:

{| class="wikitable"
|-
! Parameter !! Description !! Value !! Required
|-
| <code>"event"</code> || event type || <code>"playhead"</code>, <code>"complete"</code>, or <code>"delete"</code> || Yes
|-
| <code>"position"</code> || creditable position || playhead position in seconds or UTC timestamp in seconds for livestream || Yes
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || Yes
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || Yes
|}

===== Example Event =====
You can call events by passing values in the required parameters:

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"metadata": {
"static": [static metadata],
"content": [content metadata],
"ad": [ad metadata]
},
// Event Parameters
"event": [event], // event name
"position": [playheadPosition], //position in seconds
"type": [asset type], // values are "content" or "ad"
"utc": "1472760000000" //unix timestamp in milliseconds
}
</syntaxhighlight>

'''Note:''' The full payload including "devInfo" and "metadata" must be populated in each event request.

===== Sample Event Lifecycle =====
The sample event lifecycle can be used as a reference for identifying the order for calling events and values to pass.

<syntaxhighlight lang="javascript">
// Start of Session: session ID created when App is opened

// Preroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472760000000"}

// Midroll
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content resumes at 15 minutes
Content Playhead {"event": "playhead", "position": "900", "type": "content", "utc": "1472760000000"}

// Content completes at 30 minutes
Complete {"event": "complete", "position": "1800", "type": "content", "utc": "1472760000000"}

// Postroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472760000000"}
</syntaxhighlight>

'''Sample Event Lifecycle - Detailed Storyline'''
This detailed event sequence provides additional insight for the correct events to call when handling certain playback scenarios.
<syntaxhighlight lang='javascript'>// SESSION STARTS
// Start of Session: session ID created when App is opened

// PREROLL
// Preroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Preroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "15", "type": "ad", "utc": "1472761500000"}

// CONTENT
// Content Start - Start new content streams with a position of "0" incrementing the position every 10 seconds.
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472761500000"}

// Content Stop Before Ad Break - Send a playhead update including the current content positon before an Ad break.
Content Playhead {"event": "playhead", "position": "299", "type": "content", "utc": "1472787400000"}

// MIDROLL
// Midroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472787500000"}

// Midroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "60", "type": "ad", "utc": "1472793500000"}

// CONTENT
// Content resumes at 5 minutes - Send playhead update with the current resumed position, and begin incrimenting the positon every 10 seconds.
Content Playhead {"event": "playhead", "position": "300", "type": "content", "utc": "1472799500000"}

// Content completes at 10:12 - Make sure to send in the playhead event with the final content position before sending the complete event.
Final Content Playhead {"event": "playhead", "position": "612", "type": "content", "utc": "1472830700000"}

Complete {"event": "complete", "position": "612", "type": "content", "utc": "1472830800000"}

// POSTROLL
// Postroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472830900000"}

// Postroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "45", "type": "ad", "utc": "1472835300000"}

// SESSION ENDS

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472835400000"} </syntaxhighlight>

=====Handling Playhead=====
Calling <code>"playhead"</code> is critical for accurate duration crediting. You can reference the below guidance to determine the correct playhead position to pass depending on the playback scenario.

'''Playhead: General'''
* Playhead position must start at 0 for each new asset, and be passed at least every 10 seconds.
* Final postion must be sent at the end of content or an ad

'''Playhead: Ads'''
* The final position must be sent when switching from content to ad, or ad to content.
* Each ad playhead position should be 0 at ad start.
* For Ad Pods, playhead must be called, and reset to 0 for each individual ad.
* The last content position before an Ad should be sent before switching to Ads.
* When content has resumed following an ad break, the playhead position update must continue where the previous content segment left off.

'''Playhead: User Actions'''
* Upon user scrubbing, the current position must be sent before a user scrubs, and the new position should be sent where the user lands, and begin sending in the 10 second updates thereafter.
* On pause, send the current position and then discontinue sending playhead event updates.
* If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

===== Interruption Scenarios =====

As part of configuring events, you will need to handle all possible interruption scenarios such as:

*Pause / Play
*Network Loss (Wi-Fi / Airplane Mode / Cellular)
*Wi-Fi OFF / ON
*Call Interrupt (SIM or Third party Skype / Hangout call)
*Alarm Interrupt
*Content Buffering
*Device Lock / Unlock (Video players only, not for Audio players)
*App going Background / Foreground (Video players only, not for Audio players)
*App Crash or Exit
*Channel / Station Change Scenario
*Unplugging of headphone

When playback is temporarily interrupted (e.g. pause, content buffering), the app needs to send the last known playhead position.

*If an app is sent to background for more than 5 minutes, please create a new session ID. Otherwise, use the same session ID as before.
*If loss of Internet occurs, please queue the API calls that would have been made. Once Internet connectivity is regained, please spool off the API calls in order of first generated (Note: if doing so, please use the UTC time in milliseconds)

When playback is permanently interrupted, the app needs to send delete immediately.
*If an app crashes, please create a new session ID. No delete call will be necessary as the previous session will timeout.

Once playback resumes after delete occurs, a new session will need to be created with a unique session ID. All of the required metadata and events will need to be sent.

'''Note:''' The session will automatically timeout after 30 minutes of inactivity.

=== Example Request ===

Now that we walked through the Cloud API integration steps, your requests should have the following components: Session ID, App ID, and Payload. You can reference the example below when your reviewing your integration.

<syntaxhighlight lang="javascript">
// 1. Create Session ID
sessionID = Date.now()+String(Math.random()*1000000 >> 0); // Must be GUID for each viewing session

// 2. Define URL Structure with App ID and Session ID
sessionURL = http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false"
},

// 3.2 Configure Payload: metadata
"metadata": {
"static": {}, // object for measuring static content
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"segB": "Custom Segment B", // custom segment
"segC": "Custom Segment C", // custom segment
"crossId1": "Standard Episode ID", // episode ID
"crossId2": "Content Originator ID", // content orginator (required for distributors)
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2", // ad load flag
"hasAds": "1", // content contains ads = 1 / no ads = 0
"progen": "CV" // program genre abbreviation
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}

// Append payload to URL
var image = new Image()
image.onerror = function() {
// wait and send again
}
(new Image).src = sessionURL+encodeURI(JSON.stringify(payload));
</syntaxhighlight>

==== Enable Debug Logging ====

Now that you have set up the Cloud API requests, you can enable debug logging to validate your integration. Enabling debug logging is required for Nielsen certification.

==== GET Request ====

Display GET Request to console using a name to identify each event (e.g. playhead).

<syntaxhighlight lang="javascript">
console.log("Event", image);
</syntaxhighlight>

==== Payload ====

Output payload to identify required metadata and events.

<syntaxhighlight lang="javascript">
console.log("Event Payload", payload);
</syntaxhighlight>

==== HTTP Response Code ====

Confirm request was completed by viewing HTTP response code.

<syntaxhighlight lang="javascript">
code = msg.GetResponseCode();
console.log("Response Code", code);
</syntaxhighlight>

You can reference the HTTP Response Code table when reviewing your requests:

{| class="wikitable"
|-
! Status Code !! Status Text !! Description
|-
| <code>200</code> || OK || request received
|-
| <code>403</code> || Forbidden || invalid App ID
|-
| <code>404</code> || Not Found || JSON issue
|}

== Opt-Out ==
Your app must provide a means for the user to Opt-Out, or Opt-In to Nielsen Measurement. The Opt-Out requirement can be fulfilled by creating an Opt-Out/Opt-In button, toggle switch, or slider within the app "Settings", or "About" section to allow the user selection. If you have the ability to render text within the Opt-Out screen, it is recommended to add the Privacy Information included below.

[[File:Nielsen Opt-Out.png|link=]]

You will need to store the User Opt-Out (uoo) status, so that it can be retrieved and populated in the <code>"devInfo"</code> metadata which will be sent in every Cloud API event (playhead, complete, & delete).

*In addition, you will need to ensure that the devId field is a blank value if a user has elected to Opt-Out

*If the device offers "Limit Ad Tracking" or "Opt-Out" device settings, you must set uoo=true, and also ensure that the devId is set to a blank value if the user elects to enable this setting.

{| class="wikitable"
|-
! uoo Key !! Description !! Values
|-
| uoo || Device is Opted-In to Nielsen Measurement (Recommended Default Setting) || <code>"false"</code>
|-
| uoo || Device is Opted-Out of Nielsen Measurement || <code>"true"</code>
|}

===== devInfo Opt-In JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Roku Sample App",
"apv": "1",
"devId": "7be25cf9-8c40-5cc2-871e-19bf41940288",
"uoo": "false"
},
</syntaxhighlight>

===== devInfo Opt-Out JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Roku Sample App",
"apv": "1",
"devId": "", //devId must be blank when a user elects to Opt-Out.
"uoo": "true"
},
</syntaxhighlight>

===== Privacy Information Template To Include In Opt-Out Screen =====

<blockquote>
'''''ABOUT NIELSEN MEASUREMENT'''''

Television and the way we watch it have come a long way since Nielsen began measuring TV audiences in 1950. Today, the ability to watch our favorite shows at any time and on multiple devices amplifies the need for exceptionally adept and flexible audience measurement capabilities.

Consumers are changing with the times, and the same goes for us. As technology continues to evolve and media companies try new ways to attract viewers, understanding what consumers are watching — and what they're watching on — is more important than ever. Today, viewing video is a personal and mobile experience — anytime and anywhere. Our capabilities provide relevant metrics that are necessary to inform successful marketing and programming and drive continued growth. As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process and use. While our digital measurement products are not used to identify you in any way, they help us and our clients measure and analyze how consumers engage with media across online, mobile and emerging technologies, and offer insights into consumer behavior.

'''''YOUR CHOICES'''''

Nielsen believes that you should have a choice about whether to contribute to our research and insights. To opt out, or opt into Nielsen measurement please make the appropriate selection within the app. If you have this app on more than one device, you will need to opt out of this app on each device. To learn more about our digital measurement products and your choices in regard to them, please visit http://www.nielsen.com/digitalprivacy.

'''''Disclosure Template'''''

Additionally, you must update the App description information from the App Distribution Store with the Nielsen Measurement disclosure below:

This app features Nielsen's proprietary measurement software which will allow you to contribute to market research, like Nielsen's TV Ratings. Please see http://www.nielsen.com/digitalprivacy for more information.
</blockquote>

== Testing ==
Before providing an app build to Nielsen for testing, it is important to run validation checks once you have enabled debug logging.

=== Payload Validation ===

Ensure that all of the required payload data is populating while testing several videos. The following areas are critical to measurement:
*devInfo
*Asset metadata for both content, and ads
*Events
*Opt-Out status

=== Player Events ===
Review event calls:

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset.
*Final playhead position is sent on content, or ad before switching between assets.
*Content metadata remains constant throughout an episode, or clip play.
*Ad metadata is populated appropriately for each individual ad.
*Playhead position update resumes for content after an ad break, and resets to 0 for each individual ad.
*For scrubbing, last current position should be sent while scrubbing occurs, and the new position should also be sent where the user scrubs to.
*Exiting a stream early should execute the last current position in a playhead update to receive accurate duration.
*Upon pause, the current position should be sent, and playhead updates should stop incrementing until resume play occurs.

==== complete ====
*Check that the complete event executes upon content complete after the final playhead update is sent
*Do not execute the complete event for ads

==== delete ====
*Check to see that the delete event occurs upon app exit

==== GET Request Format ====
*Ensure that the event payloads are formatted in JSON
*Check to see that each of the Cloud API GET requests are properly encoded

==== HTTP Response ====
*Make sure that each of the Cloud API Get requests are received by the Nielsen Cloud API properly through use of the HTTP Response Code outputs enabled in console.

==== Opt-Out ====
*Test the "uoo" key gets populated accurately for both Opt-In and Opt-Out selections by validating the Cloud API events called after the user Opt-Out/Opt-In selection.
*Test that the devId field is populated with a blank value if a user has elected to Opt-Out. For example: "devId": "",
*If the device supports "Limit Ad Tracking" or has device "Opt-Out" settings, test that uoo=true, and that devId is set to a blank value if enabled in the device settings.

== Go Live ==
After your integration has been certified, you will need to: Change Endpoint and Disable Logging.

'''Change Endpoint:''' You will need to update to the production endpoint:

*Testing: <code>http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://cloudapi.imrworldwide.com/nmapi/v2/</code>

Your production URL structure should now be:
<code>https://cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</code>

'''Disable Logging:''' You can now disable debug logging