Nielsen SDK Documentation

DCR Implementation Guide – Cloud API

This page describes how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR) measurement for media player applications. For specific device support, please reach out to your Nielsen representative.

Cloud API Implementation Overview

Prerequisites

Before you begin, you will need

  • App ID (appid): Unique ID assigned to your player/site and configured by product.
  • Measurement Metadata: Metadata must be prepared to be included in API.
  • Measurement Template: URL template to generate image requests for measurement.
  • Opt-Out Template: URL template to generate user Opt-Out request in order to provide users with a means for opting out of Nielsen measurement.

If you do not have any of these pre-requisites or if you have any questions, please contact our SDK sales support team.

Step 1: Prepare URL Path with appid, and Prepare Session ID.

There is a testing URL structure to be used during the implementation and certification stages, and a production URL structure to be used once an implementation has been certified by Nielsen. Note that the testing URL is non-SSL, and the production URL uses HTTP-over-SSL (HTTPS).

  • Testing URL path: http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[API Data]
  • Production URL path: https://cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[API Data]

The appid will be provided to you by your Nielsen Technical Account Manager.

Generate a unique Session ID for each new user session.

Example SessionID Creation

A unique SessionID must be created upon app launch. This will allow measurement to occur for the entire duration that a user is within the app. The session must be deleted upon exiting the app. Sessions will expire after 30 minutes of Cloud inactivity.

sessionID = Date.now()+String(Math.random()*1000000 >> 0);

 

The example above uses random number to distinguish sessions within the same millisecond however you can use any GUID library that is unique per session, but the session ID must remain consistent throughout each individual session.

The following is a general example of how SessionID can be configured across platforms

sessionID = <> + <>;

Step 2: Setup Image Request, and Prepare API URL Template

In order to execute Cloud API calls, image requests will need to be setup.

var sendURL = “http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[API Data]”;

var img = new Image();

img.src = sendURL+encodeURI(JSON.stringify(MetadataSample));

 

Sample API URL Template

http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=

{

  “devInfo”: “deviceInfo object”,

  “metadata”:

  {

    “static”: “static metadata object”,

    “content”: “content metadata object”,

    “ad”: “ad metadata object”

  },

  “event”: “event”,

  “position”: “playhead position”,

  “type”: “content” or “ad”,

  “data”: “”,

  “index”: [message index],

  “utc”: “1458484840”

}

 

Step 3: Prepare Device info

Device info must be passed in devInfo parameter when calling any Cloud API event. The available parameters are listed in the table below.

Device info Parameters

ParametersDescriptionValueRequired?
(Y/N)
devIdUnique Identifier used to identify the device. i.e. IDFA or Google Play IDDevice derived.
Client will be responsible for obtaining this ID from the user device.
Yes
bldVrsnBuild version from the app distribution point.Client specifiedNo
apnApplication name. Unique string identifying the application.Client specifiedYes
apvVersion of the App BuildClient specifiedYes

Step 4: Prepare Content & Ad Metadata Objects.

The content and ad metadata for each asset should always be passed in each event until they are changed. During an episode the content metadata would remain constant until the content has ended. Ads should be updated for every ad being played individually.

Content Metadata Example

Include metadata of the content into the metadata section of the API URL (with event parameter “type”:”content”). This metadata should remain persistent until a new ad asset is loaded.

{

  “type”: “content”,

  “assetid”: “VID345-67483”,

  “isfullepisode”: “y”,

  “program”: “programName”,

  “title”: “Program S3 – EP1”,

  “length”: “3600”,

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

}

When content has resumed following an ad break, the playhead position update must continue where previous content segment left off.

Ad Metadata Example

Include metadata of the ad into the metadata section of the API URL (with event parameter “type”:”ad”).

{

  “type”: “preroll”, //midroll || postroll,

  “assetid”: “AD361-84413”

}

If there is no unique assetid for Ads, then send Ad-1, Ad-2 etc. Refer to metadata for more details on Nielsen keys for handling metadata inputs.

Step 5: Setup Event Parameters, and Enable Cloud API Player Events.

Event Parameters

ParametersDescriptionValueRequired?
(Y/N)
eventMeasurement event type“playhead”, “complete”, “delete”Yes
positionVideo player playhead positionClient configured playhead position, or UTC for live.Yes
typeAsset Type being measured“content” or  “ad”Yes
utcUnix timestamp in milliseconds – must be passed every 10 seconds“1456448742”Yes

Cloud API Events

Cloud API Event – playhead (content|ad)

The playhead event is for tracking progress, allowing the Cloud API to properly credit the time spent in the current asset. The progress event must be sent at an interval update of every 10 seconds passed as a whole number. The final playhead position should also be sent before an asset has changed to properly capture full duration.

