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 static pages. 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 SessionID.

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.

  • Testing URL Structure: http://sandbox.cloudapi.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=[API Data]
  • Production URL Structure: 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.

Example Image Request (JavaScript Example)

var sendURL =””https://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

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

{

  “devInfo”: [deviceInfo],

  “metadata”:

  {

    “static”: [static metadata],

    “content”: [content metadata],

    “ad”: [ad metadata]

  },

  “event”: [event],

  “position”: [playhead position],

  “type”: [asset type],

  “data”: [event specific data],

  “index”: [message index],

  “utc”: [UTC]

}

Step 3: Prepare devInfo For Initialization.

Initialization Parameters

To initialize Cloud API, parameters must be passed as devInfo when calling the initialization event (init). The available parameters are listed in the table below.

Parameters Description Value Required? (Y/N)
devId Unique Identifier used to identify the device. i.e. IDFA, Google Play ID, Roku Device ID Device derived. Client will be responsible for obtaining this ID from the user device. Yes
bldVrsn Build version from the app distribution point. Client specified No
apn Unique string identifying the implementation. Client specified Yes
apv Version of the App Build Client specified Yes

Step 4: Prepare Static Metadata Object

Static Metadata Example

{

  “type”: “static”,

  “assetid”: “ID724-38054”,

  “section”: “App Section”,

  “segA”: “Custom SegmentA”,

  “segB”: “Custom SegmentB”,

  “segC”: “Custom SegmentC”

}

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

Event Parameters

ParametersDescriptionValueRequired? (Y/N)
eventEvent Types“playhead”, “Complete”, “delete”Yes
positionCreditable position.Client configured position for static duration measurement.Yes
dataStatic Visibility & Viewability Indicator“visible”: “1”, “focus”: “1” Hardcode Both Values to: “1”Yes
typeContent Type“static”Yes
utcTimer For Time Spent Updated Every 10 Seconds“1456448742”Yes

The data event parameter should only be used for static measurement to provide the static state (“visible”: “1”, “focus”: “1”), and is not needed for video measurement.

Configure and Fire Cloud API Events

When a user launches the app, and the devInfo must be supplied. The user can navigate through an app during the same app session.

Cloud API Event – playhead (content|ad)

The playhead event must be sent every ten seconds, and must pass the position in UTC in milliseconds (as a whole number). The static metadata remains constant throughout each section being measured, and must be updated once a user has navigated to a new section. The final playhead position is also 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”

   },

   “metadata”:

   {

     “static”: {content metadata object},

     “content”: {},

     “ad”: {}

   },

   “event”: “playhead”,

   “position”: “1456448742000”,

   “data”: {“visible”:”1″, “focus”:”1″},

   “type”: “static”,

   “index”: “0”,

   “utc”: “1456448742000”

}


complete

The complete event must be sent when a user exits an app section, and the position should be updated to receive accurate duration measurement.

{

   “devInfo”:

   {

     “devId”: “12345”,

     “bldVrsn”: “1.0.0.1”,

     “apn”: “NielsenSampleApp”,

     “apv”: “1.0”

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

   },

   “metadata”:

   {

     “static”: {static metadata object},

     “content”: “”,

     “ad”: {}

   },

   “event”: “complete”,

   “position”: “1456448752000”,

   “data”: {“visible”:”1″, “focus”:”1″},

   “type”: “static”,

   “index”: “0”,

   “utc”: “1456448752000”

}


Cloud API Event – delete

The delete event must be sent when the session is completed, or terminated. The session will expire after 30 minutes of Cloud inactivity.

{

   “devInfo”:

   {

     “devId”: “12345”,

     “bldVrsn”: “1.0.0.1”,

     “apn”: “NielsenSampleApp”,

     “apv”: “1.0”

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

   },

   “metadata”:

   {

     “static”: {static metadata object},

     “content”: {},

     “ad”: {}

   },

   “event”: “delete”,

   “position”: “1456448762000”,

   “data”: {“visible”:”1″, “focus”:”1″},

   “type”: “static”,

   “index”: “0”,

   “utc”: “1456448762000”

}

Click here for information on the metadata that can be passed as a JSON string.

Sample Events Sequence

Pseudo CodeDescription

[CloudAPI-MeasurementURL init:Send-DeviceMetadata];

Initialize Session

[CloudAPI-MeasurementURL staticstart:Send-StaticMetadata];

Static Start Event Upon App Section Load

[CloudAPI-MeasurementURL staticposition:position];

Static Position Sent Every Ten Seconds

[CloudAPI-MeasurementURL staticend:Send-StaticMetadata];

Static End Event Upon App Section Exit

[CloudAPI-MeasurementURL delete:Send-DeviceMetadata];

Delete Session

Step 6: Account For Interruption Scenarios with API Events

Interruption Scenarios

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

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

In case of encountering one of the above interruptions, the player application needs to send complete immediately and withhold from sending playhead updates.

If app crashes or is exited, send delete if possible, however we delete a session after 30 minutes if there is no Cloud activity.

Start sending the events for the new viewing session once the app viewing has resumed. A new sessionID will be needed, and the appropriate metadata will need to be sent. Begin sending playhead once the viewing session resumes.

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

Cloud API Nielsen Measurement Opt-Out

Your app must provide a means for the user to opt-out of, or opt back into Nielsen Measurement. To implement the opt-out option, you must include a webview within the app accessible from the “Settings”, or “About” section which loads the Opt-Out URL template included below. The URL must be loaded in a webview within your app so that the user can select the option to Opt-Out.

Testing Opt-Out URL Structure

https://sandbox.cloudapi.imrworldwide.com/nmapi/v1/[appid]/[sessionID]/privacy/?[devInfo]

 

Production Opt-Out URL Structure

https://cloudapi.imrworldwide.com/nmapi/v1/[appid]/[sessionID]/privacy/?[devInfo]

Additionally, you must update the Distribution App Store Disclosure to inform the user that the app features Nielsen measurement.

Disclosure Template

This app features Nielsen’s proprietary measurement software which will allow you to contribute to market research, like Nielsen”s TV Ratings. Please see www.nielsen.com/digitalprivacy for more information. for more information.

Pre-Certification Checklists

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