Engineering Client Portal - User contributions [en]

File:250807 AGF Metadata Static-Display v.1.0 english.pdf

2025-10-01T08:55:44Z

MichelFodjo: 250807_AGF Metadata Static-Display_v.1.0_english

== Summary ==
250807_AGF Metadata Static-Display_v.1.0_english

File:250807 AGF Metadata Static-Display v.1.0 deutsch.pdf

2025-10-01T08:54:02Z

MichelFodjo: 250807_AGF Metadata Static-Display_v.1.0_deutsch

== Summary ==
250807_AGF Metadata Static-Display_v.1.0_deutsch

DCR Germany Video Cloud API

2023-10-18T13:01:59Z

MichelFodjo: /* Interruption Scenarios */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing Cloud API =
This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.

<pre style="color: orange">
PLease note that you have to use the Staging Cloud API Endpoint until you get the green light from Nielsen to move to Production!
</pre>

__TOC__
==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 by your assigned Technical Account Manager upon starting the integration.

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Provided by Nielsen
|}

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

====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. '''Note:'''The "P" prefix must be removed from the App ID received before adding it to the URL, i.e. if you received PDF20695-XXXX-XXXX-XXXX-3E334133D917 from Nielsen , your url will then be : <code>[endpoint]/DF20695-XXXX-XXXX-XXXX-3E334133D917/[sessionID]/a?b=[payload]</code>
*<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://sc-eucert.nmrodam.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://sc-eucert.nmrodam.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms],
"sessid": [unique view session ID for each video play]
}
</syntaxhighlight>

===Create Session ID and send EMM Ping===

====Create Session ID====

A unique Session ID <code>[sessionID]</code> must be created upon app launch and provided in the URL. This will allow the measurement to occur for the entire duration that a user is within the app.

A Session ID needs to be completely unique so it is recommended to use our generation method example provided below to create unique alpha-numerical 29 characters + 10 characters UTC timestamp, to guarantee there are no repeats, also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference and use.

Session ID example: '''LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088'''
 

<syntaxhighlight lang="javascript">
'''// Create random GUID'''
function buildGUID() {
var UAIDbase62Characters = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
var UAIDpayloadLength = 29;

function UAIDgetRandom62() {
var r1;
do {
r1 = Math.floor(Math.random() * (16 * 62));
} while (r1 > 61);
return r1;
}

var uid = '';
for (var a = 0; a < UAIDpayloadLength; a++) {
uid += UAIDbase62Characters.charAt(UAIDgetRandom62());
}
var timestamp_ms = new Date().getTime();
uid += String(timestamp_ms).substring(3);
return uid;
}
</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.

====Send EMM Ping (only for Mobile (iOS and Android) and Browser)====
An EMM Ping must be sent using the created unique Session ID <code>[sessionID]</code> upon start of the first stream playback.
<syntaxhighlight lang="javascript">
https://[sessionID].uaid.nmrodam.com/
</syntaxhighlight>
Also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference.

===Create View Session ID for each Video Start===
An View Session ID <code>[sessid]</code> must be created upon start of each stream playback, sessid is unique per video play.

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

<syntaxhighlight lang="javascript">https://sc-eucert.nmrodam.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

===Configure Payload===

====Description 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">
// 1. Create Session ID using the UUID Generator code provided
sessionID = LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088 // Example sessionID

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

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "",
"apn": "AppName",
"apv": "1.0"
},

// 3.2 Configure Payload: metadata
"metadata": {
"content": { // object for measuring video content
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
// custom metadata
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
},
"ad": {
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Werbung",
"nol_c17": "p17,preroll"
}
},

// 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
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609" // create and pass a unique sessid for each video play using UUID Generator code provided
}
</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) - Not required for AGF || custom ||
|-
| apn || app name || custom || ✓
|-
| apv || app build version || custom || ✓
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "",
"apn": "AppName",
"apv": "1.0"
},
</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 =====

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

For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required/Obligatory
|-
| type || type of asset || <code>"content"</code> || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no [[Special Characters]]) || ✓
|-
| program ||(string) name of program (254 character limit) || custom || ✓
|-
| title ||(string) episode title (max 254 characters) || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| length || length of content in seconds || <code>seconds</code> ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| clientid ||
parent ID – value is automatically populated through provided App ID. 
In order to override the brand configured to the App ID, pass parent 
value here and the sub-brand ID associated with that brand in the subbrand 
key (e.g. multiple brands in App)
||
provided by Nielsen
||
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided 
App ID. In order to override the sub-brand configured to the App ID, value can 
be passed here (e.g. multiple sub-brands in App)
||
provided by Nielsen
||

|-
| nol_c0 || number of episode part (Sendungsteilenummer) || number || ✓
|-
| nol_c2 || web only || 'Y' or 'N' || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || duration in seconds || `seconds` ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c12 || type of asset || 'Trailer' or 'Content' || ✓
|-
| nol_c13 || original air time || `(YYYY-MM-TT)T(HH:mm:ss) Example: 2004-06-14T23:34:30 ||
|-
| nol_c14 || ISO 8601 timestamp || `(YYYY-MM-TT)T(HH:mm:ss)` ||
|-
| nol_c15 || format ID || custom ||
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c18 || livestream || 'Y' or 'N' || ✓
|-
| nol_c19 || custom variable || custom ||
|-
| nol_c20 || GfK-ID || custom ||
|}
 

====== Example Content metadata ======
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
// custom metadata
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
}</syntaxhighlight>

===== Ad Metadata (optional for public broadcasters) =====
====== Description of Ad metadata ======
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

 
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no SPACE - no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters]) || ✓
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen ||
|-
| title || only the AD-ID is necessary || custom, <AD-ID> without "VAST" Prefix or other, i.e. '2352723141' || ✓
|-
| length || length of Ad in seconds || length of Ad in seconds || ✓
|-
| nol_c1 || universal AdID (Additional AD-ID to be used by second or third marketers) || custom, i.e. 'adgapid_022_800160_1601097_001_0_0' ||
|-
| nol_c2 || web only || 'Y' or 'N' ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || duration of the video file in seconds || || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c11 || AD-ID (unique ID of an advertisement. Necessary if ads are being broadcasted) || custom, i.e. '2352723141' || ✓
|-
| nol_c12 || content type (key distinction of content, advertising, and Trailer) || 'Werbung' || ✓
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c17 || ad placement type (placement information of advertisement) || 'preroll', 'midroll', 'postroll' or 'other' || ✓
|}

====== Example Ad metadata ======
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Werbung",
"nol_c17": "p17,preroll"
}

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

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

'''General'''
* Playhead position in seconds, must be passed as a whole number every 10 seconds.
* The final playhead position should be sent before before sending "complete" event when content playback is complete.

'''Live Stream'''
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position. Note that ad playheads must also use Unix Time for each single Ad in an Ad Pod.

'''VoD Stream'''
* For VoD stream use the player position for Content and Ad at playback start of a content or single Ad in an Ad Pod, playheads will then be 0, 10, 20, ....

'''End of an Asset'''
* Final postion must be sent at the end of Content or Ad playback

'''Ads'''
* The final playhead position must be sent when switching from content to ad, or ad to content.
* For Ad Pods, playhead must be called for each individual ad.
* When content has resumed following a mid-roll ad break, the next playhead position must continue where the previous content segment left off.

'''User Actions'''
* SCRUBBING: 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.
* PAUSE: When content is paused, send current playhead position and stop passing playhead position until content is resumed.
* EXIT Stream: If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

|-
| <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. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is optional and can be sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. 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> || ✓
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || ✓
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || ✓
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || ✓
|-style="background-color:#d0f6f8;"
| <code>"sessid"</code> || Unique View Session ID must be created upon start of each stream playback, sessid is unique per video play. || <code>"xxxjavd6wzirm93xb95uxjy1ac5wu1627638609"</code> || ✓
|}

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

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"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
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}
</syntaxhighlight>

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

===== Sample Event Lifecycle for VoD Stream =====
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 for VoD Stream - 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>

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

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

*Wi-Fi OFF / ON
*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.

see '''[[#Payload Example|Payload Example]]'''

// Append payload to URL
function sendPayloadToNielsen() {
var payloadStr = JSON.stringify(payload); // payload as string
var imgPing = new Image();
imgPing.onload = function() {
// onload event, payload succesfull sent
};
imgPing.onerror = function() {
// handle error i.e. wait and send again
};
imgPing.src = sessionURL+encodeURIComponent(payloadStr);
}
</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
|}

== Review the Reference Implementation for VoD and Live Streams ==

The Reference Implementation covers vod and Live use cases.
It also covers DAI (Dynamic Ad Insertion) with preroll and postroll Ads.

In order to start live stream select the checkbox "isLive" in the <code>Playback Settings</code> below the video player.

Start the Reference Implementation for AGF by selection Germany in the country dropbox [https://nielsenonlinesupport.com/agf/RefImplCloudAPI/index.htm?debug=true RefImplCloudAPI].
<blockquote>
Review the Nielsen CloudAPI Call Sequence below the Video Player.
</blockquote>

== Disclose Nielsen Privacy Statement ==

The Nielsen Cloud API measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen Cloud API measurement is utilizing a cookieless domain.

In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:

A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=de .

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

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

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset for VoD stream and UTC Unix Time in seconds for Live stream.
*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.

== 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://sc-eucert.nmrodam.com/nmapi/v2/</code>
*Production: <code>https://???.nmrodam.com/nmapi/v2/</code>

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

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

DCR Sweden Video iOS SDK

2023-09-28T12:12:48Z

MichelFodjo:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

__TOC__

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

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || '''Nielsen SDK''' || Includes SDK frameworks and '''sample implementation'''; "See [[iOS SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Implementation ==
Version 8 of the Nielsen App SDK comes in three versions. One that is enabled to work with the App Tracking Transparency Framework, another version that does not use the Ad Framework, and a version for Kids Apps or where no ID is required.

{| class="wikitable"
|-
! SDK Flavor
! Description
|-
| '''iOS Ad Version'''
|* Opt-In and Opt-Out functionality managed by the [https://developer.apple.com/documentation/apptrackingtransparency AppTrackingTransparency framework]. * The Nielsen SDK will attempt to collect the IDFA (Id for Advertisers) on the device. * For iOS14+, if the value returned is <code>ATTrackingManager.AuthorizationStatus.authorized</code>. * If the device is running iOS12 or iOS13, the Limit Ad Tracking setting is requested.
|-
| '''iOS No Ad Framework'''
|* Without the Ad Framework, the Nielsen SDK cannot read the IDFA, so it will attempt to retrieve the [https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor ID for Vendors (IDFV)]. * The IDFV may be used for analytics across apps from the same content provider. * The developer is required to present the User Choice Optout page. The detailed requirement is described in the [https://engineeringportal.nielsen.com//docs/DCR_Sweden_Video_iOS_SDK#Global_iOS_SDK_No_Ad_Framework_Opt-out Global iOS SDK No Ad Framework Opt-out] Section.
|-
| '''iOS SDK No ID'''
|* This version of the Nielsen SDK is perfect for Kid apps, or where no ID is required. * Please review the [https://engineeringportal.nielsen.com/docs/DCR_Sweden_Video_iOS_SDK#Global_iOS_SDK_No_ID_Opt-out Global iOS SDK No ID Opt-out] Section.
|}
=== How to obtain the NielsenAppApi.Framework ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of CocoaPods. We recommend using the CocoaPods-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_iOS_Artifactory_Guide|Select to obtain CocoaPods implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
* [[DCR_Video_iOS_SDK_xcframework|Using the XCFramework bundle]]

== Setting up your iOS Development Environment ==

=== Special Notes regarding iOS17 or TVOS17 ===
Beginning with iOS/TVOS 17, Apple is adding several requirements for App developers around tracking, use of Identifier For Advertisers (IDFA), and certain system APIs.

This requirement entails users manually opting in to declare all domains employed for tracking purposes, which includes the collection of IDFAs (Identifier for Advertisers).
Currently, even if users choose not to opt in for tracking, it's essential to note that our Nielsen Digital SDKs continue to carry out measurements and transmit data without relying on IDFA. However, this new privacy measure introduced by Apple necessitates that we bring this development to your attention, as it could potentially impact your Nielsen measurement and tracking for iOS app usage.

In order to minimize the impact, we are asking that clients do the following:

* '''Do not declare the Nielsen imrworldwide.com domain in the privacy manifest.'''
* Update to the latest Nielsen SDK release >= 9.2.0.0 when compiling your app for iOS 17.

For any additional information please refer to the Nielsen global page: [[DCR and DTVR with iOS17 or TVOS17]].

=== Configuring Xcode Development Environment ===
Starting with SDK version 6.0.0.0, the Nielsen App SDK is compatible with Apple iOS versions 8.0 and above. In addition, the SDK uses the WKWebView class instead of the deprecated UIWebView as per Apple guidelines.

=== Importing Frameworks ===

1) Extract “NielsenAppApi.Framework” from the Nielsen App SDK zip file and copy it to the Frameworks folder of the Xcode project. 

2) Import following frameworks and libraries into the Frameworks of the Xcode project before creating an instance of the Nielsen App SDK object.
* UIKit.framework
* Foundation.framework
* AdSupport.framework
* SystemConfiguration.framework
* Security.framework
** Nielsen Analytics framework makes use of a number of functions in this library.
* AVFoundation.framework
** This framework is mandatory for the iOS SDK version 5.1.1 to work.
* CoreLocation.framework
* CoreMedia.framework
* NielsenAppApi.framework
* libc++.tbd (as SDK contains Objective-C++ source file)
** Alternatively, include -lstdc++ in Build Settings → Other Linker Flag of the Xcode project 

3) Include header file <code>NielsenAppApi/NielsenAppApi.h</code> to the View Controller's header file. 

Note:
* The SDK uses the NSURLSession instead of the deprecated NSURLConnection.
* All communications between the SDK and the Census (Collection Facility) use HTTPS
 
==== Using Swift ====
To import a set of Objective-C files in the same app target as your Swift code, you rely on an Objective-C bridging header to expose those files to Swift. Xcode offers to create this header file when you add a Swift file to an existing Objective-C app, or an Objective-C file to an existing Swift app.

Select File/New File/Objective-C File 
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] 
Once this file has been created, you need to add the following:
<syntaxhighlight lang="swift">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>

==== Using Objective-C ====
Add the code
<syntaxhighlight lang ="objective-c">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
to the View Controller’s header file.
 

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_unknown || Hashed email using SHA512. This email is used by MMS reach model.
|| Client-defined || Required if login feature || "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..."
|-
| enableFpid || true/false value is required to set collection of first-party ID.
|| Nielsen-specified || NO || <syntaxhighlight lang="javascript">
{enableFpid: "true"} //alternative: false
</syntaxhighlight>
|}
 

==== Sample SDK Initialization Code ====

Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>If App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.</blockquote>

===== Using Objective-C=====
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appversion": "1.0",
@"appname": "app name here",
@"nol_devDebug": @"DEBUG",
@"hem_unknown": @"924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8...",
@"enableFpid": @"true"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

===== Using Swift =====

<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"appversion": "1.0",
"appname": "app name here",
"nol_devDebug": "DEBUG",
"hem_unknown": "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8...",
"enableFpid": "true"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
 
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
The life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# '''Processing state''' – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called

<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted NSString or an NSDictionary object. The JSON passed in the SDK must be well-formed.
* NSDictionary object
** If an object of the unexpected type is passed to the method, the error message will be logged.
** The error message will be logged if the string has an invalid JSON format.
* JSON value must be a string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

==== Create Content Metadata ====
Content metadata should remain constant throughout the entirety of an episode/clip, including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content metadata.
 

'''Note:''' Program and title metadata values should be passed to SDK as UTF-8 strings.

==== Create Ad Metadata ====
The Ad Metadata (if applicable) should be passed for each individual ad.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of ad metadata. 

'''Note:''' All metadata values should be passed as UTF-8 strings.

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

=== MetaData Example ===

==== Using Objective-C ====
<syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @
{
@"assetid" : "uniqueassetid",
@"type" : "content",
@"program" : "program name",
@"title" : "episode title",
@"length" : "2600"
//Please see the metadata link above for all content parameters
}

NSDictionary *adMetadata = @
{
@"assetid" : "uniquepostrolladid",
@"type" : "postroll"
//please see metadata link above for all ad parameters
}
</syntaxhighlight>

==== Using Swift ====
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
]

let contentMetadata = [
"assetid" : "uniqueassetid",
"type" : "content",
"program" : "program name",
"title" : "episode title",
"length" : "2600"
//Please see the metadata link above for all content parameters
]

let adMetadata = [
"assetid" : "uniquepostrolladid",
"type" : "postroll"
//Please see the metadata link above for all ad parameters
]

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player. Call play only when initially starting the video.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi play:channelInfo];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.play(channelInfo);</syntaxhighlight>
 

==== loadMetadata ====
It needs to be called at the beginning of each asset, and pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the beginning of the playlist - see below API call sequence examples.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi loadMetadata:metadataDict];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(metadataDict)</syntaxhighlight>
 

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass the current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass the whole number that increments only by 1 like 1,2,3..
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">
[self.nielsenAppApi playheadPosition:pos];
</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">
self.nielsenAppApi?.playheadPosition(pos);
</syntaxhighlight>
 

==== stop ====
Call when
* ads complete playing
* When a user pauses playback
* upon any user interruption scenario - see below chapter Interruption scenario
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi stop];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.stop;</syntaxhighlight>
 

==== end ====
Call when the content asset completes playback. Stops measurement progress.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi end];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.end</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no 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",
...
}</syntaxhighlight>
Call [[playheadPosition|playheadPosition()]] every one second until a pause.
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.playheadPosition(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 Ads ====
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|playheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of a 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.playheadPosition(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="2" | 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
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.playheadPosition(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.playheadPosition(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="2" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| 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.playheadPosition(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 the previous content segment was left off.</blockquote>

== Stop/Resume the Measurement for video Playback Interruptions ==
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 <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Privacy and Opt-Out ==

There are currently three flavours of the Nielsen SDK. Please check the "Implementation" section to compare the three flavours. Implementing opt-out for the three flavours is different:
# '''[[#Global_iOS_SDK_Opt-out|Global iOS SDK Opt-out]]''' - managed by ''AppTracking'' or ''Limit Ad Tracking'' setting on device.
# '''[[#Global_iOS_SDK_No_Ad_Framework_Opt-out|Global iOS SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without the Ad Framework.
# '''[[#Global_iOS_SDK_No_ID_Opt-out|Global iOS SDK No ID Opt-out]]''' - Direct call to SDK. It should be used for Kids Category.
__NOTOC__
=== Global iOS SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen iOS

The Nielsen SDK automatically leverages the iOS's '''Limit Ad Tracking''' or '''AppTracking''' setting.
* If the User's device is running < iOS 13.x, the Nielsen SDK will check the status of '''Limit Ad Tracking'''.
* iOS14 modifies the way Apple manages the collection of a User's Opt-In status through '''AppTracking'''. Starting with Version 8.x+, the Nielsen App SDK will check the iOS version during initialization. If the device is running iOS12 or iOS13, the Limit Ad Tracking setting is requested. If iOS14.x +, then AppTracking is utilized.
==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global iOS SDK, this optOutURL informs the user how to deactivate/activate “App Tracking/Limit Ad Tracking”.

In addition, the following text must be included in your app store description.
<blockquote>"Please note: This app features Nielsen’s proprietary measurement software, which contributes to market research, like Nielsen’s TV Ratings. Please see https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=sv for more information"</blockquote>

==== Sample Code for Global Build ====
===== Swift =====
<syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

class OptOutVC: UIViewController, NielsenAppApiDelegate, WKNavigationDelegate {
var nielsenApi : NielsenAppApi!
var webView: WKWebView!

override func loadView() {
webView = WKWebView()
webView.navigationDelegate = self
view = webView
}

override func viewDidLoad() {
super.viewDidLoad()

if let appApi = self.nielsenApi {
//Getting the optPut URL from SDK
if let url = URL(string: appApi.optOutURL) {
webView.load(URLRequest(url: url))
webView.allowsBackForwardNavigationGestures = true
}}}

func closeOptOutView() {
self.dismiss(animated: true, completion: nil)
}}
</syntaxhighlight>

===== Objective-C =====
<syntaxhighlight lang="objective-c">

#import "OptOutVC.h"
#import "NielsenInit.h"
#import <NielsenAppApi/NielsenAppApi.h>

@interface OptOutVC ()

@property (weak, nonatomic) IBOutlet UIWebView *webView;
@end

@implementation OptOutVC

- (void)viewDidLoad {
[super viewDidLoad];

- (void)viewDidLoad {
[super viewDidLoad];
//Getting the optPut URL from eventTracker
[self.webView loadRequest:[NSURLRequest requestWithURL:[NSURL
URLWithString:self.nielsenApi.optOutURL]]];
}}

</syntaxhighlight>

=== Global iOS SDK No Ad Framework Opt-out ===
The ''User Choice'' method can be used without the Ad Framework, or in situations where the publisher does not wish to use the [https://developer.apple.com/documentation/apptrackingtransparency App Tracking Transparency Framework]. As this flavour of the Nielsen, SDK does not use the Ad Framework, so it is necessary to display an Optout Page to the user and capture their selection.

Similar to the Global iOS SDK Flavor, it is a requirement to display a WebView element whose loadUrl is set to the
value obtained from optOutURL. This special URL indicates Opt-in, or Opt-out and closes the WebView. '''The steps are as follows:'''

* Get the Nielsen opt-out URL via [[optOutURL]]
* Display a WebView element whose loadUrl is set to the value obtained from [[optOutURL]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and closes the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut]] function
** Example: <syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

==== Sample code for No Ad Framework Build ====
===== Swift =====
<syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

class OptOutVC: UIViewController, NielsenAppApiDelegate, WKNavigationDelegate {
var nielsenApi : NielsenAppApi!
var webView: WKWebView!

override func loadView() {
webView = WKWebView()
webView.navigationDelegate = self
view = webView
}

override func viewDidLoad() {
super.viewDidLoad()

if let appApi = self.nielsenApi {
//Getting the optPut URL from SDK
if let url = URL(string: appApi.optOutURL) {
webView.load(URLRequest(url: url))
webView.allowsBackForwardNavigationGestures = true
}}}

func closeOptOutView() {
self.dismiss(animated: true, completion: nil)
}

func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler:
@escaping (WKNavigationActionPolicy) -> Void) {
print(navigationAction.request.url?.absoluteString as Any) //For debugging to check what is being passed from webpage.
if navigationAction.request.url?.absoluteString == "nielsen://close" {
closeOptOutView()
decisionHandler(.cancel)
} else {
if let url = navigationAction.request.url?.absoluteString, url.hasPrefix("nielsen") {
nielsenApi?.userOptOut(url). //either nielsenappsdk://1 or nielsenappsdk://0
decisionHandler(.cancel)
} else {
if navigationAction.navigationType == .linkActivated {
if let url = navigationAction.request.url?.absoluteString, url.hasSuffix("#") {
decisionHandler(.allow)
} else {
decisionHandler(.cancel)
webView.load(navigationAction.request)
}
} else {
decisionHandler(.allow)
}}}}

}

</syntaxhighlight>

===== Objective-C =====
<syntaxhighlight lang="objective-c">

#import "OptOutVC.h"
#import "NielsenInit.h"
#import <NielsenAppApi/NielsenAppApi.h>

@interface OptOutVC ()

@property (weak, nonatomic) IBOutlet UIWebView *webView;
@end

@implementation OptOutVC

- (void)viewDidLoad {
[super viewDidLoad];

- (void)viewDidLoad {
[super viewDidLoad];
//Getting the optPut URL from eventTracker
[self.webView loadRequest:[NSURLRequest requestWithURL:[NSURL
URLWithString:self.nielsenApi.optOutURL]]];
}

- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction
decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler
{
if ([navigationAction.request.URL.absoluteString isEqualToString:kNielsenWebClose])
{ [self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
decisionHandler(WKNavigationActionPolicyCancel);
} else {
if ([navigationAction.request.URL.absoluteString hasPrefix:@"nielsen"])
{[self.nielsenAppApi userOptOut:navigationAction.request.URL.absoluteString];
decisionHandler(WKNavigationActionPolicyCancel);
} else {
if (navigationAction.navigationType == WKNavigationTypeLinkActivated)
{ if ([navigationAction.request.URL.absoluteString hasSuffix:@"#"])
{decisionHandler(WKNavigationActionPolicyAllow);
} else {
decisionHandler(WKNavigationActionPolicyCancel);
[webView loadRequest:[NSURLRequest requestWithURL:navigationAction.request.URL]];
}} else {
decisionHandler(WKNavigationActionPolicyAllow);
}}}
}

</syntaxhighlight>

=== Global iOS SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the [https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-iOS-App-SDK-GlobalNoId_latest.zip NoID version] of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt out selection:
<syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Retrieve current Opt-Out preference ==
Whether the user is opted out via OS-level Opt-out or via User Choice Opt-out, the current Opt-Out status as detected by the SDK is available via the [[optOutStatus]] property in the Nielsen SDK API
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus
</syntaxhighlight> 
 

=== First Party ID (FPID)===
- The broadcaster must enableFPID in the initialization settings which is set to <code>true</code> or <code>false</code> depending on user consent. This is to be set by the broadcaster when initializing our SDK. 

- The <code>enableFpid</code> flag is needed to enable/disable FPID usage for the AppID. The default value for this flag is true. If this flag is changed from true to false, then the AppSDK should wipe out the stored FPID and use a blank value for the FPID parameter in all the pings. 

- Generated FPID value is stored in the persistent memory until the application is uninstalled from a device or until FPID is wiped out or until it is expired. 

- The default value for this parameter is 180 days. Once this timeout is reached, the FPID should be regenerated. 

== Optional Step for AirPlay ==
To implement OTT measurement, report OTT changes to the SDK using the public API interface: [[updateOTT]]

In order to detect AirPlay and mirroring changes, we use AVAudioSessionPortDescription properties that are different on different iOS versions. We found that on iOS versions 8 - 10 <code>AVAudioSessionPortDescription</code> has the following values: 
<code>
AirPlay: type = AirPlay; name = Apple TV 4K; UID = DC:56:E7:53:72:85-airplay 
Mirroring: type = AirPlay; name = Apple TV 4K; UID = DC:56:E7:53:72:85-screen
</code> 

For iOS 11+ some parameters like name and UID have different values: 
<code>
AirPlay: type = AirPlay; name = AirPlay; UID = 0eb63aae-5915-45f1-b0f7-0102a0e50d53 
Mirroring: type = AirPlay; name = Apple TV 4K; UID = 4335E8A9-1C0A-4251-9000-28CA5FA2F3CF-192731714653291-screen 
</code>

The following code snipped is suggested for AirPlay/mirroring detection on iOS devices.

{{ExampleCode|
|Objective C =
<syntaxhighlight lang="objective-c">
– (void)updateOTT:(id)ottInfo;
</syntaxhighlight>
=== Subscribe to AVAudioSessionRouteChangeNotification ===
<syntaxhighlight lang="objective-c">
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handleRouteChanged:) name:AVAudioSessionRouteChangeNotification object:nil];
</syntaxhighlight>

=== Handle AVAudioSessionRouteChangeNotification and prepare OTT dictionary:===
<syntaxhighlight lang="objective-c">
- (void)handleRouteChanged:(NSNotification *)notification
{
NSMutableDictionary *ottDict = [NSMutableDictionary dictionaryWithDictionary: @{@"ottStatus": @"0"}];

AVAudioSession *audioSession = [AVAudioSession sharedInstance];
AVAudioSessionRouteDescription *currentRoute = audioSession.currentRoute;
for (AVAudioSessionPortDescription *outputPort in currentRoute.outputs) {
if ([outputPort.portType isEqualToString:AVAudioSessionPortAirPlay]) {
ottDict[@"ottStatus"] = @"1";
ottDict[@"ottDeviceModel"] = outputPort.portName;
ottDict[@"ottDeviceID"] = outputPort.UID;

if ([outputPort.portName isEqualToString:@"AirPlay"]) {
ottDict[@"ottDevice"] = @"airplay";
ottDict[@"ottType"] = @"airplay";
}
else {
if ([outputPort.portName containsString:@"Apple TV"]) {
ottDict[@"ottDevice"] = @"appleTV";
}
else {
ottDict[@"ottDevice"] = @"other";
}

if ([outputPort.UID hasSuffix:@"airplay"]) {
ottDict[@"ottType"] = @"airplay";
}
else if ([outputPort.UID hasSuffix:@"screen"]) {
ottDict[@"ottType"] = @"mirroring";
}
else {
ottDict[@"ottType"] = @"other";
}
}
}
}

// report OTT status update to Nielsen SDK
[self reportOTTWithDict:ottDict];
}
</syntaxhighlight>

=== Report OTT update to the Nielsen SDK ===
<syntaxhighlight lang="objective-c">
- (void)reportOTTWithDict:(NSDictionary *)ottDict
{
[self.nielsenSDK updateOTT:ottDict];
}
</syntaxhighlight>

|Swift =
<syntaxhighlight lang="swift">
nielsenSdk.updateOTT(currentStatus)
</syntaxhighlight>

=== Subscribe to AVAudioSessionRouteChangeNotification ===
<syntaxhighlight lang="swift">
NotificationCenter.default.addObserver(self, selector: #selector(handleRouteChanged(_:)), name: NSNotification.Name.AVAudioSessionRouteChange, object: nil)
</syntaxhighlight>

=== Handle AVAudioSessionRouteChangeNotification and prepare OTT dictionary:===

<syntaxhighlight lang ="Swift">
func handleRouteChanged(_ notification: Notification) {
var currentStatus: [String: String] = ["ottStatus": "0"]

let session = AVAudioSession.sharedInstance()
let currentRoute = session.currentRoute
for outputPort in currentRoute.outputs {
if outputPort.portType == AVAudioSessionPortAirPlay {
currentStatus["ottStatus"] = "1"
currentStatus["ottDeviceModel"] = outputPort.portName
currentStatus["ottDeviceID"] = outputPort.uid

if outputPort.portName == "AirPlay" {
currentStatus["ottDevice"] = "airplay"
currentStatus["ottType"] = "airplay"
}
else {
if outputPort.portName.contains("Apple TV") {
currentStatus["ottDevice"] = "appleTV"
}
else {
currentStatus["ottDevice"] = "other"
}

if outputPort.uid.hasSuffix("airplay") {
currentStatus["ottType"] = "airplay"
}
else if outputPort.uid.hasSuffix("screen") {
currentStatus["ottType"] = "mirroring"
}
else {
currentStatus["ottType"] = "other"
}
}
}
}

// report OTT status update to Nielsen SDK
self.reportOTTUpdate(currentStatus)
}
</syntaxhighlight>

=== Report OTT update to the Nielsen SDK===
<syntaxhighlight lang ="Swift">
func reportOTTUpdate(_ ottDict: [String: String]) {
if let nielsenSdk = self.nielsenAppApi {
nielsenSdk.updateOTT(currentStatus)
}
}
</syntaxhighlight>
}}

== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via the same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "imr" and confirm the presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910685&ch=se-910685_c01_P&asn=defChnAsset&fp_id=a2nfmy17lyvkhlxqstvmgypqly90m1629966210&fp_cr_tm=1629966210&fp_acc_tm=1629966210&fp_emm_tm=1629966210&ve_id=20A7CFD5-9860-4256-A6CE-45C251F4C243&sessionId=yvx0rtsxydmaxueji8zgfzj0f2f1w1629966209&tl=&prv=1&c6=vc,c01&ca=se-910685_c01_51HERB1501&cg=Play%20%3E%20Webbtv%20%3E%20Nyheter&c13=asid,P3D8D326A-2DBC-486A-8FD8-9AF4452B2A41&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,Aftonbladet&plugv=&playerv=&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_00000&c9=devid,12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8&enc=true&c1=nuid,12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8&at=timer&rt=video&c16=sdkv,ai.8.1.0&c27=cln,15&crs=&lat=&lon=&c29=plid,16299662096458868&c30=bldv,ai.8.1.0.0_gsxaoni&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,iOS14.6&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,5.47.83.0.25245&c51=adl,15&c52=noad,1&sd=15&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=51HERB1501&c3=st,a&c64=starttm,1629966240&adid=51HERB1501&c58=isLive,false&c59=sesid,iqal6k21r0de8gm901kif5xznar7q1629966240&c61=createtm,1629966255&c63=pipMode,&ci_userid=&is_auto_play=&pl_title=&is_prem=&is_prog=&ad_origin=&adidx=1%2F1&is_tpad=&ci_passthr=&c62=sendTime,1629966255&c68=bndlid,se.aftonbladet.Aftonbladet&c69=cvw,&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&uoo=&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,iPhone9%2C4~~devtypid,iPhone9%2C4~~sysname,iOS~~sysversion,14.6~~manuf,Apple&cat_id=a6f7fb13-8801-484c-9692-6db6dfb470aa&vtoff=0&rnd=1629966255319</nowiki></code>

== Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Going Live ==
Following Nielsen testing, you will need to:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_devDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

DCR Germany Video App SDK

2023-09-28T12:06:47Z

MichelFodjo: /* Special Notes regarding iOS17 or TVOS17 */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

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

== 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.
* <blockquote>'''No ID AppSDK''': <pre style="color: red">ONLY the No ID AppSDK should be downloaded for the AGF market!</pre>
</blockquote>

* '''Nielsen SDK:''' The Nielsen SDK package contains a variety of sample players for your reference.
Please contact our SDK sales support team if you do not have any of these prerequisites or have any questions.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

== Implementation ==
This guide covers implementation steps for iOS using Xcode and Android using Android Studio.

== Setting up your Development Environment ==

=== iOS ===

==== Special Notes regarding iOS17 or TVOS17 ====
Beginning with iOS/TVOS 17, Apple is adding several requirements for App developers around tracking, use of Identifier For Advertisers (IDFA), and certain system APIs.

Since AGF market is not making use of the IDFA, the change is expected to have no impact.

However, in order to minimize any eventual impact, we are asking that AGF clients do the following:

* '''Do not declare the Nielsen nmrodam.com domain in the privacy manifest'''
* Update to the latest Nielsen SDK release >= 9.2.0.0 when compiling your app for iOS 17

For any additional information please refer to the Nielsen global page: [[DCR and DTVR with iOS17 or TVOS17]].

==== General ====

<big>
'''Configuring Xcode Development Environment'''
</big>

Nielsen App SDK is compatible with Apple iOS versions 9.0 and above.

The SDK uses the NSURLSession instead of the deprecated NSURLConnection.

<blockquote>'''Note''': All communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

<big>'''Importing Frameworks'''</big>
The first step is to ensure that the following frameworks and libraries are imported into the Frameworks folder of the Xcode project before creating an instance of the Nielsen App SDK object.
* UIKit.framework
* Foundation.framework
* SystemConfiguration.framework
* Security.framework
** Nielsen Analytics framework uses several functions in this library.
* AVFoundation.framework
** This framework is mandatory for the iOS SDK version 5.1.1 to work.
* CoreLocation.framework
* CoreMedia.framework
* NielsenAppApi.framework
* libc++.tbd (as SDK contains Objective C++ source file)
** Alternatively, include -lstdc++ in Build Settings → Other Linker Flag of the Xcode project

<blockquote>'''Example'''
* Extract “NielsenAppApi.Framework” from the Nielsen App SDK sample app and copy it to the Frameworks folder of the Xcode project.
* Add the code <code>-#import NielsenAppApi/NielsenAppApi.h</code> to the View Controller’s header file.</blockquote>

Ensure that the following are included in the Linked Frameworks and Libraries list (located in the project’s Summary settings).
* Nielsen App SDK
* iOS security framework
 
<big>'''Using Swift'''</big>
To import a set of Objective-C files in the same app target as your Swift code, you rely on an Objective-C bridging header to expose those files to Swift. Xcode offers to create this header file when you add a Swift file to an existing Objective-C app or an Objective-C file to an existing Swift app.

Select File/New File/Objective-C File 
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] 
Once this file has been created, you need to add the following:
<syntaxhighlight lang="swift">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
<big>'''Using Objective-C'''</big>
Add the code
<syntaxhighlight lang ="objective-c">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
to the View Controller’s header file.
 

=== Android ===
==== General ====
<big>
'''Configuring Android Java Development Environment'''
</big>

*The Nielsen App SDK (located in the ''com.nielsen.app.sdk'' package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is the only public class belonging to the com.nielsen.app.sdk package.

'''Nielsen App SDK is compatible with Android OS versions 2.3+. Clients can control/configure the protocol to be used – HTTPS or HTTP to suit their needs.'''

The Nielsen App SDK 1.2 library is composed of two parts:
* The Java AppSdk.jar library runs on the Android’s Dalvik Virtual Machine.
* The C/C++ libAppSdk.so native library that runs directly on the device’s hardware.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote>

The requirement for the Java ''AppSdk.jar'' library and the ''libAppSdk.so'' native library will depend on the type of host application that will make use of them.
* '''For Video player applications'''
** The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 3.0 and later will support it natively).
** If the player application uses a 3rd party media player implementing its own HLS, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.
* '''For Audio player applications'''
** The Android OS hosting the App SDK should be at version 2.3 and later since the SDK depends on Google Play support to work properly.
Unzip the Nielsen App SDK sample app and copy the ''AppSdk.jar'' into the libs/ folder on the App’s Eclipse project. Copy the ''libAppSdk.so'' file under ''libs/armeabi/'' folder into the same Eclipse project.
* App SDK 1.2 provides support for x86, mips, and armeabi-7a architecture; the respective ''libAppSdk.so'' can be found under the ''libs/x86/'', ''libs/mips/'', and ''libs/armeabi-7a/'' folders.
Add the following permissions on the project’s ''AndroidManifest.xml'' file.
<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details on handling runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. Download the latest ''google-play-services_lib'' and include it in the App’s project in order to use the App SDK.
* App SDK checks to see if a Google service is available and updated.
* If unavailable or updated, App SDK will not use this service when executing its functions and will reference missing imports and the app will not be compiled.
To include the Google Play library in the media player project, copy the ''google-play-services_lib'' folder into the same location as the project
* Access '''File > Import'''.
* Select '''Existing Android Code into Workspace''' and click '''Next'''.
* Click '''Browse''' and navigate to the ''google-play-services_lib'' to include it into the projects.
* Select the exact '''Project Build Target''' for Eclipse to use from Android SDK.
** Android 4.4.2, etc. OR
** Edit ''project.properties'' file to point to Android target version e.g. target= android-19.
Once the google-play-services_lib is included into the App project, include the following code under the <code><application></code> node in the <code>AndroidManifest.xml</code>.

<syntaxhighlight lang="java"><meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/></syntaxhighlight>

Also, include the ''version.xml'' file that comes with the ''google-play-services_lib'' under the res/values directory of the media player project.
* Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface.

<big>'''Library'''</big>

Nielsen App SDK uses the following packages/classes from the Google Play service.
* google-play-services_lib

'''<big>Classes/package</big>'''
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

==== Add the dependency "lifecycle-extensions" to your project ====
Add the dependency "lifecycle-extensions" in the in the app gradle file as follows:
<syntaxhighlight lang="java">
implementation "androidx.lifecycle:lifecycle-extensions:2.1.0"
</syntaxhighlight>

This will enable the AppSdk to detect the application UI visibility state transitions between background and foreground by utilizing the LifeCycleObserver. This is i.e. required for the Static Measurement.

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-agf-v0.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-agf-ad-v0.png||SDK Integration Architecture Diagram - Ad]]

== SDK Initialization ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. The sharedInstance API that creates a singleton object was deprecated before version 5.1.1. (Version 4.0 for Android)

* A maximum of four SDK instances per appid are supported. When a fifth SDK instance is launched, the SDK will return “nil” from [[initWithAppInfo:delegate:]]
* When four SDK instances exist, you must destroy an old instance before creating a new one.

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || ✓ || "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || No || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || No || "1.0.2"
|-
| sfcode || Nielsen collection facility to which the SDK should connect.
'''AGF Clients'''
* "eu" (For Testing/Certification and in Production)
|| Nielsen-specified || ✓ || "eu"
|-
| nol_devDebug || Enables Nielsen console logging. Has to be set to "DEBUG" until certified
|| Nielsen-specified || Optional || "DEBUG"
|}
 

==== Sample SDK Initialization Code ====

===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"sfcode": "eu",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
 
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

====== Objective-C ======
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>If App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.</blockquote>
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
@"sfcode": "eu",
@"nol_devDebug": @"DEBUG"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

===== Android =====
====== Java ======

AppSDK is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="java">

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA")
.put("sfcode", "eu")
.put("nol_devDebug", "DEBUG");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
Here, <code>appContext</code> is the App context object and <code>appSdkConfig</code> is JSON object for holding the parameters (<code>appid</code>, <code>appname</code>, <code>sfcode</code>) the App passes to the Nielsen App SDK via a JSON string. The appid is obtained from Nielsen operational support and is unique to the app.

The integration of Nielsen App SDK will depend on the type of client app. 
* Ensure that SDK files (AppSdk.jar and libAppSdk.so [App SDK 1.2 Only]) are included under the App’s project and the App SDK is linked to the App (the setting to link App SDK to the App can be found on the property page of the App’s project).

== APP SDK Error & Event Codes ==
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.
== Configure Payload ==
=== Handling JSON Metadata ===
All the SDK methods handle only two types of objects: NSString, NSDictionary. The parameters passed must be either a JSON formatted string or a NSDictionary object. The JSON passed in the SDK must be well-formed.
* NSDictionary object
** If an object of the unexpected type is passed to the method, the error message will be logged.
** The error message will be logged if the string has an invalid JSON format.
* JSON value must be a string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, sfcode, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary.

=== Configure ChannelInfo metadata ===
==== Description of ChannelInfo metadata ====
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}
 

==== Example ChannelInfo metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelName","My Channel Name 1")
</syntaxhighlight>

=== Configure Content metadata ===

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

For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required/Obligatory
|-
| type || type of asset || <code>"content"</code> || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no [[Special Characters]]) || ✓
|-
| program ||(string) name of program (254 character limit) || custom || ✓
|-
| title ||(string) episode title (max 254 characters) || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| length || length of content in seconds || <code>seconds</code> ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| clientid ||
parent ID – value is automatically populated through provided App ID. 
In order to override the brand configured to the App ID, pass parent 
value here and the sub-brand ID associated with that brand in the subbrand 
key (e.g. multiple brands in App)
||
provided by Nielsen
||
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided 
App ID. In order to override the sub-brand configured to the App ID, value can 
be passed here (e.g. multiple sub-brands in App)
||
provided by Nielsen
||

|-
| nol_c0 || number of episode part (Sendungsteilenummer) || number || ✓
|-
| nol_c2 || web only || 'Y' or 'N' || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || duration in seconds || `seconds` ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c12 || type of asset || 'Trailer' or 'Content' || ✓
|-
| nol_c13 || original air time || `(YYYY-MM-TT)T(HH:mm:ss) Example: 2004-06-14T23:34:30 ||
|-
| nol_c14 || ISO 8601 timestamp || `(YYYY-MM-TT)T(HH:mm:ss)` ||
|-
| nol_c15 || format ID || custom ||
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c18 || livestream || 'Y' or 'N' || ✓
|-
| nol_c19 || custom variable || custom ||
|-
| nol_c20 || GfK-ID || custom ||
|}
 

==== Example Content metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
];
</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">
NSDictionary *contentMetadata = @
{@"type": @"content",
@"assetid": @"88675545",
@"length": @"3600",
@"program", "Program Name",
@"title": @"episode title",
@"nol_c0": "p0,1",
@"nol_c2": "p2,Y",
@"nol_c7": "p7,videoid123",
@"nol_c8": "p8,3600",
@"nol_c9": "p9,VideoTitle123",
@"nol_c10": "p10,clientname",
@"nol_c12": "p12,content",
@"nol_c18": "p18,N"
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">
JSONObject contentMetadata = new JSONObject()
.put("type", "content")
.put("assetid", "88675545")
.put("program", "Program Name")
.put("title", "episode title")
.put("length", "3600")
.put("nol_c0", "p0,1")
.put("nol_c2", "p2,Y")
.put("nol_c7", "p7,videoid123")
.put("nol_c8", "p8,3600")
.put("nol_c9", "p9,VideoTitle123")
.put("nol_c10", "p10,clientname")
.put("nol_c12", "p12,content")
.put("nol_c18", "p18,N")
</syntaxhighlight>

=== Configure Ad Metadata ===
==== Description of Ad metadata ====
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''
 
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no SPACE - no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters]) || ✓
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen ||
|-
| title || only the AD-ID is necessary || custom, <AD-ID> without "VAST" Prefix or other, i.e. '2352723141' || ✓
|-
| length || length of Ad in seconds || length of Ad in seconds || ✓
|-
| nol_c1 || universal AdID (Additional AD-ID to be used by second or third marketers) || custom, i.e. 'adgapid_022_800160_1601097_001_0_0' ||
|-
| nol_c2 || web only || 'Y' or 'N' ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || duration of the video file in seconds || || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c11 || AD-ID (unique ID of an advertisement. Necessary if ads are being broadcasted) || custom, i.e. '2352723141' || ✓
|-
| nol_c12 || content type (key distinction of content, advertising, and Trailer) || 'Werbung' || ✓
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c17 || ad placement type (placement information of advertisement) || 'preroll', 'midroll', 'postroll' or 'other' || ✓
|}

==== Example Ad metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let adMetadata = [
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Werbung",
"nol_c17": "p17,preroll"
];
</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">

NSDictionary *adMetadata = @
{@"type": @"preroll",
@"assetid": @"ad345-67483"",
@"title": @"ad_title",
@"length": @"25",
@"nol_c8": "p8,25",
@"nol_c10": "p10,clientname",
@"nol_c11": "p11,2352723141",
@"nol_c12": "p12,Werbung",
@"nol_c17": "p17,preroll"
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">

JSONObject adMetadata = new JSONObject()
.put("type", "preroll")
.put("assetid", "ad345-67483")
.put("title", "2352723141")
.put("length", "25")
.put("nol_c8", "p8,25")
.put("nol_c10", "p10,clientname")
.put("nol_c11", "p11,2352723141")
.put("nol_c12", "p12,Werbung")
.put("nol_c17", "p17,preroll")
</syntaxhighlight>
== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| 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.
|}

=== Life cycle of SDK instance ===
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# '''Processing state''' – The SDK instance processes playing information. [[play]] and [[loadMetadata]] calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[end]] – SDK instance exits from Processing state when this API is called.
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

'''Note''': In case of any interruptions during playback due to alarm, calendar, call, flight mode, Wi-Fi toggle, channel change, etc., call [[stop]] to pause the measurement.
* As soon as the playback resumes, call [[loadMetadata]] and [[playheadPosition]].</blockquote>

=== API Call sequence ===
==== Use Case 1: Content has no Advertisements ====
Call [[play()]] with channelName JSON as below.
'''[[#Example ChannelInfo metadata|Example ChannelInfo metadata]]'''
Call [[loadMetadata()]] with JSON metadata for content as below.
'''[[#Example Content metadata|Example Content metadata]]'''

Call [[setPlayheadPosition()]] every one second until the stream playback is interrupted or has ended.
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.
'''[[#Example ChannelInfo metadata|Example ChannelInfo metadata]]'''
<blockquote>Note: ONLY for a preroll Ad , Call [[loadMetadata()]] for Content before calling it for preroll ad </blockquote>

Call [[loadMetadata()]] with JSON metadata for ad as below.
'''[[#Example Ad metadata|Example Ad metadata]]'''
<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 the Ad playback is interrupted or has ended for each single Ad. 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 (Content resume) || <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.</blockquote>

=== Sequence of Calls ===

=== play ===
Use [[play]] to pass the channel descriptor information through channelName parameter after the SDK has been initialized and the content starts playing. If the user is returning from a '''Pause/Stop''' interaction, call [[loadMetadata]] with the same metadata and continue sending [[playheadPosition]] once the playback resumes.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c"> - (void)play:(id)channelInfo;</syntaxhighlight>
|Android = <syntaxhighlight lang="java"> public void play(JSONObject channelInfo);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenAppApi?.play(JSONObject channelInfo);</syntaxhighlight>
}}

=== loadMetadata ===
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">– (void)loadMetadata:(id)contentMetadata;</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void loadMetadata(JSONObject contentMetadata);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(contentMetadata)</syntaxhighlight>
}}

=== playheadPosition ===

"playheadPosition" has to be called every second.

* VOD :
** For Content and each single Ad, pass the current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3...
*Live :
**For Content, pass the Unix timestamp (seconds since Jan-1-1970 UTC). Pass whole number that increments only by 1 like 1631098029,1631098030,1631098031,1631098032,... .
**For each single Ad, pass the current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3...

{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">
– (void) playheadPosition: (long long) playheadPos
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
AVPlayer *player;
CMTime curTime=[player currentTime];
int pos = CMTimeGetSeconds(curTime);
[nAppApiObject playheadPosition:pos];
</syntaxhighlight>

|Swift = <syntaxhighlight lang="swift">
//Monitor the Playhead position of the AVPlayer
let timeInterval: CMTime = CMTimeMakeWithSeconds(1.0,10)
self.avPlayerViewController.player?.addPeriodicTimeObserver(forInterval: timeInterval, queue: DispatchQueue.main) {(elapsedTime: CMTime) -> Void in
if self.avPlayerViewController.player!.currentItem?.status == .readyToPlay {
let time : Float64 = self.avPlayerViewController.player!.currentTime().seconds;
let pos = Int64(time);
NSLog("New Elapse Time = \(time)");
self.nielsenAppApi?.playheadPosition(pos);
}
}
}
</syntaxhighlight>
|Android = <syntaxhighlight lang="java">
public void setPlayheadPosition(long position)
</syntaxhighlight>
}}

=== stop ===
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">– (void) stop</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void stop()</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.stop</syntaxhighlight>
}}

=== end ===
Call when the content asset completes playback. Stops measurement progress.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">- (void) end;</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void stop()</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.stop</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 and withhold sending playhead position.
* '''For video content:'''
** Call [[loadMetadata]] with the same metadata and continue sending [[playheadPosition]] once the playback resumes.
* '''For ads:'''
** just continue sending [[playheadPosition]] once the playback resumes (no [[loadMetadata]]).

Additional information:
* '''For type 'content': '''Sending a "loadMetadata" event after a "stop" event will be handled by the SDK as a "resume", as long as the "assetid" and "type" are the same and not changed from the values before the "stop" event happened. Changing "assetid" value will lead into a new stream. Changing of "type" from "content" to "preroll" ("midroll", "postroll") will lead into a new object (ad) with that content stream. Changing any other parameter (eg. "program" or "title") for the content will not affect the reported content data (will stay as in the very first "content" metadata)

=== App termination ===
If your app is executing a termination process and therefore ending the Content or Ad Playback, call [[end]] if the Content is playing or [[stop]] if an Ad is playing.

== Privacy and Opt-Out ==

The AppSDK measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen AppSDK measurement is utilizing a cookieless domain.
In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=de .

Please contact your Nielsen SDK support team directly for any related questions.

== Going Live ==
Following Nielsen testing, users need to make one update to the initialization call to ensure that the site is being measured properly.

# '''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:

'''<big>iOS Example:</big>'''

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"sfcode": "eu"
// Remove Flag: "nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

'''<big>Android Example:</big>'''
<syntaxhighlight lang="java">
try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("sfcode", "eu")
// Remove Flag: "nol_devDebug": "DEBUG"

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>

'''Note''': before going live, you have to inform the Nielsen team - this is necessary because the Nielsen team has to adjust internal configuration parameters to enable data collection. Without that notification, no data will be collected, and no data will be reported.

DCR Denmark Video iOS SDK

2023-09-28T12:06:03Z

MichelFodjo: /* Special Notes regarding iOS17 or TVOS17 */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

__TOC__

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

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || '''Nielsen SDK''' || Includes SDK frameworks and '''sample implementation'''; "See [[iOS SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Step 1: Setting up your iOS Development Environment ==

=== Special Notes regarding iOS17 or TVOS17 ===
Beginning with iOS/TVOS 17, Apple is adding several requirements for App developers around tracking, use of Identifier For Advertisers (IDFA), and certain system APIs.

This requirement entails users manually opting in to declare all domains employed for tracking purposes, which includes the collection of IDFAs (Identifier for Advertisers).
Currently, even if users choose not to opt in for tracking, it's essential to note that our Nielsen Digital SDKs continue to carry out measurements and transmit data without relying on IDFA. However, this new privacy measure introduced by Apple necessitates that we bring this development to your attention, as it could potentially impact your Nielsen measurement and tracking for iOS app usage.

In order to minimize the impact, we are asking that clients do the following:

* '''Do not declare the Nielsen imrworldwide.com domain in the privacy manifest.'''
* Update to the latest Nielsen SDK release >= 9.2.0.0 when compiling your app for iOS 17.

For any additional information please refer to the Nielsen global page: [[DCR and DTVR with iOS17 or TVOS17]].

=== Configuring Xcode Development Environment ===
Starting with SDK version 6.0.0.0, the Nielsen App SDK is compatible with Apple iOS versions 8.0 and above. In addition, the SDK uses the WKWebView class instead of the deprecated UIWebView as per Apple guidelines.

=== Importing Frameworks ===

1) Extract “NielsenAppApi.Framework” from the Nielsen App SDK zip file and copy it to Frameworks folder of the Xcode project. 

2) Import following frameworks and libraries into the Frameworks of the Xcode project before creating an instance of the Nielsen App SDK object.
* UIKit.framework
* Foundation.framework
* AdSupport.framework
* SystemConfiguration.framework
* Security.framework
** Nielsen Analytics framework makes use of a number of functions in this library.
* AVFoundation.framework
** This framework is mandatory for the iOS SDK version 5.1.1 to work.
* CoreLocation.framework
* CoreMedia.framework
* NielsenAppApi.framework
* libc++.tbd (as SDK contains Objective-C++ source file)
** Alternatively, include -lstdc++ in Build Settings → Other Linker Flag of the Xcode project 

3) Include header file <code>NielsenAppApi/NielsenAppApi.h</code> to the View Controller's header file. 

Note:
* The SDK uses the NSURLSession instead of the deprecated NSURLConnection.
* All communications between the SDK and the Census (Collection Facility) use HTTPS
 
==== Using Swift ====
To import a set of Objective-C files in the same app target as your Swift code, you rely on an Objective-C bridging header to expose those files to Swift. Xcode offers to create this header file when you add a Swift file to an existing Objective-C app, or an Objective-C file to an existing Swift app.

Select File/New File/Objective-C File 
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] 
Once this file has been created, you need to add the following:
<syntaxhighlight lang="swift">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>

==== Using Objective-C ====
Add the code
<syntaxhighlight lang ="objective-c">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
to the View Controller’s header file.
 

== Step 2: Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || ✓ || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || '''value is automatically populated through App Name included in the App Resource File''' || || "Nielsen Sample App"
|-
| appversion || Current version of the app used || '''value is automatically populated through App Version included in the App Resource File''' || || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || || "DEBUG"
|}
 

==== Sample SDK Initialization Code ====

Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>If App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.</blockquote>

===== Using Objective-C=====
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"nol_devDebug": @"DEBUG"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

===== Using Swift =====

<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
 
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# '''Processing state''' – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called

<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Step 3: Create Metadata Objects ==
The parameters passed must be either a JSON formatted NSString or a NSDictionary object. The JSON passed in the SDK must be well-formed.
* NSDictionary object
** If an object of unexpected type is passed to the method, the error message will be logged.
** If string has invalid JSON format, the error message will be logged.
* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

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

 
<blockquote> program and title metadata values should be passed to SDK as UTF-8 strings. </blockquote>

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || "content" for main content || ✓
|-
| assetid || unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| program || name of program || custom || ✓
|-
| title || episode name || custom || ✓
|-
| length || length of content in seconds || Length of content in seconds (86400 seconds for live stream (24/7). For Event-Live streams planned length. For VoD video length)|| ✓
|-
| airdate || the original date (local time with hh:mm:ss as 24h time stamp) content became available. This date does not change if the content is rebroadcasted on linear TV. || YYYYMMDD HH:MI:SS (if not known set it to eg. "19700101 00:00:00") || ✓
|-
| isfullepisode || full episode flag ||
* "y" full episode (full content for a program)
* "n" non full episode (only one part of the entire content for a program , i.e. preview, sub-episodes)
||
✓
|-
|adloadtype || type of Ad load
||
:
* "1" Linear - matches TV ad load
* "2" Dynamic - Dynamic Ad Insertion (DAI)
||
✓
|-style="background-color:#d0f6f8;"
|stationId || Unique Gracenote Station ID generated by Nielsen that uniquely identifies a live channel
||
provided by Nielsen
||
✓
|-style="background-color:#d0f6f8;"
|islivestn || Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-style="background-color:#d0f6f8;"
|pbstarttm || Playback Start Time (UTC): Unix timestamp in seconds matching the broadcast time for Content and Ad when a user starts and joins a live stream (seconds since Jan-1-1970 UTC)
||
i.e. "1631098029" for live stream and ""(empty string) for a VoD.
||
✓
|-
| subbrand || vcid/sub-brand/Channel ID – value is automatically populated through provided AppID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands/Channels in the App)
||
provided by Nielsen
||
✓
|}

=== Create Ad Metadata (optional for DR) ===
The Ad Metadata (if applicable) should be passed for each individual ad.

Note: All metadata values should be passed as UTF-8 strings.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> <code>"ad"</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to Ad || custom (no [[Special Characters]]) || ✓
|-style="background-color:#d0f6f8;"
|stationId || Unique Gracenote Station ID generated by Nielsen that uniquely identifies a live channel
||
provided by Nielsen
||
✓
|-style="background-color:#d0f6f8;"
|islivestn || Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-style="background-color:#d0f6f8;"
|pbstarttm || Playback Start Time (UTC): Unix timestamp in seconds matching the broadcast time for Content and Ad when a user starts and joins a live stream (seconds since Jan-1-1970 UTC)
||
i.e. "1631098029" for live stream and ""(empty string) for a VoD.
||
✓
|-
| subbrand || vcid/sub-brand/Channel ID – value is automatically populated through provided AppID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands/Channels in the App) || provided by Nielsen || ✓
|}

=== MetaData Example ===

==== Using Objective-C ====
<syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @
{
@"assetid" : "unique_content_id",
@"type" : "content",
@"program" : "program name",
@"title" : "episode title",
@"length" : "length in seconds",
@"airdate" : "20161013 20:00:00",
@"isfullepisode" : "y",
@"adloadtype" : "2",
@"subbrand" : "c05",
@"stationId" : "TESTXXYYSSWWLL",
@"islivestn" : "y",
@"pbstarttm" : "1631098029"
}

NSDictionary *adMetadata = @
{
@"assetid" : "unique_postroll_ad_id",
@"type" : "postroll",
@"subbrand" : "c05",
@"stationId" : "TESTXXYYSSWWLL",
@"islivestn" : "y",
@"pbstarttm" : "1631098029"
}
</syntaxhighlight>

==== Using Swift ====
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
]

let contentMetadata = [
"assetid" : "unique_content_id",
"type" : "content",
"program" : "program name",
"title" : "episode title",
"length" : "length in seconds",
"airdate" : "20200713 10:22:00",
"isfullepisode" : "y",
"adloadtype" : "2",
"subbrand" : "c05",
"stationId" : "TESTXXYYSSWWLL",
"islivestn" : "y",
"pbstarttm" : "1631098029"
]

let adMetadata = [
"assetid" : "unique_postroll_ad_id",
"type" : "postroll",
"subbrand" : "c05",
"stationId" : "TESTXXYYSSWWLL",
"islivestn" : "y",
"pbstarttm" : "1631098029"
]

</syntaxhighlight>

== Step 4: Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player. Call play only when initially starting the video.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi play:channelInfo];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.play(channelInfo);</syntaxhighlight>
 

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi loadMetadata:metadataDict];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(metadataDict)</syntaxhighlight>
 

==== playheadPosition ====
<pre style="background-color:#d0f6f8">
Note: "playheadPosition" has to be called every second and the value passed should match the broadcast time for live channel.
</pre>
* VOD: current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3... 
* Live: Unix timestamp matching the broadcast time for Content and Ad (seconds since Jan-1-1970 UTC). Pass whole number that increments only by 1 like 1631098029,1631098030,1631098031,1631098032,... 

===== Using Objective-C =====
<syntaxhighlight lang="objective-c">
[self.nielsenAppApi playheadPosition:pos];
</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">
self.nielsenAppApi?.playheadPosition(pos);
</syntaxhighlight>
 

==== sendID3 ====
Needs to be called when ID3 Tags are included in the Video Stream.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi sendID3:id3];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.sendID3(id3)</syntaxhighlight>
 
<blockquote>
ID3 Tags are parsed from the Video Stream, refer to the DK Reference Implementation [http://nielsenonlinesupport.com/dk/index.htm sdkRefImplDK] on how to parse ID3 Tags included in a sample HLS Stream.
For further technical details, please contact your Technical Account Manager (TAM).
</blockquote>

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi stop];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.stop;</syntaxhighlight>
 

==== end ====
Call when the content asset completes playback. Stops measurement progress.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi end];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.end</syntaxhighlight>
 

=== Start the Measurement ===
In order to start the measurement, follow the 3 first steps below i.e. for Content without Ads. When terminating the Content playback call <code>end</code> to terminate the Content Measurement for the given asset.

{| class="wikitable"
|-
! Playlist !! Sample code !! Description
|-
| rowspan="2" | 1. Start of stream || <code>play(channelName)</code> || channelName contains JSON metadata of channel/video name being played
|-
| <code>loadMetadata(contentMetadataObject)</code> || contentMetadataObject contains the JSON metadata for the content being played
|-
| 2. Content is playing|| <code>playheadPosition(position)</code> || playheadPosition is position of the playhead while the content is being played
|-
| || <code>sendID3(id3)</code> || id3 is an ID3 Tag parsed from the Video Stream, pass ID3 Tag immediately to SDK when found
|-
| 3. End of Stream || <code>end</code> || Content playback is completed.
|}

== Step 5: Stop/Resume the Measurement for video Playback Interruptions ==
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 <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Step 6: Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Step 7 : Disclose Nielsen Privacy Statement ==
The App SDK uses Mobile Ad IDs (Android ID or IDFA) which are fully hashed on the device before being sent to Nielsen (Nielsen never receives un-hashed values).
Users retain the possibility to oppose the use of Mobile Ad IDs, or to reset them, by using the functionality provided by the mobile operating system (iOS or Android).

In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=da .

== Step 8 : Review the Reference Implementation for VoD and Live Streams ==

The Reference Implementation covers VoD and Live use cases.
It also covers DAI (Dynamic Ad Insertion) with preroll Ad.

Download the Reference Implementation for iOS [https://nielsenonlinesupport.com/dk/ios/DKRefImplSwift.zip DKRefImplSwift].
Unzip and open the project in Xcode, then run it i.e. in the simulator or on iOS device and then filter the Xcode output with "##" in order to see only relevant Nielsen SDK API Calls, as below:
<syntaxhighlight
==##> Nielsen SDK NielsenInit.getAppApi() - create Instance
==##!!> LandingVC -- viewDidAppear
==##!!> LandingVC -- Nielsen SDK eventOccurred
==##> Nielsen SDK .play(sdkMethods.loadChannelInfo())
==##> Nielsen SDK nielsenApi.loadMetadata
==##> Nielsen SDK updatePlayheadPosition, pos = 0 / 378
==##> Nielsen SDK updatePlayheadPosition, pos = 1 / 378
==##> Nielsen SDK updatePlayheadPosition, pos = 2 / 378
==##> Nielsen SDK updatePlayheadPosition, pos = 3 / 378
==##> Nielsen SDK updatePlayheadPosition, pos = 4 / 378
==##> terminatePlaybackSession Nielsen SDK end()
==##!!> LandingVC -- viewDidAppear
</syntaxhighlight>

== Step 9 : Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "nmr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-dmk.nmrodam.com/cgi-bin/gn?prd=dcr&ci=us-500207&ch=us-500207_c77_P&asn=defChnAsset&fp_id=&fp_cr_tm=&fp_acc_tm=&fp_emm_tm=&ve_id=&devmodel=&manuf=&sysname=&sysversion=&sessionId=zlmmxkq867zt4bpnumlyz6dpn9hyp1610980356&tl=Episode%201&prv=1&c6=vc%2Cc77&ca=us-500207_c77_VID5556674-123456&cg=TAMSample%20DK&c13=asid%2CP10DF14BA-937E-436D-99DF-ED39A0422387&c32=segA%2CNA&c33=segB%2CNA&c34=segC%2CNA&c15=apn%2C&plugv=&playerv=&sup=1&segment2=&segment1=&forward=0&ad=0&cr=4_00_99_V1_00000&c9=devid%2C&enc=true&c1=nuid%2C999&at=view&rt=video&c16=sdkv%2Cbj.6.0.0&c27=cln%2C0&crs=&lat=&lon=&c29=plid%2C16109803568088038&c30=bldv%2C6.0.0.563&st=dcr&c7=osgrp%2C&c8=devgrp%2C&c10=plt%2C&c40=adbid%2C&c14=osver%2CNA&c26=dmap%2C1&dd=&hrd=&wkd=&c35=adrsid%2C&c36=cref1%2C&c37=cref2%2C&c11=agg%2C1&c12=apv%2C&c51=adl%2C0&c52=noad%2C0&sd=170&devtypid=&pc=NA&c53=fef%2Cy&c54=oad%2C20200713%2010%3A22%3A00&c55=cref3%2C&c57=adldf%2C2&ai=VID5556674-123456&c3=st%2Cc&c64=starttm%2C1610980392&adid=VID5556674-123456&c58=isLive%2Cfalse&c59=sesid%2Cgezrb92q4i9b9jg7acxgn783gjw0a1610980365&c61=createtm%2C1610980392&c63=pipMode%2C&c68=bndlid%2C&nodeTM=&logTM=&c73=phtype%2C&c74=dvcnm%2C&c76=adbsnid%2C&c77=adsuprt%2C2&uoo=&evdata=&c71=ottflg%2C0&c72=otttyp%2Cnone&c44=progen%2C&davty=0&si=http%3A%2F%2Fnielsenonlinesupport.com%2Fdk%2Findex.htm&c66=mediaurl%2Cassets%252FRTVOD_C3%252Fprog_index.m3u8&c62=sendTime%2C1610980392&rnd=714644</nowiki></code>

== Step 10 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Step 11 : Going Live ==
After the integration has been certified (but not prior that), disable debug logging by deleting {nol_devDebug: "DEBUG"} from initialization call - see Step 2.

DCR Denmark Video iOS SDK

2023-09-28T12:05:10Z

MichelFodjo:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

__TOC__

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

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || '''Nielsen SDK''' || Includes SDK frameworks and '''sample implementation'''; "See [[iOS SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Step 1: Setting up your iOS Development Environment ==

=== Special Notes regarding iOS17 or TVOS17 ===
Beginning with iOS/TVOS 17, Apple is adding several requirements for App developers around tracking, use of Identifier For Advertisers (IDFA), and certain system APIs.

This requirement entails users manually opting in to declare all domains employed for tracking purposes, which includes the collection of IDFAs (Identifier for Advertisers).
Currently, even if users choose not to opt in for tracking, it's essential to note that our Nielsen Digital SDKs continue to carry out measurements and transmit data without relying on IDFA. However, this new privacy measure introduced by Apple necessitates that we bring this development to your attention, as it could potentially impact your Nielsen measurement and tracking for iOS app usage.

In order to minimize the impact, we are asking that clients do the following:

* '''Do not declare the Nielsen imrworldwide.com domain in the privacy manifest.'''
* Update to the latest Nielsen SDK release >= 9,2.0.0 when compiling your app for iOS 17.

For any additional information please refer to the Nielsen global page: [[DCR and DTVR with iOS17 or TVOS17]].

=== Configuring Xcode Development Environment ===
Starting with SDK version 6.0.0.0, the Nielsen App SDK is compatible with Apple iOS versions 8.0 and above. In addition, the SDK uses the WKWebView class instead of the deprecated UIWebView as per Apple guidelines.

=== Importing Frameworks ===

1) Extract “NielsenAppApi.Framework” from the Nielsen App SDK zip file and copy it to Frameworks folder of the Xcode project. 

2) Import following frameworks and libraries into the Frameworks of the Xcode project before creating an instance of the Nielsen App SDK object.
* UIKit.framework
* Foundation.framework
* AdSupport.framework
* SystemConfiguration.framework
* Security.framework
** Nielsen Analytics framework makes use of a number of functions in this library.
* AVFoundation.framework
** This framework is mandatory for the iOS SDK version 5.1.1 to work.
* CoreLocation.framework
* CoreMedia.framework
* NielsenAppApi.framework
* libc++.tbd (as SDK contains Objective-C++ source file)
** Alternatively, include -lstdc++ in Build Settings → Other Linker Flag of the Xcode project 

3) Include header file <code>NielsenAppApi/NielsenAppApi.h</code> to the View Controller's header file. 

Note:
* The SDK uses the NSURLSession instead of the deprecated NSURLConnection.
* All communications between the SDK and the Census (Collection Facility) use HTTPS
 
==== Using Swift ====
To import a set of Objective-C files in the same app target as your Swift code, you rely on an Objective-C bridging header to expose those files to Swift. Xcode offers to create this header file when you add a Swift file to an existing Objective-C app, or an Objective-C file to an existing Swift app.

Select File/New File/Objective-C File 
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] 
Once this file has been created, you need to add the following:
<syntaxhighlight lang="swift">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>

==== Using Objective-C ====
Add the code
<syntaxhighlight lang ="objective-c">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
to the View Controller’s header file.
 

== Step 2: Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || ✓ || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || '''value is automatically populated through App Name included in the App Resource File''' || || "Nielsen Sample App"
|-
| appversion || Current version of the app used || '''value is automatically populated through App Version included in the App Resource File''' || || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || || "DEBUG"
|}
 

==== Sample SDK Initialization Code ====

Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>If App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.</blockquote>

===== Using Objective-C=====
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"nol_devDebug": @"DEBUG"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

===== Using Swift =====

<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
 
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# '''Processing state''' – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called

<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Step 3: Create Metadata Objects ==
The parameters passed must be either a JSON formatted NSString or a NSDictionary object. The JSON passed in the SDK must be well-formed.
* NSDictionary object
** If an object of unexpected type is passed to the method, the error message will be logged.
** If string has invalid JSON format, the error message will be logged.
* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

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

 
<blockquote> program and title metadata values should be passed to SDK as UTF-8 strings. </blockquote>

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || "content" for main content || ✓
|-
| assetid || unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| program || name of program || custom || ✓
|-
| title || episode name || custom || ✓
|-
| length || length of content in seconds || Length of content in seconds (86400 seconds for live stream (24/7). For Event-Live streams planned length. For VoD video length)|| ✓
|-
| airdate || the original date (local time with hh:mm:ss as 24h time stamp) content became available. This date does not change if the content is rebroadcasted on linear TV. || YYYYMMDD HH:MI:SS (if not known set it to eg. "19700101 00:00:00") || ✓
|-
| isfullepisode || full episode flag ||
* "y" full episode (full content for a program)
* "n" non full episode (only one part of the entire content for a program , i.e. preview, sub-episodes)
||
✓
|-
|adloadtype || type of Ad load
||
:
* "1" Linear - matches TV ad load
* "2" Dynamic - Dynamic Ad Insertion (DAI)
||
✓
|-style="background-color:#d0f6f8;"
|stationId || Unique Gracenote Station ID generated by Nielsen that uniquely identifies a live channel
||
provided by Nielsen
||
✓
|-style="background-color:#d0f6f8;"
|islivestn || Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-style="background-color:#d0f6f8;"
|pbstarttm || Playback Start Time (UTC): Unix timestamp in seconds matching the broadcast time for Content and Ad when a user starts and joins a live stream (seconds since Jan-1-1970 UTC)
||
i.e. "1631098029" for live stream and ""(empty string) for a VoD.
||
✓
|-
| subbrand || vcid/sub-brand/Channel ID – value is automatically populated through provided AppID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands/Channels in the App)
||
provided by Nielsen
||
✓
|}

=== Create Ad Metadata (optional for DR) ===
The Ad Metadata (if applicable) should be passed for each individual ad.

Note: All metadata values should be passed as UTF-8 strings.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> <code>"ad"</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to Ad || custom (no [[Special Characters]]) || ✓
|-style="background-color:#d0f6f8;"
|stationId || Unique Gracenote Station ID generated by Nielsen that uniquely identifies a live channel
||
provided by Nielsen
||
✓
|-style="background-color:#d0f6f8;"
|islivestn || Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-style="background-color:#d0f6f8;"
|pbstarttm || Playback Start Time (UTC): Unix timestamp in seconds matching the broadcast time for Content and Ad when a user starts and joins a live stream (seconds since Jan-1-1970 UTC)
||
i.e. "1631098029" for live stream and ""(empty string) for a VoD.
||
✓
|-
| subbrand || vcid/sub-brand/Channel ID – value is automatically populated through provided AppID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands/Channels in the App) || provided by Nielsen || ✓
|}

=== MetaData Example ===

==== Using Objective-C ====
<syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @
{
@"assetid" : "unique_content_id",
@"type" : "content",
@"program" : "program name",
@"title" : "episode title",
@"length" : "length in seconds",
@"airdate" : "20161013 20:00:00",
@"isfullepisode" : "y",
@"adloadtype" : "2",
@"subbrand" : "c05",
@"stationId" : "TESTXXYYSSWWLL",
@"islivestn" : "y",
@"pbstarttm" : "1631098029"
}

NSDictionary *adMetadata = @
{
@"assetid" : "unique_postroll_ad_id",
@"type" : "postroll",
@"subbrand" : "c05",
@"stationId" : "TESTXXYYSSWWLL",
@"islivestn" : "y",
@"pbstarttm" : "1631098029"
}
</syntaxhighlight>

==== Using Swift ====
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
]

let contentMetadata = [
"assetid" : "unique_content_id",
"type" : "content",
"program" : "program name",
"title" : "episode title",
"length" : "length in seconds",
"airdate" : "20200713 10:22:00",
"isfullepisode" : "y",
"adloadtype" : "2",
"subbrand" : "c05",
"stationId" : "TESTXXYYSSWWLL",
"islivestn" : "y",
"pbstarttm" : "1631098029"
]

let adMetadata = [
"assetid" : "unique_postroll_ad_id",
"type" : "postroll",
"subbrand" : "c05",
"stationId" : "TESTXXYYSSWWLL",
"islivestn" : "y",
"pbstarttm" : "1631098029"
]

</syntaxhighlight>

== Step 4: Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player. Call play only when initially starting the video.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi play:channelInfo];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.play(channelInfo);</syntaxhighlight>
 

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi loadMetadata:metadataDict];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(metadataDict)</syntaxhighlight>
 

==== playheadPosition ====
<pre style="background-color:#d0f6f8">
Note: "playheadPosition" has to be called every second and the value passed should match the broadcast time for live channel.
</pre>
* VOD: current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3... 
* Live: Unix timestamp matching the broadcast time for Content and Ad (seconds since Jan-1-1970 UTC). Pass whole number that increments only by 1 like 1631098029,1631098030,1631098031,1631098032,... 

===== Using Objective-C =====
<syntaxhighlight lang="objective-c">
[self.nielsenAppApi playheadPosition:pos];
</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">
self.nielsenAppApi?.playheadPosition(pos);
</syntaxhighlight>
 

==== sendID3 ====
Needs to be called when ID3 Tags are included in the Video Stream.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi sendID3:id3];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.sendID3(id3)</syntaxhighlight>
 
<blockquote>
ID3 Tags are parsed from the Video Stream, refer to the DK Reference Implementation [http://nielsenonlinesupport.com/dk/index.htm sdkRefImplDK] on how to parse ID3 Tags included in a sample HLS Stream.
For further technical details, please contact your Technical Account Manager (TAM).
</blockquote>

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi stop];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.stop;</syntaxhighlight>
 

==== end ====
Call when the content asset completes playback. Stops measurement progress.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi end];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.end</syntaxhighlight>
 

=== Start the Measurement ===
In order to start the measurement, follow the 3 first steps below i.e. for Content without Ads. When terminating the Content playback call <code>end</code> to terminate the Content Measurement for the given asset.

{| class="wikitable"
|-
! Playlist !! Sample code !! Description
|-
| rowspan="2" | 1. Start of stream || <code>play(channelName)</code> || channelName contains JSON metadata of channel/video name being played
|-
| <code>loadMetadata(contentMetadataObject)</code> || contentMetadataObject contains the JSON metadata for the content being played
|-
| 2. Content is playing|| <code>playheadPosition(position)</code> || playheadPosition is position of the playhead while the content is being played
|-
| || <code>sendID3(id3)</code> || id3 is an ID3 Tag parsed from the Video Stream, pass ID3 Tag immediately to SDK when found
|-
| 3. End of Stream || <code>end</code> || Content playback is completed.
|}

== Step 5: Stop/Resume the Measurement for video Playback Interruptions ==
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 <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Step 6: Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Step 7 : Disclose Nielsen Privacy Statement ==
The App SDK uses Mobile Ad IDs (Android ID or IDFA) which are fully hashed on the device before being sent to Nielsen (Nielsen never receives un-hashed values).
Users retain the possibility to oppose the use of Mobile Ad IDs, or to reset them, by using the functionality provided by the mobile operating system (iOS or Android).

In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=da .

== Step 8 : Review the Reference Implementation for VoD and Live Streams ==

The Reference Implementation covers VoD and Live use cases.
It also covers DAI (Dynamic Ad Insertion) with preroll Ad.

Download the Reference Implementation for iOS [https://nielsenonlinesupport.com/dk/ios/DKRefImplSwift.zip DKRefImplSwift].
Unzip and open the project in Xcode, then run it i.e. in the simulator or on iOS device and then filter the Xcode output with "##" in order to see only relevant Nielsen SDK API Calls, as below:
<syntaxhighlight
==##> Nielsen SDK NielsenInit.getAppApi() - create Instance
==##!!> LandingVC -- viewDidAppear
==##!!> LandingVC -- Nielsen SDK eventOccurred
==##> Nielsen SDK .play(sdkMethods.loadChannelInfo())
==##> Nielsen SDK nielsenApi.loadMetadata
==##> Nielsen SDK updatePlayheadPosition, pos = 0 / 378
==##> Nielsen SDK updatePlayheadPosition, pos = 1 / 378
==##> Nielsen SDK updatePlayheadPosition, pos = 2 / 378
==##> Nielsen SDK updatePlayheadPosition, pos = 3 / 378
==##> Nielsen SDK updatePlayheadPosition, pos = 4 / 378
==##> terminatePlaybackSession Nielsen SDK end()
==##!!> LandingVC -- viewDidAppear
</syntaxhighlight>

== Step 9 : Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "nmr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-dmk.nmrodam.com/cgi-bin/gn?prd=dcr&ci=us-500207&ch=us-500207_c77_P&asn=defChnAsset&fp_id=&fp_cr_tm=&fp_acc_tm=&fp_emm_tm=&ve_id=&devmodel=&manuf=&sysname=&sysversion=&sessionId=zlmmxkq867zt4bpnumlyz6dpn9hyp1610980356&tl=Episode%201&prv=1&c6=vc%2Cc77&ca=us-500207_c77_VID5556674-123456&cg=TAMSample%20DK&c13=asid%2CP10DF14BA-937E-436D-99DF-ED39A0422387&c32=segA%2CNA&c33=segB%2CNA&c34=segC%2CNA&c15=apn%2C&plugv=&playerv=&sup=1&segment2=&segment1=&forward=0&ad=0&cr=4_00_99_V1_00000&c9=devid%2C&enc=true&c1=nuid%2C999&at=view&rt=video&c16=sdkv%2Cbj.6.0.0&c27=cln%2C0&crs=&lat=&lon=&c29=plid%2C16109803568088038&c30=bldv%2C6.0.0.563&st=dcr&c7=osgrp%2C&c8=devgrp%2C&c10=plt%2C&c40=adbid%2C&c14=osver%2CNA&c26=dmap%2C1&dd=&hrd=&wkd=&c35=adrsid%2C&c36=cref1%2C&c37=cref2%2C&c11=agg%2C1&c12=apv%2C&c51=adl%2C0&c52=noad%2C0&sd=170&devtypid=&pc=NA&c53=fef%2Cy&c54=oad%2C20200713%2010%3A22%3A00&c55=cref3%2C&c57=adldf%2C2&ai=VID5556674-123456&c3=st%2Cc&c64=starttm%2C1610980392&adid=VID5556674-123456&c58=isLive%2Cfalse&c59=sesid%2Cgezrb92q4i9b9jg7acxgn783gjw0a1610980365&c61=createtm%2C1610980392&c63=pipMode%2C&c68=bndlid%2C&nodeTM=&logTM=&c73=phtype%2C&c74=dvcnm%2C&c76=adbsnid%2C&c77=adsuprt%2C2&uoo=&evdata=&c71=ottflg%2C0&c72=otttyp%2Cnone&c44=progen%2C&davty=0&si=http%3A%2F%2Fnielsenonlinesupport.com%2Fdk%2Findex.htm&c66=mediaurl%2Cassets%252FRTVOD_C3%252Fprog_index.m3u8&c62=sendTime%2C1610980392&rnd=714644</nowiki></code>

== Step 10 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Step 11 : Going Live ==
After the integration has been certified (but not prior that), disable debug logging by deleting {nol_devDebug: "DEBUG"} from initialization call - see Step 2.

DCR Germany Video App SDK

2023-09-28T11:43:49Z

MichelFodjo:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

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

== 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.
* <blockquote>'''No ID AppSDK''': <pre style="color: red">ONLY the No ID AppSDK should be downloaded for the AGF market!</pre>
</blockquote>

* '''Nielsen SDK:''' The Nielsen SDK package contains a variety of sample players for your reference.
Please contact our SDK sales support team if you do not have any of these prerequisites or have any questions.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

== Implementation ==
This guide covers implementation steps for iOS using Xcode and Android using Android Studio.

== Setting up your Development Environment ==

=== iOS ===

==== Special Notes regarding iOS17 or TVOS17 ====
Beginning with iOS/TVOS 17, Apple is adding several requirements for App developers around tracking, use of Identifier For Advertisers (IDFA), and certain system APIs.

Since AGF market is not making use of the IDFA, the change is expected to have no impact.

However, in order to minimize any eventual impact, we are asking that AGF clients do the following:

* '''Do not declare the Nielsen nmrodam.com domain in the privacy manifest'''
* Update to the latest Nielsen SDK release >= 9,2.0.0 when compiling your app for iOS 17

For any additional information please refer to the Nielsen global page: [[DCR and DTVR with iOS17 or TVOS17]].

==== General ====

<big>
'''Configuring Xcode Development Environment'''
</big>

Nielsen App SDK is compatible with Apple iOS versions 9.0 and above.

The SDK uses the NSURLSession instead of the deprecated NSURLConnection.

<blockquote>'''Note''': All communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

<big>'''Importing Frameworks'''</big>
The first step is to ensure that the following frameworks and libraries are imported into the Frameworks folder of the Xcode project before creating an instance of the Nielsen App SDK object.
* UIKit.framework
* Foundation.framework
* SystemConfiguration.framework
* Security.framework
** Nielsen Analytics framework uses several functions in this library.
* AVFoundation.framework
** This framework is mandatory for the iOS SDK version 5.1.1 to work.
* CoreLocation.framework
* CoreMedia.framework
* NielsenAppApi.framework
* libc++.tbd (as SDK contains Objective C++ source file)
** Alternatively, include -lstdc++ in Build Settings → Other Linker Flag of the Xcode project

<blockquote>'''Example'''
* Extract “NielsenAppApi.Framework” from the Nielsen App SDK sample app and copy it to the Frameworks folder of the Xcode project.
* Add the code <code>-#import NielsenAppApi/NielsenAppApi.h</code> to the View Controller’s header file.</blockquote>

Ensure that the following are included in the Linked Frameworks and Libraries list (located in the project’s Summary settings).
* Nielsen App SDK
* iOS security framework
 
<big>'''Using Swift'''</big>
To import a set of Objective-C files in the same app target as your Swift code, you rely on an Objective-C bridging header to expose those files to Swift. Xcode offers to create this header file when you add a Swift file to an existing Objective-C app or an Objective-C file to an existing Swift app.

Select File/New File/Objective-C File 
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] 
Once this file has been created, you need to add the following:
<syntaxhighlight lang="swift">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
<big>'''Using Objective-C'''</big>
Add the code
<syntaxhighlight lang ="objective-c">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
to the View Controller’s header file.
 

=== Android ===
==== General ====
<big>
'''Configuring Android Java Development Environment'''
</big>

*The Nielsen App SDK (located in the ''com.nielsen.app.sdk'' package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is the only public class belonging to the com.nielsen.app.sdk package.

'''Nielsen App SDK is compatible with Android OS versions 2.3+. Clients can control/configure the protocol to be used – HTTPS or HTTP to suit their needs.'''

The Nielsen App SDK 1.2 library is composed of two parts:
* The Java AppSdk.jar library runs on the Android’s Dalvik Virtual Machine.
* The C/C++ libAppSdk.so native library that runs directly on the device’s hardware.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote>

The requirement for the Java ''AppSdk.jar'' library and the ''libAppSdk.so'' native library will depend on the type of host application that will make use of them.
* '''For Video player applications'''
** The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 3.0 and later will support it natively).
** If the player application uses a 3rd party media player implementing its own HLS, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.
* '''For Audio player applications'''
** The Android OS hosting the App SDK should be at version 2.3 and later since the SDK depends on Google Play support to work properly.
Unzip the Nielsen App SDK sample app and copy the ''AppSdk.jar'' into the libs/ folder on the App’s Eclipse project. Copy the ''libAppSdk.so'' file under ''libs/armeabi/'' folder into the same Eclipse project.
* App SDK 1.2 provides support for x86, mips, and armeabi-7a architecture; the respective ''libAppSdk.so'' can be found under the ''libs/x86/'', ''libs/mips/'', and ''libs/armeabi-7a/'' folders.
Add the following permissions on the project’s ''AndroidManifest.xml'' file.
<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details on handling runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. Download the latest ''google-play-services_lib'' and include it in the App’s project in order to use the App SDK.
* App SDK checks to see if a Google service is available and updated.
* If unavailable or updated, App SDK will not use this service when executing its functions and will reference missing imports and the app will not be compiled.
To include the Google Play library in the media player project, copy the ''google-play-services_lib'' folder into the same location as the project
* Access '''File > Import'''.
* Select '''Existing Android Code into Workspace''' and click '''Next'''.
* Click '''Browse''' and navigate to the ''google-play-services_lib'' to include it into the projects.
* Select the exact '''Project Build Target''' for Eclipse to use from Android SDK.
** Android 4.4.2, etc. OR
** Edit ''project.properties'' file to point to Android target version e.g. target= android-19.
Once the google-play-services_lib is included into the App project, include the following code under the <code><application></code> node in the <code>AndroidManifest.xml</code>.

<syntaxhighlight lang="java"><meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/></syntaxhighlight>

Also, include the ''version.xml'' file that comes with the ''google-play-services_lib'' under the res/values directory of the media player project.
* Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface.

<big>'''Library'''</big>

Nielsen App SDK uses the following packages/classes from the Google Play service.
* google-play-services_lib

'''<big>Classes/package</big>'''
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

==== Add the dependency "lifecycle-extensions" to your project ====
Add the dependency "lifecycle-extensions" in the in the app gradle file as follows:
<syntaxhighlight lang="java">
implementation "androidx.lifecycle:lifecycle-extensions:2.1.0"
</syntaxhighlight>

This will enable the AppSdk to detect the application UI visibility state transitions between background and foreground by utilizing the LifeCycleObserver. This is i.e. required for the Static Measurement.

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-agf-v0.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-agf-ad-v0.png||SDK Integration Architecture Diagram - Ad]]

== SDK Initialization ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. The sharedInstance API that creates a singleton object was deprecated before version 5.1.1. (Version 4.0 for Android)

* A maximum of four SDK instances per appid are supported. When a fifth SDK instance is launched, the SDK will return “nil” from [[initWithAppInfo:delegate:]]
* When four SDK instances exist, you must destroy an old instance before creating a new one.

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || ✓ || "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || No || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || No || "1.0.2"
|-
| sfcode || Nielsen collection facility to which the SDK should connect.
'''AGF Clients'''
* "eu" (For Testing/Certification and in Production)
|| Nielsen-specified || ✓ || "eu"
|-
| nol_devDebug || Enables Nielsen console logging. Has to be set to "DEBUG" until certified
|| Nielsen-specified || Optional || "DEBUG"
|}
 

==== Sample SDK Initialization Code ====

===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"sfcode": "eu",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
 
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

====== Objective-C ======
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>If App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.</blockquote>
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
@"sfcode": "eu",
@"nol_devDebug": @"DEBUG"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

===== Android =====
====== Java ======

AppSDK is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="java">

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA")
.put("sfcode", "eu")
.put("nol_devDebug", "DEBUG");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
Here, <code>appContext</code> is the App context object and <code>appSdkConfig</code> is JSON object for holding the parameters (<code>appid</code>, <code>appname</code>, <code>sfcode</code>) the App passes to the Nielsen App SDK via a JSON string. The appid is obtained from Nielsen operational support and is unique to the app.

The integration of Nielsen App SDK will depend on the type of client app. 
* Ensure that SDK files (AppSdk.jar and libAppSdk.so [App SDK 1.2 Only]) are included under the App’s project and the App SDK is linked to the App (the setting to link App SDK to the App can be found on the property page of the App’s project).

== APP SDK Error & Event Codes ==
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.
== Configure Payload ==
=== Handling JSON Metadata ===
All the SDK methods handle only two types of objects: NSString, NSDictionary. The parameters passed must be either a JSON formatted string or a NSDictionary object. The JSON passed in the SDK must be well-formed.
* NSDictionary object
** If an object of the unexpected type is passed to the method, the error message will be logged.
** The error message will be logged if the string has an invalid JSON format.
* JSON value must be a string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, sfcode, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary.

=== Configure ChannelInfo metadata ===
==== Description of ChannelInfo metadata ====
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}
 

==== Example ChannelInfo metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelName","My Channel Name 1")
</syntaxhighlight>

=== Configure Content metadata ===

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

For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required/Obligatory
|-
| type || type of asset || <code>"content"</code> || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no [[Special Characters]]) || ✓
|-
| program ||(string) name of program (254 character limit) || custom || ✓
|-
| title ||(string) episode title (max 254 characters) || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| length || length of content in seconds || <code>seconds</code> ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| clientid ||
parent ID – value is automatically populated through provided App ID. 
In order to override the brand configured to the App ID, pass parent 
value here and the sub-brand ID associated with that brand in the subbrand 
key (e.g. multiple brands in App)
||
provided by Nielsen
||
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided 
App ID. In order to override the sub-brand configured to the App ID, value can 
be passed here (e.g. multiple sub-brands in App)
||
provided by Nielsen
||

|-
| nol_c0 || number of episode part (Sendungsteilenummer) || number || ✓
|-
| nol_c2 || web only || 'Y' or 'N' || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || duration in seconds || `seconds` ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c12 || type of asset || 'Trailer' or 'Content' || ✓
|-
| nol_c13 || original air time || `(YYYY-MM-TT)T(HH:mm:ss) Example: 2004-06-14T23:34:30 ||
|-
| nol_c14 || ISO 8601 timestamp || `(YYYY-MM-TT)T(HH:mm:ss)` ||
|-
| nol_c15 || format ID || custom ||
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c18 || livestream || 'Y' or 'N' || ✓
|-
| nol_c19 || custom variable || custom ||
|-
| nol_c20 || GfK-ID || custom ||
|}
 

==== Example Content metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
];
</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">
NSDictionary *contentMetadata = @
{@"type": @"content",
@"assetid": @"88675545",
@"length": @"3600",
@"program", "Program Name",
@"title": @"episode title",
@"nol_c0": "p0,1",
@"nol_c2": "p2,Y",
@"nol_c7": "p7,videoid123",
@"nol_c8": "p8,3600",
@"nol_c9": "p9,VideoTitle123",
@"nol_c10": "p10,clientname",
@"nol_c12": "p12,content",
@"nol_c18": "p18,N"
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">
JSONObject contentMetadata = new JSONObject()
.put("type", "content")
.put("assetid", "88675545")
.put("program", "Program Name")
.put("title", "episode title")
.put("length", "3600")
.put("nol_c0", "p0,1")
.put("nol_c2", "p2,Y")
.put("nol_c7", "p7,videoid123")
.put("nol_c8", "p8,3600")
.put("nol_c9", "p9,VideoTitle123")
.put("nol_c10", "p10,clientname")
.put("nol_c12", "p12,content")
.put("nol_c18", "p18,N")
</syntaxhighlight>

=== Configure Ad Metadata ===
==== Description of Ad metadata ====
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''
 
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no SPACE - no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters]) || ✓
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen ||
|-
| title || only the AD-ID is necessary || custom, <AD-ID> without "VAST" Prefix or other, i.e. '2352723141' || ✓
|-
| length || length of Ad in seconds || length of Ad in seconds || ✓
|-
| nol_c1 || universal AdID (Additional AD-ID to be used by second or third marketers) || custom, i.e. 'adgapid_022_800160_1601097_001_0_0' ||
|-
| nol_c2 || web only || 'Y' or 'N' ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || duration of the video file in seconds || || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c11 || AD-ID (unique ID of an advertisement. Necessary if ads are being broadcasted) || custom, i.e. '2352723141' || ✓
|-
| nol_c12 || content type (key distinction of content, advertising, and Trailer) || 'Werbung' || ✓
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c17 || ad placement type (placement information of advertisement) || 'preroll', 'midroll', 'postroll' or 'other' || ✓
|}

==== Example Ad metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let adMetadata = [
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Werbung",
"nol_c17": "p17,preroll"
];
</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">

NSDictionary *adMetadata = @
{@"type": @"preroll",
@"assetid": @"ad345-67483"",
@"title": @"ad_title",
@"length": @"25",
@"nol_c8": "p8,25",
@"nol_c10": "p10,clientname",
@"nol_c11": "p11,2352723141",
@"nol_c12": "p12,Werbung",
@"nol_c17": "p17,preroll"
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">

JSONObject adMetadata = new JSONObject()
.put("type", "preroll")
.put("assetid", "ad345-67483")
.put("title", "2352723141")
.put("length", "25")
.put("nol_c8", "p8,25")
.put("nol_c10", "p10,clientname")
.put("nol_c11", "p11,2352723141")
.put("nol_c12", "p12,Werbung")
.put("nol_c17", "p17,preroll")
</syntaxhighlight>
== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| 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.
|}

=== Life cycle of SDK instance ===
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# '''Processing state''' – The SDK instance processes playing information. [[play]] and [[loadMetadata]] calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[end]] – SDK instance exits from Processing state when this API is called.
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

'''Note''': In case of any interruptions during playback due to alarm, calendar, call, flight mode, Wi-Fi toggle, channel change, etc., call [[stop]] to pause the measurement.
* As soon as the playback resumes, call [[loadMetadata]] and [[playheadPosition]].</blockquote>

=== API Call sequence ===
==== Use Case 1: Content has no Advertisements ====
Call [[play()]] with channelName JSON as below.
'''[[#Example ChannelInfo metadata|Example ChannelInfo metadata]]'''
Call [[loadMetadata()]] with JSON metadata for content as below.
'''[[#Example Content metadata|Example Content metadata]]'''

Call [[setPlayheadPosition()]] every one second until the stream playback is interrupted or has ended.
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.
'''[[#Example ChannelInfo metadata|Example ChannelInfo metadata]]'''
<blockquote>Note: ONLY for a preroll Ad , Call [[loadMetadata()]] for Content before calling it for preroll ad </blockquote>

Call [[loadMetadata()]] with JSON metadata for ad as below.
'''[[#Example Ad metadata|Example Ad metadata]]'''
<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 the Ad playback is interrupted or has ended for each single Ad. 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 (Content resume) || <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.</blockquote>

=== Sequence of Calls ===

=== play ===
Use [[play]] to pass the channel descriptor information through channelName parameter after the SDK has been initialized and the content starts playing. If the user is returning from a '''Pause/Stop''' interaction, call [[loadMetadata]] with the same metadata and continue sending [[playheadPosition]] once the playback resumes.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c"> - (void)play:(id)channelInfo;</syntaxhighlight>
|Android = <syntaxhighlight lang="java"> public void play(JSONObject channelInfo);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenAppApi?.play(JSONObject channelInfo);</syntaxhighlight>
}}

=== loadMetadata ===
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">– (void)loadMetadata:(id)contentMetadata;</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void loadMetadata(JSONObject contentMetadata);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(contentMetadata)</syntaxhighlight>
}}

=== playheadPosition ===

"playheadPosition" has to be called every second.

* VOD :
** For Content and each single Ad, pass the current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3...
*Live :
**For Content, pass the Unix timestamp (seconds since Jan-1-1970 UTC). Pass whole number that increments only by 1 like 1631098029,1631098030,1631098031,1631098032,... .
**For each single Ad, pass the current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3...

{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">
– (void) playheadPosition: (long long) playheadPos
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
AVPlayer *player;
CMTime curTime=[player currentTime];
int pos = CMTimeGetSeconds(curTime);
[nAppApiObject playheadPosition:pos];
</syntaxhighlight>

|Swift = <syntaxhighlight lang="swift">
//Monitor the Playhead position of the AVPlayer
let timeInterval: CMTime = CMTimeMakeWithSeconds(1.0,10)
self.avPlayerViewController.player?.addPeriodicTimeObserver(forInterval: timeInterval, queue: DispatchQueue.main) {(elapsedTime: CMTime) -> Void in
if self.avPlayerViewController.player!.currentItem?.status == .readyToPlay {
let time : Float64 = self.avPlayerViewController.player!.currentTime().seconds;
let pos = Int64(time);
NSLog("New Elapse Time = \(time)");
self.nielsenAppApi?.playheadPosition(pos);
}
}
}
</syntaxhighlight>
|Android = <syntaxhighlight lang="java">
public void setPlayheadPosition(long position)
</syntaxhighlight>
}}

=== stop ===
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">– (void) stop</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void stop()</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.stop</syntaxhighlight>
}}

=== end ===
Call when the content asset completes playback. Stops measurement progress.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">- (void) end;</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void stop()</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.stop</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 and withhold sending playhead position.
* '''For video content:'''
** Call [[loadMetadata]] with the same metadata and continue sending [[playheadPosition]] once the playback resumes.
* '''For ads:'''
** just continue sending [[playheadPosition]] once the playback resumes (no [[loadMetadata]]).

Additional information:
* '''For type 'content': '''Sending a "loadMetadata" event after a "stop" event will be handled by the SDK as a "resume", as long as the "assetid" and "type" are the same and not changed from the values before the "stop" event happened. Changing "assetid" value will lead into a new stream. Changing of "type" from "content" to "preroll" ("midroll", "postroll") will lead into a new object (ad) with that content stream. Changing any other parameter (eg. "program" or "title") for the content will not affect the reported content data (will stay as in the very first "content" metadata)

=== App termination ===
If your app is executing a termination process and therefore ending the Content or Ad Playback, call [[end]] if the Content is playing or [[stop]] if an Ad is playing.

== Privacy and Opt-Out ==

The AppSDK measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen AppSDK measurement is utilizing a cookieless domain.
In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=de .

Please contact your Nielsen SDK support team directly for any related questions.

== Going Live ==
Following Nielsen testing, users need to make one update to the initialization call to ensure that the site is being measured properly.

# '''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:

'''<big>iOS Example:</big>'''

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"sfcode": "eu"
// Remove Flag: "nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

'''<big>Android Example:</big>'''
<syntaxhighlight lang="java">
try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("sfcode", "eu")
// Remove Flag: "nol_devDebug": "DEBUG"

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>

'''Note''': before going live, you have to inform the Nielsen team - this is necessary because the Nielsen team has to adjust internal configuration parameters to enable data collection. Without that notification, no data will be collected, and no data will be reported.

DCR Czech Video Browser SDK

2023-09-25T09:36:32Z

MichelFodjo: /* Step 1: Configure SDK */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{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. If not, please contact Nielsen local staff - See [[Czech Contacts]].

<syntaxhighlight lang="html">
apid: "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
</syntaxhighlight>

== Step 1: Configure SDK ==
Add the following script tag (Static Queue Snippet) to the website:
<syntaxhighlight lang="javascript">
<script>
!function(e,n){
function t(e){
return"object"==typeof e?JSON.parse(JSON.stringify(e)):e
}
e[n]=e[n]||
{
nlsQ:function(o,r,c){
var s=e.document,
a=s.createElement("script");
a.async=1,
a.src=("http:"===e.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+o+".js#name="+r+"&ns="+n;
var i=s.getElementsByTagName("script")[0];
return i.parentNode.insertBefore(a,i),
e[n][r]=e[n][r]||{g:c||{},
ggPM:function(o,c,s,a,i){e[n][r].q=e[n][r].q||[];try{var l=t([o,c,s,a,i]);e[n][r].q.push(l)}
catch(e){console&&console.log&&console.log("Error: Cannot register event in Nielsen SDK queue.")}},
trackEvent:function(o){e[n][r].te=e[n][r].te||[];try{var c=t(o);e[n][r].te.push(c)}
catch(e){console&&console.log&&console.log("Error: Cannot register event in Nielsen SDK queue.")}}},
e[n][r]
}
}
}(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.

== Step 2: Create SDK Instance==
To initialize the SDK, create an SDK instance by making the initialization call (already added in above code):

<syntaxhighlight lang="javascript">
var nSdkInstance = NOLBUNDLE.nlsQ("appid", "instanceName", {debugMode"});
</syntaxhighlight> 

When creating an instance, pass the following values:
{| class="wikitable"
|-
! Parameter !! Description !! Required !! Values
|-
| apid || Unique ID assigned to player/site ||Yes ||'PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
|instanceName || Name of SDK instance or Player||Yes || "any string value"
|-
| debugMode || Enables Nielsen console logging. Only required for testing ||No || "{nol_sdkDebug: "debug"})"
|}

==== Example SDK Initialization ====
For development phase - including DEBUG mode 

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

For production phase (after approval)
<syntaxhighlight lang="javascript">
var nSdkInstance = NOLBUNDLE.nlsQ("XXXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXX","myPlayerName");
</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”.

== Step 3: Create Metadata Objects ==
The metadata received for each asset is used for classification and reporting. 

There are two types of asset metadata:
*content: identify video
*ad: identify each ad

=== Content Metadata ===
Content metadata should remain constant throughout the completion of an episode / clip including the ads play. 
See [[Czech SDK Metadata]].

=== Ad Metadata ===
The ad metadata should be passed for each individual ad. 
See [[Czech SDK Metadata]].

== Step 4 : Call Nielsen APIs ==
The method for calling SDK API events is ggPM().

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

=== Type of SDK Events ===
{| class="wikitable"
|-
! Event !! Parameter !! Description!! Example
|-
| loadMetadata || content or ad metadata JSON || Needs to be called at the beginning of each asset|| nSdkInstance.ggPM("loadMetadata", metadataObjectContent)
|-
| setPlayheadPosition|| playhead position in seconds as integer || Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it's possible to seek back in Live content, then pass related Unix timestamp (not current)|| nSdkInstance.ggPM("setPlayheadPosition", currentPosition);
|-
| stop || playhead position in seconds as integer || Call when content or ads complete playing and pass playhead position, call stop when pausing playback|| nSdkInstance.ggPM("stop", parseInt(playerPosition));
|-
| end || playhead position in seconds as integer || Call when the current video asset completes playback and pass the playhead position.|| nSdkInstance.ggPM("end", parseInt(playerPosition));
|}

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

* If 1st video in playlist is content - call 'loadMetadata' for content. If 1st video in playlist is ad (not content), call 'loadMetadata' for content and than 'loadMetadata' for add - see below SDK Event Lifecycle.

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

* If last video in playlist is content (not ad) - call 'end' at the end of playlist. If last video in playlist in ad (not content), than call 'end' at the end of content video and stop at the end of ad - see bellow SDK Event Sequence. Summary: call 'end' at the end of the content stream, if the user switches to another piece of content, when the browser is refreshed or closed.
</blockquote>

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

Playlist for this sample is : preRoll → content → midRoll → content resumed → postRoll

<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);

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

== Step 5 : Interrupt Scenarios ==
Even when user or system interrupts playback you have to make sure that such interrupt will be handles as follows:

=== Pause Event ===
To indicate pause, stop passing the playhead position to the SDK and call STOP event. 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. ad vs. content).

<syntaxhighlight lang="javascript">
window.addEventListener('beforeunload', function(event)
{
// indicate <stop> inside 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>

== Step 6 : 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

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

The following paragraph is a template for an opt-out statement (in Czech).
<blockquote>
Tato aplikace obsahuje proprietární měřicí software společnosti Nielsen, který uživatelům umožní přispívat k průzkumu trhu. Chcete-li se dozvědět více o informacích, které může software Nielsen shromažďovat a o Vaší možnosti měření deaktivovat, přečtěte si zásady ochrany osobních údajů Nielsen Digital Measurement na <a href=http://cdn-gl.imrworldwide.com/priv/browser/cz/cs/optout.html>Nielsen Digital Measurement Privacy Policy</a>
</blockquote>

=== Opt-out status ===
Optional : to retrieve Opt-Out status call getOptOutStatus() , result is boolean value true (OptOuted = not measuring) or false (not OptOuted = measuring).
<syntaxhighlight lang="javascript">
nSdkInstance.getOptOutStatus();
</syntaxhighlight>

== Step 7 : Test your player by yourself ==
See how to test the player at https://www.youtube.com/watch?v=t9eUsf9yh8w

=== Test SDK API calls ===
Use the Chrome and install add-on to verify SDK API calls: "Nielsen SDK Inspector" (https://chrome.google.com/webstore/search/%20Nielsen%20SDK%20Inspector)

=== Test outgoing pings ===
to verify outgoing pings use Charles Proxy or any other proxy sw capable to sniff your network traffic. Filter URLs to "imrworld".
Example of such ping :

<code><nowiki>http://secure-eu-cert.imrworldwide.com</nowiki>/cgi-bin/gn?prd=dcr&ci=de-205177&ch=de-205177_c01_static-123_P&asn=static-123&prv=1&c6=vc,c01&ca=NA&c13=asid,T74896328-A13B-4985-8798-0AEBFA228D3E&c32=segA,segA%20example&c33=segB,segB%20example&c34=segC,segC%20example&c15=apn,&sup=1&segment2=&segment1=&forward=0&ad=0&cr=V&c9=devid,&enc=true&c1=nuid,88b7cd07-f83d-45b1-8db1-20b4e2caae55&at=view&rt=text&c16=sdkv,bj.6.0.0&c27=cln,0&crs=&lat=&lon=&c29=plid,14966485169569829&c30=bldv,6.0.0.1&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,NA&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,&c51=adl,0&c52=noad,0&devtypid=&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=static-123&c3=st,c&c64=starttm,1496648518&adid=static-123&c58=isLive,false&c59=sesid,&c61=createtm,1496648517&c63=pipMode,&c68=bndlid,&c73=phtype,&c74=dvcnm,&c76=adbsnid,&df=0&sessionId=14966485169569829&c44=progen,&davty=0&si=http%3A%2F%2Fsdkdemo.admosphere.cz%2FBrowserSdk6static%2Fdemo1cz%2F&c66=mediaurl,&c62=sendTime,1496648517&rnd=496564</code>

== Step 8 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for verification - see [[Czech Contacts]].

== Step 9 : Going Live ==
After the integration has been certified (but not prior that), users will need to disable debug logging by deleting {nol_sdkDebug: 'DEBUG'} from initialization call - see Step 2.

== Demos ==
See live demos with sample implementation available at http://sdkdemo.admosphere.cz/

DCR Czech Static Browser SDK

2023-09-25T09:35:33Z

MichelFodjo: /* Step 1: Add Static Queue Snippet */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

This guide will show you how to enable page measurement (aka Static) on your website(s). The Nielsen Tracking Code must be added to each page with different metadata.

== 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. If not, please contact Nielsen local staff - see [[Czech Contacts]]. 

<syntaxhighlight lang="html">
apid: "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
</syntaxhighlight>
 

== Step 1: Add 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(e,n){
function t(e){
return"object"==typeof e?JSON.parse(JSON.stringify(e)):e
}
e[n]=e[n]||
{
nlsQ:function(o,r,c){
var s=e.document,
a=s.createElement("script");
a.async=1,
a.src=("http:"===e.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+o+".js#name="+r+"&ns="+n;
var i=s.getElementsByTagName("script")[0];
return i.parentNode.insertBefore(a,i),
e[n][r]=e[n][r]||{g:c||{},
ggPM:function(o,c,s,a,i){e[n][r].q=e[n][r].q||[];try{var l=t([o,c,s,a,i]);e[n][r].q.push(l)}
catch(e){console&&console.log&&console.log("Error: Cannot register event in Nielsen SDK queue.")}},
trackEvent:function(o){e[n][r].te=e[n][r].te||[];try{var c=t(o);e[n][r].te.push(c)}
catch(e){console&&console.log&&console.log("Error: Cannot register event in Nielsen SDK queue.")}}},
e[n][r]
}
}
}(window,"NOLBUNDLE");
</syntaxhighlight>

== Step 2: Create SDK Instance ==
While creating an SDK instance, initialize the SDK by calling:

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

The initialization call has the below parameters:
{| class="wikitable"
|-
! Parameter !! Description !! Required !! Values
|-
| apid || Unique ID assigned to player/site ||Yes ||'PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
|instanceName || Name of SDK instance||Yes || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing ||No || "{nol_sdkDebug: "debug"})"
|}

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

== Step 3: Create Metadata Object ==

<syntaxhighlight lang="javascript">
// 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
};
</syntaxhighlight> 

Metadata can be passed through key-values using the Nielsen reserved keys.
See [[Czech Metadata]].
 

'''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)
|}
So for example, if your site has 30 sections (e.g. News, Sports, Videos, Music, etc.), we would only measure for the first 25 sections. The same applies to the custom breakout parameters segA/B/C.

== Step 4: Call staticstart Event ==
Start static measurement :
<syntaxhighlight lang="javascript">
// Event 'staticstart' Call
nSdkInstance.ggPM("staticstart", nielsenMetadata);
</syntaxhighlight>

The content metadata object is passed as a parameter.

== Step 5: Call staticend Event ==
Stop static measurement = to end the current static session and track a new static content:
<syntaxhighlight lang="javascript">
// Event 'staticend' Call
nSdkInstance.ggPM("staticend", nielsenMetadata);
</syntaxhighlight>

The content metadata object is passed as a parameter. 
Recommendation : Do not place this call inside onBeforeUnload method, because SDK need some time and resources to deliver data to cloud.

== Step 6 : 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

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

The following paragraph is a template for an opt-out statement (in Czech).
<blockquote>
Tato aplikace obsahuje proprietární měřicí software společnosti Nielsen, který uživatelům umožní přispívat k průzkumu trhu. Chcete-li se dozvědět více o informacích, které může software Nielsen shromažďovat a o Vaší možnosti měření deaktivovat, přečtěte si zásady ochrany osobních údajů Nielsen Digital Measurement na <a href=https://www.nielsen.com/cz/cs/legal/privacy-statement/digital-measurement/>Nielsen Digital Measurement Privacy Policy</a>
</blockquote>

=== Opt-out status ===
Optional : to retrieve Opt-Out status call getOptOutStatus() , result is boolean value true (OptOuted = not measuring) or false (not OptOuted = measuring).
<syntaxhighlight lang="javascript">
nSdkInstance.getOptOutStatus();
</syntaxhighlight>

== Step 7 : Test your player by your self ==

see how to test player at https://www.youtube.com/watch?v=t9eUsf9yh8w&feature=youtu.be

=== Test SKD API calls ===
to verify SDK API calls use Chrome and install add-on called "Nielsen SDK Inspector" (https://chrome.google.com/webstore/search/%20Nielsen%20SDK%20Inspector) 

=== Test outgoing pings ===
to verify outgoing pings use Charles Proxy or any other proxy sw capable to sniff your network traffic. Filter URLs to "imrworld".
Example of such ping :

<code><nowiki>http://secure-eu-cert.imrworldwide.com</nowiki>/cgi-bin/gn?prd=dcr&ci=de-205177&ch=de-205177_c01_static-123_P&asn=static-123&sessionId=b45a84a8-7847-4b2d-8cec-36baad20ed29&prv=1&c6=vc,c01&ca=NA&c13=asid,T74896328-A13B-4985-8798-0AEBFA228D3E&c32=segA,segA%20example&c33=segB,segB%20example&c34=segC,segC%20example&c15=apn,&sup=1&segment2=&segment1=&forward=0&ad=0&cr=V&c9=devid,&enc=true&c1=nuid,2ccec3b2-36a5-4eeb-a408-4d6eec7e1083&at=view&rt=text&c16=sdkv,bj.6.0.0&c27=cln,0&crs=&lat=&lon=&c29=plid,14991647575861178&c30=bldv,6.0.0.15&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,NA&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,&c51=adl,0&c52=noad,0&devtypid=&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=static-123&c3=st,c&c64=starttm,1499164759&adid=static-123&c58=isLive,false&c59=sesid,&c61=createtm,1499164772&c63=pipMode,&c68=bndlid,&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&df=0&c44=progen,&davty=0&si=http%3A%2F%2Fsdkdemo.admosphere.cz%2FBrowserSdk6static%2Fdemo1cz%2F&c66=mediaurl,&c62=sendTime,1499164772&rnd=397839</code>

== Step 8 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for verification - see [[Czech Contacts]].

== Step 9 : Going Live ==
After the integration has been certified (but not prior that), users will need to disable debug logging by deleting {nol_sdkDebug: 'DEBUG'} from initialization call - see Step 2.

== Demos ==
see live demos with sample implementation available at at http://sdkdemo.admosphere.cz/

DCR AppSDK Flavors

2023-08-02T12:25:05Z

MichelFodjo: Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}} Category:Digital __TOC__ == Android AppSDK Flavors == '''There are 3 ver..."

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

__TOC__

== Android AppSDK Flavors ==

'''There are 3 versions available starting with the Nielsen AppSDK 8.1.0.0.'''

{| class="wikitable"
|-
! AppSDK Flavor
! Description
|-
| '''Android Ad Version'''
|
* With the Ad Framework
* Opt-In and Opt-Out functionality managed by Opt out of Ads Personlization setting on device.
* The Nielsen AppSDK will collect the [https://developer.android.com/training/articles/ad-id Google Advertising ID] unless the user Opts Out.
* If the Google Play Service is unavailable, (ie: Amazon and Huawei devices) the Nielsen AppSDK will secure the Android ID.
|-
| '''Android No Ad Framework'''
|
* Without the Ad Framework, the Nielsen AppSDK cannot read the Google Advertising ID, so will retrieve the '''AndroidID'''.
* The AndroidID is a 64-bit number (expressed as a hexadecimal string), unique to each combination of app-signing key, user and device.
* The developer is required to present the User Choice Opt Out page which is described in the Privacy Section.
|-
| '''Android AppSDK noID'''
|
* This version of the Nielsen AppSDK is perfect for Kid apps, or where no ID is required.
* Please review the Privacy Section
|}

== iOS AppSDK Flavors ==
'''There are 3 versions available starting with the Nielsen AppSDK 8.0.0.0.'''.

{| class="wikitable"
|-
! AppSDK Flavor
! Description
|-
| '''iOS Ad Version'''
|
* With the Ad Framework
* Opt-In and Opt-Out functionality managed by the [https://developer.apple.com/documentation/apptrackingtransparency AppTrackingTransparency framework].
* The Nielsen AppSDK will attempt to collect the IDFA (Id for Advertisers) on the device.
* For iOS14+, if the value '''ATTrackingManager.AuthorizationStatus.authorized''' is returned.
* If the device is running iOS12 or iOS13, the Limit Ad Tracking setting is requested.
|-
| '''iOS No Ad Framework'''
|
* Without the Ad Framework, the Nielsen AppSDK cannot read the IDFA, so it will attempt to retrieve the '''IDFV'''.
* The [https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor ID for Vendors (IDFV)], may be used for analytics across apps from the same content provider.
* The developer is required to present the User Choice Opt Out page which is described in the Privacy Section.
|-
| '''iOS AppSDK noID'''
|
* This version of the Nielsen AppSDK is perfect for Kid apps, or where no ID is required.
* Please review the Privacy Section
|}

DCR Germany Static Browser SDK

2023-07-14T11:15:20Z

MichelFodjo:

DCR Germany Video App SDK

2023-06-30T09:08:21Z

MichelFodjo:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

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

== 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.
* <blockquote>'''No ID AppSDK''': <pre style="color: red">ONLY the No ID AppSDK should be downloaded for the AGF market!</pre>
</blockquote>

* '''Nielsen SDK:''' The Nielsen SDK package contains a variety of sample players for your reference.
Please contact our SDK sales support team if you do not have any of these prerequisites or have any questions.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

== Implementation ==
This guide covers implementation steps for iOS using Xcode and Android using Android Studio.

== Setting up your Development Environment ==

=== iOS ===

<big>
'''Configuring Xcode Development Environment'''
</big>

Nielsen App SDK is compatible with Apple iOS versions 9.0 and above.

The SDK uses the NSURLSession instead of the deprecated NSURLConnection.

<blockquote>'''Note''': All communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

<big>'''Importing Frameworks'''</big>
The first step is to ensure that the following frameworks and libraries are imported into the Frameworks folder of the Xcode project before creating an instance of the Nielsen App SDK object.
* UIKit.framework
* Foundation.framework
* SystemConfiguration.framework
* Security.framework
** Nielsen Analytics framework uses several functions in this library.
* AVFoundation.framework
** This framework is mandatory for the iOS SDK version 5.1.1 to work.
* CoreLocation.framework
* CoreMedia.framework
* NielsenAppApi.framework
* libc++.tbd (as SDK contains Objective C++ source file)
** Alternatively, include -lstdc++ in Build Settings → Other Linker Flag of the Xcode project

<blockquote>'''Example'''
* Extract “NielsenAppApi.Framework” from the Nielsen App SDK sample app and copy it to the Frameworks folder of the Xcode project.
* Add the code <code>-#import NielsenAppApi/NielsenAppApi.h</code> to the View Controller’s header file.</blockquote>

Ensure that the following are included in the Linked Frameworks and Libraries list (located in the project’s Summary settings).
* Nielsen App SDK
* iOS security framework
 
<big>'''Using Swift'''</big>
To import a set of Objective-C files in the same app target as your Swift code, you rely on an Objective-C bridging header to expose those files to Swift. Xcode offers to create this header file when you add a Swift file to an existing Objective-C app or an Objective-C file to an existing Swift app.

Select File/New File/Objective-C File 
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] 
Once this file has been created, you need to add the following:
<syntaxhighlight lang="swift">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
<big>'''Using Objective-C'''</big>
Add the code
<syntaxhighlight lang ="objective-c">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
to the View Controller’s header file.
 

=== Android ===
==== General ====
<big>
'''Configuring Android Java Development Environment'''
</big>

*The Nielsen App SDK (located in the ''com.nielsen.app.sdk'' package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is the only public class belonging to the com.nielsen.app.sdk package.

'''Nielsen App SDK is compatible with Android OS versions 2.3+. Clients can control/configure the protocol to be used – HTTPS or HTTP to suit their needs.'''

The Nielsen App SDK 1.2 library is composed of two parts:
* The Java AppSdk.jar library runs on the Android’s Dalvik Virtual Machine.
* The C/C++ libAppSdk.so native library that runs directly on the device’s hardware.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote>

The requirement for the Java ''AppSdk.jar'' library and the ''libAppSdk.so'' native library will depend on the type of host application that will make use of them.
* '''For Video player applications'''
** The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 3.0 and later will support it natively).
** If the player application uses a 3rd party media player implementing its own HLS, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.
* '''For Audio player applications'''
** The Android OS hosting the App SDK should be at version 2.3 and later since the SDK depends on Google Play support to work properly.
Unzip the Nielsen App SDK sample app and copy the ''AppSdk.jar'' into the libs/ folder on the App’s Eclipse project. Copy the ''libAppSdk.so'' file under ''libs/armeabi/'' folder into the same Eclipse project.
* App SDK 1.2 provides support for x86, mips, and armeabi-7a architecture; the respective ''libAppSdk.so'' can be found under the ''libs/x86/'', ''libs/mips/'', and ''libs/armeabi-7a/'' folders.
Add the following permissions on the project’s ''AndroidManifest.xml'' file.
<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details on handling runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. Download the latest ''google-play-services_lib'' and include it in the App’s project in order to use the App SDK.
* App SDK checks to see if a Google service is available and updated.
* If unavailable or updated, App SDK will not use this service when executing its functions and will reference missing imports and the app will not be compiled.
To include the Google Play library in the media player project, copy the ''google-play-services_lib'' folder into the same location as the project
* Access '''File > Import'''.
* Select '''Existing Android Code into Workspace''' and click '''Next'''.
* Click '''Browse''' and navigate to the ''google-play-services_lib'' to include it into the projects.
* Select the exact '''Project Build Target''' for Eclipse to use from Android SDK.
** Android 4.4.2, etc. OR
** Edit ''project.properties'' file to point to Android target version e.g. target= android-19.
Once the google-play-services_lib is included into the App project, include the following code under the <code><application></code> node in the <code>AndroidManifest.xml</code>.

<syntaxhighlight lang="java"><meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/></syntaxhighlight>

Also, include the ''version.xml'' file that comes with the ''google-play-services_lib'' under the res/values directory of the media player project.
* Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface.

<big>'''Library'''</big>

Nielsen App SDK uses the following packages/classes from the Google Play service.
* google-play-services_lib

'''<big>Classes/package</big>'''
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

==== Add the dependency "lifecycle-extensions" to your project ====
Add the dependency "lifecycle-extensions" in the in the app gradle file as follows:
<syntaxhighlight lang="java">
implementation "androidx.lifecycle:lifecycle-extensions:2.1.0"
</syntaxhighlight>

This will enable the AppSdk to detect the application UI visibility state transitions between background and foreground by utilizing the LifeCycleObserver. This is i.e. required for the Static Measurement.

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-agf-v0.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-agf-ad-v0.png||SDK Integration Architecture Diagram - Ad]]

== SDK Initialization ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. The sharedInstance API that creates a singleton object was deprecated before version 5.1.1. (Version 4.0 for Android)

* A maximum of four SDK instances per appid are supported. When a fifth SDK instance is launched, the SDK will return “nil” from [[initWithAppInfo:delegate:]]
* When four SDK instances exist, you must destroy an old instance before creating a new one.

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || ✓ || "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || No || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || No || "1.0.2"
|-
| sfcode || Nielsen collection facility to which the SDK should connect.
'''AGF Clients'''
* "eu" (For Testing/Certification and in Production)
|| Nielsen-specified || ✓ || "eu"
|-
| nol_devDebug || Enables Nielsen console logging. Has to be set to "DEBUG" until certified
|| Nielsen-specified || Optional || "DEBUG"
|}
 

==== Sample SDK Initialization Code ====

===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"sfcode": "eu",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
 
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

====== Objective-C ======
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>If App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.</blockquote>
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
@"sfcode": "eu",
@"nol_devDebug": @"DEBUG"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

===== Android =====
====== Java ======

AppSDK is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="java">

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA")
.put("sfcode", "eu")
.put("nol_devDebug", "DEBUG");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
Here, <code>appContext</code> is the App context object and <code>appSdkConfig</code> is JSON object for holding the parameters (<code>appid</code>, <code>appname</code>, <code>sfcode</code>) the App passes to the Nielsen App SDK via a JSON string. The appid is obtained from Nielsen operational support and is unique to the app.

The integration of Nielsen App SDK will depend on the type of client app. 
* Ensure that SDK files (AppSdk.jar and libAppSdk.so [App SDK 1.2 Only]) are included under the App’s project and the App SDK is linked to the App (the setting to link App SDK to the App can be found on the property page of the App’s project).

== APP SDK Error & Event Codes ==
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.
== Configure Payload ==
=== Handling JSON Metadata ===
All the SDK methods handle only two types of objects: NSString, NSDictionary. The parameters passed must be either a JSON formatted string or a NSDictionary object. The JSON passed in the SDK must be well-formed.
* NSDictionary object
** If an object of the unexpected type is passed to the method, the error message will be logged.
** The error message will be logged if the string has an invalid JSON format.
* JSON value must be a string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, sfcode, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary.

=== Configure ChannelInfo metadata ===
==== Description of ChannelInfo metadata ====
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}
 

==== Example ChannelInfo metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelName","My Channel Name 1")
</syntaxhighlight>

=== Configure Content metadata ===

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

For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required/Obligatory
|-
| type || type of asset || <code>"content"</code> || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no [[Special Characters]]) || ✓
|-
| program ||(string) name of program (254 character limit) || custom || ✓
|-
| title ||(string) episode title (max 254 characters) || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| length || length of content in seconds || <code>seconds</code> ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| clientid ||
parent ID – value is automatically populated through provided App ID. 
In order to override the brand configured to the App ID, pass parent 
value here and the sub-brand ID associated with that brand in the subbrand 
key (e.g. multiple brands in App)
||
provided by Nielsen
||
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided 
App ID. In order to override the sub-brand configured to the App ID, value can 
be passed here (e.g. multiple sub-brands in App)
||
provided by Nielsen
||

|-
| nol_c0 || number of episode part (Sendungsteilenummer) || number || ✓
|-
| nol_c2 || web only || 'Y' or 'N' || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || duration in seconds || `seconds` ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c12 || type of asset || 'Trailer' or 'Content' || ✓
|-
| nol_c13 || original air time || `(YYYY-MM-TT)T(HH:mm:ss) Example: 2004-06-14T23:34:30 ||
|-
| nol_c14 || ISO 8601 timestamp || `(YYYY-MM-TT)T(HH:mm:ss)` ||
|-
| nol_c15 || format ID || custom ||
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c18 || livestream || 'Y' or 'N' || ✓
|-
| nol_c19 || custom variable || custom ||
|-
| nol_c20 || GfK-ID || custom ||
|}
 

==== Example Content metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
];
</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">
NSDictionary *contentMetadata = @
{@"type": @"content",
@"assetid": @"88675545",
@"length": @"3600",
@"program", "Program Name",
@"title": @"episode title",
@"nol_c0": "p0,1",
@"nol_c2": "p2,Y",
@"nol_c7": "p7,videoid123",
@"nol_c8": "p8,3600",
@"nol_c9": "p9,VideoTitle123",
@"nol_c10": "p10,clientname",
@"nol_c12": "p12,content",
@"nol_c18": "p18,N"
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">
JSONObject contentMetadata = new JSONObject()
.put("type", "content")
.put("assetid", "88675545")
.put("program", "Program Name")
.put("title", "episode title")
.put("length", "3600")
.put("nol_c0", "p0,1")
.put("nol_c2", "p2,Y")
.put("nol_c7", "p7,videoid123")
.put("nol_c8", "p8,3600")
.put("nol_c9", "p9,VideoTitle123")
.put("nol_c10", "p10,clientname")
.put("nol_c12", "p12,content")
.put("nol_c18", "p18,N")
</syntaxhighlight>

=== Configure Ad Metadata ===
==== Description of Ad metadata ====
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''
 
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no SPACE - no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters]) || ✓
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen ||
|-
| title || only the AD-ID is necessary || custom, <AD-ID> without "VAST" Prefix or other, i.e. '2352723141' || ✓
|-
| length || length of Ad in seconds || length of Ad in seconds || ✓
|-
| nol_c1 || universal AdID (Additional AD-ID to be used by second or third marketers) || custom, i.e. 'adgapid_022_800160_1601097_001_0_0' ||
|-
| nol_c2 || web only || 'Y' or 'N' ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || duration of the video file in seconds || || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c11 || AD-ID (unique ID of an advertisement. Necessary if ads are being broadcasted) || custom, i.e. '2352723141' || ✓
|-
| nol_c12 || content type (key distinction of content, advertising, and Trailer) || 'Werbung' || ✓
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c17 || ad placement type (placement information of advertisement) || 'preroll', 'midroll', 'postroll' or 'other' || ✓
|}

==== Example Ad metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let adMetadata = [
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Werbung",
"nol_c17": "p17,preroll"
];
</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">

NSDictionary *adMetadata = @
{@"type": @"preroll",
@"assetid": @"ad345-67483"",
@"title": @"ad_title",
@"length": @"25",
@"nol_c8": "p8,25",
@"nol_c10": "p10,clientname",
@"nol_c11": "p11,2352723141",
@"nol_c12": "p12,Werbung",
@"nol_c17": "p17,preroll"
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">

JSONObject adMetadata = new JSONObject()
.put("type", "preroll")
.put("assetid", "ad345-67483")
.put("title", "2352723141")
.put("length", "25")
.put("nol_c8", "p8,25")
.put("nol_c10", "p10,clientname")
.put("nol_c11", "p11,2352723141")
.put("nol_c12", "p12,Werbung")
.put("nol_c17", "p17,preroll")
</syntaxhighlight>
== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| 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.
|}

=== Life cycle of SDK instance ===
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# '''Processing state''' – The SDK instance processes playing information. [[play]] and [[loadMetadata]] calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[end]] – SDK instance exits from Processing state when this API is called.
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

'''Note''': In case of any interruptions during playback due to alarm, calendar, call, flight mode, Wi-Fi toggle, channel change, etc., call [[stop]] to pause the measurement.
* As soon as the playback resumes, call [[loadMetadata]] and [[playheadPosition]].</blockquote>

=== API Call sequence ===
==== Use Case 1: Content has no Advertisements ====
Call [[play()]] with channelName JSON as below.
'''[[#Example ChannelInfo metadata|Example ChannelInfo metadata]]'''
Call [[loadMetadata()]] with JSON metadata for content as below.
'''[[#Example Content metadata|Example Content metadata]]'''

Call [[setPlayheadPosition()]] every one second until the stream playback is interrupted or has ended.
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.
'''[[#Example ChannelInfo metadata|Example ChannelInfo metadata]]'''
<blockquote>Note: ONLY for a preroll Ad , Call [[loadMetadata()]] for Content before calling it for preroll ad </blockquote>

Call [[loadMetadata()]] with JSON metadata for ad as below.
'''[[#Example Ad metadata|Example Ad metadata]]'''
<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 the Ad playback is interrupted or has ended for each single Ad. 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 (Content resume) || <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.</blockquote>

=== Sequence of Calls ===

=== play ===
Use [[play]] to pass the channel descriptor information through channelName parameter after the SDK has been initialized and the content starts playing. If the user is returning from a '''Pause/Stop''' interaction, call [[loadMetadata]] with the same metadata and continue sending [[playheadPosition]] once the playback resumes.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c"> - (void)play:(id)channelInfo;</syntaxhighlight>
|Android = <syntaxhighlight lang="java"> public void play(JSONObject channelInfo);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenAppApi?.play(JSONObject channelInfo);</syntaxhighlight>
}}

=== loadMetadata ===
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">– (void)loadMetadata:(id)contentMetadata;</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void loadMetadata(JSONObject contentMetadata);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(contentMetadata)</syntaxhighlight>
}}

=== playheadPosition ===

"playheadPosition" has to be called every second.

* VOD :
** For Content and each single Ad, pass the current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3...
*Live :
**For Content, pass the Unix timestamp (seconds since Jan-1-1970 UTC). Pass whole number that increments only by 1 like 1631098029,1631098030,1631098031,1631098032,... .
**For each single Ad, pass the current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3...

{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">
– (void) playheadPosition: (long long) playheadPos
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
AVPlayer *player;
CMTime curTime=[player currentTime];
int pos = CMTimeGetSeconds(curTime);
[nAppApiObject playheadPosition:pos];
</syntaxhighlight>

|Swift = <syntaxhighlight lang="swift">
//Monitor the Playhead position of the AVPlayer
let timeInterval: CMTime = CMTimeMakeWithSeconds(1.0,10)
self.avPlayerViewController.player?.addPeriodicTimeObserver(forInterval: timeInterval, queue: DispatchQueue.main) {(elapsedTime: CMTime) -> Void in
if self.avPlayerViewController.player!.currentItem?.status == .readyToPlay {
let time : Float64 = self.avPlayerViewController.player!.currentTime().seconds;
let pos = Int64(time);
NSLog("New Elapse Time = \(time)");
self.nielsenAppApi?.playheadPosition(pos);
}
}
}
</syntaxhighlight>
|Android = <syntaxhighlight lang="java">
public void setPlayheadPosition(long position)
</syntaxhighlight>
}}

=== stop ===
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">– (void) stop</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void stop()</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.stop</syntaxhighlight>
}}

=== end ===
Call when the content asset completes playback. Stops measurement progress.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">- (void) end;</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void stop()</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.stop</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 and withhold sending playhead position.
* '''For video content:'''
** Call [[loadMetadata]] with the same metadata and continue sending [[playheadPosition]] once the playback resumes.
* '''For ads:'''
** just continue sending [[playheadPosition]] once the playback resumes (no [[loadMetadata]]).

Additional information:
* '''For type 'content': '''Sending a "loadMetadata" event after a "stop" event will be handled by the SDK as a "resume", as long as the "assetid" and "type" are the same and not changed from the values before the "stop" event happened. Changing "assetid" value will lead into a new stream. Changing of "type" from "content" to "preroll" ("midroll", "postroll") will lead into a new object (ad) with that content stream. Changing any other parameter (eg. "program" or "title") for the content will not affect the reported content data (will stay as in the very first "content" metadata)

=== App termination ===
If your app is executing a termination process and therefore ending the Content or Ad Playback, call [[end]] if the Content is playing or [[stop]] if an Ad is playing.

== Privacy and Opt-Out ==

The AppSDK measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen AppSDK measurement is utilizing a cookieless domain.
In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=de .

Please contact your Nielsen SDK support team directly for any related questions.

== Going Live ==
Following Nielsen testing, users need to make one update to the initialization call to ensure that the site is being measured properly.

# '''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:

'''<big>iOS Example:</big>'''

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"sfcode": "eu"
// Remove Flag: "nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

'''<big>Android Example:</big>'''
<syntaxhighlight lang="java">
try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("sfcode", "eu")
// Remove Flag: "nol_devDebug": "DEBUG"

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>

'''Note''': before going live, you have to inform the Nielsen team - this is necessary because the Nielsen team has to adjust internal configuration parameters to enable data collection. Without that notification, no data will be collected, and no data will be reported.

DCR Germany Video Browser SDK

2023-06-30T09:05:46Z

MichelFodjo:

DCR Germany Video Cloud API

2023-06-30T09:03:09Z

MichelFodjo: /* DCR Integration Utilizing Cloud API */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing Cloud API =
This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.

<pre style="color: orange">
PLease note that you have to use the Staging Cloud API Endpoint until you get the green light from Nielsen to move to Production!
</pre>

__TOC__
==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 by your assigned Technical Account Manager upon starting the integration.

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Provided by Nielsen
|}

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

====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. '''Note:'''The "P" prefix must be removed from the App ID received before adding it to the URL, i.e. if you received PDF20695-XXXX-XXXX-XXXX-3E334133D917 from Nielsen , your url will then be : <code>[endpoint]/DF20695-XXXX-XXXX-XXXX-3E334133D917/[sessionID]/a?b=[payload]</code>
*<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://sc-eucert.nmrodam.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://sc-eucert.nmrodam.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms],
"sessid": [unique view session ID for each video play]
}
</syntaxhighlight>

===Create Session ID and send EMM Ping===

====Create Session ID====

A unique Session ID <code>[sessionID]</code> must be created upon app launch and provided in the URL. This will allow the measurement to occur for the entire duration that a user is within the app.

A Session ID needs to be completely unique so it is recommended to use our generation method example provided below to create unique alpha-numerical 29 characters + 10 characters UTC timestamp, to guarantee there are no repeats, also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference and use.

Session ID example: '''LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088'''
 

<syntaxhighlight lang="javascript">
'''// Create random GUID'''
function buildGUID() {
var UAIDbase62Characters = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
var UAIDpayloadLength = 29;

function UAIDgetRandom62() {
var r1;
do {
r1 = Math.floor(Math.random() * (16 * 62));
} while (r1 > 61);
return r1;
}

var uid = '';
for (var a = 0; a < UAIDpayloadLength; a++) {
uid += UAIDbase62Characters.charAt(UAIDgetRandom62());
}
var timestamp_ms = new Date().getTime();
uid += String(timestamp_ms).substring(3);
return uid;
}
</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.

====Send EMM Ping (only for Mobile (iOS and Android) and Browser)====
An EMM Ping must be sent using the created unique Session ID <code>[sessionID]</code> upon start of the first stream playback.
<syntaxhighlight lang="javascript">
https://[sessionID].uaid.nmrodam.com/
</syntaxhighlight>
Also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference.

===Create View Session ID for each Video Start===
An View Session ID <code>[sessid]</code> must be created upon start of each stream playback, sessid is unique per video play.

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

<syntaxhighlight lang="javascript">https://sc-eucert.nmrodam.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

===Configure Payload===

====Description 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">
// 1. Create Session ID using the UUID Generator code provided
sessionID = LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088 // Example sessionID

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

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "",
"apn": "AppName",
"apv": "1.0"
},

// 3.2 Configure Payload: metadata
"metadata": {
"content": { // object for measuring video content
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
// custom metadata
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
},
"ad": {
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Werbung",
"nol_c17": "p17,preroll"
}
},

// 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
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609" // create and pass a unique sessid for each video play using UUID Generator code provided
}
</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) - Not required for AGF || custom ||
|-
| apn || app name || custom || ✓
|-
| apv || app build version || custom || ✓
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "",
"apn": "AppName",
"apv": "1.0"
},
</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 =====

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

For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required/Obligatory
|-
| type || type of asset || <code>"content"</code> || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no [[Special Characters]]) || ✓
|-
| program ||(string) name of program (254 character limit) || custom || ✓
|-
| title ||(string) episode title (max 254 characters) || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| length || length of content in seconds || <code>seconds</code> ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| clientid ||
parent ID – value is automatically populated through provided App ID. 
In order to override the brand configured to the App ID, pass parent 
value here and the sub-brand ID associated with that brand in the subbrand 
key (e.g. multiple brands in App)
||
provided by Nielsen
||
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided 
App ID. In order to override the sub-brand configured to the App ID, value can 
be passed here (e.g. multiple sub-brands in App)
||
provided by Nielsen
||

|-
| nol_c0 || number of episode part (Sendungsteilenummer) || number || ✓
|-
| nol_c2 || web only || 'Y' or 'N' || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || duration in seconds || `seconds` ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c12 || type of asset || 'Trailer' or 'Content' || ✓
|-
| nol_c13 || original air time || `(YYYY-MM-TT)T(HH:mm:ss) Example: 2004-06-14T23:34:30 ||
|-
| nol_c14 || ISO 8601 timestamp || `(YYYY-MM-TT)T(HH:mm:ss)` ||
|-
| nol_c15 || format ID || custom ||
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c18 || livestream || 'Y' or 'N' || ✓
|-
| nol_c19 || custom variable || custom ||
|-
| nol_c20 || GfK-ID || custom ||
|}
 

====== Example Content metadata ======
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
// custom metadata
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
}</syntaxhighlight>

===== Ad Metadata (optional for public broadcasters) =====
====== Description of Ad metadata ======
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

 
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no SPACE - no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters]) || ✓
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen ||
|-
| title || only the AD-ID is necessary || custom, <AD-ID> without "VAST" Prefix or other, i.e. '2352723141' || ✓
|-
| length || length of Ad in seconds || length of Ad in seconds || ✓
|-
| nol_c1 || universal AdID (Additional AD-ID to be used by second or third marketers) || custom, i.e. 'adgapid_022_800160_1601097_001_0_0' ||
|-
| nol_c2 || web only || 'Y' or 'N' ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || duration of the video file in seconds || || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c11 || AD-ID (unique ID of an advertisement. Necessary if ads are being broadcasted) || custom, i.e. '2352723141' || ✓
|-
| nol_c12 || content type (key distinction of content, advertising, and Trailer) || 'Werbung' || ✓
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c17 || ad placement type (placement information of advertisement) || 'preroll', 'midroll', 'postroll' or 'other' || ✓
|}

====== Example Ad metadata ======
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Werbung",
"nol_c17": "p17,preroll"
}

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

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

'''General'''
* Playhead position in seconds, must be passed as a whole number every 10 seconds.
* The final playhead position should be sent before before sending "complete" event when content playback is complete.

'''Live Stream'''
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position. Note that ad playheads must also use Unix Time for each single Ad in an Ad Pod.

'''VoD Stream'''
* For VoD stream use the player position for Content and Ad at playback start of a content or single Ad in an Ad Pod, playheads will then be 0, 10, 20, ....

'''End of an Asset'''
* Final postion must be sent at the end of Content or Ad playback

'''Ads'''
* The final playhead position must be sent when switching from content to ad, or ad to content.
* For Ad Pods, playhead must be called for each individual ad.
* When content has resumed following a mid-roll ad break, the next playhead position must continue where the previous content segment left off.

'''User Actions'''
* SCRUBBING: 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.
* PAUSE: When content is paused, send current playhead position and stop passing playhead position until content is resumed.
* EXIT Stream: If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

|-
| <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. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is optional and can be sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. 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> || ✓
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || ✓
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || ✓
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || ✓
|-style="background-color:#d0f6f8;"
| <code>"sessid"</code> || Unique View Session ID must be created upon start of each stream playback, sessid is unique per video play. || <code>"xxxjavd6wzirm93xb95uxjy1ac5wu1627638609"</code> || ✓
|}

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

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"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
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}
</syntaxhighlight>

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

===== Sample Event Lifecycle for VoD Stream =====
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 for VoD Stream - 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>

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

see '''[[#Payload Example|Payload Example]]'''

// Append payload to URL
function sendPayloadToNielsen() {
var payloadStr = JSON.stringify(payload); // payload as string
var imgPing = new Image();
imgPing.onload = function() {
// onload event, payload succesfull sent
};
imgPing.onerror = function() {
// handle error i.e. wait and send again
};
imgPing.src = sessionURL+encodeURIComponent(payloadStr);
}
</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
|}

== Review the Reference Implementation for VoD and Live Streams ==

The Reference Implementation covers vod and Live use cases.
It also covers DAI (Dynamic Ad Insertion) with preroll and postroll Ads.

In order to start live stream select the checkbox "isLive" in the <code>Playback Settings</code> below the video player.

Start the Reference Implementation for AGF by selection Germany in the country dropbox [https://nielsenonlinesupport.com/agf/RefImplCloudAPI/index.htm?debug=true RefImplCloudAPI].
<blockquote>
Review the Nielsen CloudAPI Call Sequence below the Video Player.
</blockquote>

== Disclose Nielsen Privacy Statement ==

The Nielsen Cloud API measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen Cloud API measurement is utilizing a cookieless domain.

In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:

A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=de .

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

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

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset for VoD stream and UTC Unix Time in seconds for Live stream.
*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.

== 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://sc-eucert.nmrodam.com/nmapi/v2/</code>
*Production: <code>https://???.nmrodam.com/nmapi/v2/</code>

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

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

DCR Germany Video Cloud API

2023-06-19T12:51:27Z

MichelFodjo:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing Cloud API =
This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.

<pre style="color: orange">
PLease note that you have to use the Staging Cloud API Endpoint until you get the green light from Nielsen to move to Production!
</pre>

__TOC__
==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 by your assigned Technical Account Manager upon starting the integration.

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Provided by Nielsen
|}

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

====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. '''Note:'''The "P" prefix must be removed from the App ID received before adding it to the URL, i.e. if you received PDF20695-XXXX-XXXX-XXXX-3E334133D917 from Nielsen , your url will then be : <code>[endpoint]/DF20695-XXXX-XXXX-XXXX-3E334133D917/[sessionID]/a?b=[payload]</code>
*<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://sc-eucert.nmrodam.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://sc-eucert.nmrodam.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms],
"sessid": [unique view session ID for each video play]
}
</syntaxhighlight>

===Create Session ID and send EMM Ping===

====Create Session ID====

A unique Session ID <code>[sessionID]</code> must be created upon app launch and provided in the URL. This will allow the measurement to occur for the entire duration that a user is within the app.

A Session ID needs to be completely unique so it is recommended to use our generation method example provided below to create unique alpha-numerical 29 characters + 10 characters UTC timestamp, to guarantee there are no repeats, also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference and use.

Session ID example: '''LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088'''
 

<syntaxhighlight lang="javascript">
'''// Create random GUID'''
function buildGUID() {
var UAIDbase62Characters = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
var UAIDpayloadLength = 29;

function UAIDgetRandom62() {
var r1;
do {
r1 = Math.floor(Math.random() * (16 * 62));
} while (r1 > 61);
return r1;
}

var uid = '';
for (var a = 0; a < UAIDpayloadLength; a++) {
uid += UAIDbase62Characters.charAt(UAIDgetRandom62());
}
var timestamp_ms = new Date().getTime();
uid += String(timestamp_ms).substring(3);
return uid;
}
</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.

====Send EMM Ping (only for Mobile (iOS and Android) and Browser)====
An EMM Ping must be sent using the created unique Session ID <code>[sessionID]</code> upon start of the first stream playback.
<syntaxhighlight lang="javascript">
https://[sessionID].uaid.nmrodam.com/
</syntaxhighlight>
Also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference.

===Create View Session ID for each Video Start===
An View Session ID <code>[sessid]</code> must be created upon start of each stream playback, sessid is unique per video play.

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

<syntaxhighlight lang="javascript">https://sc-eucert.nmrodam.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

===Configure Payload===

====Description 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">
// 1. Create Session ID using the UUID Generator code provided
sessionID = LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088 // Example sessionID

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

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "",
"apn": "AppName",
"apv": "1.0"
},

// 3.2 Configure Payload: metadata
"metadata": {
"content": { // object for measuring video content
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
// custom metadata
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
},
"ad": {
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Ad",
"nol_c17": "p17,preroll"
}
},

// 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
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609" // create and pass a unique sessid for each video play using UUID Generator code provided
}
</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) - Not required for AGF || custom ||
|-
| apn || app name || custom || ✓
|-
| apv || app build version || custom || ✓
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "",
"apn": "AppName",
"apv": "1.0"
},
</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 =====

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

For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required/Obligatory
|-
| type || type of asset || <code>"content"</code> || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no [[Special Characters]]) || ✓
|-
| program ||(string) name of program (254 character limit) || custom || ✓
|-
| title ||(string) episode title (max 254 characters) || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| length || length of content in seconds || <code>seconds</code> ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| clientid ||
parent ID – value is automatically populated through provided App ID. 
In order to override the brand configured to the App ID, pass parent 
value here and the sub-brand ID associated with that brand in the subbrand 
key (e.g. multiple brands in App)
||
provided by Nielsen
||
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided 
App ID. In order to override the sub-brand configured to the App ID, value can 
be passed here (e.g. multiple sub-brands in App)
||
provided by Nielsen
||

|-
| nol_c0 || number of episode part (Sendungsteilenummer) || number || ✓
|-
| nol_c2 || web only || 'Y' or 'N' || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || duration in seconds || `seconds` ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c12 || type of asset || 'Trailer' or 'Content' || ✓
|-
| nol_c13 || original air time || `(YYYY-MM-TT)T(HH:mm:ss) Example: 2004-06-14T23:34:30 ||
|-
| nol_c14 || ISO 8601 timestamp || `(YYYY-MM-TT)T(HH:mm:ss)` ||
|-
| nol_c15 || format ID || custom ||
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c18 || livestream || 'Y' or 'N' || ✓
|-
| nol_c19 || custom variable || custom ||
|-
| nol_c20 || GfK-ID || custom ||
|}
 

====== Example Content metadata ======
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
// custom metadata
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
}</syntaxhighlight>

===== Ad Metadata (optional for public broadcasters) =====
====== Description of Ad metadata ======
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

 
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no SPACE - no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters]) || ✓
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen ||
|-
| title || only the AD-ID is necessary || custom, <AD-ID> without "VAST" Prefix or other, i.e. '2352723141' || ✓
|-
| length || length of Ad in seconds || length of Ad in seconds || ✓
|-
| nol_c1 || universal AdID (Additional AD-ID to be used by second or third marketers) || custom, i.e. 'adgapid_022_800160_1601097_001_0_0' ||
|-
| nol_c2 || web only || 'Y' or 'N' ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || duration of the video file in seconds || || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c11 || AD-ID (unique ID of an advertisement. Necessary if ads are being broadcasted) || custom, i.e. '2352723141' || ✓
|-
| nol_c12 || content type (key distinction of content, advertising, and Trailer) || 'Ad' || ✓
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c17 || ad placement type (placement information of advertisement) || 'preroll', 'midroll', 'postroll' or 'other' || ✓
|}

====== Example Ad metadata ======
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Ad",
"nol_c17": "p17,preroll"
}

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

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

'''General'''
* Playhead position in seconds, must be passed as a whole number every 10 seconds.
* The final playhead position should be sent before before sending "complete" event when content playback is complete.

'''Live Stream'''
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position. Note that ad playheads must also use Unix Time for each single Ad in an Ad Pod.

'''VoD Stream'''
* For VoD stream use the player position for Content and Ad at playback start of a content or single Ad in an Ad Pod, playheads will then be 0, 10, 20, ....

'''End of an Asset'''
* Final postion must be sent at the end of Content or Ad playback

'''Ads'''
* The final playhead position must be sent when switching from content to ad, or ad to content.
* For Ad Pods, playhead must be called for each individual ad.
* When content has resumed following a mid-roll ad break, the next playhead position must continue where the previous content segment left off.

'''User Actions'''
* SCRUBBING: 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.
* PAUSE: When content is paused, send current playhead position and stop passing playhead position until content is resumed.
* EXIT Stream: If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

|-
| <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. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is optional and can be sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. 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> || ✓
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || ✓
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || ✓
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || ✓
|-style="background-color:#d0f6f8;"
| <code>"sessid"</code> || Unique View Session ID must be created upon start of each stream playback, sessid is unique per video play. || <code>"xxxjavd6wzirm93xb95uxjy1ac5wu1627638609"</code> || ✓
|}

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

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"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
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}
</syntaxhighlight>

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

===== Sample Event Lifecycle for VoD Stream =====
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 for VoD Stream - 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>

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

see '''[[#Payload Example|Payload Example]]'''

// Append payload to URL
function sendPayloadToNielsen() {
var payloadStr = JSON.stringify(payload); // payload as string
var imgPing = new Image();
imgPing.onload = function() {
// onload event, payload succesfull sent
};
imgPing.onerror = function() {
// handle error i.e. wait and send again
};
imgPing.src = sessionURL+encodeURIComponent(payloadStr);
}
</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
|}

== Review the Reference Implementation for VoD and Live Streams ==

The Reference Implementation covers vod and Live use cases.
It also covers DAI (Dynamic Ad Insertion) with preroll and postroll Ads.

In order to start live stream select the checkbox "isLive" in the <code>Playback Settings</code> below the video player.

Start the Reference Implementation for AGF by selection Germany in the country dropbox [https://nielsenonlinesupport.com/agf/RefImplCloudAPI/index.htm?debug=true RefImplCloudAPI].
<blockquote>
Review the Nielsen CloudAPI Call Sequence below the Video Player.
</blockquote>

== Disclose Nielsen Privacy Statement ==

The Nielsen Cloud API measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen Cloud API measurement is utilizing a cookieless domain.

In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:

A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=de .

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

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

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset for VoD stream and UTC Unix Time in seconds for Live stream.
*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.

== 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://sc-eucert.nmrodam.com/nmapi/v2/</code>
*Production: <code>https://???.nmrodam.com/nmapi/v2/</code>

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

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

Sweden SDK Metadata

2023-05-30T08:39:58Z

MichelFodjo: /* Content Metadata */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= Digital Metadata =
Digital Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.
 
'''Section 1''' focuses on the content metadata
 
'''Section 2''' focuses on the Ad metadata.
 

'''Note:''' All metadata values should be passed as UTF-8 strings. 

== Content Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| userid || || the user login ID. Used by MMS reach model. ''The uploaded value needs to be hashed with SHA512''. This is the user login ID on player. We prefer a numeric value. (please '''do not''' use user email address)|| "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa..." || required if login feature

|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. (max: 20 characters). In addition to this metadata for content needs to be reported to MMS via TitleService. Contact online@mms.se for more information. ||
For VoD use internal format. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters] 
For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 
A complete list of channel reference libraries with channel numbers is on the [https://mms.se/for-vara-kunder/teknisk-dokumentation-tv/referensbandade-kanaler/ MMS homepage] tab "referensbandade kanaler".
|| ✓ 
|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for VoD, video length
* for event-Live stream, the planned length.
* for simulcast and 24/7 live stream, 86400
|| ✓
|-
| clientpassparam || MMS Values, mms_values || pass-through parameters || For clients that provide DAI (dynamic ad insertion) service, this has a standard format: origcode=channelnumber.
'''Example:''' origcode=29
See the complete list of channel reference library with the channel number on [https://mms.se/for-vara-kunder/teknisk-dokumentation-tv/referensbandade-kanaler/ MMS homepage] tab "referensbandade kanaler". Please use string, JSON format is not accepted. 
Length limit: 250 characters. A longer string may be truncated due to URL length limitation.
|| required for clients that have DAI service (Telia, Telenor, Allente, Comhem, Boxer, Sappa, Discovery, Cmore)
|-
| program || Program Name, ns_st_pr || program name || '''custom''' '''example:''' leif-och-billy 
Leave blank for simulcast. '''Please restrain from using special characters like "/" or ";"'''
|| ✓
|-
| title || Episode Name, ns_st_ep || episode name || '''custom''' '''example:''' en-ny-tjej-i-byn 
Leave blank for simulcast. '''Please restrain from using special characters like "/" or ";"'''
|| ✓
|-
| playlisttitle || Title Playlist, ns_st_pl || playlist reference as a string || string value with playlist name for '''example:''' barn ||
|-
| ispremiumcontent || MMS Premium, mms_premium || identify premium level via yes or no || "yes" or "no" || ✓
|-
| isautoplay || Auto Start, mms_auto || identify if autoplay is enabled on the video || "yes" or "no" || ✓
|-
| plugv || Player Version, ns_st_mv || player version. increment by 1 for each new version. || alphanumeric '''example:''' 1.0.1 || ✓
|-
| playerv || Mediaplayer, ns_st_mp || player identifier || alphanumeric '''example:''' HTML5, JW Player, Sonic || ✓
|}

Example of metadata object for content:

<syntaxhighlight lang="javascript">
var contentMetadataObject = {
type: "content",
userid: "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa…",
assetid: "simulcast_29",
length: "3359", //seconds
clientpassparam: "origcode=29",
program: "leif-och-billy",
title: "en-ny-tjej-i-byn",
playlisttitle: "barn",
ispremiumcontent: "yes",
isautoplay: "yes",
plugv: "1.0.1",
playerv: "Sonic"
};
</syntaxhighlight>

== Ad Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || Ad Type, ns_st_ad || type of ad || "preroll", "midroll", "postroll", "ad" if specific ad type cannot be identified. || ✓
|-
| assetid || Film Code, mms_customadid || custom Ad ID || Film code/Copy code.
'''Custom examples''': S1MYME202B, 51TRER1001, H1KYLE3032, E1UMBR1001

In case of no Film Code is available, use the string "empty".

For programmatic ads that you are sending "programmatic" as Film Code today, use "programmatic_{current UTC time in epoch form}".
|| ✓
|-
| length || Clip Length, ns_st_cl || length of ad in seconds || Length of ad in seconds. || ✓
|-
| isprogrammatic || Programmatic, mms_programmatic || identify if the ad is bought prommatic. || "yes" or "no" ||
|-
| isthirdpartyad || MMS Thirdparty, mms_thirdparty || identify if the ad is from third party ad server || "yes" or "no" ||
|-
| adplatformorigin || MMS Origin, mms_origin || identify where an ad is originated. It is used when isprogrammatic=yes or isthirdpartyad=yes. || custom '''examples:''' Smartclip, YuMe
||
|-
| adidx || Position in Break, ns_st_an || placement in ad break. It is passed by ad servers. || Custom with the following format:
{ad placement}/{total number of ads in an ad break} 

'''Example:''' 2/5, the second ad in an ad break with 5 ads.
|| ✓
|-
| ad_campaign || MMS Ad campaign ID, campaign_id || campaign ID of an Ad || custom string value containing in general letters and digits ||
|}

Example of metadata object for Ad:

<syntaxhighlight lang="javascript">
var prerollMetadataObject = {
type: "preroll",
assetid: "E1UMBR1001",
length: "30", //seconds
isprogrammatic: "yes",
isthirdpartyad: "yes",
adplatformorigin: "YuMe",
adidx: "1/5"
};
</syntaxhighlight>

DCR France Video Browser SDK

2023-05-23T06:40:01Z

MichelFodjo: /* Review the Reference Implementation for VoD and Live Streams */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Mediametrie Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

__TOC__

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

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|}

=== Review SDK Integration Architecture Diagram ===

==== For Content Playback ====

[[File:nlsn-sdk-achitecture-diagram-content-fr.png||SDK Integration Architecture Diagram - Content]]

==== For Ad Playback ====
[[File:nlsn-sdk-achitecture-diagram-ad-fr.png||SDK Integration Architecture Diagram - Ad]]

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

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

Add the following script tag to the website i.e. within the <head></head> tag :

<syntaxhighlight lang="javascript">
!function(e,n){
function t(e){
return"object"==typeof e?JSON.parse(JSON.stringify(e)):e
}
e[n]=e[n]||
{
nlsQ:function(o,r,c){
var s=e.document,
a=s.createElement("script");
a.async=1,
a.src=("http:"===e.location.protocol?"http:":"https:")+"//cdn-gl.nmrodam.com/conf/"+o+".js#name="+r+"&ns="+n;
var i=s.getElementsByTagName("script")[0];
return i.parentNode.insertBefore(a,i),
e[n][r]=e[n][r]||{g:c||{},
ggPM:function(o,c,s,a,i){e[n][r].q=e[n][r].q||[];try{var l=t([o,c,s,a,i]);e[n][r].q.push(l)}
catch(e){console&&console.log&&console.log("Error: Cannot register event in Nielsen SDK queue.")}},
trackEvent:function(o){e[n][r].te=e[n][r].te||[];try{var c=t(o);e[n][r].te.push(c)}
catch(e){console&&console.log&&console.log("Error: Cannot register event in Nielsen SDK queue.")}}},
e[n][r]
}
}
}(window,"NOLBUNDLE");
</syntaxhighlight>
 

=== Create SDK Instance ===
To initialize the SDK, create an SDK instance by making the initialization call:

==== Initialization API Call ====
<syntaxhighlight lang="javascript">
NOLBUNDLE.nlsQ("<appid>", "<instanceName>",{nol_sdkDebug: "debug"});
</syntaxhighlight>
 
For creating an instance, pass the following values: (<code>nol_sdkDebug</code> is optional)
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| appid || Unique ID assigned to player/website || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
|instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging if desired. || <syntaxhighlight lang="javascript">
{nol_sdkDebug: "debug"}
</syntaxhighlight>
|}

When the initialization call is made, a unique static configuration file, <appid>.js, will be downloaded based on the appid and will be cached on the user’s browser.

==== Sample SDK Initialization Call ====

<syntaxhighlight lang="javascript">

var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance", {
nol_sdkDebug: "debug"
});

</syntaxhighlight>

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

=== Create Metadata Objects ===
Before starting any measurement of an asset(Content or Ad) with the created SDK Instance, you need to create an asset metadata object in order to identify the asset.
There are two types of asset metadata:
*content: identify a video
*ad: identify each ad

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

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

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

Please see the [[France SDK Metadata#Content Metadata|Mediametrie Content Metadata]] for the complete list of content metadata.

==== Create Ad Metadata ====
The Ad Metadata (if applicable) should be passed for each individual ad.

Note: All metadata values should be passed as UTF-8 strings.

Please see the [[France SDK Metadata#Ad Metadata|Mediametrie Ad Metadata]] for the complete list of content metadata.
 
<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>

=== Start the Measurement ===
Nielsen APIs calls are made by calling the function ggPM("event", parameter, ...) with "event" Parameter indicating the SDK API.
<syntaxhighlight lang="javascript">
nSdkInstance.ggPM("event", parameter, ...);
</syntaxhighlight>

{| 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 
* VOD: current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3... 
* Live: Unix timestamp matching the broadcast time for Content and Ad (seconds since Jan-1-1970 UTC). Pass whole number that increments only by 1 like 1631098029,1631098030,1631098031,1631098032,... 
||
Pass playhead position every second during playback, the value passed should match the broadcast time for live channel.

|-
| "stop" || playhead position in seconds || Call when content interrupted/paused 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. 
Example: At the end of the content stream, if the user switches to another piece of content, when the browser is refreshed or closed.
|}

Start the measurement by calling the "event" names "loadMetadata" followed by "setPlayheadPosition".

<syntaxhighlight lang="javascript">
// START OF STREAM (main content)
nSdkInstance.ggPM("loadMetadata", contentMetadataObject);
// CONTENT plays
// pass playhead every second
nSdkInstance.ggPM("setPlayheadPosition", playheadPosition);
</syntaxhighlight>

== Stop/Resume the Measurement for video Playback Interruptions ==

=== Handle Video Playback Interruption ===
The setPlayheadPostion event is used for handling playback interruption. To indicate that the video player is not playing (i.e. paused, buffering), stop passing the playhead position to the SDK.
Once the Playback resumes , begin sending the playhead position again with the correct playhead value.

=== List of video Playback Interruptions ===
The following possible video Playback Interruptions must be handled:
* Player PAUSED
* Player BUFFERING
* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button
* Network Loss

=== Example for handling Playback Interruption: Browser/Tab close/Page Reload ===
<syntaxhighlight lang="javascript">
window.addEventListener("beforeunload", function(event)
{
// Only inside an Ad indicate <stop> for the ad
nSdkInstance.ggPM("stop", playheadPosition);

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

<blockquote>'''Note:''' additional code may be needed in order to support specific browser versions (e.g. older versions of Internet Explorer).</blockquote>

== SDK Call Sequence ==
The sample event lifecycles can be used as a reference for identifying the order for calling events.

=== Content Playback Call Sequence ===
<syntaxhighlight lang="javascript">
// START OF STREAM
nSdkInstance.ggPM("loadMetadata", contentMetadataObject);
// CONTENT plays
// pass playhead every second
//
nSdkInstance.ggPM("setPlayheadPosition", playheadPosition);
//
// END OF STREAM
nSdkInstance.ggPM("end", playheadPosition);
</syntaxhighlight>

=== Ad Playback Call Sequence ===
<syntaxhighlight lang="javascript">
// START OF Ad
nSdkInstance.ggPM("loadMetadata", adMetadataObject);
// Ad plays
// pass playhead every second
//
nSdkInstance.ggPM("setPlayheadPosition", playheadPosition);
// END OF Ad
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" or "end".

* For Ad Pods, events must be called for each individual Ad. Each Ad playhead position should begin at "0" when an 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>

== Review the Reference Implementation for VoD and Live Streams ==

The Reference Implementation covers vod and Live use cases.
It also covers DAI (Dynamic Ad Insertion) with preroll and postroll Ads.

 
Make sure the country "France" is selected in the country dropdown list.
 
In order to start live stream select the checkbox "isLive" below the video player.

Start the Reference Implementation for Mediametrie [https://nielsenonlinesupport.com/mediametrie/sdkRefImpl/index.htm sdkRefImpl].
<blockquote>
Review the Nielsen SDK Call Sequence below the Video Player.
</blockquote>

== Disclose Nielsen Privacy Statement ==
The Browser SDK video measurement does not set cross-domain cookies, therefore no centralized opt-out functionality is available. The Nielsen Browser SDK does not set cookies associated with the collection domain. The SDK sets specific cookie for the domain where the player is hosted (first party) and this cookie is not used across websites.
The only personal information collected with the SDK network pings is the IP address, which is anonymized immediately after collection.

In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://www.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/ .

== Test your player by yourself ==
=== Guide ===
1. Run your player in the Browser, start a video 
2. Open the Developer Network View in order to monitor network traffic 
3. Filter the network traffic by "nmr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-fr.nmrodam.com/cgi-bin/gn?prd=dcr&ci=us-500207&ch=us-500207_c77_P&asn=defChnAsset&fp_id=xknspa6p3viv2medizzvw8tld2smg1682583576&fp_cr_tm=1682583576685&fp_acc_tm=1684322226258&fp_emm_tm=1684322226288&ve_id=&sessionId=c81tzsiqvhqm6zswkeftmjjyip3fe1684322243&tl=Episode%201&prv=1&c6=vc,c77&ca=us-500207_c77_VID5556674-123456&cg=TAMSample%20FR&c13=asid,P1D11AF9D-E3FE-438C-B861-ED47543FF0E2&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=&playerv=&sup=1&segment2=&segment1=&forward=0&ad=0&cr=4_00_99_D1_00000&c9=devid,&enc=true&c1=nuid,999&at=timer&rt=video&c16=sdkv,bj.6.0.0&c27=cln,6&crs=&lat=&lon=&c29=plid,16843222430632178&c30=bldv,6.0.0.662&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,NA&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,&c51=adl,15&c52=noad,0&sd=170&pc=NA&c53=fef,y&c54=oad,20200713%2010%3A22%3A00&c55=cref3,&c57=adldf,2&ai=VID5556674-123456&c3=st,c&c64=starttm,1684322269&adid=VID5556674-123456&c58=isLive,false&c59=sesid,3dn2br9l4y9rr2iuxycsdnlh3zwvd1684322245&c61=createtm,1684322275&c63=pipMode,&c68=bndlid,&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=&c71=ottflg,0&c72=otttyp,none&c44=progen,&davty=1&si=https%3A%2F%2Fnielsenonlinesupport.com%2Fmichel%2Fmediametrie%2FsdkRefImpl%2Findex.htm&c66=mediaurl,assets%252FRTVOD_C3%252Fprog_index.m3u8&sdd=&c62=sendTime,1684322275&rnd=582363</nowiki></code>

== Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Going Live ==
After the integration has been certified (but not prior that), disable debug logging by deleting {nol_sdkDebug: "DEBUG"} from Initialization API Call.

Mediametrie Implementation Documentation

2023-05-17T15:03:10Z

MichelFodjo:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
{{CategoryIcon|DCR.png|Mediametrie Documentation}}

__NOTOC__

<blockquote>The following guides are specific for Mediametrie.</blockquote>

{| class="wikitable"
|-
! style="width: 90px;" | Mediametrie
! style="width: 90px;" | Type
! style="width: 45px;" |
! style="width: 45px;" | OS
! style="width: 40%;" | Guide
!| Links
|-
| rowspan="4" | {{SmallIcon|FRFlag.png}}
| rowspan="4" | {{SmallIcon|SDKIcon.png}}
| rowspan="4" | {{OSIcon|VideoIcon.png}}
|-
| {{OSIcon|macOSIcon.png}}
| '''[[DCR France Video iOS SDK]]'''
|
|-
| {{OSIcon|AndroidIcon.png}}
| '''[[DCR France Video Android SDK]]'''
|
|-
| {{OSIcon|BrowserIcon.png}}
| '''[[DCR France Video Browser SDK]]'''
|
|}

France SDK Metadata

2023-05-17T14:32:37Z

MichelFodjo: Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Mediametrie Implementation Documentation}} {{CurrentBreadcrumb}} Category:Digital = France SDK Metadata = Digital Met..."

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Mediametrie Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= France SDK Metadata =
Digital Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.
 
'''Section 1''' focuses on the Content metadata
 
'''Section 2''' focuses on the Ad metadata.
 

'''Note:''' All metadata values should be passed as '''UTF-8 strings'''. 

__TOC__

== Content Metadata ==
==== Create Content Metadata ====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''. 
 

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || "content" for main content || ✓
|-
| assetid || unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| program || name of program || custom || ✓
|-
| title || episode name || custom || ✓
|-
| length || length of content in seconds || Length of content in seconds (86400 seconds for live stream (24/7). For Event-Live streams planned length. For VoD video length)|| ✓
|-
| airdate || the original date (local time with hh:mm:ss as 24h time stamp) content became available. This date does not change if the content is rebroadcasted on linear TV. || YYYYMMDD HH:MI:SS (if not known set it to eg. "19700101 00:00:00") || ✓
|-
| isfullepisode || full episode flag ||
* "y" full episode (full content for a program)
* "n" non full episode (only one part of the entire content for a program , i.e. preview, sub-episodes)
||
✓
|-
|adloadtype || type of Ad load
||
:
* "1" Linear - matches TV ad load
* "2" Dynamic - Dynamic Ad Insertion (DAI)
||
✓
|-
|islivestn || Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || vcid/sub-brand/Channel ID – value is automatically populated through provided AppID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands/Channels in the App)
||
provided by Nielsen
||
✓
|}

===== Example Content Object =====
<syntaxhighlight lang="javascript">
var contentMetadataObject =
{
type: "content",
assetid: "unique_content_id",
program: "program name",
title: "episode title",
length: "length in seconds",
airdate: "20200713 10:22:00",
isfullepisode: "y",
adloadtype: "2",
subbrand: "c05",
islivestn: "y"
};
</syntaxhighlight>

== Ad Metadata ==
==== Create Ad Metadata ====
The Ad Metadata (if applicable) should be passed for each individual ad.

'''Note:''' All metadata values should be passed as '''UTF-8 strings'''. 

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || "preroll", "midroll", "postroll". "ad" If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to Ad || custom (no [[Special Characters]]) || ✓
|-
| length || length of the Ad in seconds || length of the Ad in seconds|| ✓
|-
|islivestn || Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || vcid/sub-brand/Channel ID – value is automatically populated through provided AppID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands/Channels in the App) || provided by Nielsen || ✓
|}

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
var adMetadataObject =
{
type: "preroll",
assetid: "unique_preroll_ad_id",
length: "length in seconds",
subbrand: "c05",
islivestn: "y"
};
</syntaxhighlight>
 
<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>

DCR France Video Browser SDK

2023-05-17T14:30:49Z

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Mediametrie Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

__TOC__

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

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|}

=== Review SDK Integration Architecture Diagram ===

==== For Content Playback ====

[[File:nlsn-sdk-achitecture-diagram-content-fr.png||SDK Integration Architecture Diagram - Content]]

==== For Ad Playback ====
[[File:nlsn-sdk-achitecture-diagram-ad-fr.png||SDK Integration Architecture Diagram - Ad]]

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

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

Add the following script tag to the website i.e. within the <head></head> tag :

<syntaxhighlight lang="javascript">
!function(e,n){
function t(e){
return"object"==typeof e?JSON.parse(JSON.stringify(e)):e
}
e[n]=e[n]||
{
nlsQ:function(o,r,c){
var s=e.document,
a=s.createElement("script");
a.async=1,
a.src=("http:"===e.location.protocol?"http:":"https:")+"//cdn-gl.nmrodam.com/conf/"+o+".js#name="+r+"&ns="+n;
var i=s.getElementsByTagName("script")[0];
return i.parentNode.insertBefore(a,i),
e[n][r]=e[n][r]||{g:c||{},
ggPM:function(o,c,s,a,i){e[n][r].q=e[n][r].q||[];try{var l=t([o,c,s,a,i]);e[n][r].q.push(l)}
catch(e){console&&console.log&&console.log("Error: Cannot register event in Nielsen SDK queue.")}},
trackEvent:function(o){e[n][r].te=e[n][r].te||[];try{var c=t(o);e[n][r].te.push(c)}
catch(e){console&&console.log&&console.log("Error: Cannot register event in Nielsen SDK queue.")}}},
e[n][r]
}
}
}(window,"NOLBUNDLE");
</syntaxhighlight>
 

=== Create SDK Instance ===
To initialize the SDK, create an SDK instance by making the initialization call:

==== Initialization API Call ====
<syntaxhighlight lang="javascript">
NOLBUNDLE.nlsQ("<appid>", "<instanceName>",{nol_sdkDebug: "debug"});
</syntaxhighlight>
 
For creating an instance, pass the following values: (<code>nol_sdkDebug</code> is optional)
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| appid || Unique ID assigned to player/website || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
|instanceName || Name of SDK instance || "any string value"
|-
| nol_sdkDebug || Enables Nielsen console logging if desired. || <syntaxhighlight lang="javascript">
{nol_sdkDebug: "debug"}
</syntaxhighlight>
|}

When the initialization call is made, a unique static configuration file, <appid>.js, will be downloaded based on the appid and will be cached on the user’s browser.

==== Sample SDK Initialization Call ====

<syntaxhighlight lang="javascript">

var nSdkInstance = NOLBUNDLE.nlsQ("PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX", "nlsnInstance", {
nol_sdkDebug: "debug"
});

</syntaxhighlight>

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

=== Create Metadata Objects ===
Before starting any measurement of an asset(Content or Ad) with the created SDK Instance, you need to create an asset metadata object in order to identify the asset.
There are two types of asset metadata:
*content: identify a video
*ad: identify each ad

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

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

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

Please see the [[France SDK Metadata#Content Metadata|Mediametrie Content Metadata]] for the complete list of content metadata.

==== Create Ad Metadata ====
The Ad Metadata (if applicable) should be passed for each individual ad.

Note: All metadata values should be passed as UTF-8 strings.

Please see the [[France SDK Metadata#Ad Metadata|Mediametrie Ad Metadata]] for the complete list of content metadata.
 
<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>

=== Start the Measurement ===
Nielsen APIs calls are made by calling the function ggPM("event", parameter, ...) with "event" Parameter indicating the SDK API.
<syntaxhighlight lang="javascript">
nSdkInstance.ggPM("event", parameter, ...);
</syntaxhighlight>

{| 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 
* VOD: current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3... 
* Live: Unix timestamp matching the broadcast time for Content and Ad (seconds since Jan-1-1970 UTC). Pass whole number that increments only by 1 like 1631098029,1631098030,1631098031,1631098032,... 
||
Pass playhead position every second during playback, the value passed should match the broadcast time for live channel.

|-
| "stop" || playhead position in seconds || Call when content interrupted/paused 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. 
Example: At the end of the content stream, if the user switches to another piece of content, when the browser is refreshed or closed.
|}

Start the measurement by calling the "event" names "loadMetadata" followed by "setPlayheadPosition".

<syntaxhighlight lang="javascript">
// START OF STREAM (main content)
nSdkInstance.ggPM("loadMetadata", contentMetadataObject);
// CONTENT plays
// pass playhead every second
nSdkInstance.ggPM("setPlayheadPosition", playheadPosition);
</syntaxhighlight>

== Stop/Resume the Measurement for video Playback Interruptions ==

=== Handle Video Playback Interruption ===
The setPlayheadPostion event is used for handling playback interruption. To indicate that the video player is not playing (i.e. paused, buffering), stop passing the playhead position to the SDK.
Once the Playback resumes , begin sending the playhead position again with the correct playhead value.

=== List of video Playback Interruptions ===
The following possible video Playback Interruptions must be handled:
* Player PAUSED
* Player BUFFERING
* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button
* Network Loss

=== Example for handling Playback Interruption: Browser/Tab close/Page Reload ===
<syntaxhighlight lang="javascript">
window.addEventListener("beforeunload", function(event)
{
// Only inside an Ad indicate <stop> for the ad
nSdkInstance.ggPM("stop", playheadPosition);

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

<blockquote>'''Note:''' additional code may be needed in order to support specific browser versions (e.g. older versions of Internet Explorer).</blockquote>

== SDK Call Sequence ==
The sample event lifecycles can be used as a reference for identifying the order for calling events.

=== Content Playback Call Sequence ===
<syntaxhighlight lang="javascript">
// START OF STREAM
nSdkInstance.ggPM("loadMetadata", contentMetadataObject);
// CONTENT plays
// pass playhead every second
//
nSdkInstance.ggPM("setPlayheadPosition", playheadPosition);
//
// END OF STREAM
nSdkInstance.ggPM("end", playheadPosition);
</syntaxhighlight>

=== Ad Playback Call Sequence ===
<syntaxhighlight lang="javascript">
// START OF Ad
nSdkInstance.ggPM("loadMetadata", adMetadataObject);
// Ad plays
// pass playhead every second
//
nSdkInstance.ggPM("setPlayheadPosition", playheadPosition);
// END OF Ad
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" or "end".

* For Ad Pods, events must be called for each individual Ad. Each Ad playhead position should begin at "0" when an 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>

== Review the Reference Implementation for VoD and Live Streams ==

The Reference Implementation covers vod and Live use cases.
It also covers DAI (Dynamic Ad Insertion) with preroll and postroll Ads.

 
Make sure the country "France" is selected in the country dropdown list.
 
In order to start live stream select the checkbox "isLive" below the video player.

Start the Reference Implementation for Mediametrie [https://nielsenonlinesupport.com/michel/mediametrie/sdkRefImpl/index.htm sdkRefImpl].
<blockquote>
Review the Nielsen SDK Call Sequence below the Video Player.
</blockquote>

== Disclose Nielsen Privacy Statement ==
The Browser SDK video measurement does not set cross-domain cookies, therefore no centralized opt-out functionality is available. The Nielsen Browser SDK does not set cookies associated with the collection domain. The SDK sets specific cookie for the domain where the player is hosted (first party) and this cookie is not used across websites.
The only personal information collected with the SDK network pings is the IP address, which is anonymized immediately after collection.

In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://www.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/ .

== Test your player by yourself ==
=== Guide ===
1. Run your player in the Browser, start a video 
2. Open the Developer Network View in order to monitor network traffic 
3. Filter the network traffic by "nmr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-fr.nmrodam.com/cgi-bin/gn?prd=dcr&ci=us-500207&ch=us-500207_c77_P&asn=defChnAsset&fp_id=xknspa6p3viv2medizzvw8tld2smg1682583576&fp_cr_tm=1682583576685&fp_acc_tm=1684322226258&fp_emm_tm=1684322226288&ve_id=&sessionId=c81tzsiqvhqm6zswkeftmjjyip3fe1684322243&tl=Episode%201&prv=1&c6=vc,c77&ca=us-500207_c77_VID5556674-123456&cg=TAMSample%20FR&c13=asid,P1D11AF9D-E3FE-438C-B861-ED47543FF0E2&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=&playerv=&sup=1&segment2=&segment1=&forward=0&ad=0&cr=4_00_99_D1_00000&c9=devid,&enc=true&c1=nuid,999&at=timer&rt=video&c16=sdkv,bj.6.0.0&c27=cln,6&crs=&lat=&lon=&c29=plid,16843222430632178&c30=bldv,6.0.0.662&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,NA&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,&c51=adl,15&c52=noad,0&sd=170&pc=NA&c53=fef,y&c54=oad,20200713%2010%3A22%3A00&c55=cref3,&c57=adldf,2&ai=VID5556674-123456&c3=st,c&c64=starttm,1684322269&adid=VID5556674-123456&c58=isLive,false&c59=sesid,3dn2br9l4y9rr2iuxycsdnlh3zwvd1684322245&c61=createtm,1684322275&c63=pipMode,&c68=bndlid,&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=&c71=ottflg,0&c72=otttyp,none&c44=progen,&davty=1&si=https%3A%2F%2Fnielsenonlinesupport.com%2Fmichel%2Fmediametrie%2FsdkRefImpl%2Findex.htm&c66=mediaurl,assets%252FRTVOD_C3%252Fprog_index.m3u8&sdd=&c62=sendTime,1684322275&rnd=582363</nowiki></code>

== Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Going Live ==
After the integration has been certified (but not prior that), disable debug logging by deleting {nol_sdkDebug: "DEBUG"} from Initialization API Call.

DCR France Video Android SDK

2023-05-17T14:29:20Z

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|Mediametrie Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

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

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || "App ID (appid)" || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || "Nielsen SDK" || Includes SDK frameworks and "sample implementation"; "See [[Android SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Step 1: Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service CLasses and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

== Step 2: Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || ✓ || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || '''value is automatically populated through App Name included in the App Resource File''' || || "Nielsen Sample App"
|-
| appversion || Current version of the app used || '''value is automatically populated through App Name included in the App Resource File''' || || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || || "DEBUG"
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("nol_devDebug", "DEBUG"); // only for debug builds

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("nol_devDebug", "DEBUG"); // only for debug builds

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# ""Initial state"" – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the ""Initial state"".
# ""Idle state"" – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# ""Processing state"" – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# ""Disabled state"" – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Step 3: Create Metadata Objects ==
The parameters passed must be either a JSON formatted string or a NSDictionary object. The JSON passed in the SDK must be well-formed.
* NSDictionary object
** If an object of unexpected type is passed to the method, the error message will be logged.
** If string has invalid JSON format, the error message will be logged.
* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

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

Note: All metadata values should be passed as UTF-8 strings.

Please see the [[France SDK Metadata#Content Metadata|Mediametrie Content Metadata]] for the complete list of content metadata.

=== Create Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.

Note: All metadata values should be passed as UTF-8 strings.

Please see the [[France SDK Metadata#Ad Metadata|Mediametrie Ad Metadata]] for the complete list of content metadata.
 

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelName","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "unique_content_id")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "length in seconds")
.put("airdate", "20200713 10:22:00")
.put("isfullepisode", "y")
.put("adloadtype", "2")
.put("subbrand", "c05")
.put("islivestn", "y");

JSONObject adMetadata = new JSONObject()
.put("assetid", "unique_postroll_ad_id")
.put("type", "postroll")
.put("length", "length in seconds")
.put("subbrand", "c05")
.put("islivestn", "y");

</syntaxhighlight>

== Step 4: Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
<pre style="background-color:#d0f6f8">
Note: "setPlayheadPosition" has to be called every second and the value passed should match the broadcast time for live channel.
</pre>
* VOD: current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3... 
* Live: Unix timestamp matching the broadcast time for Content and Ad (seconds since Jan-1-1970 UTC). Pass whole number that increments only by 1 like 1631098029,1631098030,1631098031,1631098032,... 

<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== Start the Measurement ===
In order to start the measurement, follow the 3 first steps below for Content without Ads. When terminating the Content playback call <code>end</code> to terminate the Content Measurement for the given asset.

{| class="wikitable"
|-
! Playlist !! Sample code !! Description
|-
| rowspan="2" | 1. Start of stream || <code>play(channelName)</code> || channelName contains JSON metadata of channel/video name being played
|-
| <code>loadMetadata(contentMetadataObject)</code> || contentMetadataObject contains the JSON metadata for the content being played
|-
| 2. Content is playing || <code>playheadPosition(position)</code> || playheadPosition is position of the playhead while the content is being played
|-
| 3. End of Stream || <code>end</code> || Content playback is completed.
|}

== Step 5: Stop/Resume the Measurement for video Playback Interruptions ==
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 <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Step 6: Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-fr.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-fr.png||SDK Integration Architecture Diagram - Ad]]

== Step 7 : Disclose Nielsen Privacy Statement ==
The App SDK uses Mobile Ad IDs (Android ID or IDFA) which are fully hashed on the device before being sent to Nielsen (Nielsen never receives un-hashed values).
Users retain the possibility to oppose the use of Mobile Ad IDs, or to reset them, by using the functionality provided by the mobile operating system (iOS or Android).

In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://www.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/ .

== Step 8 : Review the Reference Implementation for VoD and Live Streams ==

The Reference Implementation covers VoD and Live use cases.
It also covers DAI (Dynamic Ad Insertion) with preroll Ad.

Download the Reference Implementation for Android [https://nielsenonlinesupport.com/dk/android/DKRefPLAYER.zip DKRefPLAYER].
Unzip and open the project in Android Studio, then run it i.e. in the simulator or on Android device and then filter the Logcat output with ">>>" in order to see only relevant Nielsen SDK API Calls, as below:

<syntaxhighlight lang="java">
2021-04-08 15:11:27.075 D/NielsenInit: ====>>> SDK CALL : class NielsenInit :: Create new AppSdk() Instance.
2021-04-08 15:11:27.568 D/NielsenInit: ====>>> SDK EVENT - onAppSdkEvent: Description = Nielsen App SDK is initiated. AppSdk.jar aa.8.0.0.0_gsxaon. App SDK was successfully initiatedCode l param : 1617887487Code i param 2000
2021-04-08 15:11:29.497 D/NielsenInit: ====>>> SDK EVENT - onAppSdkEvent: Description = Nielsen App SDK has started up. AppSdk.jar aa.8.0.0.0_gsxaon. Config file successfully loaded and parsed.Code l param : 1617887489Code i param 2001
2021-04-08 15:11:42.736 D/MainActivity: ====>>> SDK CALL : appSdk.play(sdkMethods.loadChannelInfo());
2021-04-08 15:11:42.738 D/MainActivity: ====>>> SDK CALL : onPrepared() : appSdk.loadMetadata(data)
2021-04-08 15:11:43.065 D/MainActivity: ====>>> Media Player Event : onInfo ();what = 3
2021-04-08 15:11:43.065 D/MainActivity: ====>>> Media Player Event : first video frame pushed for rendering.
2021-04-08 15:11:43.747 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 0 / 224
2021-04-08 15:11:44.752 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 1 / 224
2021-04-08 15:11:45.759 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 2 / 224
2021-04-08 15:11:46.764 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 3 / 224
2021-04-08 15:11:47.767 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 4 / 224
2021-04-08 15:11:48.772 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 5 / 224
2021-04-08 15:11:49.777 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 6 / 224
2021-04-08 15:11:50.781 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 7 / 224
2021-04-08 15:11:51.819 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 8 / 224
2021-04-08 15:11:51.821 D/MainActivity: ====>>> Activity onPause()
2021-04-08 15:11:52.668 D/MainActivity: ====>>>: Activity onDestroy()
2021-04-08 15:11:52.668 D/MainActivity: ====>>> SDK CALL : terminateNielsenSDK () :appSdk.end();
</syntaxhighlight>

== Step 9 : Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "nmr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-fr.nmrodam.com/cgi-bin/gn?prd=dcr&ci=us-500207&ch=us-500207_c77_P&asn=defChnAsset&fp_id=&fp_cr_tm=&fp_acc_tm=&fp_emm_tm=&ve_id=&devmodel=&manuf=&sysname=&sysversion=&sessionId=zlmmxkq867zt4bpnumlyz6dpn9hyp1610980356&tl=Episode%201&prv=1&c6=vc%2Cc77&ca=us-500207_c77_VID5556674-123456&cg=TAMSample%20DK&c13=asid%2CP10DF14BA-937E-436D-99DF-ED39A0422387&c32=segA%2CNA&c33=segB%2CNA&c34=segC%2CNA&c15=apn%2C&plugv=&playerv=&sup=1&segment2=&segment1=&forward=0&ad=0&cr=4_00_99_V1_00000&c9=devid%2C&enc=true&c1=nuid%2C999&at=view&rt=video&c16=sdkv%2Cbj.6.0.0&c27=cln%2C0&crs=&lat=&lon=&c29=plid%2C16109803568088038&c30=bldv%2C6.0.0.563&st=dcr&c7=osgrp%2C&c8=devgrp%2C&c10=plt%2C&c40=adbid%2C&c14=osver%2CNA&c26=dmap%2C1&dd=&hrd=&wkd=&c35=adrsid%2C&c36=cref1%2C&c37=cref2%2C&c11=agg%2C1&c12=apv%2C&c51=adl%2C0&c52=noad%2C0&sd=170&devtypid=&pc=NA&c53=fef%2Cy&c54=oad%2C20200713%2010%3A22%3A00&c55=cref3%2C&c57=adldf%2C2&ai=VID5556674-123456&c3=st%2Cc&c64=starttm%2C1610980392&adid=VID5556674-123456&c58=isLive%2Cfalse&c59=sesid%2Cgezrb92q4i9b9jg7acxgn783gjw0a1610980365&c61=createtm%2C1610980392&c63=pipMode%2C&c68=bndlid%2C&nodeTM=&logTM=&c73=phtype%2C&c74=dvcnm%2C&c76=adbsnid%2C&c77=adsuprt%2C2&uoo=&evdata=&c71=ottflg%2C0&c72=otttyp%2Cnone&c44=progen%2C&davty=0&si=http%3A%2F%2Fnielsenonlinesupport.com%2Fdk%2Findex.htm&c66=mediaurl%2Cassets%252FRTVOD_C3%252Fprog_index.m3u8&c62=sendTime%2C1610980392&rnd=714644</nowiki></code>

== Step 10 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Step 11 : Going Live ==
After the integration has been certified (but not prior that), disable debug logging by deleting {nol_devDebug: "DEBUG"} from initialization call - see Step 2.

File:nlsn-sdk-achitecture-diagram-ad-fr.png

2023-05-17T14:27:02Z

MichelFodjo: nlsn-sdk-achitecture-diagram-ad-fr.png

== Summary ==
nlsn-sdk-achitecture-diagram-ad-fr.png

File:nlsn-sdk-achitecture-diagram-content-fr.png

2023-05-17T14:25:49Z

MichelFodjo: nlsn-sdk-achitecture-diagram-content-fr.png

== Summary ==
nlsn-sdk-achitecture-diagram-content-fr.png

Sweden SDK Metadata

2023-04-26T08:58:24Z

MichelFodjo:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= Digital Metadata =
Digital Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.
 
'''Section 1''' focuses on the content metadata
 
'''Section 2''' focuses on the Ad metadata.
 

'''Note:''' All metadata values should be passed as UTF-8 strings. 

== Content Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| userid || || the user login ID. Used by MMS reach model. ''The uploaded value needs to be hashed with SHA512''. This is the user login ID on player. We prefer a numeric value. (please '''do not''' use user email address)|| "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa..." || required if login feature

|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. (max: 20 characters). In addition to this metadata for content needs to be reported to MMS via TitleService. Contact online@mms.se for more information. ||
For VoD use internal format. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters] 
For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 
A complete list of channel reference libraries with channel numbers is on the [https://mms.se/for-vara-kunder/teknisk-dokumentation-tv/referensbandade-kanaler/ MMS homepage] tab "referensbandade kanaler".
|| ✓ 
|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for VoD, video length
* for event-Live stream, the planned length. If planned length not available, then put default value 0
* for simulcast and 24/7 live stream, 86400
|| ✓
|-
| clientpassparam || MMS Values, mms_values || pass-through parameters || For clients that provide DAI (dynamic ad insertion) service, this has a standard format: origcode=channelnumber.
'''Example:''' origcode=29
See the complete list of channel reference library with the channel number on [https://mms.se/for-vara-kunder/teknisk-dokumentation-tv/referensbandade-kanaler/ MMS homepage] tab "referensbandade kanaler". Please use string, JSON format is not accepted. 
Length limit: 250 characters. A longer string may be truncated due to URL length limitation.
|| required for clients that have DAI service (Telia, Telenor, Allente, Comhem, Boxer, Sappa, Discovery, Cmore)
|-
| program || Program Name, ns_st_pr || program name || '''custom''' '''example:''' leif-och-billy 
Leave blank for simulcast. '''Please restrain from using special characters like "/" or ";"'''
|| ✓
|-
| title || Episode Name, ns_st_ep || episode name || '''custom''' '''example:''' en-ny-tjej-i-byn 
Leave blank for simulcast. '''Please restrain from using special characters like "/" or ";"'''
|| ✓
|-
| playlisttitle || Title Playlist, ns_st_pl || playlist reference as a string || string value with playlist name for '''example:''' barn ||
|-
| ispremiumcontent || MMS Premium, mms_premium || identify premium level via yes or no || "yes" or "no" || ✓
|-
| isautoplay || Auto Start, mms_auto || identify if autoplay is enabled on the video || "yes" or "no" || ✓
|-
| plugv || Player Version, ns_st_mv || player version. increment by 1 for each new version. || alphanumeric '''example:''' 1.0.1 || ✓
|-
| playerv || Mediaplayer, ns_st_mp || player identifier || alphanumeric '''example:''' HTML5, JW Player, Sonic || ✓
|}

Example of metadata object for content:

<syntaxhighlight lang="javascript">
var contentMetadataObject = {
type: "content",
userid: "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa…",
assetid: "simulcast_29",
length: "3359", //seconds
clientpassparam: "origcode=29",
program: "leif-och-billy",
title: "en-ny-tjej-i-byn",
playlisttitle: "barn",
ispremiumcontent: "yes",
isautoplay: "yes",
plugv: "1.0.1",
playerv: "Sonic"
};
</syntaxhighlight>

== Ad Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || Ad Type, ns_st_ad || type of ad || "preroll", "midroll", "postroll", "ad" if specific ad type cannot be identified. || ✓
|-
| assetid || Film Code, mms_customadid || custom Ad ID || Film code/Copy code.
'''Custom examples''': S1MYME202B, 51TRER1001, H1KYLE3032, E1UMBR1001

In case of no Film Code is available, use the string "empty".

For programmatic ads that you are sending "programmatic" as Film Code today, use "programmatic_{current UTC time in epoch form}".
|| ✓
|-
| length || Clip Length, ns_st_cl || length of ad in seconds || Length of ad in seconds. || ✓
|-
| isprogrammatic || Programmatic, mms_programmatic || identify if the ad is bought prommatic. || "yes" or "no" ||
|-
| isthirdpartyad || MMS Thirdparty, mms_thirdparty || identify if the ad is from third party ad server || "yes" or "no" ||
|-
| adplatformorigin || MMS Origin, mms_origin || identify where an ad is originated. It is used when isprogrammatic=yes or isthirdpartyad=yes. || custom '''examples:''' Smartclip, YuMe
||
|-
| adidx || Position in Break, ns_st_an || placement in ad break. It is passed by ad servers. || Custom with the following format:
{ad placement}/{total number of ads in an ad break} 

'''Example:''' 2/5, the second ad in an ad break with 5 ads.
|| ✓
|-
| ad_campaign || MMS Ad campaign ID, campaign_id || campaign ID of an Ad || custom string value containing in general letters and digits ||
|}

Example of metadata object for Ad:

<syntaxhighlight lang="javascript">
var prerollMetadataObject = {
type: "preroll",
assetid: "E1UMBR1001",
length: "30", //seconds
isprogrammatic: "yes",
isthirdpartyad: "yes",
adplatformorigin: "YuMe",
adidx: "1/5"
};
</syntaxhighlight>

DCR Germany Static Browser SDK

2023-03-31T09:43:18Z

MichelFodjo:

AGF Metadata Convention

2023-03-31T09:40:37Z

MichelFodjo:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__TOC__

= AGF Metadata Convention =

The Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.

'''Note:''' All metadata values should be passed as UTF-8 strings. 

== Static Measurement ==

<blockquote>'''AppSDK version >= 9.1.0.0 is required''': <pre style="color: red">
The newly introduced AppSDK API staticEnd() is required for the Static Measurement.
The staticEnd() API is available only for AppSDK version 9.1.0.0 or higher </pre>
</blockquote>

{| class="wikitable"
|-
! Key !! Description !! Values !! Required (Obligatory) !! AGF Convention !! Example data - RTL
|-
| type || type of asset || <code>"static"</code> || ✓ || hardcoded string required by Nielsen || <code>"static"</code>
|-
| assetid || unique ID assigned to each article/page; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations) || custom (no [[Special Characters]]) || ✓ || Content Article ID. If it is not an article page and therefore no ID is available, the page path is used. || "999452"
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section) || custom (no [[Special Characters]]) || ✓ || Section of Website or App || "_rtl_portal_news"
|-
| segA || custom segment for reporting: unique values across custom segments (segA + segB + segC) || custom || ✓ || AGOF code or comparable unit code. If the AGOF code is not available, set "Unknown" || "dbrsowf_rtlnews"
|-
| segB || custom segment for reporting: unique values across custom segments (segA + segB + segC) || custom || ✓ || Value to define content view count vs. 'Werbetraeger' view count. For Content: "CPI" . For 'Werbetraeger': "WPI" || For Content: "CPI" . For 'Werbetraeger' after user interaction with the site and newly loaded Content: "WPI".
|-
| segC || custom segment for reporting: unique values across custom segments (segA + segB + segC) || custom || || Program name || "IBES"
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen || ✓ || Same as video measurement, provided by Nielsen || "c01"
|}

== Video Measurement ==

Please refer to this AGF PDF Document: '''[https://nielsendownloads.digitalengsdk.com/digital/220907_AGF+Custom+Variables+and+Metadata+DCR+SDK++v1.8_english.pdf Metadata Document for Video]'''

DCR Germany Static App SDK

2023-03-31T09:39:56Z

MichelFodjo:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Overview ==
The Nielsen App SDK is one of multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for iOS and Android Apps developers to integrate Nielsen Measurement into their App for the Static Content Measurement.

This guide will show you how to enable Static measurement in your App. The Nielsen App Static Measurement of each different page/section requires different metadata.

== Prerequisites ==
* To get started, an AppID is needed. The AppID is a unique ID assigned to the App. This will be provided upon starting the integration from Nielsen.

<syntaxhighlight lang="javascript">
apid: "XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" // eg. PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA
</syntaxhighlight>

* <blockquote>'''No ID AppSDK''': <pre style="color: red">ONLY the No ID AppSDK should be downloaded for the AGF market!</pre>
</blockquote>

* <blockquote>'''AppSDK version >= 9.1.0.0 is required''': <pre style="color: red"> The newly introduced AppSDK API staticEnd() is available only for AppSDK version 9.1.0.0 or higher </pre>
</blockquote>

== Step 1: Set up your Development Environment ==

=== iOS ===
For setting up your iOS Development Environment, refer to [[DCR Germany Video App SDK#iOS]]

=== Android ===
For setting up your Android Development Environment, refer to [[DCR Germany Video App SDK#Android]]

== Step 2: Create and Initialize SDK Instance ==

The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. The sharedInstance API that creates a singleton object was deprecated prior to version 5.1.1. (Version 4.0 for Android)

* A maximum of four SDK instances per appid are supported. When a fifth SDK instance is launched, the SDK will return “nil” from [[initWithAppInfo:delegate:]]
* When four SDK instances exist, you must destroy an old instance before creating a new one.

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || ✓ || "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || No || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || No || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Has to be set to "DEBUG" until certified
|| Nielsen-specified || Optional || "DEBUG"
|}
 

==== Sample SDK Initialization Code ====

===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
 
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

====== Objective-C ======
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>If App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.</blockquote>
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
@"nol_devDebug": @"DEBUG"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

===== Android =====
====== Java ======

AppSDK is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="java">

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA")
.put("nol_devDebug", "DEBUG");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
Here, <code>appContext</code> is the App context object and <code>appSdkConfig</code> is JSON object for holding the parameters (<code>appid</code>, <code>appname</code>, <code>sfcode</code>) the App passes to the Nielsen App SDK via a JSON string. The appid is obtained from Nielsen operational support and is unique to the app.

The integration of Nielsen App SDK will depend on type of client app. 
* Ensure that SDK file AppSdk.jar is included under the App’s project and the App SDK is linked to the App (the setting to link App SDK to the App can be found on property page of the App’s project).

== Step 3: Review the APP SDK Error & Event Codes ==
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

== Step 4: Create Metadata Object for your page section ==

The full description of the other key/value pairs for Metadata can be found here:
'''[[AGF Metadata Convention#Static Measurement|AGF Metadata Convention for Static Measurement]]'''

=== Example Web Page Metadata Object ===

==== iOS ====

===== Swift =====
<syntaxhighlight lang="swift">
class SDKMethods : NSObject{
func loadStaticMaster() -> [String : Any] {
//Loading Static Main data
let staticData =
[
"type": "static",
"assetid": "Unique_asset_ID",
"section": "Unique_section_ID",
"segA": "Unique_section_segA",
"segB": "Mandatory_section_segB",
"segC": "Optional_section_segC",
"subbrand": "subbrand_received_from_Nielsen"
]
return staticData
}
</syntaxhighlight>

===== Objective-C =====

<syntaxhighlight lang="objective-c">
NSDictionary * staticMetadata = @ {
@ "type": @ "static",
@ "assetid": @ "Unique_asset_ID",
@ "section": @ "Unique_section_ID",
@ "segA": @ "Unique_section_segA",
@ "segB": @ "Mandatory_section_segB",
@ "segC": @ "Optional_section_segC",
@ "subbrand": @ "subbrand_received_from_Nielsen"
}
</syntaxhighlight>

==== Android ====
<syntaxhighlight lang="java"> staticMetadata = new JSONObject()
.put("type", "static")
.put("section", "Unique_section_ID")
.put("assetid", "Unique_asset_ID")
.put("segA", "Unique_section_segA")
.put("segB", "Mandatory_section_segB")
.put("segC","Optional_section_segC")
.put("subbrand","subbrand_received_from_Nielsen");
</syntaxhighlight>

== Step 5: Start the Measurement by calling the loadMetadata AppSDK API ==

Use the metadata object created in the previous step in the loadMetadata AppSDK API Call.

{{ExampleCode|
|Android = <syntaxhighlight lang="java">public void loadMetadata(JSONObject contentMetadata);</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">- (void)loadMetadata:(id)contentMetadata;</syntaxhighlight>
}}
 
<blockquote>
[[Image:AlertIcon.png|left|60px|link=|class=smallIcon]] Call <code>staticEnd()</code> to stop the static measurement of the current page before starting a new measurement with <code>loadMetadata()</code> for the next page.'''
</blockquote>

== Step 6: Include the measurement of Advertising Medium (Werbeträger) if applicable ==

=== Description ===

A page impression is a user action on the page that leads or could lead to an advertisement being called up. Each user action may only be counted once.

However, a page impression occurs when the content of the viewport of the respective device is completely reloaded/rendered by scrolling/swiping and replaced by new
content.

When counting views, a distinction is made between content
views (CPI) and advertising medium views after a user action (WPI). There can be
only one content view per page. Each additional user action on the same page (click,
scroll or swipe, e.g. click through an image gallery) will lead to an advertising medium view (WPI) accordingly. The implementation should follow the IVW guidelines for
defining user actions.

'''Note''':
The differentiation between the measurement of Content vs. advertising medium is achieved by setting accordingly the "segB" value in the metadata object , see '''[[AGF Metadata Convention#Static Measurement|AGF Metadata Convention for Static Measurement]]'''

=== Implementation Details ===
How to trigger a page impression for advertising medium?
In order to trigger a new view for an advertising medium, you have to stop the measurement of the page and start the measurement of the advertising medium, see example code below:

==== Stop static measurement for the page(current metadata): ====
{{ExampleCode|
|Android = <syntaxhighlight lang="java"> public void staticEnd(); </syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">- (void)staticEnd; </syntaxhighlight>
}}

==== Start static measurement for the advertising medium after user interaction(new metadata): ====
{{ExampleCode|
|Android = <syntaxhighlight lang="java">public void loadMetadata(JSONObject contentMetadata);</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">- (void)loadMetadata:(id)contentMetadata;</syntaxhighlight>
}}

== Step 7: Privacy and Opt-Out ==

The AppSDK measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen AppSDK measurement is utilizing a cookieless domain.
In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=de .

Please contact your Nielsen SDK support team directly for any related questions.

== Step 8: Going Live ==
Following Nielsen testing, users need to make one update to the initialization call to ensure that the site is being measured properly.

# '''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:

'''<big>iOS Example:</big>'''

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
// Remove Flag: "nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

'''<big>Android Example:</big>'''
<syntaxhighlight lang="java">
try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
// Remove Flag: "nol_devDebug": "DEBUG"

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>

'''Note''': before going live you have to inform Nielsen team - this is necessary, because Nielsen team has to adjust internal configuration parameter to enable data collection. Without that notification no data will be collected and no data will be reported.

AGF Implementation Documentation

2023-03-31T07:41:55Z

MichelFodjo:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
{{CategoryIcon|DCR.png|AGF Documentation & Downloads}}

__NOTOC__

<blockquote>The following guides are specific for AGF.</blockquote>

<h1>Video Measurement</h1>

{| class="wikitable"
|-
| colspan="6" style="background-color:white;" |
|-
! colspan="6" style="text-align: center;" |'''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''
|-
! style="width: 90px;" | AGF
! style="width: 90px;" |
! style="width: 45px;" |
! style="width: 45px;" | OS
!| Guide
!| Download
|-
| rowspan="4" | {{SmallIcon|DEFlagIcon.png}}
| rowspan="3" | {{SmallIcon|SDKIcon.png}}
| rowspan="4" | {{OSIcon|VideoIcon.png}}
| {{OSIcon|macOSIcon.png}}
| rowspan="2" | '''[[DCR Germany Video App SDK]]'''
| rowspan="2" |'''[[Special:Downloads|Download - NO ID AppSDK]]'''
|-
|{{OSIcon|AndroidIcon.png}}
|-
| {{OSIcon|BrowserIcon.png}}
| '''[[DCR Germany Video Browser SDK]]'''
| rowspan="2" |
|-
| {{SmallIcon|CloudAPIIcon.png}}
| {{OSIcon|APIIcon.png}}
| '''[[DCR Germany Video Cloud API]]'''
|}

<h1>Static Measurement</h1>

{| class="wikitable"
|-
| colspan="6" style="background-color:white;" |
|-
! colspan="6" style="text-align: center;" |'''[[AGF Metadata Convention#Static Measurement|AGF Metadata Convention for Static Measurement]]'''
|-
! style="width: 90px;" | AGF
! style="width: 90px;" |
! style="width: 45px;" |
! style="width: 45px;" | OS
!| Guide
!| Download
|-
| rowspan="5" | {{SmallIcon|DEFlagIcon.png}}
| rowspan="4" | {{SmallIcon|SDKIcon.png}}
| rowspan="5" | {{OSIcon|StaticIcon.png}}
| {{OSIcon|macOSIcon.png}}
| rowspan="2" | '''[[DCR Germany Static App SDK]]''' '''[[DCR Germany Static Hybrid App SDK]]'''
| rowspan="2" |'''[[Special:Downloads|Download - NO ID AppSDK]]'''
|-
|{{OSIcon|AndroidIcon.png}}
|-
| rowspan="3" |{{OSIcon|BrowserIcon.png}}
| '''[[DCR Germany Static Browser SDK]]'''
| rowspan="4" |
|-
| '''[[DCR Germany Static Google Tag Manager]]'''
|-
| {{SmallIcon|CloudAPIIcon.png}}
| '''[[DCR Germany Static Google AMP Cloud API]]'''
|}

DCR Germany Static Hybrid App SDK

2023-03-31T07:26:00Z

MichelFodjo:

DCR Germany Static Hybrid App SDK

2023-03-30T16:07:48Z

MichelFodjo: Created page with "{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}} Category:Digital <pre style="color: red"> PLease note that t..."

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

<pre style="color: red">
PLease note that this Hybrid App SDK Integration Guide is not yet released for AGF/Germany!
</pre>

== Overview ==
The Nielsen App SDK is one of multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for iOS and Android Apps developers to integrate Nielsen Measurement into their App for the Static Content Measurement.

This guide will show you how to enable Static measurement in the WebView of your Hybrid App. The Nielsen App Static Measurement of each different page/section requires different metadata.

== Prerequisites ==
* To get started, an AppID is needed. The AppID is a unique ID assigned to the App. This will be provided upon starting the integration from Nielsen.

<syntaxhighlight lang="javascript">
apid: "XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" // eg. PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA
</syntaxhighlight>

* <blockquote>'''No ID AppSDK''': <pre style="color: red">ONLY the No ID AppSDK should be downloaded for the AGF market!</pre>
</blockquote>

* <blockquote>'''WebView page is tagged with Browser SDK''': <pre style="color: red">Make sure that the content loaded in the WebView of your App is already tagged with Nielsen Browser SDK!</pre>
</blockquote>

== Step 1: Set up your Development Environment ==

=== iOS ===
For setting up your iOS Development Environment, refer to [[DCR Germany Video App SDK#iOS]]

=== Android ===
<blockquote>
<pre style="color: red">
NielsenAppSDKJSHandler in Android only supports Android X. Hence only get Android x enabled Appsdk.jar from Nielsen.
</pre>
</blockquote>
For setting up your Android Development Environment, refer to [[DCR Germany Video App SDK#Android]]

== Step 2: Implement the Nielsen AppSDK JS Handler ==

=== Description ===
Tag every page with BSDK, BSDK will check for availability of AppSDK handler in the page before loading itself. On the native side, inject the webview with JS handler which listens the call from BSDK and relay it to AppSDK and vice versa
On the native side, embed AppSDK in the App project, so that JS handler in webview can relay the calls from JS to native SDK interface.

=== Implementation ===

==== iOS ====

===== Add NielsenAppSDKJSHandler instance =====
Add NielsenAppSDKJSHandler instance as web view message handler object conforming to WKScriptMessageHandler protocol with name: "NielsenSDKMsg". That starts the listening to Browser SDK api calls in AppSDK.

====== Swift ======

<syntaxhighlight lang="swift">
self.jsAppSDK = NielsenAppSDKJSHandler(apiType: "ggPM") // or apiType:"any string" or apiType:nil
if let jsAppSDK = self.jsAppSDK {
self.webView?.configuration.userContentController.add(jsAppSDK, name: "NielsenSDKMsg")
}
</syntaxhighlight>

====== Objective-C ======
<syntaxhighlight lang="objective-c">
self.jsAppSDK = [[NielsenAppSDKJSHandler alloc] initWithApiType:@"ggPM"]; // or initWithApiType:@"any string" or initWithApiType:nil
[self.webView.configuration.userContentController addScriptMessageHandler:self.jsAppSDK name:@"NielsenSDKMsg"];
@end
</syntaxhighlight>

<blockquote>
Please make sure that you don't use any other name than “NielsenSDKMsg” for adding WKScriptMessageHandler instance as javascript listener otherwise you won't receive BSDK api calls in APPSDK.
</blockquote>

===== remove NielsenAppSDKJSHandler instance when WebView is being unloaded =====
To delete NielsenAppSDKJSHandler instance it should be detached from web view and pointer to it should be set to nil.

====== Swift ======

<syntaxhighlight lang="swift">
self.webView?.configuration.userContentController.removeScriptMessageHandler(forName: "NielsenSDKMsg")
self.jsAppSDK = nil
</syntaxhighlight>

====== Objective-C ======
<syntaxhighlight lang="objective-c">
[self.webView.configuration.userContentController removeScriptMessageHandlerForName:@"NielsenSDKMsg"];
self.jsAppSDK = nil;
</syntaxhighlight>

==== Android ====

===== Enable the javascript on webview using below lines =====

<syntaxhighlight lang="java">

WebSettings webSetting = webView.getSettings();
webSetting.setJavaScriptEnabled(true);

</syntaxhighlight>

===== Add NielsenAppSDKJSHandler instance as javascript interface to webview with name “NielsenAppSDK” =====

That starts the listening to Browser SDK api calls in AppSDK.

<syntaxhighlight lang="java">
webView.addJavascriptInterface(new NielsenAppSDKJSHandler(getApplicationContext()), "NielsenAppSDK");
</syntaxhighlight>

Sweden SDK Metadata

2023-02-21T08:19:22Z

MichelFodjo: /* Content Metadata */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= Digital Metadata =
Digital Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.
 
'''Section 1''' focuses on the content metadata
 
'''Section 2''' focuses on the Ad metadata.
 

'''Note:''' All metadata values should be passed as UTF-8 strings. 

== Content Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| userid || || the user login ID. Used by MMS reach model. ''The uploaded value needs to be hashed with SHA512''. This is the user login ID on player. We prefer a numeric value. (please '''do not''' use user email address)|| "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa..." || required if login feature

|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. (max: 20 characters). In addition to this metadata for content needs to be reported to MMS via TitleService. Contact online@mms.se for more information. ||
For VoD use internal format. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters] 
For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 
A complete list of channel reference libraries with channel numbers is on the [https://mms.se/for-vara-kunder/teknisk-dokumentation-tv/referensbandade-kanaler/ MMS homepage] tab "referensbandade kanaler".
|| ✓ 
|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for VoD, video length
* for event-Live stream, the planned length. If planned length not available, then put default value 0
* for simulcast and 24/7 live stream, 86400
|| ✓
|-
| clientpassparam || MMS Values, mms_values || pass-through parameters || For clients that provide DAI (dynamic ad insertion) service, this has a standard format: origcode=channelnumber.
'''Example:''' origcode=29
See the complete list of channel reference library with the channel number on [https://mms.se/for-vara-kunder/teknisk-dokumentation-tv/referensbandade-kanaler/ MMS homepage] tab "referensbandade kanaler". Please use string, JSON format is not accepted. 
Length limit: 250 characters. A longer string may be truncated due to URL length limitation.
|| required for clients that have DAI service (Telia, Telenor, Allente, Comhem, Boxer, Sappa, Discovery, Cmore)
|-
| program || Program Name, ns_st_pr || program name || '''custom''' '''example:''' leif-och-billy 
Leave blank for simulcast. '''Please restrain from using special characters like "/" or ";"'''
|| ✓
|-
| title || Episode Name, ns_st_ep || episode name || '''custom''' '''example:''' en-ny-tjej-i-byn 
Leave blank for simulcast. '''Please restrain from using special characters like "/" or ";"'''
|| ✓
|-
| playlisttitle || Title Playlist, ns_st_pl || playlist reference as a string || string value with playlist name for '''example:''' barn ||
|-
| ispremiumcontent || MMS Premium, mms_premium || identify premium level via yes or no || "yes" or "no" || ✓
|-
| isautoplay || Auto Start, mms_auto || identify if autoplay is enabled on the video || "yes" or "no" || ✓
|-
| plugv || Player Version, ns_st_mv || player version. increment by 1 for each new version. || alphanumeric '''example:''' 1.0.1 || ✓
|-
| playerv || Mediaplayer, ns_st_mp || player identifier || alphanumeric '''example:''' HTML5, JW Player, Sonic || ✓
|}

Example of metadata object for content:

<syntaxhighlight lang="javascript">
var contentMetadataObject = {
type: "content",
userid: "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa…",
assetid: "simulcast_29",
length: "3359", //seconds
clientpassparam: "origcode=29",
program: "leif-och-billy",
title: "en-ny-tjej-i-byn",
playlisttitle: "barn",
ispremiumcontent: "yes",
isautoplay: "yes",
plugv: "1.0.1",
playerv: "Sonic"
};
</syntaxhighlight>

== Ad Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || Ad Type, ns_st_ad || type of ad || "preroll", "midroll", "postroll", "ad" if specific ad type cannot be identified. || ✓
|-
| assetid || Film Code, mms_customadid || custom Ad ID || Film code/Copy code.
'''Custom examples''': S1MYME202B, 51TRER1001, H1KYLE3032, E1UMBR1001

In case of no Film Code is available, use the string "empty".

For programmatic ads that you are sending "programmatic" as Film Code today, use "programmatic_{current UTC time in epoch form}".
|| ✓
|-
| length || Clip Length, ns_st_cl || length of ad in seconds || Length of ad in seconds. || ✓
|-
| isprogrammatic || Programmatic, mms_programmatic || identify if the ad is bought prommatic. || "yes" or "no" ||
|-
| isthirdpartyad || MMS Thirdparty, mms_thirdparty || identify if the ad is from third party ad server || "yes" or "no" ||
|-
| adplatformorigin || MMS Origin, mms_origin || identify where an ad is originated. It is used when isprogrammatic=yes or isthirdpartyad=yes. || custom '''examples:''' Smartclip, YuMe
||
|-
| adidx || Position in Break, ns_st_an || placement in ad break. It is passed by ad servers. || Custom with the following format:
{ad placement}/{total number of ads in an ad break} 

'''Example:''' 2/5, the second ad in an ad break with 5 ads.
|| ✓
|}

Example of metadata object for Ad:

<syntaxhighlight lang="javascript">
var prerollMetadataObject = {
type: "preroll",
assetid: "E1UMBR1001",
length: "30", //seconds
isprogrammatic: "yes",
isthirdpartyad: "yes",
adplatformorigin: "YuMe",
adidx: "1/5"
};
</syntaxhighlight>

DCR Germany Static Browser SDK

2023-02-17T14:39:14Z

MichelFodjo:

DCR Germany Static App SDK

2023-02-17T14:37:09Z

MichelFodjo:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Overview ==
The Nielsen App SDK is one of multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for iOS and Android Apps developers to integrate Nielsen Measurement into their App for the Static Content Measurement.

This guide will show you how to enable Static measurement in your App. The Nielsen App Static Measurement of each different page/section requires different metadata.

== Prerequisites ==
* To get started, an AppID is needed. The AppID is a unique ID assigned to the App. This will be provided upon starting the integration from Nielsen.

<syntaxhighlight lang="javascript">
apid: "XXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" // eg. PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA
</syntaxhighlight>

* <blockquote>'''No ID AppSDK''': <pre style="color: red">ONLY the No ID AppSDK should be downloaded for the AGF market!</pre>
</blockquote>

== Step 1: Set up your Development Environment ==

=== iOS ===
For setting up your iOS Development Environment, refer to [[DCR Germany Video App SDK#iOS]]

=== Android ===
For setting up your Android Development Environment, refer to [[DCR Germany Video App SDK#Android]]

== Step 2: Create and Initialize SDK Instance ==

The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. The sharedInstance API that creates a singleton object was deprecated prior to version 5.1.1. (Version 4.0 for Android)

* A maximum of four SDK instances per appid are supported. When a fifth SDK instance is launched, the SDK will return “nil” from [[initWithAppInfo:delegate:]]
* When four SDK instances exist, you must destroy an old instance before creating a new one.

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || ✓ || "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || No || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || No || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Has to be set to "DEBUG" until certified
|| Nielsen-specified || Optional || "DEBUG"
|}
 

==== Sample SDK Initialization Code ====

===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
 
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

====== Objective-C ======
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>If App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.</blockquote>
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
@"nol_devDebug": @"DEBUG"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

===== Android =====
====== Java ======

AppSDK is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="java">

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA")
.put("nol_devDebug", "DEBUG");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
Here, <code>appContext</code> is the App context object and <code>appSdkConfig</code> is JSON object for holding the parameters (<code>appid</code>, <code>appname</code>, <code>sfcode</code>) the App passes to the Nielsen App SDK via a JSON string. The appid is obtained from Nielsen operational support and is unique to the app.

The integration of Nielsen App SDK will depend on type of client app. 
* Ensure that SDK file AppSdk.jar is included under the App’s project and the App SDK is linked to the App (the setting to link App SDK to the App can be found on property page of the App’s project).

== Step 3: Review the APP SDK Error & Event Codes ==
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

== Step 4: Create Metadata Object for your page section ==

The full description of the other key/value pairs for Metadata can be found here:
'''[[AGF Metadata Convention#Static Measurement|AGF Metadata Convention for Static Measurement]]'''

=== Example Web Page Metadata Object ===

==== iOS ====

===== Swift =====
<syntaxhighlight lang="swift">
class SDKMethods : NSObject{
func loadStaticMaster() -> [String : Any] {
//Loading Static Main data
let staticData =
[
"type": "static",
"assetid": "Unique_asset_ID",
"section": "Unique_section_ID",
"segA": "Unique_section_segA",
"segB": "Mandatory_section_segB",
"segC": "Optional_section_segC",
"subbrand": "subbrand_received_from_Nielsen"
]
return staticData
}
</syntaxhighlight>

===== Objective-C =====

<syntaxhighlight lang="objective-c">
NSDictionary * staticMetadata = @ {
@ "type": @ "static",
@ "assetid": @ "Unique_asset_ID",
@ "section": @ "Unique_section_ID",
@ "segA": @ "Unique_section_segA",
@ "segB": @ "Mandatory_section_segB",
@ "segC": @ "Optional_section_segC",
@ "subbrand": @ "subbrand_received_from_Nielsen"
}
</syntaxhighlight>

==== Android ====
<syntaxhighlight lang="java"> staticMetadata = new JSONObject()
.put("type", "static")
.put("section", "Unique_section_ID")
.put("assetid", "Unique_asset_ID")
.put("segA", "Unique_section_segA")
.put("segB", "Mandatory_section_segB")
.put("segC","Optional_section_segC")
.put("subbrand","subbrand_received_from_Nielsen");
</syntaxhighlight>

== Step 5: Start the Measurement by calling the loadMetadata AppSDK API ==

Use the metadata object created in the previous step in the loadMetadata AppSDK API Call.

{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">– (void)loadMetadata:(id)contentMetadata;</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void loadMetadata(JSONObject contentMetadata);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(contentMetadata)</syntaxhighlight>
}}

== Step 6: Include the measurement of Advertising Medium (Werbeträger) if applicable ==

=== Description ===

A page impression is a user action on the page that leads or could lead to an advertisement being called up. Each user action may only be counted once.

However, a page impression occurs when the content of the viewport of the respective device is completely reloaded/rendered by scrolling/swiping and replaced by new
content.

When counting views, a distinction is made between content
views (CPI) and advertising medium views after a user action (WPI). There can be
only one content view per page. Each additional user action on the same page (click,
scroll or swipe, e.g. click through an image gallery) will lead to an advertising medium view (WPI) accordingly. The implementation should follow the IVW guidelines for
defining user actions.

'''Note''':
The differentiation between the measurement of Content vs. advertising medium is achieved by setting accordingly the "segB" value in the metadata object , see '''[[AGF Metadata Convention#Static Measurement|AGF Metadata Convention for Static Measurement]]'''

=== Implementation Details ===
How to trigger a page impression for advertising medium?
In order to trigger a a new view for an advertising medium, you have to set the segB metadata value including the timestamp (i.e. "WPI_1674049210") and then call loadMetadata, see example code below:

{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">– (void)loadMetadata:(id)contentMetadata;</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void loadMetadata(JSONObject contentMetadata);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(contentMetadata)</syntaxhighlight>
}}

== Step 7: Privacy and Opt-Out ==

The AppSDK measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen AppSDK measurement is utilizing a cookieless domain.
In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=de .

Please contact your Nielsen SDK support team directly for any related questions.

== Step 8: Going Live ==
Following Nielsen testing, users need to make one update to the initialization call to ensure that the site is being measured properly.

# '''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:

'''<big>iOS Example:</big>'''

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
// Remove Flag: "nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

'''<big>Android Example:</big>'''
<syntaxhighlight lang="java">
try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
// Remove Flag: "nol_devDebug": "DEBUG"

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>

'''Note''': before going live you have to inform Nielsen team - this is necessary, because Nielsen team has to adjust internal configuration parameter to enable data collection. Without that notification no data will be collected and no data will be reported.

AGF Metadata Convention

2023-02-17T10:47:07Z

MichelFodjo: /* Static Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__TOC__

= AGF Metadata Convention =

The Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.

'''Note:''' All metadata values should be passed as UTF-8 strings. 

== Static Measurement ==

{| class="wikitable"
|-
! Key !! Description !! Values !! Required (Obligatory) !! AGF Convention !! Example data - RTL
|-
| type || type of asset || <code>"static"</code> || ✓ || hardcoded string required by Nielsen || <code>"static"</code>
|-
| assetid || unique ID assigned to each article/page; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations) || custom (no [[Special Characters]]) || ✓ || Content Article ID. If it is not an article page and therefore no ID is available, the page path is used. || "999452"
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section) || custom (no [[Special Characters]]) || ✓ || Section of Website or App || "_rtl_portal_news"
|-
| segA || custom segment for reporting: unique values across custom segments (segA + segB + segC) || custom || ✓ || AGOF code or comparable unit code. If the AGOF code is not available, set "Unknown" || "dbrsowf_rtlnews"
|-
| segB || custom segment for reporting: unique values across custom segments (segA + segB + segC) || custom || ✓ || Value to define content view count vs. 'Werbetraeger' view count. For Content: "CPI" . For 'Werbetraeger': "WPI_timestamp" (Timestamp in whole seconds, not milliseconds) || For Content: "CPI" . For 'Werbetraeger' after user interaction with the site and newly loaded Content: "WPI_1657634473".
|-
| segC || custom segment for reporting: unique values across custom segments (segA + segB + segC) || custom || || Program name || "IBES"
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen || ✓ || Same as video measurement, provided by Nielsen || "c01"
|}

== Video Measurement ==

Please refer to this AGF PDF Document: '''[https://nielsendownloads.digitalengsdk.com/digital/220907_AGF+Custom+Variables+and+Metadata+DCR+SDK++v1.8_english.pdf Metadata Document for Video]'''

AGF Metadata Convention

2023-02-15T09:01:40Z

MichelFodjo: /* Static Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__TOC__

= AGF Metadata Convention =

The Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.

'''Note:''' All metadata values should be passed as UTF-8 strings. 

== Static Measurement ==

{| class="wikitable"
|-
! Key !! Description !! Values !! Required (Obligatory) !! AGF Convention !! Example data - RTL
|-
| type || type of asset || <code>"static"</code> || ✓ || hardcoded string required by Nielsen || <code>"static"</code>
|-
| assetid || unique ID assigned to each article/page; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations) || custom (no [[Special Characters]]) || ✓ || Content Article ID. If it is not an article page and therefore no ID is available, the page path is used. || "999452"
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section) || custom (no [[Special Characters]]) || ✓ || Section of Website or App || "_rtl_portal_news"
|-
| segA || custom segment for reporting: unique values across custom segments (segA + segB + segC) || custom || ✓ || AGOF code or comparable unit code || "dbrsowf_rtlnews"
|-
| segB || custom segment for reporting: unique values across custom segments (segA + segB + segC) || custom || ✓ || Value to define content view count vs. 'Werbetraeger' view count. For Content: "CPI" . For 'Werbetraeger': "WPI_timestamp" (Timestamp in whole seconds, not milliseconds) || For Content: "CPI" . For 'Werbetraeger' after user interaction with the site and newly loaded Content: "WPI_1657634473".
|-
| segC || custom segment for reporting: unique values across custom segments (segA + segB + segC) || custom || || Program name || "IBES"
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen || ✓ || Same as video measurement, provided by Nielsen || "c01"
|}

== Video Measurement ==

Please refer to this AGF PDF Document: '''[https://nielsendownloads.digitalengsdk.com/digital/220907_AGF+Custom+Variables+and+Metadata+DCR+SDK++v1.8_english.pdf Metadata Document for Video]'''

DCR Germany Video Cloud API

2023-02-13T08:05:13Z

MichelFodjo: /* Review the Reference Implementation for VoD and Live Streams */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing Cloud API =
This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.

<pre style="color: red">
PLease note that the Cloud API Product is not yet rolled out in Germany!
</pre>

__TOC__
==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 by your assigned Technical Account Manager upon starting the integration.

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Provided by Nielsen
|}

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

====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. '''Note:'''The "P" prefix must be removed from the App ID received before adding it to the URL, i.e. if you received PDF20695-XXXX-XXXX-XXXX-3E334133D917 from Nielsen , your url will then be : <code>[endpoint]/DF20695-XXXX-XXXX-XXXX-3E334133D917/[sessionID]/a?b=[payload]</code>
*<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://sc-eucert.nmrodam.com/nmapi/v2/</code>
*Production: <code>https://agfcapi.nmrodam.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://sc-eucert.nmrodam.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms],
"sessid": [unique view session ID for each video play]
}
</syntaxhighlight>

===Create Session ID and send EMM Ping===

====Create Session ID====

A unique Session ID <code>[sessionID]</code> must be created upon app launch and provided in the URL. This will allow the measurement to occur for the entire duration that a user is within the app.

A Session ID needs to be completely unique so it is recommended to use our generation method example provided below to create unique alpha-numerical 29 characters + 10 characters UTC timestamp, to guarantee there are no repeats, also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference and use.

Session ID example: '''LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088'''
 

<syntaxhighlight lang="javascript">
'''// Create random GUID'''
function buildGUID() {
var UAIDbase62Characters = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
var UAIDpayloadLength = 29;

function UAIDgetRandom62() {
var r1;
do {
r1 = Math.floor(Math.random() * (16 * 62));
} while (r1 > 61);
return r1;
}

var uid = '';
for (var a = 0; a < UAIDpayloadLength; a++) {
uid += UAIDbase62Characters.charAt(UAIDgetRandom62());
}
var timestamp_ms = new Date().getTime();
uid += String(timestamp_ms).substring(3);
return uid;
}
</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.

====Send EMM Ping (only for Mobile (iOS and Android) and Browser)====
An EMM Ping must be sent using the created unique Session ID <code>[sessionID]</code> upon start of the first stream playback.
<syntaxhighlight lang="javascript">
https://[sessionID].uaid.nmrodam.com/
</syntaxhighlight>
Also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference.

===Create View Session ID for each Video Start===
An View Session ID <code>[sessid]</code> must be created upon start of each stream playback, sessid is unique per video play.

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

<syntaxhighlight lang="javascript">https://sc-eucert.nmrodam.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

===Configure Payload===

====Description 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">
// 1. Create Session ID using the UUID Generator code provided
sessionID = LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088 // Example sessionID

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

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "",
"apn": "AppName",
"apv": "1.0"
},

// 3.2 Configure Payload: metadata
"metadata": {
"content": { // object for measuring video content
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
// custom metadata
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
},
"ad": {
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Ad",
"nol_c17": "p17,preroll"
}
},

// 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
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609" // create and pass a unique sessid for each video play using UUID Generator code provided
}
</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) - Not required for AGF || custom ||
|-
| apn || app name || custom || ✓
|-
| apv || app build version || custom || ✓
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "",
"apn": "AppName",
"apv": "1.0"
},
</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 =====

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

For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required/Obligatory
|-
| type || type of asset || <code>"content"</code> || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no [[Special Characters]]) || ✓
|-
| program ||(string) name of program (254 character limit) || custom || ✓
|-
| title ||(string) episode title (max 254 characters) || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| length || length of content in seconds || <code>seconds</code> ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| clientid ||
parent ID – value is automatically populated through provided App ID. 
In order to override the brand configured to the App ID, pass parent 
value here and the sub-brand ID associated with that brand in the subbrand 
key (e.g. multiple brands in App)
||
provided by Nielsen
||
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided 
App ID. In order to override the sub-brand configured to the App ID, value can 
be passed here (e.g. multiple sub-brands in App)
||
provided by Nielsen
||

|-
| nol_c0 || number of episode part (Sendungsteilenummer) || number || ✓
|-
| nol_c2 || web only || 'Y' or 'N' || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || duration in seconds || `seconds` ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c12 || type of asset || 'Trailer' or 'Content' || ✓
|-
| nol_c13 || original air time || `(YYYY-MM-TT)T(HH:mm:ss) Example: 2004-06-14T23:34:30 ||
|-
| nol_c14 || ISO 8601 timestamp || `(YYYY-MM-TT)T(HH:mm:ss)` ||
|-
| nol_c15 || format ID || custom ||
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c18 || livestream || 'Y' or 'N' || ✓
|-
| nol_c19 || custom variable || custom ||
|-
| nol_c20 || GfK-ID || custom ||
|}
 

====== Example Content metadata ======
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
// custom metadata
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
}</syntaxhighlight>

===== Ad Metadata (optional for public broadcasters) =====
====== Description of Ad metadata ======
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

 
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no SPACE - no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters]) || ✓
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen ||
|-
| title || only the AD-ID is necessary || custom, <AD-ID> without "VAST" Prefix or other, i.e. '2352723141' || ✓
|-
| length || length of Ad in seconds || length of Ad in seconds || ✓
|-
| nol_c1 || universal AdID (Additional AD-ID to be used by second or third marketers) || custom, i.e. 'adgapid_022_800160_1601097_001_0_0' ||
|-
| nol_c2 || web only || 'Y' or 'N' ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || duration of the video file in seconds || || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c11 || AD-ID (unique ID of an advertisement. Necessary if ads are being broadcasted) || custom, i.e. '2352723141' || ✓
|-
| nol_c12 || content type (key distinction of content, advertising, and Trailer) || 'Ad' || ✓
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c17 || ad placement type (placement information of advertisement) || 'preroll', 'midroll', 'postroll' or 'other' || ✓
|}

====== Example Ad metadata ======
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Ad",
"nol_c17": "p17,preroll"
}

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

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

'''General'''
* Playhead position in seconds, must be passed as a whole number every 10 seconds.
* The final playhead position should be sent before before sending "complete" event when content playback is complete.

'''Live Stream'''
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position. Note that ad playheads must also use Unix Time for each single Ad in an Ad Pod.

'''VoD Stream'''
* For VoD stream use the player position for Content and Ad at playback start of a content or single Ad in an Ad Pod, playheads will then be 0, 10, 20, ....

'''End of an Asset'''
* Final postion must be sent at the end of Content or Ad playback

'''Ads'''
* The final playhead position must be sent when switching from content to ad, or ad to content.
* For Ad Pods, playhead must be called for each individual ad.
* When content has resumed following a mid-roll ad break, the next playhead position must continue where the previous content segment left off.

'''User Actions'''
* SCRUBBING: 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.
* PAUSE: When content is paused, send current playhead position and stop passing playhead position until content is resumed.
* EXIT Stream: If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

|-
| <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. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is optional and can be sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. 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> || ✓
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || ✓
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || ✓
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || ✓
|-style="background-color:#d0f6f8;"
| <code>"sessid"</code> || Unique View Session ID must be created upon start of each stream playback, sessid is unique per video play. || <code>"xxxjavd6wzirm93xb95uxjy1ac5wu1627638609"</code> || ✓
|}

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

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"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
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}
</syntaxhighlight>

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

===== Sample Event Lifecycle for VoD Stream =====
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 for VoD Stream - 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>

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

see '''[[#Payload Example|Payload Example]]'''

// Append payload to URL
function sendPayloadToNielsen() {
var payloadStr = JSON.stringify(payload); // payload as string
var imgPing = new Image();
imgPing.onload = function() {
// onload event, payload succesfull sent
};
imgPing.onerror = function() {
// handle error i.e. wait and send again
};
imgPing.src = sessionURL+encodeURIComponent(payloadStr);
}
</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
|}

== Review the Reference Implementation for VoD and Live Streams ==

The Reference Implementation covers vod and Live use cases.
It also covers DAI (Dynamic Ad Insertion) with preroll and postroll Ads.

In order to start live stream select the checkbox "isLive" in the <code>Playback Settings</code> below the video player.

Start the Reference Implementation for AGF by selection Germany in the country dropbox [https://nielsenonlinesupport.com/agf/RefImplCloudAPI/index.htm?debug=true RefImplCloudAPI].
<blockquote>
Review the Nielsen CloudAPI Call Sequence below the Video Player.
</blockquote>

== Disclose Nielsen Privacy Statement ==

The Nielsen Cloud API measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen Cloud API measurement is utilizing a cookieless domain.

In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:

A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=de .

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

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

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset for VoD stream and UTC Unix Time in seconds for Live stream.
*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.

== 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://sc-eucert.nmrodam.com/nmapi/v2/</code>
*Production: <code>https://agfcapi.nmrodam.com/nmapi/v2/</code>

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

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

DCR Sweden Video Android SDK

2023-02-10T12:34:47Z

MichelFodjo: /* Implementation */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Overview ==
The Nielsen SDK is one of the multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like It supports a variety of Nielsen Measurement Products like Digital in TV Ratings ([[DCR & DTVR|DTVR]]), Digital Content Ratings ([[DCR & DTVR|DCR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a subsection/page in the application.
 
This ''SDK Android integration guide'' is applicable for '''Android TV''' as well.

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || "App ID (appid)" || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || "Nielsen SDK" || Includes SDK frameworks and "sample implementation"; "See [[Android SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Implementation ==
The Nielsen Android SDK comes in three flavors.

{| class="wikitable"
|-
! SDK Flavor
! Description
|-
| '''Android Ad Version'''
|
* Opt-In and Opt-Out functionality managed by Opt out of Ads Personalization setting on the device.
* The Nielsen SDK will collect the [https://developer.android.com/training/articles/ad-id Google Advertising ID] unless the user Opts out.
* If the Google Play Service is unavailable (ie, Amazon and Huawei devices), the Nielsen SDK will secure the Android ID.
|-
| '''Android No Ad Framework'''
|
* Without the Google Play Services SDK, the Nielsen SDK cannot read the Google Advertising ID, so it will retrieve the Android ID.
* The Android ID is a 64-bit number (expressed as a hexadecimal string) unique to each combination of the app-signing key, user and device.
* The developer is required to present the User Choice Opt-Out page, which is described in the [[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]].
|-
| '''Android SDK noID'''
|
* This version of the Nielsen SDK is perfect for Kid apps, or where no ID is required.
* For the requirement, please review the [[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]].
|}

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions to the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Required Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control/configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 will later support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work correctly.

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_unknown || Hashed email using SHA512. This email is used by MMS reach model.
|| Client-defined || Required if login feature || "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..."
|-
| enableFpid || true/false value is required to set collection of first-party ID.
|| Nielsen-specified || NO || <syntaxhighlight lang="javascript">
{enableFpid: "true"} //alternative: false
</syntaxhighlight>
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG") // only for debug builds
.put("hem_unknown", "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8...")
.put("enableFpid", "true"); // alternative is false;

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So the whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG") // only for debug builds
.put("hem_unknown", "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8...")
.put("enableFpid", "true"); // alternative is false;

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the ""Initial state"".
# '''Idle state'''– The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# '''Processing state''' – The SDK instance processes playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be a string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

==== Create Content Metadata ====
Content metadata should remain constant throughout the entirety of an episode/clip, including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content metadata.
 

'''Note:''' Program and title metadata values should be passed to SDK as UTF-8 strings.

==== Create Ad Metadata ====
The Ad Metadata (if applicable) should be passed for each individual ad.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of ad metadata. 

'''Note:''' All metadata values should be passed as UTF-8 strings.

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

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelName","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");
//please see metadata link above for all content parameters

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");
//please see metadata link above for all ad parameters
</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
It needs to be called at the beginning of each asset and pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the beginning of the playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass the current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass the whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

==== stop ====
Call when
* ads complete playing
* When a user pauses playback
* upon any user interruption scenario - see below chapter Interruption scenario

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

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",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
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(); </code> || // Call at start of each new stream
|-
| <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
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| Resume Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "My Channel Name 1"
}</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 / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of the 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(channelInfo); </code> || // channelName contains JSON metadata of channel 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="2" | 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
|-
| 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="2" | 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
|-
| 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 the previous content segment was left off.</blockquote>

== Handling Foreground and Background states ==
There are a few approaches to managing the Foreground and Background states of an app available to use for state measurement.

*Utilizing the Androidx LifeCycleObserver (The recommended approach starting sdk version 7.1.0.0+)
*Utilizing the SdkBgFgDetectionUtility class
*Adding a tag to the Manifest XML
*Manual Management
=== The LifeCycleObserver ===
AndroidX replaces the original support library APIs with packages in the androidx namespace, and Android Studio 3.2 and higher provide an automated migration tool. (Select '''Refactor> Migrate to AndroidX''' from the menu bar.)

Starting with version 7.1.0, with AndroidX support, an additional utility is provided in the AppSDK - application background/foreground state detection by the AppSdk leveraging the Android Architecture component "LifeCycleObserver".

The AppSdk is now capable of detecting the application UI visibility state transitions between background and foreground without forcing the applications to register for AppSdk's AppSdkApplication class, which is responsible for handling the detection of application background/foreground state transitions at present.

<blockquote>Please note that if you already have an app designed that utilizes the depreciated SdkBgFgDetectionUtility Class, the AppSDK will ignore any calls to these methods if it can utilize the LifeCycleObserver. LifeCycleObserver based auto-detection will take precedence.</blockquote>

==== Adding the AndroidX dependency ====
In order to make use of the app background/foreground state transition auto detection feature of AndroidX AppSdk, the app gradle file needs the androidx dependency. The AppSdk API calls - <code>appInForeground()</code> and <code>appInBackground()</code> will still be respected by AppSdk by executing the old AppSdk flow of handling "app in foreground" and "app in background" states as is.

==== Using the LifeCycle Extension ====
The following androidx dependency is required in the app gradle file:

<syntaxhighlight lang="java">implementation "androidx.lifecycle:lifecycle-extensions:2.1.0"</syntaxhighlight>

<blockquote>If you would like to take advantage of this auto-detection feature of AppSdk at the very initial stage (e.g. splash screen or at of app launch time), before the AppSdk is initialized, you can do so by calling the following newly introduced AppSdk public API, passing the application context :

<syntaxhighlight lang="java">public static void registerLifeCycleObserver(Context applicationContext)</syntaxhighlight></blockquote>

==== Log messages for the new auto detection ====

*When the AppSdk app successfully registers for the LifeCycleObserver : <code>Registered LifeCycleObserver for App Background/Foreground auto-detection</code>
*When the app enters the foreground state :<code>App is in foreground, auto-detected by AppSDK</code>
*When the app enters the background state :<code>App is in background, auto-detected by AppSDK</code>
*If the client app doesn't have the "androidx" gradle dependency and AppSdk fails to register LifeCycleObserver :<code>AndroidX LifecycleObserver can not be observed. Please use androidx dependency to activate SDK auto-detection of app background/foreground state.</code>
*When the appInForeground() is explicitly called while LifeCycleObserver auto detection is active :<code>Ignoring the appInBackground() call, as the App Background/Foreground auto-detection is active. The current state is - foreground</code>
*When the appInBackground() is explicitly called while LifeCycleObserver auto detection is active :<code>Ignoring the appInBackground() call, as the App Background/Foreground auto-detection is active. The current state is - background</code>

=== The SdkBgFgDetectionUtility class ===
Foreground/Background state measurement is a requirement of Nielsen AppSDK implementation which is especially crucial for static measurement. It may be implemented in multiple ways for Android. This includes

*Enable the Nielsen SDK to measure background/foreground state by making the relevant update to the AndroidManifest.
*Integrate Nielsen’s SdkBgFgDetectionUtility class within your Custom Application Class.
*Custom implementation of the required methods within your application.

==== ForeGround/Background Measurement via AndroidManifest ====
The simplest way to measure the app background/foreground state is to add the following application tag to the Manifest XML. Integrating this into the Manifest XML will enable the SDK to measure app state directly. This approach is supported for Android 4.0 and up only; it requires that the application class is not in use for some other purpose.

<syntaxhighlight lang="java"> <application android:name="com.nielsen.app.sdk.AppSdkApplication"> </syntaxhighlight>

==== Using the Android SdkBgFbDetectionUtility Class ====
For developers who are already using the application class, it is recommended that the background/foreground state is implemented using the [[Android Background Foreground|SdkBgFgDetectionUtility class.]] The [[Android Background Foreground|SdkBgFgDetectionUtility class.]] is compatible with Android 4+ and has been made available to Nielsen clients. (You will need to copy/paste the code provided into a file).

==== Manual Background/ForeGround State Management ====
In cases where the developer is not able to use the AndroidManifest.xml solution nor the Nielsen provided [[Android Background Foreground|SdkBgFgDetectionUtility class.]], the developer will need to manually identify the change of state through the application and call the respective API (appInForeground() or appInBackground()) to inform the SDK regarding the change of state from background to foreground or foreground to background.

The SDK is informed about app state using the below methods.

<syntaxhighlight lang="java">AppLaunchMeasurementManager.appInForeground(getApplicationContext());</syntaxhighlight>
<syntaxhighlight lang="java">AppLaunchMeasurementManager.appInBackground(getApplicationContext());</syntaxhighlight>
Within the lifecycle of individual activities, onResume() and onPause() are best suited to provide an indication of the app state.

Correct foreground/background state measurement is crucial to Static App measurement within Nielsen Digital Content Ratings (DCR).

== Stop/Resume the Measurement for video Playback Interruptions ==
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 <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Privacy and Opt-Out ==
There are currently three flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device.
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. It can be used without Google Play Services or when using the No Ad version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. It should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

==== Retrieve current Opt-Out preference ====
Whether the user is opted out via OS-level Opt-out or via App-level Opt-out, the current Opt-Out status as detected by the SDK is available via the [[getOptOutStatus()]] property in the Nielsen Android SDK API. <code>appSdk.getOptOutStatus()</code>

===Global OptOut Example ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services, such as when using the No Ad or No ID versions.

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and closes the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>
===No Ad Framework Optout Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the No ID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page or have the similar text available within the native app. Include the "About Nielsen Measurement" and "Your Choices" link in the Privacy Policy / EULA or as a button near the link to the app's Privacy Policy.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software, which contributes to market research, like Nielsen’s TV Ratings. Please see https://www.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=sv for more information"'''</blockquote>

=== First Party ID (FPID)===
- The broadcaster must enableFPID in the initialization settings which is set to <code>true</code> or <code>false</code> depending on user consent. This is to be set by the broadcaster when initializing our SDK. 

- The <code>enableFpid</code> flag is needed to enable/disable FPID usage for the AppID. The default value for this flag is true. If this flag is changed from true to false, then the AppSDK should wipe out the stored FPID and use a blank value for FPID parameter in all the pings. 

- Generated FPID value is stored in the persistent memory until the application is uninstalled from a device, when FPID is wiped out, or when it is expired. 

- The default value for this parameter is 180 days. Once this timeout is reached, the FPID should be regenerated. 

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via the same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "imr" and confirm the presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

== Step 9 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

DCR Sweden Video Android SDK

2023-02-10T12:31:48Z

MichelFodjo: /* Implementation */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Overview ==
The Nielsen SDK is one of the multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like It supports a variety of Nielsen Measurement Products like Digital in TV Ratings ([[DCR & DTVR|DTVR]]), Digital Content Ratings ([[DCR & DTVR|DCR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a subsection/page in the application.
 
This ''SDK Android integration guide'' is applicable for '''Android TV''' as well.

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || "App ID (appid)" || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || "Nielsen SDK" || Includes SDK frameworks and "sample implementation"; "See [[Android SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Implementation ==
The Nielsen Android SDK comes in three flavors.

{| class="wikitable"
|-
! SDK Flavor
! Description
|-
| '''Android Ad Version'''
|* Opt-In and Opt-Out functionality managed by Opt out of Ads Personalization setting on the device. * The Nielsen SDK will collect the [https://developer.android.com/training/articles/ad-id Google Advertising ID] unless the user Opts out. * If the Google Play Service is unavailable (ie, Amazon and Huawei devices), the Nielsen SDK will secure the Android ID. 
|-
| '''Android No Ad Framework'''
|* Without the Google Play Services SDK, the Nielsen SDK cannot read the Google Advertising ID, so it will retrieve the Android ID. * The Android ID is a 64-bit number (expressed as a hexadecimal string) unique to each combination of the app-signing key, user and device. * The developer is required to present the User Choice Opt-Out page, which is described in the [[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]].
|-
| '''Android SDK noID'''
|* This version of the Nielsen SDK is perfect for Kid apps, or where no ID is required. * For the requirement, please review the [[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]].
|}

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions to the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Required Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control/configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 will later support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work correctly.

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_unknown || Hashed email using SHA512. This email is used by MMS reach model.
|| Client-defined || Required if login feature || "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..."
|-
| enableFpid || true/false value is required to set collection of first-party ID.
|| Nielsen-specified || NO || <syntaxhighlight lang="javascript">
{enableFpid: "true"} //alternative: false
</syntaxhighlight>
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG") // only for debug builds
.put("hem_unknown", "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8...")
.put("enableFpid", "true"); // alternative is false;

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So the whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG") // only for debug builds
.put("hem_unknown", "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8...")
.put("enableFpid", "true"); // alternative is false;

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the ""Initial state"".
# '''Idle state'''– The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# '''Processing state''' – The SDK instance processes playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be a string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

==== Create Content Metadata ====
Content metadata should remain constant throughout the entirety of an episode/clip, including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content metadata.
 

'''Note:''' Program and title metadata values should be passed to SDK as UTF-8 strings.

==== Create Ad Metadata ====
The Ad Metadata (if applicable) should be passed for each individual ad.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of ad metadata. 

'''Note:''' All metadata values should be passed as UTF-8 strings.

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

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelName","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");
//please see metadata link above for all content parameters

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");
//please see metadata link above for all ad parameters
</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
It needs to be called at the beginning of each asset and pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the beginning of the playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass the current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass the whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

==== stop ====
Call when
* ads complete playing
* When a user pauses playback
* upon any user interruption scenario - see below chapter Interruption scenario

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

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",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
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(); </code> || // Call at start of each new stream
|-
| <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
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| Resume Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "My Channel Name 1"
}</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 / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of the 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(channelInfo); </code> || // channelName contains JSON metadata of channel 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="2" | 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
|-
| 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="2" | 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
|-
| 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 the previous content segment was left off.</blockquote>

== Handling Foreground and Background states ==
There are a few approaches to managing the Foreground and Background states of an app available to use for state measurement.

*Utilizing the Androidx LifeCycleObserver (The recommended approach starting sdk version 7.1.0.0+)
*Utilizing the SdkBgFgDetectionUtility class
*Adding a tag to the Manifest XML
*Manual Management
=== The LifeCycleObserver ===
AndroidX replaces the original support library APIs with packages in the androidx namespace, and Android Studio 3.2 and higher provide an automated migration tool. (Select '''Refactor> Migrate to AndroidX''' from the menu bar.)

Starting with version 7.1.0, with AndroidX support, an additional utility is provided in the AppSDK - application background/foreground state detection by the AppSdk leveraging the Android Architecture component "LifeCycleObserver".

The AppSdk is now capable of detecting the application UI visibility state transitions between background and foreground without forcing the applications to register for AppSdk's AppSdkApplication class, which is responsible for handling the detection of application background/foreground state transitions at present.

<blockquote>Please note that if you already have an app designed that utilizes the depreciated SdkBgFgDetectionUtility Class, the AppSDK will ignore any calls to these methods if it can utilize the LifeCycleObserver. LifeCycleObserver based auto-detection will take precedence.</blockquote>

==== Adding the AndroidX dependency ====
In order to make use of the app background/foreground state transition auto detection feature of AndroidX AppSdk, the app gradle file needs the androidx dependency. The AppSdk API calls - <code>appInForeground()</code> and <code>appInBackground()</code> will still be respected by AppSdk by executing the old AppSdk flow of handling "app in foreground" and "app in background" states as is.

==== Using the LifeCycle Extension ====
The following androidx dependency is required in the app gradle file:

<syntaxhighlight lang="java">implementation "androidx.lifecycle:lifecycle-extensions:2.1.0"</syntaxhighlight>

<blockquote>If you would like to take advantage of this auto-detection feature of AppSdk at the very initial stage (e.g. splash screen or at of app launch time), before the AppSdk is initialized, you can do so by calling the following newly introduced AppSdk public API, passing the application context :

<syntaxhighlight lang="java">public static void registerLifeCycleObserver(Context applicationContext)</syntaxhighlight></blockquote>

==== Log messages for the new auto detection ====

*When the AppSdk app successfully registers for the LifeCycleObserver : <code>Registered LifeCycleObserver for App Background/Foreground auto-detection</code>
*When the app enters the foreground state :<code>App is in foreground, auto-detected by AppSDK</code>
*When the app enters the background state :<code>App is in background, auto-detected by AppSDK</code>
*If the client app doesn't have the "androidx" gradle dependency and AppSdk fails to register LifeCycleObserver :<code>AndroidX LifecycleObserver can not be observed. Please use androidx dependency to activate SDK auto-detection of app background/foreground state.</code>
*When the appInForeground() is explicitly called while LifeCycleObserver auto detection is active :<code>Ignoring the appInBackground() call, as the App Background/Foreground auto-detection is active. The current state is - foreground</code>
*When the appInBackground() is explicitly called while LifeCycleObserver auto detection is active :<code>Ignoring the appInBackground() call, as the App Background/Foreground auto-detection is active. The current state is - background</code>

=== The SdkBgFgDetectionUtility class ===
Foreground/Background state measurement is a requirement of Nielsen AppSDK implementation which is especially crucial for static measurement. It may be implemented in multiple ways for Android. This includes

*Enable the Nielsen SDK to measure background/foreground state by making the relevant update to the AndroidManifest.
*Integrate Nielsen’s SdkBgFgDetectionUtility class within your Custom Application Class.
*Custom implementation of the required methods within your application.

==== ForeGround/Background Measurement via AndroidManifest ====
The simplest way to measure the app background/foreground state is to add the following application tag to the Manifest XML. Integrating this into the Manifest XML will enable the SDK to measure app state directly. This approach is supported for Android 4.0 and up only; it requires that the application class is not in use for some other purpose.

<syntaxhighlight lang="java"> <application android:name="com.nielsen.app.sdk.AppSdkApplication"> </syntaxhighlight>

==== Using the Android SdkBgFbDetectionUtility Class ====
For developers who are already using the application class, it is recommended that the background/foreground state is implemented using the [[Android Background Foreground|SdkBgFgDetectionUtility class.]] The [[Android Background Foreground|SdkBgFgDetectionUtility class.]] is compatible with Android 4+ and has been made available to Nielsen clients. (You will need to copy/paste the code provided into a file).

==== Manual Background/ForeGround State Management ====
In cases where the developer is not able to use the AndroidManifest.xml solution nor the Nielsen provided [[Android Background Foreground|SdkBgFgDetectionUtility class.]], the developer will need to manually identify the change of state through the application and call the respective API (appInForeground() or appInBackground()) to inform the SDK regarding the change of state from background to foreground or foreground to background.

The SDK is informed about app state using the below methods.

<syntaxhighlight lang="java">AppLaunchMeasurementManager.appInForeground(getApplicationContext());</syntaxhighlight>
<syntaxhighlight lang="java">AppLaunchMeasurementManager.appInBackground(getApplicationContext());</syntaxhighlight>
Within the lifecycle of individual activities, onResume() and onPause() are best suited to provide an indication of the app state.

Correct foreground/background state measurement is crucial to Static App measurement within Nielsen Digital Content Ratings (DCR).

== Stop/Resume the Measurement for video Playback Interruptions ==
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 <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Privacy and Opt-Out ==
There are currently three flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device.
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. It can be used without Google Play Services or when using the No Ad version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. It should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

==== Retrieve current Opt-Out preference ====
Whether the user is opted out via OS-level Opt-out or via App-level Opt-out, the current Opt-Out status as detected by the SDK is available via the [[getOptOutStatus()]] property in the Nielsen Android SDK API. <code>appSdk.getOptOutStatus()</code>

===Global OptOut Example ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services, such as when using the No Ad or No ID versions.

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and closes the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>
===No Ad Framework Optout Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the No ID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page or have the similar text available within the native app. Include the "About Nielsen Measurement" and "Your Choices" link in the Privacy Policy / EULA or as a button near the link to the app's Privacy Policy.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software, which contributes to market research, like Nielsen’s TV Ratings. Please see https://www.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=sv for more information"'''</blockquote>

=== First Party ID (FPID)===
- The broadcaster must enableFPID in the initialization settings which is set to <code>true</code> or <code>false</code> depending on user consent. This is to be set by the broadcaster when initializing our SDK. 

- The <code>enableFpid</code> flag is needed to enable/disable FPID usage for the AppID. The default value for this flag is true. If this flag is changed from true to false, then the AppSDK should wipe out the stored FPID and use a blank value for FPID parameter in all the pings. 

- Generated FPID value is stored in the persistent memory until the application is uninstalled from a device, when FPID is wiped out, or when it is expired. 

- The default value for this parameter is 180 days. Once this timeout is reached, the FPID should be regenerated. 

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via the same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "imr" and confirm the presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

== Step 9 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

DCR Germany Video Cloud API

2023-02-03T11:44:43Z

MichelFodjo: /* Create Session ID */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing Cloud API =
This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.

<pre style="color: red">
PLease note that the Cloud API Product is not yet rolled out in Germany!
</pre>

__TOC__
==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 by your assigned Technical Account Manager upon starting the integration.

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Provided by Nielsen
|}

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

====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. '''Note:'''The "P" prefix must be removed from the App ID received before adding it to the URL, i.e. if you received PDF20695-XXXX-XXXX-XXXX-3E334133D917 from Nielsen , your url will then be : <code>[endpoint]/DF20695-XXXX-XXXX-XXXX-3E334133D917/[sessionID]/a?b=[payload]</code>
*<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://sc-eucert.nmrodam.com/nmapi/v2/</code>
*Production: <code>https://agfcapi.nmrodam.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://sc-eucert.nmrodam.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms],
"sessid": [unique view session ID for each video play]
}
</syntaxhighlight>

===Create Session ID and send EMM Ping===

====Create Session ID====

A unique Session ID <code>[sessionID]</code> must be created upon app launch and provided in the URL. This will allow the measurement to occur for the entire duration that a user is within the app.

A Session ID needs to be completely unique so it is recommended to use our generation method example provided below to create unique alpha-numerical 29 characters + 10 characters UTC timestamp, to guarantee there are no repeats, also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference and use.

Session ID example: '''LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088'''
 

<syntaxhighlight lang="javascript">
'''// Create random GUID'''
function buildGUID() {
var UAIDbase62Characters = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
var UAIDpayloadLength = 29;

function UAIDgetRandom62() {
var r1;
do {
r1 = Math.floor(Math.random() * (16 * 62));
} while (r1 > 61);
return r1;
}

var uid = '';
for (var a = 0; a < UAIDpayloadLength; a++) {
uid += UAIDbase62Characters.charAt(UAIDgetRandom62());
}
var timestamp_ms = new Date().getTime();
uid += String(timestamp_ms).substring(3);
return uid;
}
</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.

====Send EMM Ping (only for Mobile (iOS and Android) and Browser)====
An EMM Ping must be sent using the created unique Session ID <code>[sessionID]</code> upon start of the first stream playback.
<syntaxhighlight lang="javascript">
https://[sessionID].uaid.nmrodam.com/
</syntaxhighlight>
Also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference.

===Create View Session ID for each Video Start===
An View Session ID <code>[sessid]</code> must be created upon start of each stream playback, sessid is unique per video play.

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

<syntaxhighlight lang="javascript">https://sc-eucert.nmrodam.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

===Configure Payload===

====Description 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">
// 1. Create Session ID using the UUID Generator code provided
sessionID = LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088 // Example sessionID

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

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "",
"apn": "AppName",
"apv": "1.0"
},

// 3.2 Configure Payload: metadata
"metadata": {
"content": { // object for measuring video content
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
// custom metadata
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
},
"ad": {
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Ad",
"nol_c17": "p17,preroll"
}
},

// 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
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609" // create and pass a unique sessid for each video play using UUID Generator code provided
}
</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) - Not required for AGF || custom ||
|-
| apn || app name || custom || ✓
|-
| apv || app build version || custom || ✓
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "",
"apn": "AppName",
"apv": "1.0"
},
</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 =====

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

For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required/Obligatory
|-
| type || type of asset || <code>"content"</code> || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no [[Special Characters]]) || ✓
|-
| program ||(string) name of program (254 character limit) || custom || ✓
|-
| title ||(string) episode title (max 254 characters) || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| length || length of content in seconds || <code>seconds</code> ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| clientid ||
parent ID – value is automatically populated through provided App ID. 
In order to override the brand configured to the App ID, pass parent 
value here and the sub-brand ID associated with that brand in the subbrand 
key (e.g. multiple brands in App)
||
provided by Nielsen
||
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided 
App ID. In order to override the sub-brand configured to the App ID, value can 
be passed here (e.g. multiple sub-brands in App)
||
provided by Nielsen
||

|-
| nol_c0 || number of episode part (Sendungsteilenummer) || number || ✓
|-
| nol_c2 || web only || 'Y' or 'N' || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || duration in seconds || `seconds` ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c12 || type of asset || 'Trailer' or 'Content' || ✓
|-
| nol_c13 || original air time || `(YYYY-MM-TT)T(HH:mm:ss) Example: 2004-06-14T23:34:30 ||
|-
| nol_c14 || ISO 8601 timestamp || `(YYYY-MM-TT)T(HH:mm:ss)` ||
|-
| nol_c15 || format ID || custom ||
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c18 || livestream || 'Y' or 'N' || ✓
|-
| nol_c19 || custom variable || custom ||
|-
| nol_c20 || GfK-ID || custom ||
|}
 

====== Example Content metadata ======
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
// custom metadata
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
}</syntaxhighlight>

===== Ad Metadata (optional for public broadcasters) =====
====== Description of Ad metadata ======
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

 
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no SPACE - no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters]) || ✓
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen ||
|-
| title || only the AD-ID is necessary || custom, <AD-ID> without "VAST" Prefix or other, i.e. '2352723141' || ✓
|-
| length || length of Ad in seconds || length of Ad in seconds || ✓
|-
| nol_c1 || universal AdID (Additional AD-ID to be used by second or third marketers) || custom, i.e. 'adgapid_022_800160_1601097_001_0_0' ||
|-
| nol_c2 || web only || 'Y' or 'N' ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || duration of the video file in seconds || || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c11 || AD-ID (unique ID of an advertisement. Necessary if ads are being broadcasted) || custom, i.e. '2352723141' || ✓
|-
| nol_c12 || content type (key distinction of content, advertising, and Trailer) || 'Ad' || ✓
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c17 || ad placement type (placement information of advertisement) || 'preroll', 'midroll', 'postroll' or 'other' || ✓
|}

====== Example Ad metadata ======
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Ad",
"nol_c17": "p17,preroll"
}

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

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

'''General'''
* Playhead position in seconds, must be passed as a whole number every 10 seconds.
* The final playhead position should be sent before before sending "complete" event when content playback is complete.

'''Live Stream'''
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position. Note that ad playheads must also use Unix Time for each single Ad in an Ad Pod.

'''VoD Stream'''
* For VoD stream use the player position for Content and Ad at playback start of a content or single Ad in an Ad Pod, playheads will then be 0, 10, 20, ....

'''End of an Asset'''
* Final postion must be sent at the end of Content or Ad playback

'''Ads'''
* The final playhead position must be sent when switching from content to ad, or ad to content.
* For Ad Pods, playhead must be called for each individual ad.
* When content has resumed following a mid-roll ad break, the next playhead position must continue where the previous content segment left off.

'''User Actions'''
* SCRUBBING: 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.
* PAUSE: When content is paused, send current playhead position and stop passing playhead position until content is resumed.
* EXIT Stream: If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

|-
| <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. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is optional and can be sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. 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> || ✓
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || ✓
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || ✓
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || ✓
|-style="background-color:#d0f6f8;"
| <code>"sessid"</code> || Unique View Session ID must be created upon start of each stream playback, sessid is unique per video play. || <code>"xxxjavd6wzirm93xb95uxjy1ac5wu1627638609"</code> || ✓
|}

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

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"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
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}
</syntaxhighlight>

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

===== Sample Event Lifecycle for VoD Stream =====
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 for VoD Stream - 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>

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

see '''[[#Payload Example|Payload Example]]'''

// Append payload to URL
function sendPayloadToNielsen() {
var payloadStr = JSON.stringify(payload); // payload as string
var imgPing = new Image();
imgPing.onload = function() {
// onload event, payload succesfull sent
};
imgPing.onerror = function() {
// handle error i.e. wait and send again
};
imgPing.src = sessionURL+encodeURIComponent(payloadStr);
}
</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
|}

== Review the Reference Implementation for VoD and Live Streams ==

The Reference Implementation covers vod and Live use cases.
It also covers DAI (Dynamic Ad Insertion) with preroll and postroll Ads.

In order to start live stream select the checkbox "isLive" in the <code>Playback Settings</code> below the video player.

Start the Reference Implementation for DK [https://nielsenonlinesupport.com/dk/cloudapi/index.htm?debug=true RefImplCloudAPIDK].
<blockquote>
Review the Nielsen CloudAPI Call Sequence below the Video Player.
</blockquote>

== Disclose Nielsen Privacy Statement ==

The Nielsen Cloud API measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen Cloud API measurement is utilizing a cookieless domain.

In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:

A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=de .

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

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

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset for VoD stream and UTC Unix Time in seconds for Live stream.
*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.

== 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://sc-eucert.nmrodam.com/nmapi/v2/</code>
*Production: <code>https://agfcapi.nmrodam.com/nmapi/v2/</code>

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

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

DCR Sweden Video Cloud API

2023-01-31T08:35:54Z

MichelFodjo: /* Configure Payload: devInfo */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing Cloud API =
This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.
__TOC__
==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 by your assigned Technical Account Manager upon starting the integration.

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Provided by Nielsen
|}

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

====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.
** '''Note: P prefix must be removed before adding it to the URL'''
** Example App ID with P prefix: "PDF20695-XXXX-XXXX-XXXX-3E334133D917"
** <code>https://sc-eucert.imrworldwide.com/nmapi/v2/DF20695-XXXX-XXXX-XXXX-3E334133D917/[sessionID]/a?b=[payload]</code>
*<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://sc-eucert.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://capi-sw.imrworldwide.com/nmapi/v2/</code>
 

Please note that our Endpoints use TLS 1.2 and above, older devices using TLS 1.0 OR 1.1 is not compatible with the endpoints above. 

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://sc-eucert.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms]
}
</syntaxhighlight>

===Create Session ID and send EMM Ping===

====Create Session ID====

A unique Session ID <code>[sessionID]</code> must be created upon app launch and provided in the URL. This will allow the measurement to occur for the entire duration that a user is within the app.

A Session ID needs to be completely unique so it is recommended to use our generation method example provided below to create unique alpha-numerical 29 characters + 10 characters UTC timestamp, to guarantee there are no repeats, also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference and use.

Session ID example: '''LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088'''
 

<syntaxhighlight lang="javascript">
'''// Create random GUID'''
function buildGUID() {
var UAIDbase62Characters = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
var UAIDpayloadLength = 29;

function UAIDgetRandom62() {
var r1;
do {
r1 = Math.floor(Math.random() * (16 * 62));
} while (r1 > 61);
return r1;
}

var uid = '';
for (var a = 0; a < UAIDpayloadLength; a++) {
uid += UAIDbase62Characters.charAt(UAIDgetRandom62());
}
uid += Math.floor(new Date().getTime() / 1000);
return uid;
}
</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.

====Send EMM Ping====
An EMM Ping must be sent using the created unique Session ID <code>[sessionID]</code> upon start of the first stream playback.
<syntaxhighlight lang="javascript">
https://[sessionID].uaid.imrworldwide.com/
</syntaxhighlight>
Also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference.

===Create First Party ID===
* An First Party ID <code>[fpid]</code> must be created and stored on the device. It is re-used until the expiration date or if the user has deleted it from the device storage.
The default expiration date should be set to the equivalent of 180 days.
* Additionally the Creation Time <code>[fpcrtm]</code> of the First Party ID should be stored as well. The same value should be used as long as the First Party ID is available on the device. This Unix timestamp is in milliseconds.

===Create View Session ID for each Video Start===
An View Session ID <code>[sessid]</code> must be created upon start of each stream playback, sessid is unique per video play.

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

<syntaxhighlight lang="javascript">https://sc-eucert.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",
"fpid": "First Party ID",
"fpcrtm": "Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)"
"hem_unknown" : "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..."
},

// 3.2 Configure Payload: metadata
"metadata": {
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "uniqueassetid_simulcast", // unique ID for video
"userid": "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa…", // SHA512 hashed userid
"clientpassparam": "origcode=29", // Custom parameters passed
"program": "Program Name leif-och-billy", // program name
"title": "Episode Title S3 - EP1 en-ny-tjej-i-byn", // episode name
"length": "3359", // content duration in seconds
"playlisttitle": "barn", //playlist title
"ispremiumcontent": "yes", //identify premium level content
"isautoplay": "yes", //identify if autoplay is enabled
"plugv": "1.0.1", //player version
"playerv": "Sonic" // player identifier
},
"ad": {
"type": "preroll", // type of ad
"assetid": "E1UMBR1001", // unique ID for ad
"length": "30", // ad duration in seconds
"isprogrammatic": "yes",//identify if the ad is bought prommatic
"isthirdpartyad": "yes",//identify if the ad is from third party ad server
"adplatformorigin": "YuMe",//identity of ad origin
"adidx": "1/5" //placement in ad break
}
},

// 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
|-style="background-color:#d0f6f8;"
| devId || unique Device ID of a user device (e.g. SHA-256 hashed value of i.e. Advertising ID, Roku Device ID). Please verify your implemented SHA-256 by passing "00000000-0000-0000-0000-000000000000" which should return "12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8" || custom || ✓
|-
| apn || app name || custom || ✓
|-
| apv || app build version || custom || ✓
|-
|-
| uoo || device opt-out status || <code>"true"</code> or <code>"false"</code> || ✓
|-
|-
| hem_unknown || Hashed email using SHA512. This email is used by MMS reach model. (required if login feature) || custom || ✓
|-
|-style="background-color:#d0f6f8;"
| fpid || First Party ID || custom || ✓
|-style="background-color:#d0f6f8;"
| fpcrtm || Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds) || custom || ✓
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "First Party ID",
"fpcrtm": "Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)"
"hem_unknown" : "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..." //SHA512 hashed value
},
</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.

===== Create Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.
 
'''Note:''' program and title metadata values should be passed as UTF-8 strings.

===== Example Content Object =====
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "uniqueassetid",
"length": "2600",
"program": "program name",
"title": "episode title"
}</syntaxhighlight>

===== Create Ad Metadata =====
The Ad Metadata (if applicable) should be passed for each individual ad.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata. 

'''Note:''' All metadata values should be passed as UTF-8 strings.

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "unique_preroll_ad_id"
}
</syntaxhighlight>
 
<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>

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

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

'''General'''
* Playhead position in seconds, must be passed as a whole number every 10 seconds.
* The final playhead position should be sent before before sending "complete" event when content playback is complete.

'''Live Stream'''
* For Live streams, use Unix Time (in seconds) as the playhead position. Note that ad playheads must also use Unix Time for each single Ad in an Ad Pod.

'''VoD Stream'''
* For VoD stream use the player position for Content and Ad at playback start of a content or single Ad in an Ad Pod, playheads will then be 0, 10, 20, ....

'''End of an Asset'''
* Final postion must be sent at the end of Content or Ad playback

'''Ads'''
* The final playhead position must be sent when switching from content to ad, or ad to content.
* For Ad Pods, playhead must be called for each individual ad.
* When content has resumed following a mid-roll ad break, the next playhead position must continue where the previous content segment left off.

'''User Actions'''
* SCRUBBING: 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.
* PAUSE: When content is paused, send current playhead position and stop passing playhead position until content is resumed.
* EXIT Stream: If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

|-
| <code>"complete"</code> || The complete event must be sent when full playback of the content has completed . Before calling the complete event, a final playhead update with the final position is required to be sent to receive full duration credit. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. 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> || ✓
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || ✓
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || ✓
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || ✓
|-style="background-color:#d0f6f8;"
| <code>"sessid"</code> || Unique View Session ID must be created upon start of each stream playback, sessid is unique per video play. || <code>"xxxjavd6wzirm93xb95uxjy1ac5wu1627638609"</code> || ✓
|}

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

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"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
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}
</syntaxhighlight>

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

===== Sample Event Lifecycle for VoD Stream =====
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 for VoD Stream - 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>

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

'''Note:''' A 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 = LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088 // Example sessionID created using a UUID Generator

// 2. Define URL Structure with App ID and Session ID
sessionURL = https://sc-eucert.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",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000"
"hem_unknown" : "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..." //SHA512 hashed value
},

// 3.2 Configure Payload: metadata
"metadata": {
"type": "content", // "content" for video
"assetid": "uniqueassetid_simulcast", // unique ID for video
"userid": "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa…", // SHA512 hashed userid
"clientpassparam": "origcode=29", // Custom parameters passed
"program": "Program Name leif-och-billy", // program name
"title": "Episode Title S3 - EP1 en-ny-tjej-i-byn", // episode name
"length": "3359", // content duration in seconds
"playlisttitle": "barn", //playlist title
"ispremiumcontent": "yes", //identify premium level content
"isautoplay": "yes", //identify if autoplay is enabled
"plugv": "1.0.1", //player version
"playerv": "Sonic" // player identifier
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123", // unique ID for ad
"length": "3359", // ad duration in seconds
"isprogrammatic": "yes",//identify if the ad is bought prommatic
"isthirdpartyad": "yes",//identify if the ad is from third party ad server
"adplatformorigin": "YuMe",//identity of ad origin
"adidx": "1/5" //placement in ad break
}
},

// 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
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}

// Append payload to URL
function sendPayloadToNielsen() {
var payloadStr = JSON.stringify(payload); // payload as string
var imgPing = new Image();
imgPing.onload = function() {
// onload event, payload succesfull sent
};
imgPing.onerror = function() {
// handle error i.e. wait and send again
};
imgPing.src = sessionURL+encodeURIComponent(payloadStr);
}
</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 should set <code>uoo=true</code> or <code>uoo=false</code> depending on the user's privacy setting. Also, ensure that the <code>devId</code> 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.

[[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": "Cloud API Sample App",
"apv": "1",
"devId": "7be25cf9-8c40-5cc2-871e-19bf41940288",
"uoo": "false"
},
</syntaxhighlight>

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

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API 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 =====

Additionally, all applications must display the Nielsen privacy policy within their application, typically in the Settings/About screen of your application. The Nielsen privacy policy text is listed below in English and Swedish.
 ENGLISH 
<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 client's 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, or make the appropriate selection within the application's settings. 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 https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=en-se

</blockquote>
 SWEDISH 
<blockquote>
'''''OM NIELSEN-MÄTNINGEN'''''

Television och våra tittarvanor har utvecklats mycket sedan Nielsen började mäta tv-publiken på 1950-talet. Dagens möjlighet att titta på program när som helst och på flera olika enheter ökar behovet av exceptionellt kompetenta och flexibla produkter för publikmätning.

Konsumenterna ändras med tiden och likaså Nielsen. I takt med att tekniken fortsätter att utvecklas och medieföretagen försöker hitta nya sätt att tilltala tittare, är det viktigare än någonsin att förstå vad konsumenterna tittar på och med vilken typ av enhet. I dag är det en personlig och obunden upplevelse att se på en video – du kan se när som helst och var som helst. Våra produkter ger relevanta mätvärden som är nödvändiga för att informera om framgångsrik marknadsföring och programmering samt för att gynna en fortsatt tillväxt.

Som global ledare inom information och mätning strävar vi efter att skydda integriteten och säkerheten för de personuppgifter som vi samlar in, behandlar och använder..Även om våra digitala mätningsprodukter inte används för att identifiera dig på något sätt, hjälper de oss och våra klienter att mäta och analysera konsumenters medievanor online, på mobila enheter och via annan ny teknik som kan komma att utvecklas.

'''''DINA VAL'''''

Nielsen anser att du alltid ska ha ett val kring huruvida du vill bidra till vår forskning och insikter. För att avböja till Nielsens mätningar på en specifik enhet behöver du därför endast avaktivera/aktivera mätningen genom ”App Tracking/Limit Ad Tracking” (för iOS-enheter) eller ”Opt out of Ads Personalization” (för Android-enheter) som finns i din enhets inställningar. Om du har applikationer på flera mobila enheter måste du ändra inställningarna på varje enhet.

Om du ändrar dig efter att du har avböjt och vill medverka på nytt, kan du aktivera/avaktivera mätningen genom "App Tracking/ Limit Ad Tracking” (för iOS-enheter) eller "Opt out of Ads Personalization” (för Android-enheter) i enhetens inställningar.

Mer information om våra digitala mätprodukter och programvara samt om dina val när det gäller dessa finns på vår sida https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=sv

</blockquote>

'''''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 https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=sv for more information.

== Review the Reference Implementation for VoD and Live Streams ==

The Reference Implementation covers vod and Live use cases.
It also covers DAI (Dynamic Ad Insertion) with preroll and post-roll Ads.

In order to start live stream select the checkbox "isLive" in the <code>Playback Settings</code> below the video player.

Start the Reference Implementation for Sweden [http://nielsenonlinesupport.com/michel/sdkRefImplCloudDK/index.htm RefImplCloudAPISE].
<blockquote>
Review the Nielsen CloudAPI Call Sequence below the Video Player.
</blockquote>

== Disclose Nielsen Privacy Statement ==

In order to disclose the Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third-party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=en-se

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

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

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset for VoD stream and UTC Unix Time in seconds for Live stream.
*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 the Endpoint and Disable Logging.

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

*Testing: <code>https://sc-eucert.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://capi-sw.imrworldwide.com/nmapi/v2/</code>

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

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

DCR Germany Video Cloud API

2023-01-27T10:32:28Z

MichelFodjo: /* Description of Ad metadata */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing Cloud API =
This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.

<pre style="color: red">
PLease note that the Cloud API Product is not yet rolled out in Germany!
</pre>

__TOC__
==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 by your assigned Technical Account Manager upon starting the integration.

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Provided by Nielsen
|}

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

====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. '''Note:'''The "P" prefix must be removed from the App ID received before adding it to the URL, i.e. if you received PDF20695-XXXX-XXXX-XXXX-3E334133D917 from Nielsen , your url will then be : <code>[endpoint]/DF20695-XXXX-XXXX-XXXX-3E334133D917/[sessionID]/a?b=[payload]</code>
*<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://sc-eucert.nmrodam.com/nmapi/v2/</code>
*Production: <code>https://agfcapi.nmrodam.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://sc-eucert.nmrodam.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms],
"sessid": [unique view session ID for each video play]
}
</syntaxhighlight>

===Create Session ID and send EMM Ping===

====Create Session ID====

A unique Session ID <code>[sessionID]</code> must be created upon app launch and provided in the URL. This will allow the measurement to occur for the entire duration that a user is within the app.

A Session ID needs to be completely unique so it is recommended to use our generation method example provided below to create unique alpha-numerical 29 characters + 10 characters UTC timestamp, to guarantee there are no repeats, also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference and use.

Session ID example: '''LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088'''
 

<syntaxhighlight lang="javascript">
'''// Create random GUID'''
function buildGUID() {
var UAIDbase62Characters = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
var UAIDpayloadLength = 29;

function UAIDgetRandom62() {
var r1;
do {
r1 = Math.floor(Math.random() * (16 * 62));
} while (r1 > 61);
return r1;
}

var uid = '';
for (var a = 0; a < UAIDpayloadLength; a++) {
uid += UAIDbase62Characters.charAt(UAIDgetRandom62());
}
uid += Math.floor(new Date().getTime() / 1000);
return uid;
}
</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.

====Send EMM Ping (only for Mobile (iOS and Android) and Browser)====
An EMM Ping must be sent using the created unique Session ID <code>[sessionID]</code> upon start of the first stream playback.
<syntaxhighlight lang="javascript">
https://[sessionID].uaid.nmrodam.com/
</syntaxhighlight>
Also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference.

===Create View Session ID for each Video Start===
An View Session ID <code>[sessid]</code> must be created upon start of each stream playback, sessid is unique per video play.

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

<syntaxhighlight lang="javascript">https://sc-eucert.nmrodam.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

===Configure Payload===

====Description 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">
// 1. Create Session ID using the UUID Generator code provided
sessionID = LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088 // Example sessionID

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

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "",
"apn": "AppName",
"apv": "1.0"
},

// 3.2 Configure Payload: metadata
"metadata": {
"content": { // object for measuring video content
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
// custom metadata
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
},
"ad": {
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Ad",
"nol_c17": "p17,preroll"
}
},

// 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
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609" // create and pass a unique sessid for each video play using UUID Generator code provided
}
</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) - Not required for AGF || custom ||
|-
| apn || app name || custom || ✓
|-
| apv || app build version || custom || ✓
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "",
"apn": "AppName",
"apv": "1.0"
},
</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 =====

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

For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required/Obligatory
|-
| type || type of asset || <code>"content"</code> || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no [[Special Characters]]) || ✓
|-
| program ||(string) name of program (254 character limit) || custom || ✓
|-
| title ||(string) episode title (max 254 characters) || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| length || length of content in seconds || <code>seconds</code> ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| clientid ||
parent ID – value is automatically populated through provided App ID. 
In order to override the brand configured to the App ID, pass parent 
value here and the sub-brand ID associated with that brand in the subbrand 
key (e.g. multiple brands in App)
||
provided by Nielsen
||
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided 
App ID. In order to override the sub-brand configured to the App ID, value can 
be passed here (e.g. multiple sub-brands in App)
||
provided by Nielsen
||

|-
| nol_c0 || number of episode part (Sendungsteilenummer) || number || ✓
|-
| nol_c2 || web only || 'Y' or 'N' || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || duration in seconds || `seconds` ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c12 || type of asset || 'Trailer' or 'Content' || ✓
|-
| nol_c13 || original air time || `(YYYY-MM-TT)T(HH:mm:ss) Example: 2004-06-14T23:34:30 ||
|-
| nol_c14 || ISO 8601 timestamp || `(YYYY-MM-TT)T(HH:mm:ss)` ||
|-
| nol_c15 || format ID || custom ||
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c18 || livestream || 'Y' or 'N' || ✓
|-
| nol_c19 || custom variable || custom ||
|-
| nol_c20 || GfK-ID || custom ||
|}
 

====== Example Content metadata ======
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
// custom metadata
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
}</syntaxhighlight>

===== Ad Metadata (optional for public broadcasters) =====
====== Description of Ad metadata ======
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

 
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no SPACE - no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters]) || ✓
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen ||
|-
| title || only the AD-ID is necessary || custom, <AD-ID> without "VAST" Prefix or other, i.e. '2352723141' || ✓
|-
| length || length of Ad in seconds || length of Ad in seconds || ✓
|-
| nol_c1 || universal AdID (Additional AD-ID to be used by second or third marketers) || custom, i.e. 'adgapid_022_800160_1601097_001_0_0' ||
|-
| nol_c2 || web only || 'Y' or 'N' ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || duration of the video file in seconds || || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c11 || AD-ID (unique ID of an advertisement. Necessary if ads are being broadcasted) || custom, i.e. '2352723141' || ✓
|-
| nol_c12 || content type (key distinction of content, advertising, and Trailer) || 'Ad' || ✓
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c17 || ad placement type (placement information of advertisement) || 'preroll', 'midroll', 'postroll' or 'other' || ✓
|}

====== Example Ad metadata ======
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Ad",
"nol_c17": "p17,preroll"
}

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

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

'''General'''
* Playhead position in seconds, must be passed as a whole number every 10 seconds.
* The final playhead position should be sent before before sending "complete" event when content playback is complete.

'''Live Stream'''
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position. Note that ad playheads must also use Unix Time for each single Ad in an Ad Pod.

'''VoD Stream'''
* For VoD stream use the player position for Content and Ad at playback start of a content or single Ad in an Ad Pod, playheads will then be 0, 10, 20, ....

'''End of an Asset'''
* Final postion must be sent at the end of Content or Ad playback

'''Ads'''
* The final playhead position must be sent when switching from content to ad, or ad to content.
* For Ad Pods, playhead must be called for each individual ad.
* When content has resumed following a mid-roll ad break, the next playhead position must continue where the previous content segment left off.

'''User Actions'''
* SCRUBBING: 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.
* PAUSE: When content is paused, send current playhead position and stop passing playhead position until content is resumed.
* EXIT Stream: If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

|-
| <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. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is optional and can be sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. 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> || ✓
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || ✓
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || ✓
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || ✓
|-style="background-color:#d0f6f8;"
| <code>"sessid"</code> || Unique View Session ID must be created upon start of each stream playback, sessid is unique per video play. || <code>"xxxjavd6wzirm93xb95uxjy1ac5wu1627638609"</code> || ✓
|}

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

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"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
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}
</syntaxhighlight>

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

===== Sample Event Lifecycle for VoD Stream =====
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 for VoD Stream - 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>

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

see '''[[#Payload Example|Payload Example]]'''

// Append payload to URL
function sendPayloadToNielsen() {
var payloadStr = JSON.stringify(payload); // payload as string
var imgPing = new Image();
imgPing.onload = function() {
// onload event, payload succesfull sent
};
imgPing.onerror = function() {
// handle error i.e. wait and send again
};
imgPing.src = sessionURL+encodeURIComponent(payloadStr);
}
</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
|}

== Review the Reference Implementation for VoD and Live Streams ==

The Reference Implementation covers vod and Live use cases.
It also covers DAI (Dynamic Ad Insertion) with preroll and postroll Ads.

In order to start live stream select the checkbox "isLive" in the <code>Playback Settings</code> below the video player.

Start the Reference Implementation for DK [https://nielsenonlinesupport.com/dk/cloudapi/index.htm?debug=true RefImplCloudAPIDK].
<blockquote>
Review the Nielsen CloudAPI Call Sequence below the Video Player.
</blockquote>

== Disclose Nielsen Privacy Statement ==

The Nielsen Cloud API measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen Cloud API measurement is utilizing a cookieless domain.

In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:

A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=de .

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

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

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset for VoD stream and UTC Unix Time in seconds for Live stream.
*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.

== 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://sc-eucert.nmrodam.com/nmapi/v2/</code>
*Production: <code>https://agfcapi.nmrodam.com/nmapi/v2/</code>

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

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

DCR Germany Video Browser SDK

2023-01-27T10:24:59Z

MichelFodjo: /* Description of Ad metadata */

DCR Germany Video App SDK

2023-01-27T10:23:16Z

MichelFodjo: /* Description of Ad metadata */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

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

== 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.
* <blockquote>'''No ID AppSDK''': <pre style="color: red">ONLY the No ID AppSDK should be downloaded for the AGF market!</pre>
</blockquote>

* '''Nielsen SDK:''' The Nielsen SDK package contains a variety of sample players for your reference.
Please contact our SDK sales support team if you do not have any of these prerequisites or have any questions.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

== Implementation ==
This guide covers implementation steps for iOS using Xcode and Android using Android Studio.

== Setting up your Development Environment ==

=== iOS ===

<big>
'''Configuring Xcode Development Environment'''
</big>

Nielsen App SDK is compatible with Apple iOS versions 9.0 and above.

The SDK uses the NSURLSession instead of the deprecated NSURLConnection.

<blockquote>'''Note''': All communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

<big>'''Importing Frameworks'''</big>
The first step is to ensure that the following frameworks and libraries are imported into the Frameworks folder of the Xcode project before creating an instance of the Nielsen App SDK object.
* UIKit.framework
* Foundation.framework
* SystemConfiguration.framework
* Security.framework
** Nielsen Analytics framework uses several functions in this library.
* AVFoundation.framework
** This framework is mandatory for the iOS SDK version 5.1.1 to work.
* CoreLocation.framework
* CoreMedia.framework
* NielsenAppApi.framework
* libc++.tbd (as SDK contains Objective C++ source file)
** Alternatively, include -lstdc++ in Build Settings → Other Linker Flag of the Xcode project

<blockquote>'''Example'''
* Extract “NielsenAppApi.Framework” from the Nielsen App SDK sample app and copy it to the Frameworks folder of the Xcode project.
* Add the code <code>-#import NielsenAppApi/NielsenAppApi.h</code> to the View Controller’s header file.</blockquote>

Ensure that the following are included in the Linked Frameworks and Libraries list (located in the project’s Summary settings).
* Nielsen App SDK
* iOS security framework
 
<big>'''Using Swift'''</big>
To import a set of Objective-C files in the same app target as your Swift code, you rely on an Objective-C bridging header to expose those files to Swift. Xcode offers to create this header file when you add a Swift file to an existing Objective-C app or an Objective-C file to an existing Swift app.

Select File/New File/Objective-C File 
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] 
Once this file has been created, you need to add the following:
<syntaxhighlight lang="swift">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
<big>'''Using Objective-C'''</big>
Add the code
<syntaxhighlight lang ="objective-c">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
to the View Controller’s header file.
 

=== Android ===
==== General ====
<big>
'''Configuring Android Java Development Environment'''
</big>

*The Nielsen App SDK (located in the ''com.nielsen.app.sdk'' package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is the only public class belonging to the com.nielsen.app.sdk package.

'''Nielsen App SDK is compatible with Android OS versions 2.3+. Clients can control/configure the protocol to be used – HTTPS or HTTP to suit their needs.'''

The Nielsen App SDK 1.2 library is composed of two parts:
* The Java AppSdk.jar library runs on the Android’s Dalvik Virtual Machine.
* The C/C++ libAppSdk.so native library that runs directly on the device’s hardware.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote>

The requirement for the Java ''AppSdk.jar'' library and the ''libAppSdk.so'' native library will depend on the type of host application that will make use of them.
* '''For Video player applications'''
** The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 3.0 and later will support it natively).
** If the player application uses a 3rd party media player implementing its own HLS, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.
* '''For Audio player applications'''
** The Android OS hosting the App SDK should be at version 2.3 and later since the SDK depends on Google Play support to work properly.
Unzip the Nielsen App SDK sample app and copy the ''AppSdk.jar'' into the libs/ folder on the App’s Eclipse project. Copy the ''libAppSdk.so'' file under ''libs/armeabi/'' folder into the same Eclipse project.
* App SDK 1.2 provides support for x86, mips, and armeabi-7a architecture; the respective ''libAppSdk.so'' can be found under the ''libs/x86/'', ''libs/mips/'', and ''libs/armeabi-7a/'' folders.
Add the following permissions on the project’s ''AndroidManifest.xml'' file.
<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details on handling runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. Download the latest ''google-play-services_lib'' and include it in the App’s project in order to use the App SDK.
* App SDK checks to see if a Google service is available and updated.
* If unavailable or updated, App SDK will not use this service when executing its functions and will reference missing imports and the app will not be compiled.
To include the Google Play library in the media player project, copy the ''google-play-services_lib'' folder into the same location as the project
* Access '''File > Import'''.
* Select '''Existing Android Code into Workspace''' and click '''Next'''.
* Click '''Browse''' and navigate to the ''google-play-services_lib'' to include it into the projects.
* Select the exact '''Project Build Target''' for Eclipse to use from Android SDK.
** Android 4.4.2, etc. OR
** Edit ''project.properties'' file to point to Android target version e.g. target= android-19.
Once the google-play-services_lib is included into the App project, include the following code under the <code><application></code> node in the <code>AndroidManifest.xml</code>.

<syntaxhighlight lang="java"><meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/></syntaxhighlight>

Also, include the ''version.xml'' file that comes with the ''google-play-services_lib'' under the res/values directory of the media player project.
* Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface.

<big>'''Library'''</big>

Nielsen App SDK uses the following packages/classes from the Google Play service.
* google-play-services_lib

'''<big>Classes/package</big>'''
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

==== Add the dependency "lifecycle-extensions" to your project ====
Add the dependency "lifecycle-extensions" in the in the app gradle file as follows:
<syntaxhighlight lang="java">
implementation "androidx.lifecycle:lifecycle-extensions:2.1.0"
</syntaxhighlight>

This will enable the AppSdk to detect the application UI visibility state transitions between background and foreground by utilizing the LifeCycleObserver. This is i.e. required for the Static Measurement.

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-agf-v0.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-agf-ad-v0.png||SDK Integration Architecture Diagram - Ad]]

== SDK Initialization ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. The sharedInstance API that creates a singleton object was deprecated before version 5.1.1. (Version 4.0 for Android)

* A maximum of four SDK instances per appid are supported. When a fifth SDK instance is launched, the SDK will return “nil” from [[initWithAppInfo:delegate:]]
* When four SDK instances exist, you must destroy an old instance before creating a new one.

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || ✓ || "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || No || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || No || "1.0.2"
|-
| sfcode || Nielsen collection facility to which the SDK should connect.
'''AGF Clients'''
* "eu" (For Testing/Certification and in Production)
|| Nielsen-specified || ✓ || "eu"
|-
| nol_devDebug || Enables Nielsen console logging. Has to be set to "DEBUG" until certified
|| Nielsen-specified || Optional || "DEBUG"
|}
 

==== Sample SDK Initialization Code ====

===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"sfcode": "eu",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
 
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

====== Objective-C ======
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>If App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.</blockquote>
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
@"sfcode": "eu",
@"nol_devDebug": @"DEBUG"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

===== Android =====
====== Java ======

AppSDK is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="java">

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA")
.put("sfcode", "eu")
.put("nol_devDebug", "DEBUG");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
Here, <code>appContext</code> is the App context object and <code>appSdkConfig</code> is JSON object for holding the parameters (<code>appid</code>, <code>appname</code>, <code>sfcode</code>) the App passes to the Nielsen App SDK via a JSON string. The appid is obtained from Nielsen operational support and is unique to the app.

The integration of Nielsen App SDK will depend on the type of client app. 
* Ensure that SDK files (AppSdk.jar and libAppSdk.so [App SDK 1.2 Only]) are included under the App’s project and the App SDK is linked to the App (the setting to link App SDK to the App can be found on the property page of the App’s project).

== APP SDK Error & Event Codes ==
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.
== Configure Payload ==
=== Handling JSON Metadata ===
All the SDK methods handle only two types of objects: NSString, NSDictionary. The parameters passed must be either a JSON formatted string or a NSDictionary object. The JSON passed in the SDK must be well-formed.
* NSDictionary object
** If an object of the unexpected type is passed to the method, the error message will be logged.
** The error message will be logged if the string has an invalid JSON format.
* JSON value must be a string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, sfcode, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary.

=== Configure ChannelInfo metadata ===
==== Description of ChannelInfo metadata ====
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}
 

==== Example ChannelInfo metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelName","My Channel Name 1")
</syntaxhighlight>

=== Configure Content metadata ===

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

For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required/Obligatory
|-
| type || type of asset || <code>"content"</code> || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no [[Special Characters]]) || ✓
|-
| program ||(string) name of program (254 character limit) || custom || ✓
|-
| title ||(string) episode title (max 254 characters) || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| length || length of content in seconds || <code>seconds</code> ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| clientid ||
parent ID – value is automatically populated through provided App ID. 
In order to override the brand configured to the App ID, pass parent 
value here and the sub-brand ID associated with that brand in the subbrand 
key (e.g. multiple brands in App)
||
provided by Nielsen
||
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided 
App ID. In order to override the sub-brand configured to the App ID, value can 
be passed here (e.g. multiple sub-brands in App)
||
provided by Nielsen
||

|-
| nol_c0 || number of episode part (Sendungsteilenummer) || number || ✓
|-
| nol_c2 || web only || 'Y' or 'N' || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || duration in seconds || `seconds` ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c12 || type of asset || 'Trailer' or 'Content' || ✓
|-
| nol_c13 || original air time || `(YYYY-MM-TT)T(HH:mm:ss) Example: 2004-06-14T23:34:30 ||
|-
| nol_c14 || ISO 8601 timestamp || `(YYYY-MM-TT)T(HH:mm:ss)` ||
|-
| nol_c15 || format ID || custom ||
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c18 || livestream || 'Y' or 'N' || ✓
|-
| nol_c19 || custom variable || custom ||
|-
| nol_c20 || GfK-ID || custom ||
|}
 

==== Example Content metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
];
</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">
NSDictionary *contentMetadata = @
{@"type": @"content",
@"assetid": @"88675545",
@"length": @"3600",
@"program", "Program Name",
@"title": @"episode title",
@"nol_c0": "p0,1",
@"nol_c2": "p2,Y",
@"nol_c7": "p7,videoid123",
@"nol_c8": "p8,3600",
@"nol_c9": "p9,VideoTitle123",
@"nol_c10": "p10,clientname",
@"nol_c12": "p12,content",
@"nol_c18": "p18,N"
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">
JSONObject contentMetadata = new JSONObject()
.put("type", "content")
.put("assetid", "88675545")
.put("program", "Program Name")
.put("title", "episode title")
.put("length", "3600")
.put("nol_c0", "p0,1")
.put("nol_c2", "p2,Y")
.put("nol_c7", "p7,videoid123")
.put("nol_c8", "p8,3600")
.put("nol_c9", "p9,VideoTitle123")
.put("nol_c10", "p10,clientname")
.put("nol_c12", "p12,content")
.put("nol_c18", "p18,N")
</syntaxhighlight>

=== Configure Ad Metadata ===
==== Description of Ad metadata ====
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''
 
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no SPACE - no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters]) || ✓
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen ||
|-
| title || only the AD-ID is necessary || custom, <AD-ID> without "VAST" Prefix or other, i.e. '2352723141' || ✓
|-
| length || length of Ad in seconds || length of Ad in seconds || ✓
|-
| nol_c1 || universal AdID (Additional AD-ID to be used by second or third marketers) || custom, i.e. 'adgapid_022_800160_1601097_001_0_0' ||
|-
| nol_c2 || web only || 'Y' or 'N' ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || duration of the video file in seconds || || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c11 || AD-ID (unique ID of an advertisement. Necessary if ads are being broadcasted) || custom, i.e. '2352723141' || ✓
|-
| nol_c12 || content type (key distinction of content, advertising, and Trailer) || 'Ad' || ✓
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c17 || ad placement type (placement information of advertisement) || 'preroll', 'midroll', 'postroll' or 'other' || ✓
|}

==== Example Ad metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let adMetadata = [
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Ad",
"nol_c17": "p17,preroll"
];
</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">

NSDictionary *adMetadata = @
{@"type": @"preroll",
@"assetid": @"ad345-67483"",
@"title": @"ad_title",
@"length": @"25",
@"nol_c8": "p8,25",
@"nol_c10": "p10,clientname",
@"nol_c11": "p11,2352723141",
@"nol_c12": "p12,Ad",
@"nol_c17": "p17,preroll"
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">

JSONObject adMetadata = new JSONObject()
.put("type", "preroll")
.put("assetid", "ad345-67483")
.put("title", "2352723141")
.put("length", "25")
.put("nol_c8", "p8,25")
.put("nol_c10", "p10,clientname")
.put("nol_c11", "p11,2352723141")
.put("nol_c12", "p12,Ad")
.put("nol_c17", "p17,preroll")
</syntaxhighlight>
== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| 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.
|}

=== Life cycle of SDK instance ===
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# '''Processing state''' – The SDK instance processes playing information. [[play]] and [[loadMetadata]] calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[end]] – SDK instance exits from Processing state when this API is called.
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

'''Note''': In case of any interruptions during playback due to alarm, calendar, call, flight mode, Wi-Fi toggle, channel change, etc., call [[stop]] to pause the measurement.
* As soon as the playback resumes, call [[loadMetadata]] and [[playheadPosition]].</blockquote>

=== API Call sequence ===
==== Use Case 1: Content has no Advertisements ====
Call [[play()]] with channelName JSON as below.
'''[[#Example ChannelInfo metadata|Example ChannelInfo metadata]]'''
Call [[loadMetadata()]] with JSON metadata for content as below.
'''[[#Example Content metadata|Example Content metadata]]'''

Call [[setPlayheadPosition()]] every one second until the stream playback is interrupted or has ended.
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.
'''[[#Example ChannelInfo metadata|Example ChannelInfo metadata]]'''
<blockquote>Note: ONLY for a preroll Ad , Call [[loadMetadata()]] for Content before calling it for preroll ad </blockquote>

Call [[loadMetadata()]] with JSON metadata for ad as below.
'''[[#Example Ad metadata|Example Ad metadata]]'''
<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 the Ad playback is interrupted or has ended for each single Ad. 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 (Content resume) || <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.</blockquote>

=== Sequence of Calls ===

=== play ===
Use [[play]] to pass the channel descriptor information through channelName parameter after the SDK has been initialized and the content starts playing. If the user is returning from a '''Pause/Stop''' interaction, call [[loadMetadata]] with the same metadata and continue sending [[playheadPosition]] once the playback resumes.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c"> - (void)play:(id)channelInfo;</syntaxhighlight>
|Android = <syntaxhighlight lang="java"> public void play(JSONObject channelInfo);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenAppApi?.play(JSONObject channelInfo);</syntaxhighlight>
}}

=== loadMetadata ===
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">– (void)loadMetadata:(id)contentMetadata;</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void loadMetadata(JSONObject contentMetadata);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(contentMetadata)</syntaxhighlight>
}}

=== playheadPosition ===

"playheadPosition" has to be called every second.

* VOD :
** For Content and each single Ad, pass the current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3...
*Live :
**For Content, pass the Unix timestamp (seconds since Jan-1-1970 UTC). Pass whole number that increments only by 1 like 1631098029,1631098030,1631098031,1631098032,... .
**For each single Ad, pass the current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3...

{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">
– (void) playheadPosition: (long long) playheadPos
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
AVPlayer *player;
CMTime curTime=[player currentTime];
int pos = CMTimeGetSeconds(curTime);
[nAppApiObject playheadPosition:pos];
</syntaxhighlight>

|Swift = <syntaxhighlight lang="swift">
//Monitor the Playhead position of the AVPlayer
let timeInterval: CMTime = CMTimeMakeWithSeconds(1.0,10)
self.avPlayerViewController.player?.addPeriodicTimeObserver(forInterval: timeInterval, queue: DispatchQueue.main) {(elapsedTime: CMTime) -> Void in
if self.avPlayerViewController.player!.currentItem?.status == .readyToPlay {
let time : Float64 = self.avPlayerViewController.player!.currentTime().seconds;
let pos = Int64(time);
NSLog("New Elapse Time = \(time)");
self.nielsenAppApi?.playheadPosition(pos);
}
}
}
</syntaxhighlight>
|Android = <syntaxhighlight lang="java">
public void setPlayheadPosition(long position)
</syntaxhighlight>
}}

=== stop ===
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">– (void) stop</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void stop()</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.stop</syntaxhighlight>
}}

=== end ===
Call when the content asset completes playback. Stops measurement progress.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">- (void) end;</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void stop()</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.stop</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 and withhold sending playhead position.
* '''For video content:'''
** Call [[loadMetadata]] with the same metadata and continue sending [[playheadPosition]] once the playback resumes.
* '''For ads:'''
** just continue sending [[playheadPosition]] once the playback resumes (no [[loadMetadata]]).

Additional information:
* '''For type 'content': '''Sending a "loadMetadata" event after a "stop" event will be handled by the SDK as a "resume", as long as the "assetid" and "type" are the same and not changed from the values before the "stop" event happened. Changing "assetid" value will lead into a new stream. Changing of "type" from "content" to "preroll" ("midroll", "postroll") will lead into a new object (ad) with that content stream. Changing any other parameter (eg. "program" or "title") for the content will not affect the reported content data (will stay as in the very first "content" metadata)

=== App termination ===
If your app is executing a termination process and therefore ending the Content or Ad Playback, call [[end]] if the Content is playing or [[stop]] if an Ad is playing.

== Privacy and Opt-Out ==

The AppSDK measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen AppSDK measurement is utilizing a cookieless domain.
In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=de .

Please contact your Nielsen SDK support team directly for any related questions.

== Going Live ==
Following Nielsen testing, users need to make one update to the initialization call to ensure that the site is being measured properly.

# '''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:

'''<big>iOS Example:</big>'''

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"sfcode": "eu"
// Remove Flag: "nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

'''<big>Android Example:</big>'''
<syntaxhighlight lang="java">
try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("sfcode", "eu")
// Remove Flag: "nol_devDebug": "DEBUG"

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>

'''Note''': before going live, you have to inform the Nielsen team - this is necessary because the Nielsen team has to adjust internal configuration parameters to enable data collection. Without that notification, no data will be collected, and no data will be reported.

AGF Metadata Convention

2023-01-27T08:43:32Z

MichelFodjo: /* Static Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]
__TOC__

= AGF Metadata Convention =

The Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.

'''Note:''' All metadata values should be passed as UTF-8 strings. 

== Static Measurement ==

{| class="wikitable"
|-
! Key !! Description !! Values !! Required (Obligatory) !! AGF Convention !! Example data - RTL
|-
| type || type of asset || <code>"static"</code> || ✓ || hardcoded string required by Nielsen || <code>"static"</code>
|-
| assetid || unique ID assigned to each article/page; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations) || custom (no [[Special Characters]]) || ✓ || Content Article ID. If it is not an article page and therefore no ID is available, the page path is used. || "999452"
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section) || custom || ✓ || Section of Website or App || "/rtl_portal/news"
|-
| segA || custom segment for reporting: unique values across custom segments (segA + segB + segC) || custom || ✓ || AGOF code or comparable unit code || "dbrsowf_rtlnews"
|-
| segB || custom segment for reporting: unique values across custom segments (segA + segB + segC) || custom || ✓ || Value to define content view count vs. 'Werbetraeger' view count. For Content: "CPI" . For 'Werbetraeger': "WPI_timestamp" (Timestamp in whole seconds, not milliseconds) || For Content: "CPI" . For 'Werbetraeger' after user interaction with the site and newly loaded Content: "WPI_1657634473".
|-
| segC || custom segment for reporting: unique values across custom segments (segA + segB + segC) || custom || || Program name || "IBES"
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen || ✓ || Same as video measurement, provided by Nielsen || "c01"
|}

== Video Measurement ==

Please refer to this AGF PDF Document: '''[https://nielsendownloads.digitalengsdk.com/digital/220907_AGF+Custom+Variables+and+Metadata+DCR+SDK++v1.8_english.pdf Metadata Document for Video]'''

DCR Germany Video Cloud API

2023-01-25T16:10:18Z

MichelFodjo:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

= DCR Integration Utilizing Cloud API =
This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.

<pre style="color: red">
PLease note that the Cloud API Product is not yet rolled out in Germany!
</pre>

__TOC__
==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 by your assigned Technical Account Manager upon starting the integration.

{| class="wikitable"
|-
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Provided by Nielsen
|}

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

====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. '''Note:'''The "P" prefix must be removed from the App ID received before adding it to the URL, i.e. if you received PDF20695-XXXX-XXXX-XXXX-3E334133D917 from Nielsen , your url will then be : <code>[endpoint]/DF20695-XXXX-XXXX-XXXX-3E334133D917/[sessionID]/a?b=[payload]</code>
*<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://sc-eucert.nmrodam.com/nmapi/v2/</code>
*Production: <code>https://agfcapi.nmrodam.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://sc-eucert.nmrodam.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms],
"sessid": [unique view session ID for each video play]
}
</syntaxhighlight>

===Create Session ID and send EMM Ping===

====Create Session ID====

A unique Session ID <code>[sessionID]</code> must be created upon app launch and provided in the URL. This will allow the measurement to occur for the entire duration that a user is within the app.

A Session ID needs to be completely unique so it is recommended to use our generation method example provided below to create unique alpha-numerical 29 characters + 10 characters UTC timestamp, to guarantee there are no repeats, also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference and use.

Session ID example: '''LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088'''
 

<syntaxhighlight lang="javascript">
'''// Create random GUID'''
function buildGUID() {
var UAIDbase62Characters = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
var UAIDpayloadLength = 29;

function UAIDgetRandom62() {
var r1;
do {
r1 = Math.floor(Math.random() * (16 * 62));
} while (r1 > 61);
return r1;
}

var uid = '';
for (var a = 0; a < UAIDpayloadLength; a++) {
uid += UAIDbase62Characters.charAt(UAIDgetRandom62());
}
uid += Math.floor(new Date().getTime() / 1000);
return uid;
}
</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.

====Send EMM Ping (only for Mobile (iOS and Android) and Browser)====
An EMM Ping must be sent using the created unique Session ID <code>[sessionID]</code> upon start of the first stream playback.
<syntaxhighlight lang="javascript">
https://[sessionID].uaid.nmrodam.com/
</syntaxhighlight>
Also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference.

===Create View Session ID for each Video Start===
An View Session ID <code>[sessid]</code> must be created upon start of each stream playback, sessid is unique per video play.

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

<syntaxhighlight lang="javascript">https://sc-eucert.nmrodam.com/nmapi/v2/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

===Configure Payload===

====Description 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">
// 1. Create Session ID using the UUID Generator code provided
sessionID = LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088 // Example sessionID

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

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "",
"apn": "AppName",
"apv": "1.0"
},

// 3.2 Configure Payload: metadata
"metadata": {
"content": { // object for measuring video content
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
// custom metadata
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
},
"ad": {
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Ad",
"nol_c17": "p17,preroll"
}
},

// 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
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609" // create and pass a unique sessid for each video play using UUID Generator code provided
}
</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) - Not required for AGF || custom ||
|-
| apn || app name || custom || ✓
|-
| apv || app build version || custom || ✓
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "",
"apn": "AppName",
"apv": "1.0"
},
</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 =====

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

For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required/Obligatory
|-
| type || type of asset || <code>"content"</code> || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no [[Special Characters]]) || ✓
|-
| program ||(string) name of program (254 character limit) || custom || ✓
|-
| title ||(string) episode title (max 254 characters) || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| length || length of content in seconds || <code>seconds</code> ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| clientid ||
parent ID – value is automatically populated through provided App ID. 
In order to override the brand configured to the App ID, pass parent 
value here and the sub-brand ID associated with that brand in the subbrand 
key (e.g. multiple brands in App)
||
provided by Nielsen
||
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided 
App ID. In order to override the sub-brand configured to the App ID, value can 
be passed here (e.g. multiple sub-brands in App)
||
provided by Nielsen
||

|-
| nol_c0 || number of episode part (Sendungsteilenummer) || number || ✓
|-
| nol_c2 || web only || 'Y' or 'N' || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || duration in seconds || `seconds` ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c12 || type of asset || 'Trailer' or 'Content' || ✓
|-
| nol_c13 || original air time || `(YYYY-MM-TT)T(HH:mm:ss) Example: 2004-06-14T23:34:30 ||
|-
| nol_c14 || ISO 8601 timestamp || `(YYYY-MM-TT)T(HH:mm:ss)` ||
|-
| nol_c15 || format ID || custom ||
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c18 || livestream || 'Y' or 'N' || ✓
|-
| nol_c19 || custom variable || custom ||
|-
| nol_c20 || GfK-ID || custom ||
|}
 

====== Example Content metadata ======
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
// custom metadata
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
}</syntaxhighlight>

===== Ad Metadata (optional for public broadcasters) =====
====== Description of Ad metadata ======
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

 
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no SPACE - no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters]) || ✓
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen ||
|-
| title || only the AD-ID is necessary || custom, <AD-ID> without "VAST" Prefix or other, i.e. '2352723141' || ✓
|-
| length || length of Ad in seconds || length of Ad in seconds || ✓
|-
| nol_c1 || universal AdID (Additional AD-ID to be used by second or third marketers) || custom, i.e. 'adgapid_022_800160_1601097_001_0_0' ||
|-
| nol_c2 || web only || 'Y' or 'N' ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || duration of the video file in seconds || || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c11 || AD-ID (unique ID of an advertisement. Necessary if ads are being broadcasted) || custom, i.e. '2352723141' || ✓
|-
| nol_c12 || content type (key distinction of content, advertising, and Trailer) || 'Werbung' || ✓
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c17 || ad placement type (placement information of advertisement) || 'preroll', 'midroll', 'postroll' or 'sonstiges' || ✓
|}
====== Example Ad metadata ======
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Ad",
"nol_c17": "p17,preroll"
}

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

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

'''General'''
* Playhead position in seconds, must be passed as a whole number every 10 seconds.
* The final playhead position should be sent before before sending "complete" event when content playback is complete.

'''Live Stream'''
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position. Note that ad playheads must also use Unix Time for each single Ad in an Ad Pod.

'''VoD Stream'''
* For VoD stream use the player position for Content and Ad at playback start of a content or single Ad in an Ad Pod, playheads will then be 0, 10, 20, ....

'''End of an Asset'''
* Final postion must be sent at the end of Content or Ad playback

'''Ads'''
* The final playhead position must be sent when switching from content to ad, or ad to content.
* For Ad Pods, playhead must be called for each individual ad.
* When content has resumed following a mid-roll ad break, the next playhead position must continue where the previous content segment left off.

'''User Actions'''
* SCRUBBING: 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.
* PAUSE: When content is paused, send current playhead position and stop passing playhead position until content is resumed.
* EXIT Stream: If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

|-
| <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. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is optional and can be sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. 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> || ✓
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || ✓
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || ✓
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || ✓
|-style="background-color:#d0f6f8;"
| <code>"sessid"</code> || Unique View Session ID must be created upon start of each stream playback, sessid is unique per video play. || <code>"xxxjavd6wzirm93xb95uxjy1ac5wu1627638609"</code> || ✓
|}

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

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"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
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}
</syntaxhighlight>

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

===== Sample Event Lifecycle for VoD Stream =====
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 for VoD Stream - 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>

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

see '''[[#Payload Example|Payload Example]]'''

// Append payload to URL
function sendPayloadToNielsen() {
var payloadStr = JSON.stringify(payload); // payload as string
var imgPing = new Image();
imgPing.onload = function() {
// onload event, payload succesfull sent
};
imgPing.onerror = function() {
// handle error i.e. wait and send again
};
imgPing.src = sessionURL+encodeURIComponent(payloadStr);
}
</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
|}

== Review the Reference Implementation for VoD and Live Streams ==

The Reference Implementation covers vod and Live use cases.
It also covers DAI (Dynamic Ad Insertion) with preroll and postroll Ads.

In order to start live stream select the checkbox "isLive" in the <code>Playback Settings</code> below the video player.

Start the Reference Implementation for DK [https://nielsenonlinesupport.com/dk/cloudapi/index.htm?debug=true RefImplCloudAPIDK].
<blockquote>
Review the Nielsen CloudAPI Call Sequence below the Video Player.
</blockquote>

== Disclose Nielsen Privacy Statement ==

The Nielsen Cloud API measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen Cloud API measurement is utilizing a cookieless domain.

In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:

A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=de .

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

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

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset for VoD stream and UTC Unix Time in seconds for Live stream.
*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.

== 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://sc-eucert.nmrodam.com/nmapi/v2/</code>
*Production: <code>https://agfcapi.nmrodam.com/nmapi/v2/</code>

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

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

DCR Germany Video Browser SDK

2023-01-25T14:18:00Z

MichelFodjo: /* Description of Ad metadata */

DCR Germany Video Browser SDK

2023-01-25T14:16:35Z

MichelFodjo: /* Description of Content metadata */

DCR Germany Video App SDK

2023-01-25T14:13:57Z

MichelFodjo: /* Description of Ad metadata */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

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

== 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.
* <blockquote>'''No ID AppSDK''': <pre style="color: red">ONLY the No ID AppSDK should be downloaded for the AGF market!</pre>
</blockquote>

* '''Nielsen SDK:''' The Nielsen SDK package contains a variety of sample players for your reference.
Please contact our SDK sales support team if you do not have any of these prerequisites or have any questions.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

== Implementation ==
This guide covers implementation steps for iOS using Xcode and Android using Android Studio.

== Setting up your Development Environment ==

=== iOS ===

<big>
'''Configuring Xcode Development Environment'''
</big>

Nielsen App SDK is compatible with Apple iOS versions 9.0 and above.

The SDK uses the NSURLSession instead of the deprecated NSURLConnection.

<blockquote>'''Note''': All communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

<big>'''Importing Frameworks'''</big>
The first step is to ensure that the following frameworks and libraries are imported into the Frameworks folder of the Xcode project before creating an instance of the Nielsen App SDK object.
* UIKit.framework
* Foundation.framework
* SystemConfiguration.framework
* Security.framework
** Nielsen Analytics framework uses several functions in this library.
* AVFoundation.framework
** This framework is mandatory for the iOS SDK version 5.1.1 to work.
* CoreLocation.framework
* CoreMedia.framework
* NielsenAppApi.framework
* libc++.tbd (as SDK contains Objective C++ source file)
** Alternatively, include -lstdc++ in Build Settings → Other Linker Flag of the Xcode project

<blockquote>'''Example'''
* Extract “NielsenAppApi.Framework” from the Nielsen App SDK sample app and copy it to the Frameworks folder of the Xcode project.
* Add the code <code>-#import NielsenAppApi/NielsenAppApi.h</code> to the View Controller’s header file.</blockquote>

Ensure that the following are included in the Linked Frameworks and Libraries list (located in the project’s Summary settings).
* Nielsen App SDK
* iOS security framework
 
<big>'''Using Swift'''</big>
To import a set of Objective-C files in the same app target as your Swift code, you rely on an Objective-C bridging header to expose those files to Swift. Xcode offers to create this header file when you add a Swift file to an existing Objective-C app or an Objective-C file to an existing Swift app.

Select File/New File/Objective-C File 
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] 
Once this file has been created, you need to add the following:
<syntaxhighlight lang="swift">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
<big>'''Using Objective-C'''</big>
Add the code
<syntaxhighlight lang ="objective-c">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
to the View Controller’s header file.
 

=== Android ===
==== General ====
<big>
'''Configuring Android Java Development Environment'''
</big>

*The Nielsen App SDK (located in the ''com.nielsen.app.sdk'' package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is the only public class belonging to the com.nielsen.app.sdk package.

'''Nielsen App SDK is compatible with Android OS versions 2.3+. Clients can control/configure the protocol to be used – HTTPS or HTTP to suit their needs.'''

The Nielsen App SDK 1.2 library is composed of two parts:
* The Java AppSdk.jar library runs on the Android’s Dalvik Virtual Machine.
* The C/C++ libAppSdk.so native library that runs directly on the device’s hardware.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote>

The requirement for the Java ''AppSdk.jar'' library and the ''libAppSdk.so'' native library will depend on the type of host application that will make use of them.
* '''For Video player applications'''
** The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 3.0 and later will support it natively).
** If the player application uses a 3rd party media player implementing its own HLS, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.
* '''For Audio player applications'''
** The Android OS hosting the App SDK should be at version 2.3 and later since the SDK depends on Google Play support to work properly.
Unzip the Nielsen App SDK sample app and copy the ''AppSdk.jar'' into the libs/ folder on the App’s Eclipse project. Copy the ''libAppSdk.so'' file under ''libs/armeabi/'' folder into the same Eclipse project.
* App SDK 1.2 provides support for x86, mips, and armeabi-7a architecture; the respective ''libAppSdk.so'' can be found under the ''libs/x86/'', ''libs/mips/'', and ''libs/armeabi-7a/'' folders.
Add the following permissions on the project’s ''AndroidManifest.xml'' file.
<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details on handling runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. Download the latest ''google-play-services_lib'' and include it in the App’s project in order to use the App SDK.
* App SDK checks to see if a Google service is available and updated.
* If unavailable or updated, App SDK will not use this service when executing its functions and will reference missing imports and the app will not be compiled.
To include the Google Play library in the media player project, copy the ''google-play-services_lib'' folder into the same location as the project
* Access '''File > Import'''.
* Select '''Existing Android Code into Workspace''' and click '''Next'''.
* Click '''Browse''' and navigate to the ''google-play-services_lib'' to include it into the projects.
* Select the exact '''Project Build Target''' for Eclipse to use from Android SDK.
** Android 4.4.2, etc. OR
** Edit ''project.properties'' file to point to Android target version e.g. target= android-19.
Once the google-play-services_lib is included into the App project, include the following code under the <code><application></code> node in the <code>AndroidManifest.xml</code>.

<syntaxhighlight lang="java"><meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/></syntaxhighlight>

Also, include the ''version.xml'' file that comes with the ''google-play-services_lib'' under the res/values directory of the media player project.
* Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface.

<big>'''Library'''</big>

Nielsen App SDK uses the following packages/classes from the Google Play service.
* google-play-services_lib

'''<big>Classes/package</big>'''
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

==== Add the dependency "lifecycle-extensions" to your project ====
Add the dependency "lifecycle-extensions" in the in the app gradle file as follows:
<syntaxhighlight lang="java">
implementation "androidx.lifecycle:lifecycle-extensions:2.1.0"
</syntaxhighlight>

This will enable the AppSdk to detect the application UI visibility state transitions between background and foreground by utilizing the LifeCycleObserver. This is i.e. required for the Static Measurement.

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-agf-v0.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-agf-ad-v0.png||SDK Integration Architecture Diagram - Ad]]

== SDK Initialization ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. The sharedInstance API that creates a singleton object was deprecated before version 5.1.1. (Version 4.0 for Android)

* A maximum of four SDK instances per appid are supported. When a fifth SDK instance is launched, the SDK will return “nil” from [[initWithAppInfo:delegate:]]
* When four SDK instances exist, you must destroy an old instance before creating a new one.

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || ✓ || "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || No || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || No || "1.0.2"
|-
| sfcode || Nielsen collection facility to which the SDK should connect.
'''AGF Clients'''
* "eu" (For Testing/Certification and in Production)
|| Nielsen-specified || ✓ || "eu"
|-
| nol_devDebug || Enables Nielsen console logging. Has to be set to "DEBUG" until certified
|| Nielsen-specified || Optional || "DEBUG"
|}
 

==== Sample SDK Initialization Code ====

===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"sfcode": "eu",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
 
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

====== Objective-C ======
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>If App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.</blockquote>
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
@"sfcode": "eu",
@"nol_devDebug": @"DEBUG"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

===== Android =====
====== Java ======

AppSDK is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="java">

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA")
.put("sfcode", "eu")
.put("nol_devDebug", "DEBUG");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
Here, <code>appContext</code> is the App context object and <code>appSdkConfig</code> is JSON object for holding the parameters (<code>appid</code>, <code>appname</code>, <code>sfcode</code>) the App passes to the Nielsen App SDK via a JSON string. The appid is obtained from Nielsen operational support and is unique to the app.

The integration of Nielsen App SDK will depend on the type of client app. 
* Ensure that SDK files (AppSdk.jar and libAppSdk.so [App SDK 1.2 Only]) are included under the App’s project and the App SDK is linked to the App (the setting to link App SDK to the App can be found on the property page of the App’s project).

== APP SDK Error & Event Codes ==
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.
== Configure Payload ==
=== Handling JSON Metadata ===
All the SDK methods handle only two types of objects: NSString, NSDictionary. The parameters passed must be either a JSON formatted string or a NSDictionary object. The JSON passed in the SDK must be well-formed.
* NSDictionary object
** If an object of the unexpected type is passed to the method, the error message will be logged.
** The error message will be logged if the string has an invalid JSON format.
* JSON value must be a string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, sfcode, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary.

=== Configure ChannelInfo metadata ===
==== Description of ChannelInfo metadata ====
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}
 

==== Example ChannelInfo metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelName","My Channel Name 1")
</syntaxhighlight>

=== Configure Content metadata ===

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

For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required/Obligatory
|-
| type || type of asset || <code>"content"</code> || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no [[Special Characters]]) || ✓
|-
| program ||(string) name of program (254 character limit) || custom || ✓
|-
| title ||(string) episode title (max 254 characters) || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| length || length of content in seconds || <code>seconds</code> ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| clientid ||
parent ID – value is automatically populated through provided App ID. 
In order to override the brand configured to the App ID, pass parent 
value here and the sub-brand ID associated with that brand in the subbrand 
key (e.g. multiple brands in App)
||
provided by Nielsen
||
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided 
App ID. In order to override the sub-brand configured to the App ID, value can 
be passed here (e.g. multiple sub-brands in App)
||
provided by Nielsen
||

|-
| nol_c0 || number of episode part (Sendungsteilenummer) || number || ✓
|-
| nol_c2 || web only || 'Y' or 'N' || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || duration in seconds || `seconds` ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c12 || type of asset || 'Trailer' or 'Content' || ✓
|-
| nol_c13 || original air time || `(YYYY-MM-TT)T(HH:mm:ss) Example: 2004-06-14T23:34:30 ||
|-
| nol_c14 || ISO 8601 timestamp || `(YYYY-MM-TT)T(HH:mm:ss)` ||
|-
| nol_c15 || format ID || custom ||
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c18 || livestream || 'Y' or 'N' || ✓
|-
| nol_c19 || custom variable || custom ||
|-
| nol_c20 || GfK-ID || custom ||
|}
 

==== Example Content metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
];
</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">
NSDictionary *contentMetadata = @
{@"type": @"content",
@"assetid": @"88675545",
@"length": @"3600",
@"program", "Program Name",
@"title": @"episode title",
@"nol_c0": "p0,1",
@"nol_c2": "p2,Y",
@"nol_c7": "p7,videoid123",
@"nol_c8": "p8,3600",
@"nol_c9": "p9,VideoTitle123",
@"nol_c10": "p10,clientname",
@"nol_c12": "p12,content",
@"nol_c18": "p18,N"
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">
JSONObject contentMetadata = new JSONObject()
.put("type", "content")
.put("assetid", "88675545")
.put("program", "Program Name")
.put("title", "episode title")
.put("length", "3600")
.put("nol_c0", "p0,1")
.put("nol_c2", "p2,Y")
.put("nol_c7", "p7,videoid123")
.put("nol_c8", "p8,3600")
.put("nol_c9", "p9,VideoTitle123")
.put("nol_c10", "p10,clientname")
.put("nol_c12", "p12,content")
.put("nol_c18", "p18,N")
</syntaxhighlight>

=== Configure Ad Metadata ===
==== Description of Ad metadata ====
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''
 
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no SPACE - no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters]) || ✓
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen ||
|-
| title || only the AD-ID is necessary || custom, <AD-ID> without "VAST" Prefix or other, i.e. '2352723141' || ✓
|-
| length || length of Ad in seconds || length of Ad in seconds || ✓
|-
| nol_c1 || universal AdID (Additional AD-ID to be used by second or third marketers) || custom, i.e. 'adgapid_022_800160_1601097_001_0_0' ||
|-
| nol_c2 || web only || 'Y' or 'N' ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || duration of the video file in seconds || || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c11 || AD-ID (unique ID of an advertisement. Necessary if ads are being broadcasted) || custom, i.e. '2352723141' || ✓
|-
| nol_c12 || content type (key distinction of content, advertising, and Trailer) || 'Werbung' || ✓
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c17 || ad placement type (placement information of advertisement) || 'preroll', 'midroll', 'postroll' or 'sonstiges' || ✓
|}

==== Example Ad metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let adMetadata = [
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Ad",
"nol_c17": "p17,preroll"
];
</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">

NSDictionary *adMetadata = @
{@"type": @"preroll",
@"assetid": @"ad345-67483"",
@"title": @"ad_title",
@"length": @"25",
@"nol_c8": "p8,25",
@"nol_c10": "p10,clientname",
@"nol_c11": "p11,2352723141",
@"nol_c12": "p12,Ad",
@"nol_c17": "p17,preroll"
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">

JSONObject adMetadata = new JSONObject()
.put("type", "preroll")
.put("assetid", "ad345-67483")
.put("title", "2352723141")
.put("length", "25")
.put("nol_c8", "p8,25")
.put("nol_c10", "p10,clientname")
.put("nol_c11", "p11,2352723141")
.put("nol_c12", "p12,Ad")
.put("nol_c17", "p17,preroll")
</syntaxhighlight>
== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| 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.
|}

=== Life cycle of SDK instance ===
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# '''Processing state''' – The SDK instance processes playing information. [[play]] and [[loadMetadata]] calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[end]] – SDK instance exits from Processing state when this API is called.
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

'''Note''': In case of any interruptions during playback due to alarm, calendar, call, flight mode, Wi-Fi toggle, channel change, etc., call [[stop]] to pause the measurement.
* As soon as the playback resumes, call [[loadMetadata]] and [[playheadPosition]].</blockquote>

=== API Call sequence ===
==== Use Case 1: Content has no Advertisements ====
Call [[play()]] with channelName JSON as below.
'''[[#Example ChannelInfo metadata|Example ChannelInfo metadata]]'''
Call [[loadMetadata()]] with JSON metadata for content as below.
'''[[#Example Content metadata|Example Content metadata]]'''

Call [[setPlayheadPosition()]] every one second until the stream playback is interrupted or has ended.
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.
'''[[#Example ChannelInfo metadata|Example ChannelInfo metadata]]'''
<blockquote>Note: ONLY for a preroll Ad , Call [[loadMetadata()]] for Content before calling it for preroll ad </blockquote>

Call [[loadMetadata()]] with JSON metadata for ad as below.
'''[[#Example Ad metadata|Example Ad metadata]]'''
<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 the Ad playback is interrupted or has ended for each single Ad. 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 (Content resume) || <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.</blockquote>

=== Sequence of Calls ===

=== play ===
Use [[play]] to pass the channel descriptor information through channelName parameter after the SDK has been initialized and the content starts playing. If the user is returning from a '''Pause/Stop''' interaction, call [[loadMetadata]] with the same metadata and continue sending [[playheadPosition]] once the playback resumes.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c"> - (void)play:(id)channelInfo;</syntaxhighlight>
|Android = <syntaxhighlight lang="java"> public void play(JSONObject channelInfo);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenAppApi?.play(JSONObject channelInfo);</syntaxhighlight>
}}

=== loadMetadata ===
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">– (void)loadMetadata:(id)contentMetadata;</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void loadMetadata(JSONObject contentMetadata);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(contentMetadata)</syntaxhighlight>
}}

=== playheadPosition ===

"playheadPosition" has to be called every second.

* VOD :
** For Content and each single Ad, pass the current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3...
*Live :
**For Content, pass the Unix timestamp (seconds since Jan-1-1970 UTC). Pass whole number that increments only by 1 like 1631098029,1631098030,1631098031,1631098032,... .
**For each single Ad, pass the current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3...

{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">
– (void) playheadPosition: (long long) playheadPos
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
AVPlayer *player;
CMTime curTime=[player currentTime];
int pos = CMTimeGetSeconds(curTime);
[nAppApiObject playheadPosition:pos];
</syntaxhighlight>

|Swift = <syntaxhighlight lang="swift">
//Monitor the Playhead position of the AVPlayer
let timeInterval: CMTime = CMTimeMakeWithSeconds(1.0,10)
self.avPlayerViewController.player?.addPeriodicTimeObserver(forInterval: timeInterval, queue: DispatchQueue.main) {(elapsedTime: CMTime) -> Void in
if self.avPlayerViewController.player!.currentItem?.status == .readyToPlay {
let time : Float64 = self.avPlayerViewController.player!.currentTime().seconds;
let pos = Int64(time);
NSLog("New Elapse Time = \(time)");
self.nielsenAppApi?.playheadPosition(pos);
}
}
}
</syntaxhighlight>
|Android = <syntaxhighlight lang="java">
public void setPlayheadPosition(long position)
</syntaxhighlight>
}}

=== stop ===
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">– (void) stop</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void stop()</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.stop</syntaxhighlight>
}}

=== end ===
Call when the content asset completes playback. Stops measurement progress.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">- (void) end;</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void stop()</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.stop</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 and withhold sending playhead position.
* '''For video content:'''
** Call [[loadMetadata]] with the same metadata and continue sending [[playheadPosition]] once the playback resumes.
* '''For ads:'''
** just continue sending [[playheadPosition]] once the playback resumes (no [[loadMetadata]]).

Additional information:
* '''For type 'content': '''Sending a "loadMetadata" event after a "stop" event will be handled by the SDK as a "resume", as long as the "assetid" and "type" are the same and not changed from the values before the "stop" event happened. Changing "assetid" value will lead into a new stream. Changing of "type" from "content" to "preroll" ("midroll", "postroll") will lead into a new object (ad) with that content stream. Changing any other parameter (eg. "program" or "title") for the content will not affect the reported content data (will stay as in the very first "content" metadata)

=== App termination ===
If your app is executing a termination process and therefore ending the Content or Ad Playback, call [[end]] if the Content is playing or [[stop]] if an Ad is playing.

== Privacy and Opt-Out ==

The AppSDK measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen AppSDK measurement is utilizing a cookieless domain.
In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=de .

Please contact your Nielsen SDK support team directly for any related questions.

== Going Live ==
Following Nielsen testing, users need to make one update to the initialization call to ensure that the site is being measured properly.

# '''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:

'''<big>iOS Example:</big>'''

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"sfcode": "eu"
// Remove Flag: "nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

'''<big>Android Example:</big>'''
<syntaxhighlight lang="java">
try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("sfcode", "eu")
// Remove Flag: "nol_devDebug": "DEBUG"

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>

'''Note''': before going live, you have to inform the Nielsen team - this is necessary because the Nielsen team has to adjust internal configuration parameters to enable data collection. Without that notification, no data will be collected, and no data will be reported.

DCR Germany Video App SDK

2023-01-25T14:12:34Z

MichelFodjo:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|AGF Implementation Documentation}} {{CurrentBreadcrumb}}
[[Category:Digital]]

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

== 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.
* <blockquote>'''No ID AppSDK''': <pre style="color: red">ONLY the No ID AppSDK should be downloaded for the AGF market!</pre>
</blockquote>

* '''Nielsen SDK:''' The Nielsen SDK package contains a variety of sample players for your reference.
Please contact our SDK sales support team if you do not have any of these prerequisites or have any questions.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

== Implementation ==
This guide covers implementation steps for iOS using Xcode and Android using Android Studio.

== Setting up your Development Environment ==

=== iOS ===

<big>
'''Configuring Xcode Development Environment'''
</big>

Nielsen App SDK is compatible with Apple iOS versions 9.0 and above.

The SDK uses the NSURLSession instead of the deprecated NSURLConnection.

<blockquote>'''Note''': All communications between the SDK and the Census (Collection Facility) use HTTPS.</blockquote>

<big>'''Importing Frameworks'''</big>
The first step is to ensure that the following frameworks and libraries are imported into the Frameworks folder of the Xcode project before creating an instance of the Nielsen App SDK object.
* UIKit.framework
* Foundation.framework
* SystemConfiguration.framework
* Security.framework
** Nielsen Analytics framework uses several functions in this library.
* AVFoundation.framework
** This framework is mandatory for the iOS SDK version 5.1.1 to work.
* CoreLocation.framework
* CoreMedia.framework
* NielsenAppApi.framework
* libc++.tbd (as SDK contains Objective C++ source file)
** Alternatively, include -lstdc++ in Build Settings → Other Linker Flag of the Xcode project

<blockquote>'''Example'''
* Extract “NielsenAppApi.Framework” from the Nielsen App SDK sample app and copy it to the Frameworks folder of the Xcode project.
* Add the code <code>-#import NielsenAppApi/NielsenAppApi.h</code> to the View Controller’s header file.</blockquote>

Ensure that the following are included in the Linked Frameworks and Libraries list (located in the project’s Summary settings).
* Nielsen App SDK
* iOS security framework
 
<big>'''Using Swift'''</big>
To import a set of Objective-C files in the same app target as your Swift code, you rely on an Objective-C bridging header to expose those files to Swift. Xcode offers to create this header file when you add a Swift file to an existing Objective-C app or an Objective-C file to an existing Swift app.

Select File/New File/Objective-C File 
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] 
Once this file has been created, you need to add the following:
<syntaxhighlight lang="swift">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
<big>'''Using Objective-C'''</big>
Add the code
<syntaxhighlight lang ="objective-c">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
to the View Controller’s header file.
 

=== Android ===
==== General ====
<big>
'''Configuring Android Java Development Environment'''
</big>

*The Nielsen App SDK (located in the ''com.nielsen.app.sdk'' package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is the only public class belonging to the com.nielsen.app.sdk package.

'''Nielsen App SDK is compatible with Android OS versions 2.3+. Clients can control/configure the protocol to be used – HTTPS or HTTP to suit their needs.'''

The Nielsen App SDK 1.2 library is composed of two parts:
* The Java AppSdk.jar library runs on the Android’s Dalvik Virtual Machine.
* The C/C++ libAppSdk.so native library that runs directly on the device’s hardware.
<blockquote>'''Note''': App SDK 4.0.0 contains AppSDK.jar component only and does not support C/C++ libAppSdk.so components.</blockquote>

The requirement for the Java ''AppSdk.jar'' library and the ''libAppSdk.so'' native library will depend on the type of host application that will make use of them.
* '''For Video player applications'''
** The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 3.0 and later will support it natively).
** If the player application uses a 3rd party media player implementing its own HLS, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.
* '''For Audio player applications'''
** The Android OS hosting the App SDK should be at version 2.3 and later since the SDK depends on Google Play support to work properly.
Unzip the Nielsen App SDK sample app and copy the ''AppSdk.jar'' into the libs/ folder on the App’s Eclipse project. Copy the ''libAppSdk.so'' file under ''libs/armeabi/'' folder into the same Eclipse project.
* App SDK 1.2 provides support for x86, mips, and armeabi-7a architecture; the respective ''libAppSdk.so'' can be found under the ''libs/x86/'', ''libs/mips/'', and ''libs/armeabi-7a/'' folders.
Add the following permissions on the project’s ''AndroidManifest.xml'' file.
<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details on handling runtime permissions in Android versions, please visit [https://developer.android.com/training/permissions/requesting.html]. Download the latest ''google-play-services_lib'' and include it in the App’s project in order to use the App SDK.
* App SDK checks to see if a Google service is available and updated.
* If unavailable or updated, App SDK will not use this service when executing its functions and will reference missing imports and the app will not be compiled.
To include the Google Play library in the media player project, copy the ''google-play-services_lib'' folder into the same location as the project
* Access '''File > Import'''.
* Select '''Existing Android Code into Workspace''' and click '''Next'''.
* Click '''Browse''' and navigate to the ''google-play-services_lib'' to include it into the projects.
* Select the exact '''Project Build Target''' for Eclipse to use from Android SDK.
** Android 4.4.2, etc. OR
** Edit ''project.properties'' file to point to Android target version e.g. target= android-19.
Once the google-play-services_lib is included into the App project, include the following code under the <code><application></code> node in the <code>AndroidManifest.xml</code>.

<syntaxhighlight lang="java"><meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version"/></syntaxhighlight>

Also, include the ''version.xml'' file that comes with the ''google-play-services_lib'' under the res/values directory of the media player project.
* Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface.

<big>'''Library'''</big>

Nielsen App SDK uses the following packages/classes from the Google Play service.
* google-play-services_lib

'''<big>Classes/package</big>'''
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

==== Add the dependency "lifecycle-extensions" to your project ====
Add the dependency "lifecycle-extensions" in the in the app gradle file as follows:
<syntaxhighlight lang="java">
implementation "androidx.lifecycle:lifecycle-extensions:2.1.0"
</syntaxhighlight>

This will enable the AppSdk to detect the application UI visibility state transitions between background and foreground by utilizing the LifeCycleObserver. This is i.e. required for the Static Measurement.

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-agf-v0.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-agf-ad-v0.png||SDK Integration Architecture Diagram - Ad]]

== SDK Initialization ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. The sharedInstance API that creates a singleton object was deprecated before version 5.1.1. (Version 4.0 for Android)

* A maximum of four SDK instances per appid are supported. When a fifth SDK instance is launched, the SDK will return “nil” from [[initWithAppInfo:delegate:]]
* When four SDK instances exist, you must destroy an old instance before creating a new one.

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || ✓ || "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || No || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || No || "1.0.2"
|-
| sfcode || Nielsen collection facility to which the SDK should connect.
'''AGF Clients'''
* "eu" (For Testing/Certification and in Production)
|| Nielsen-specified || ✓ || "eu"
|-
| nol_devDebug || Enables Nielsen console logging. Has to be set to "DEBUG" until certified
|| Nielsen-specified || Optional || "DEBUG"
|}
 

==== Sample SDK Initialization Code ====

===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"sfcode": "eu",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
 
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

====== Objective-C ======
Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>If App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.</blockquote>
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
@"sfcode": "eu",
@"nol_devDebug": @"DEBUG"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

===== Android =====
====== Java ======

AppSDK is no longer a singleton object and should be initialized as below.

'''Initialization of App SDK object through a JSON object'''
<syntaxhighlight lang="java">

try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA")
.put("sfcode", "eu")
.put("nol_devDebug", "DEBUG");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
Here, <code>appContext</code> is the App context object and <code>appSdkConfig</code> is JSON object for holding the parameters (<code>appid</code>, <code>appname</code>, <code>sfcode</code>) the App passes to the Nielsen App SDK via a JSON string. The appid is obtained from Nielsen operational support and is unique to the app.

The integration of Nielsen App SDK will depend on the type of client app. 
* Ensure that SDK files (AppSdk.jar and libAppSdk.so [App SDK 1.2 Only]) are included under the App’s project and the App SDK is linked to the App (the setting to link App SDK to the App can be found on the property page of the App’s project).

== APP SDK Error & Event Codes ==
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.
== Configure Payload ==
=== Handling JSON Metadata ===
All the SDK methods handle only two types of objects: NSString, NSDictionary. The parameters passed must be either a JSON formatted string or a NSDictionary object. The JSON passed in the SDK must be well-formed.
* NSDictionary object
** If an object of the unexpected type is passed to the method, the error message will be logged.
** The error message will be logged if the string has an invalid JSON format.
* JSON value must be a string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, sfcode, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary.

=== Configure ChannelInfo metadata ===
==== Description of ChannelInfo metadata ====
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}
 

==== Example ChannelInfo metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelName","My Channel Name 1")
</syntaxhighlight>

=== Configure Content metadata ===

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

For detailed information on metadata and custom variables, see '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required/Obligatory
|-
| type || type of asset || <code>"content"</code> || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no [[Special Characters]]) || ✓
|-
| program ||(string) name of program (254 character limit) || custom || ✓
|-
| title ||(string) episode title (max 254 characters) || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| length || length of content in seconds || <code>seconds</code> ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| clientid ||
parent ID – value is automatically populated through provided App ID. 
In order to override the brand configured to the App ID, pass parent 
value here and the sub-brand ID associated with that brand in the subbrand 
key (e.g. multiple brands in App)
||
provided by Nielsen
||
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided 
App ID. In order to override the sub-brand configured to the App ID, value can 
be passed here (e.g. multiple sub-brands in App)
||
provided by Nielsen
||

|-
| nol_c0 || number of episode part (Sendungsteilenummer) || number || ✓
|-
| nol_c2 || web only || 'Y' or 'N' || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || duration in seconds || `seconds` ('86400' for 24/7 Livestream. For Event-Livestreams planned length. For VoD video length) || ✓
|-
| nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c12 || type of asset || 'Trailer' or 'Content' || ✓
|-
| nol_c13 || original air time || `(YYYY-MM-TT)T(HH:mm:ss) Example: 2004-06-14T23:34:30 ||
|-
| nol_c14 || ISO 8601 timestamp || `(YYYY-MM-TT)T(HH:mm:ss)` ||
|-
| nol_c15 || format ID || custom ||
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c18 || livestream || 'Y' or 'N' || ✓
|-
| nol_c19 || custom variable || custom ||
|-
| nol_c20 || GfK-ID || custom ||
|}
 

==== Example Content metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"program": "Program Name",
"title": "episode title",
"length": "3600",
"nol_c0": "p0,1",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c8": "p8,3600",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,clientname",
"nol_c12": "p12,content",
"nol_c18": "p18,N"
];
</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">
NSDictionary *contentMetadata = @
{@"type": @"content",
@"assetid": @"88675545",
@"length": @"3600",
@"program", "Program Name",
@"title": @"episode title",
@"nol_c0": "p0,1",
@"nol_c2": "p2,Y",
@"nol_c7": "p7,videoid123",
@"nol_c8": "p8,3600",
@"nol_c9": "p9,VideoTitle123",
@"nol_c10": "p10,clientname",
@"nol_c12": "p12,content",
@"nol_c18": "p18,N"
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">
JSONObject contentMetadata = new JSONObject()
.put("type", "content")
.put("assetid", "88675545")
.put("program", "Program Name")
.put("title", "episode title")
.put("length", "3600")
.put("nol_c0", "p0,1")
.put("nol_c2", "p2,Y")
.put("nol_c7", "p7,videoid123")
.put("nol_c8", "p8,3600")
.put("nol_c9", "p9,VideoTitle123")
.put("nol_c10", "p10,clientname")
.put("nol_c12", "p12,content")
.put("nol_c18", "p18,N")
</syntaxhighlight>

=== Configure Ad Metadata ===
==== Description of Ad metadata ====
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
 
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to asset (64 character limit; only characters 0-9, a-z, A-Z underscore and minus are allowed - no special characters or vowel mutations)|| custom (no SPACE - no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters]) || ✓
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided App ID. In order to override the sub-brand configured to the App ID, value can be passed here (e.g. multiple sub-brands in App) || provided by Nielsen ||
|-
| title || only the AD-ID is necessary || custom, <AD-ID> without "VAST" Prefix or other, i.e. '2352723141' || ✓
|-
| length || length of Ad in seconds || length of Ad in seconds || ✓
|-
| nol_c1 || universal AdID (Additional AD-ID to be used by second or third marketers) || custom, i.e. 'adgapid_022_800160_1601097_001_0_0' ||
|-
| nol_c2 || web only || 'Y' or 'N' ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || duration of the video file in seconds || || ✓
|-
| nol_c10 || publisher || custom || ✓
|-
| nol_c11 || AD-ID (unique ID of an advertisement. Necessary if ads are being broadcasted) || custom, i.e. '2352723141' || ✓
|-
| nol_c12 || content type (key distinction of content, advertising, and Trailer) || 'Werbung' || ✓
|-
| nol_c16 || content-ID (Combines different videos to a common category, content-wise, a content-ID is available for content, trailer and ads) || custom, i.e. 'dVxRcCpOqKyFz02fuss', 'dvrsowf_ten_rtlibes', etc ||
|-
| nol_c17 || ad placement type (placement information of advertisement) || 'preroll', 'midroll', 'postroll' or 'sonstiges' || ✓
|}

==== Example Ad metadata ====
===== iOS =====
====== Swift ======

<syntaxhighlight lang="swift">
let adMetadata = [
"type": "preroll",
"assetid": "ad345-67483",
"title": "ad_title",
"length": "25",
"nol_c8": "p8,25",
"nol_c10": "p10,clientname",
"nol_c11": "p11,2352723141",
"nol_c12": "p12,Ad",
"nol_c17": "p17,preroll"
];
</syntaxhighlight>

====== Objective-C ======

<syntaxhighlight lang="objective-c">

NSDictionary *adMetadata = @
{@"type": @"preroll",
@"assetid": @"ad345-67483"",
@"title": @"ad_title",
@"length": @"25",
@"nol_c8": "p8,25",
@"nol_c10": "p10,clientname",
@"nol_c11": "p11,2352723141",
@"nol_c12": "p12,Ad",
@"nol_c17": "p17,preroll"
}
</syntaxhighlight>

===== Android =====
====== Java ======
<syntaxhighlight lang="java">

JSONObject adMetadata = new JSONObject()
.put("type", "preroll")
.put("assetid", "ad345-67483")
.put("title", "2352723141")
.put("length", "25")
.put("nol_c8", "p8,25")
.put("nol_c10", "p10,clientname")
.put("nol_c11", "p11,2352723141")
.put("nol_c12", "p12,Ad")
.put("nol_c17", "p17,preroll")
</syntaxhighlight>
== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| 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.
|}

=== Life cycle of SDK instance ===
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# '''Processing state''' – The SDK instance processes playing information. [[play]] and [[loadMetadata]] calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## [[playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[end]] – SDK instance exits from Processing state when this API is called.
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

'''Note''': In case of any interruptions during playback due to alarm, calendar, call, flight mode, Wi-Fi toggle, channel change, etc., call [[stop]] to pause the measurement.
* As soon as the playback resumes, call [[loadMetadata]] and [[playheadPosition]].</blockquote>

=== API Call sequence ===
==== Use Case 1: Content has no Advertisements ====
Call [[play()]] with channelName JSON as below.
'''[[#Example ChannelInfo metadata|Example ChannelInfo metadata]]'''
Call [[loadMetadata()]] with JSON metadata for content as below.
'''[[#Example Content metadata|Example Content metadata]]'''

Call [[setPlayheadPosition()]] every one second until the stream playback is interrupted or has ended.
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.
'''[[#Example ChannelInfo metadata|Example ChannelInfo metadata]]'''
<blockquote>Note: ONLY for a preroll Ad , Call [[loadMetadata()]] for Content before calling it for preroll ad </blockquote>

Call [[loadMetadata()]] with JSON metadata for ad as below.
'''[[#Example Ad metadata|Example Ad metadata]]'''
<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 the Ad playback is interrupted or has ended for each single Ad. 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 (Content resume) || <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.</blockquote>

=== Sequence of Calls ===

=== play ===
Use [[play]] to pass the channel descriptor information through channelName parameter after the SDK has been initialized and the content starts playing. If the user is returning from a '''Pause/Stop''' interaction, call [[loadMetadata]] with the same metadata and continue sending [[playheadPosition]] once the playback resumes.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c"> - (void)play:(id)channelInfo;</syntaxhighlight>
|Android = <syntaxhighlight lang="java"> public void play(JSONObject channelInfo);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenAppApi?.play(JSONObject channelInfo);</syntaxhighlight>
}}

=== loadMetadata ===
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">– (void)loadMetadata:(id)contentMetadata;</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void loadMetadata(JSONObject contentMetadata);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(contentMetadata)</syntaxhighlight>
}}

=== playheadPosition ===

"playheadPosition" has to be called every second.

* VOD :
** For Content and each single Ad, pass the current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3...
*Live :
**For Content, pass the Unix timestamp (seconds since Jan-1-1970 UTC). Pass whole number that increments only by 1 like 1631098029,1631098030,1631098031,1631098032,... .
**For each single Ad, pass the current position in seconds. Pass whole number that increments only by 1 like 0,1,2,3...

{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">
– (void) playheadPosition: (long long) playheadPos
</syntaxhighlight>

<syntaxhighlight lang="objective-c">
AVPlayer *player;
CMTime curTime=[player currentTime];
int pos = CMTimeGetSeconds(curTime);
[nAppApiObject playheadPosition:pos];
</syntaxhighlight>

|Swift = <syntaxhighlight lang="swift">
//Monitor the Playhead position of the AVPlayer
let timeInterval: CMTime = CMTimeMakeWithSeconds(1.0,10)
self.avPlayerViewController.player?.addPeriodicTimeObserver(forInterval: timeInterval, queue: DispatchQueue.main) {(elapsedTime: CMTime) -> Void in
if self.avPlayerViewController.player!.currentItem?.status == .readyToPlay {
let time : Float64 = self.avPlayerViewController.player!.currentTime().seconds;
let pos = Int64(time);
NSLog("New Elapse Time = \(time)");
self.nielsenAppApi?.playheadPosition(pos);
}
}
}
</syntaxhighlight>
|Android = <syntaxhighlight lang="java">
public void setPlayheadPosition(long position)
</syntaxhighlight>
}}

=== stop ===
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">– (void) stop</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void stop()</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.stop</syntaxhighlight>
}}

=== end ===
Call when the content asset completes playback. Stops measurement progress.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">- (void) end;</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void stop()</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.stop</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 and withhold sending playhead position.
* '''For video content:'''
** Call [[loadMetadata]] with the same metadata and continue sending [[playheadPosition]] once the playback resumes.
* '''For ads:'''
** just continue sending [[playheadPosition]] once the playback resumes (no [[loadMetadata]]).

Additional information:
* '''For type 'content': '''Sending a "loadMetadata" event after a "stop" event will be handled by the SDK as a "resume", as long as the "assetid" and "type" are the same and not changed from the values before the "stop" event happened. Changing "assetid" value will lead into a new stream. Changing of "type" from "content" to "preroll" ("midroll", "postroll") will lead into a new object (ad) with that content stream. Changing any other parameter (eg. "program" or "title") for the content will not affect the reported content data (will stay as in the very first "content" metadata)

=== App termination ===
If your app is executing a termination process and therefore ending the Content or Ad Playback, call [[end]] if the Content is playing or [[stop]] if an Ad is playing.

== Privacy and Opt-Out ==

The AppSDK measurement is working without cookies and other personal information. No user can be identified personally, therefore an opt-out functionality is not required. The Nielsen AppSDK measurement is utilizing a cookieless domain.
In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=de .

Please contact your Nielsen SDK support team directly for any related questions.

== Going Live ==
Following Nielsen testing, users need to make one update to the initialization call to ensure that the site is being measured properly.

# '''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:

'''<big>iOS Example:</big>'''

<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"sfcode": "eu"
// Remove Flag: "nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

'''<big>Android Example:</big>'''
<syntaxhighlight lang="java">
try
{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("sfcode", "eu")
// Remove Flag: "nol_devDebug": "DEBUG"

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, appSdkListener);
}
catch (JSONException e)
{
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>

'''Note''': before going live, you have to inform the Nielsen team - this is necessary because the Nielsen team has to adjust internal configuration parameters to enable data collection. Without that notification, no data will be collected, and no data will be reported.