{

  “devInfo”:

  {

    “devId”: “12345”,

    “bldVrsn”: “1.0.0.1”,

    “apn”: “NielsenSampleApp”,

    “apv”: “1.0”

    “appid”: “TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX”

    “uoo”: “false”

  },

  “metadata”:

  {

    “static”: “”,

    “content”: {content metadata object},

    “ad”: {ad metadata object}

  },

  “event”: “playhead”,

  “position”: “300”,

  “data”: “”,

  “index”: “0”,

  “type”: “content” or “ad”,

  “utc”: “1456448742”

}

For Ad Pods, events must be called for each individual Ad. Each Ad playhead position should begin at 0 at ad start.

When content has resumed after an ad break, the playhead position update must continue from where the previous content segment left off.

Cloud API Event – complete (content)

The complete event must be sent when the content has completely ended.

{

  “devInfo”:

  {

    “devId”: “12345”,

    “bldVrsn”: “1.0.0.1”,

    “apn”: “NielsenSampleApp”,

    “apv”: “1.0”

    “appid”: “TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX”

    “uoo”: “false”

  },

  metadata:

  {

    “static”: “”,

    “content”: {content metadata object},

    “ad”: {ad metadata object}

  },

  “event”: “complete”,

  “position”: “1800”,

  “data”: “”,

  “type”: “content”,

  “index”: “0”,

  “utc”: “1456448742”

}

Cloud API Event – delete (content|ad)

The delete event must be sent when the session is completed, or terminated (e.g. app close). After 30 minutes of inactivity, the session will expire.

All creditable duration will be summarized for all asset types (content and ads) when delete occurs.

On certain platforms, it may not be possible to send the delete event on app close or other session termination events. In these cases, the delete event may be omitted.

{

  “devInfo”:

  {

    “devId”: “12345”,

    “bldVrsn”: “1.0.0.1”,

    “apn”: “NielsenSampleApp”,

    “apv”: “1.0”

    “appid”: “TXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX”

    “uoo”: “false”

  },

  metadata:

  {

    “static”: “”,

    “content”: {content metadata object},

    “ad”: {ad metadata object}

  },

  “event”: “delete”,

  “position”: “”,

  “data”: “”,

  “type”: [type], //This field is not applicable on delete

  “index”: “0”,

  “type”: “content” or “ad”,

  “utc”: “1456448742”

}

Event Sequence

The sample event sequence can be used for reference when identifying the specific events that need to be called during content and ad playback.

Content metadata should remain constant throughout the entirety of an episode/clip including when ads play, however the ad metadata should populate accurately for each individual ad.

TypePseudo Code
Preroll[CloudAPI-MeasurementURL playhead event for preroll];
Content[CloudAPI-MeasurementURL playhead event for content];
Midroll[CloudAPI-MeasurementURL playhead event for midroll];
Content

[CloudAPI-MeasurementURL playhead event for content];

[CloudAPI-MeasurementURL complete event for content];

Postroll[CloudAPI-MeasurementURL playhead event for postroll];
Delete Session Upon App Exit[CloudAPI-MeasurementURL delete event for the session];

For Ad Pods, events must be called for each individual Ad. Each Ad playhead position should begin at 0 at ad start.

Step 6: Account For Interruption Scenarios with API Events.

As part of integrating Cloud Solution, the app developer needs to handle the following possible interruption scenarios.

  • Pause / Play
  • Wi-Fi OFF / ON
  • Airplane Mode ON / OFF
  • Network Loss (Wi-Fi / Airplane / Cellular)
  • Alarm Interrupt
  • Call Interrupt (SIM or Third party Skype/Hangout call)
  • Device Lock / Unlock (Video players only, not for Audio players)
  • App going in the Background/Foreground (Video players only, not for Audio players)

In case of encountering one of the above interruptions, the player application needs to send delete immediately. Generate a new sessionID and begin sending playhead with the appropriate metadata for the new viewing session, once the playback begins.

If app crashes or is exited, send delete if possible, however the session will timeout after 30 minutes of inactivity.

Step 7: Implement Nielsen Opt-Out & Update App Store Disclosure.

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. 

Nielsen Opt-Out Button

 

Your application should display the Nielsen Privacy policy within the Nielsen opt-out screen:

 


 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.


Additionally, you should update the Distribution App Store Disclosure with the following text to inform the user that the app features Nielsen measurement:


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.


 

You will need to store the User Opt-Out (uoo) status, so that it can be retrieved and populated in the "devInfo" metadata which will be sent in every Cloud API event (playhead, complete, & delete). “uoo” should be set to “false” by default (i.e. user is opted-in), and should be set to “true” if the user chooses the opt-out option.

devInfo Opt-In JSON Payload Example 

devInfo Opt-Out JSON Payload Example

 

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 appropriatley 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 recieved 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.