Engineering Client Portal - User contributions [en]

DCR Denmark Domless SDK

2026-04-22T10:18:12Z

MichelFodjo: DOMless SDK Integration for Denmark created 22-04-2026

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

==License==
Nielsen SDK contains material that is protected by copyright laws, patent laws, trade secret laws, and by international treaty provisions and is Copyright © 2025 The Nielsen Company (US) LLC. All intellectual property rights and licenses therein are reserved by The Nielsen Company (US) LLC and its licensors. Please read the license agreement presented [https://engineeringportal.nielsen.com/wiki/Special:ClickThrough here], which must be accepted in order to download the Nielsen SDKs. For more information, reach out to your Nielsen Technical Account Manager(TAM).

== Overview ==

The Nielsen DOM-less SDK is a Javascript based cross-platform library that provides APIs that allows our clients to integrate the Nielsen SDK in DOM-less environments, e.g. ReactNative, NodeJS, etc. The new Amazon Vega/Kepler OS was certified by Nielsen for the DOM-less SDK Integration.

The Nielsen DOM-less SDK can be used for '''Video''' and '''Static''' measurements.

The Digital Content Ratings (DCR) Video product provides content consumption measurement on client mobile apps or webpages. This measurement includes insight into the total time a user spent watching the tracked content, video player events, and much more. This guide also includes a link to [[#Sample DOM-less SDK Implementation| github sample implementation]] with steps to implement the DCR Video product in a sample NodeJS app. It includes:
* DOM-less SDK Initialization
* DCR Video Metadata: information about the content being tracked
* DCR Video Events/API calls

==DOM-less SDK Initialization==

===Obtain the Nielsen Application ID (apid)===
The Nielsen <code>apid</code> is required to enable SDK functionality. A Technical Account Manager(TAM) will provide an apid for each player configuration.DOM-less SDK can support URLs that use any of the protocols – HTTPS and HTTP.

===Configure the DOM-less SDK===

====Installation====
Install with <code>npm install <nowiki>https://github.com/NielsenDigitalSDK/bsdk-domless</nowiki></code>
 and import the <code>BsdkInstance</code> into video player component <code> import { BsdkInstance } from 'bsdk-domless' </code>

======status.ok()======

Initialization of the instance can be done with <code>status.ok()</code> function or use Promise handling approach

<syntaxhighlight lang="javascript">
const instance = await new BsdkInstance(appID, instanceName, instanceMetadata, implementationHooks);
if (instance && instance.status.ok()) {
expect(instance).not.toBe(undefined);
expect(instance.status.ok()).toBe(true);
}
</syntaxhighlight>

Note: Implementation Hooks are mandatory for the DOM-less SDK instance. Please refer to the Implementation Hooks section below for details.

====Exposed Interface====
The exposed interface is as follows:

1. <code>`ggPM`</code> - method to send messages to the Nielsen SDK

2. <code>`processEvent`</code> - method to send app state to the Nielsen SDK, e.g., focus, blur, appclose

===Initialization Global Parameters===
{| class="wikitable"
|+
!'''Parameter'''
!'''Description'''
!'''Required'''
!'''Value'''
|-
|apid
|UniqueID assigned to player/site.
|Yes
|'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
|instanceName
|Name of SDK instance
|Yes
|"any string value"
|-
|domlessEnv
|Type of DOM-less environment like ReactNative, Node, etc.
|Yes
|"domlessEnv": "1", // For ReactNative
"domlessEnv": "2", // For Amazon

"domlessEnv": "3", // For NodeJS

“domlessEnv”: “4”, // For Custom
|-
|enableFpid
|Optional:turn on or off the First Party ID
|No
|"true" for turn on, "false" for turn off. The default value is "true".
|-
|nol_sdkDebug
|Enables Nielsen console logging. Only required for testing
|No
|"{nol_sdkDebug: "debug"}"
|-
|}

=== Implementation Hooks ===
This object captures the required entities for the DOM-less SDK to operate correctly. These are normally platform dependent and are expected to be passed on to the DOM-less SDK as part of its initialization. See below for the descriptions of each key.

==== '''log''' ====
Log the DOM-less SDK messages to an external stream, e.g. the browser console, stdout.

e.g. Log.debug('debug', 'NIELSEN TAGS EXPECTED TO FIRE:')

===== Methods =====
<blockquote>info()

Log.info(label: string, ...message: string[]): void

debug()

Log.debug(label: string, ...message: string[]): void

warn()

Log.warn(label: string, ...message: string[]): void

error()

Log.error(label: string, ...message: string[]): void</blockquote>

===== Parameters =====
<blockquote>label Required

● string - severity type, e.g. info, debug, warn, error or custom label

message Required

● string - message that will be output to the console</blockquote>

==== storage ====
Persistent storage of key/values, similar in behavior to browser localStorage.

e.g. storage.set('nol_lsid', 'umy3w4ik9usw2ppqmw2vkecckxfob1697308388')

===== Methods =====
<blockquote>set()

storage.set(key: string, value: string)

get()

storage.get(key: string)

remove()

storage.remove(key: string)

clear()

storage.clear()</blockquote>

==== fetch ====
Function to fetch resources from the network. Required for the transmission of the DOM-less SDK requests (pings) to the Nielsen endpoints.

e.g. Fetch(resource: string, options: object)

===== Parameters =====
<blockquote>resource Required

● A string that provides the URL of the resource to fetch

options Optional Object containing settings to apply to the request:

method

● string - request method: "GET", "POST". If one is not provided SDK will default to "GET"

headers

● object - headers to add to the outgoing request, an object literal with String values

body

● string - body to add to the request; SDK will send out string

mode

● string - mode for request: cors, no-cors, same-origin

referrer

● string - a string specifying the referrer of the request</blockquote>

====='''''<pre style="color: green; font-weight: bold; font-size: 20px">Note: Implementation Hooks are mandatory for the DOM-less SDK to function as expected.</pre>'''''=====

== DOM-less SDK API to send app state to the Nielsen SDK, e.g., focus, blur, appclose==

The method for calling events is <code>processEvent()</code>.

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

* <code>`blur`</code> - This event should be passed to processEvent when the app goes to the background.

<syntaxhighlight lang="javascript">
instance.processEvent({ type: 'blur', timestamp: Date.now() });
</syntaxhighlight>

* <code>`focus`</code> - This event should be passed to processEvent when the app goes to the foreground.

<syntaxhighlight lang="javascript">
instance.processEvent({ type: 'focus', timestamp: Date.now() });
</syntaxhighlight>

* <code>`appclose`</code> - This event should be passed prior to closing the app.

<syntaxhighlight lang="javascript">
instance.processEvent({ type: 'appclose', timestamp: Date.now() });
</syntaxhighlight>

== DOM-less SDK API to send messages to the Nielsen SDK==

=== Video Measurement ===

The method for calling events is ggPM().

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

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event name !! Values to pass !! Description !!Event #
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each content/ad metadata object and after stop event when resuming '''video content''' (not after pausing and resuming an ad). ''[[DCR Denmark Video Browser SDK#Create Metadata Objects|See details on how to create Denmark specific metadata for content and ad]]''
||15
|-
| 'setPlayheadPosition'
||
* 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 (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
||49
|-
| 'stop' || playhead position in seconds || Call when ads complete playing and on pause event (when resume will be available). The playhead position must be passed when calling stop
||7
|-
| 'end' || playhead position in seconds || This event has to be called once for the current video asset at the end of the playback.
At the end of the content stream, if the user switches to another piece of content or when the browser is refreshed or closed.
||57
|}

'''Note:''' Playhead position as integer

'''Note:''' 'setPlayheadPosition' has to be called every second

==== Example Events ====

*'''Event:''' loadMetadata | '''Value Pass ( Object ):''' Content Metadata Object

<syntaxhighlight lang="javascript">
instance.ggPM('loadMetadata', contentMetadataObject);
</syntaxhighlight>

*'''Event:''' loadMetadata | '''Value Pass ( Object ):''' Pre-roll AD Metadata Object

<syntaxhighlight lang="javascript">
instance.ggPM('loadMetadata', prerollMetadataObject);
</syntaxhighlight>

*'''Event:''' setPlayheadPosition | '''Value Pass ( Integer ):''' playheadPosition

<syntaxhighlight lang="javascript">
instance.ggPM('setPlayheadPosition', playheadPosition);
</syntaxhighlight>

*'''Event:''' stop | '''Value Pass ( Integer ):''' stopPlayheadPosition

<syntaxhighlight lang="javascript">
instance.ggPM('stop', stopPlayheadPosition);
</syntaxhighlight>

*'''Event:''' end | '''Value Pass ( Integer ):''' endPlayheadPosition

<syntaxhighlight lang="javascript">
instance.ggPM('end', endPlayheadPosition);
</syntaxhighlight>

==== Sample DOM-less SDK Implementation ====

* Sample Implementation on github [https://github.com/NielsenDigitalSDK/bsdk-domless here].

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

==== Review SDK Interrupt Scenarios ====
* [[DCR Denmark Video Browser SDK#Handle Video Playback Interruption|Handle Video Playback Interruption]]

==== Review SDK Event Lifecycle ====
* [[DCR Denmark Video Browser SDK#SDK Call Sequence |SDK Call Sequence ]]

== 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://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=da .

=== Turning off the First Party ID for Opt-out Users during the SDK Initialization ===
The First Party ID(FPID) is enabled by default in the Browser SDK. For Opt-out users, the First Party ID can be turned off during the initialization of the SDK Instance, i.e. the parameter enableFpid can be set to "false" (FPID disabled) or "true" (FPID enabled). See [[#Initialization Global Parameters|SDK Initialization Global Parameters]].

== Certification ==

While Nielsen is working on adding Support to the Certification Tool for DOM-less SDK in the future, the Certification process for the DOM-less will require detailed SDK Logs from a MMS Client integrating Nielsen DOM-less SDK. In this regard, a client will execute test cases locally and share logs for each test case with a Nielsen Technical Account Manager in charge of the Certification.

== Going Live ==
Following Nielsen testing, disable Nielsen SDK logging by adjusting the Nielsen SDK Initialization Call, this will ensure that the App or Website 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:

<syntaxhighlight lang="javascript">
const instance = new BsdkInstance(
nsdkConfig.app_id,
nsdkConfig.instance_name,
{
appName: 'BSDK RN Sample App',
domlessEnv: '1'// "1" for React Native | "2" for Amazon | "3" for NodeJS | "4" for Custom
// reference SDK interface documentation
// for additional metadata properties
},
implementationHooks
);
</syntaxhighlight>

'''Note''': before going live you have to inform Nielsen - this is necessary, because 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 Sweden Domless SDK

2026-04-22T10:08:11Z

MichelFodjo: minor typo fixed

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

==License==
Nielsen SDK contains material that is protected by copyright laws, patent laws, trade secret laws, and by international treaty provisions and is Copyright © 2025 The Nielsen Company (US) LLC. All intellectual property rights and licenses therein are reserved by The Nielsen Company (US) LLC and its licensors. Please read the license agreement presented [https://engineeringportal.nielsen.com/wiki/Special:ClickThrough here], which must be accepted in order to download the Nielsen SDKs. For more information, reach out to your Nielsen Technical Account Manager(TAM).

== Overview ==

The Nielsen DOM-less SDK is a Javascript based cross-platform library that provides APIs that allows our clients to integrate the Nielsen SDK in DOM-less environments, e.g. ReactNative, NodeJS, etc. The new Amazon Vega/Kepler OS was certified by Nielsen for the DOM-less SDK Integration.

The Nielsen DOM-less SDK can be used for '''Video''' and '''Static''' measurements.

The Digital Content Ratings (DCR) Video product provides content consumption measurement on client mobile apps or webpages. This measurement includes insight into the total time a user spent watching the tracked content, video player events, and much more. This guide also includes a link to [[#Sample DOM-less SDK Implementation| github sample implementation]] with steps to implement the DCR Video product in a sample NodeJS app. It includes:
* DOM-less SDK Initialization
* DCR Video Metadata: information about the content being tracked
* DCR Video Events/API calls

==DOM-less SDK Initialization==

===Obtain the Nielsen Application ID (apid)===
The Nielsen <code>apid</code> is required to enable SDK functionality. A Technical Account Manager(TAM) will provide an apid for each player configuration.DOM-less SDK can support URLs that use any of the protocols – HTTPS and HTTP.

===Configure the DOM-less SDK===

====Installation====
Install with <code>npm install <nowiki>https://github.com/NielsenDigitalSDK/bsdk-domless</nowiki></code>
 and import the <code>BsdkInstance</code> into video player component <code> import { BsdkInstance } from 'bsdk-domless' </code>

======status.ok()======

Initialization of the instance can be done with <code>status.ok()</code> function or use Promise handling approach

<syntaxhighlight lang="javascript">
const instance = await new BsdkInstance(appID, instanceName, instanceMetadata, implementationHooks);
if (instance && instance.status.ok()) {
expect(instance).not.toBe(undefined);
expect(instance.status.ok()).toBe(true);
}
</syntaxhighlight>

Note: Implementation Hooks are mandatory for the DOM-less SDK instance. Please refer to the Implementation Hooks section below for details.

====Exposed Interface====
The exposed interface is as follows:

1. <code>`ggPM`</code> - method to send messages to the Nielsen SDK

2. <code>`processEvent`</code> - method to send app state to the Nielsen SDK, e.g., focus, blur, appclose

===Initialization Global Parameters===
{| class="wikitable"
|+
!'''Parameter'''
!'''Description'''
!'''Required'''
!'''Value'''
|-
|apid
|UniqueID assigned to player/site.
|Yes
|'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
|instanceName
|Name of SDK instance
|Yes
|"any string value"
|-
|domlessEnv
|Type of DOM-less environment like ReactNative, Node, etc.
|Yes
|"domlessEnv": "1", // For ReactNative
"domlessEnv": "2", // For Amazon

"domlessEnv": "3", // For NodeJS

“domlessEnv”: “4”, // For Custom
|-
|hem_unknown || Hashed email using SHA512. This email is used by the MMS reach model.|| Required if login feature || <syntaxhighlight lang="javascript">
{hem_unknown: "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..."}
</syntaxhighlight>
|-
|optout
|OptOut global parameter. This optout will be maintained through the session of the SDK instance
|Yes
|"true" for opted out, "false" for NOT opted out or opted in. The default value is "false".
|-
|enableFpid
|Optional:turn on or off the First Party ID
|No
|"true" for turn on, "false" for turn off. The default value is "true".
|-
|nol_sdkDebug
|Enables Nielsen console logging. Only required for testing
|No
|"{nol_sdkDebug: "debug"}"
|-
|}

=== Implementation Hooks ===
This object captures the required entities for the DOM-less SDK to operate correctly. These are normally platform dependent and are expected to be passed on to the DOM-less SDK as part of its initialization. See below for the descriptions of each key.

==== '''log''' ====
Log the DOM-less SDK messages to an external stream, e.g. the browser console, stdout.

e.g. Log.debug('debug', 'NIELSEN TAGS EXPECTED TO FIRE:')

===== Methods =====
<blockquote>info()

Log.info(label: string, ...message: string[]): void

debug()

Log.debug(label: string, ...message: string[]): void

warn()

Log.warn(label: string, ...message: string[]): void

error()

Log.error(label: string, ...message: string[]): void</blockquote>

===== Parameters =====
<blockquote>label Required

● string - severity type, e.g. info, debug, warn, error or custom label

message Required

● string - message that will be output to the console</blockquote>

==== storage ====
Persistent storage of key/values, similar in behavior to browser localStorage.

e.g. storage.set('nol_lsid', 'umy3w4ik9usw2ppqmw2vkecckxfob1697308388')

===== Methods =====
<blockquote>set()

storage.set(key: string, value: string)

get()

storage.get(key: string)

remove()

storage.remove(key: string)

clear()

storage.clear()</blockquote>

==== fetch ====
Function to fetch resources from the network. Required for the transmission of the DOM-less SDK requests (pings) to the Nielsen endpoints.

e.g. Fetch(resource: string, options: object)

===== Parameters =====
<blockquote>resource Required

● A string that provides the URL of the resource to fetch

options Optional Object containing settings to apply to the request:

method

● string - request method: "GET", "POST". If one is not provided SDK will default to "GET"

headers

● object - headers to add to the outgoing request, an object literal with String values

body

● string - body to add to the request; SDK will send out string

mode

● string - mode for request: cors, no-cors, same-origin

referrer

● string - a string specifying the referrer of the request</blockquote>

====='''''<pre style="color: green; font-weight: bold; font-size: 20px">Note: Implementation Hooks are mandatory for the DOM-less SDK to function as expected.</pre>'''''=====

== DOM-less SDK API to send app state to the Nielsen SDK, e.g., focus, blur, appclose==

The method for calling events is <code>processEvent()</code>.

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

* <code>`blur`</code> - This event should be passed to processEvent when the app goes to the background.

<syntaxhighlight lang="javascript">
instance.processEvent({ type: 'blur', timestamp: Date.now() });
</syntaxhighlight>

* <code>`focus`</code> - This event should be passed to processEvent when the app goes to the foreground.

<syntaxhighlight lang="javascript">
instance.processEvent({ type: 'focus', timestamp: Date.now() });
</syntaxhighlight>

* <code>`appclose`</code> - This event should be passed prior to closing the app.

<syntaxhighlight lang="javascript">
instance.processEvent({ type: 'appclose', timestamp: Date.now() });
</syntaxhighlight>

== DOM-less SDK API to send messages to the Nielsen SDK==

=== Video Measurement ===

The method for calling events is ggPM().

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

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event name !! Values to pass !! Description !!Event #
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each content/ad metadata object and after stop event when resuming '''video content''' (not after pausing and resuming an ad). ''[[DCR Sweden Video Browser SDK#Create Metadata Objects|See details on how to create MMS metadata for content and ad]]''
||15
|-
| 'setPlayheadPosition'
||
* 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 (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
||49
|-
| 'stop' || playhead position in seconds || Call when ads complete playing and on pause event (when resume will be available). The playhead position must be passed when calling stop
||7
|-
| 'end' || playhead position in seconds || This event has to be called once for the current video asset at the end of the playback.
At the end of the content stream, if the user switches to another piece of content or when the browser is refreshed or closed.
||57
|}

'''Note:''' Playhead position as integer

'''Note:''' 'setPlayheadPosition' has to be called every second

==== Example Events ====

*'''Event:''' loadMetadata | '''Value Pass ( Object ):''' Content Metadata Object

<syntaxhighlight lang="javascript">
instance.ggPM('loadMetadata', contentMetadataObject);
</syntaxhighlight>

*'''Event:''' loadMetadata | '''Value Pass ( Object ):''' Pre-roll AD Metadata Object

<syntaxhighlight lang="javascript">
instance.ggPM('loadMetadata', prerollMetadataObject);
</syntaxhighlight>

*'''Event:''' setPlayheadPosition | '''Value Pass ( Integer ):''' playheadPosition

<syntaxhighlight lang="javascript">
instance.ggPM('setPlayheadPosition', playheadPosition);
</syntaxhighlight>

*'''Event:''' stop | '''Value Pass ( Integer ):''' stopPlayheadPosition

<syntaxhighlight lang="javascript">
instance.ggPM('stop', stopPlayheadPosition);
</syntaxhighlight>

*'''Event:''' end | '''Value Pass ( Integer ):''' endPlayheadPosition

<syntaxhighlight lang="javascript">
instance.ggPM('end', endPlayheadPosition);
</syntaxhighlight>

==== Sample DOM-less SDK Implementation ====

* Sample Implementation on github [https://github.com/NielsenDigitalSDK/bsdk-domless here].

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

==== Review SDK Interrupt Scenarios ====
* [[DCR Sweden Video Browser SDK#Handle Video Playback Interruption|Handle Video Playback Interruption]]

==== Review SDK Event Lifecycle ====
* [[DCR Sweden Video Browser SDK#SDK Call Sequence |SDK Call Sequence ]]

== Privacy and Opt-Out ==

The site must provide a means for the user to opt-out of, or opt back into, Nielsen Measurement. Users can opt out if they prefer not to participate in any Nielsen online measurement research. To implement the User Opt-Out option, include the following two items in your privacy policy.
*A notice that the player (or page in relation to static measurement) includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings).
*A link to the Nielsen Digital Measurement Privacy Policy at https://www.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=sv (or for English: https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=en-se)
*We have two separate entities registered with the IAB TCF, Nielsen Marketing Cloud and Nielsen LLC. The one that is relevant to Swedish measurement is Nielsen LLC (ID: 812) and not NMC. 

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 via this [https://priv-policy.imrworldwide.com/priv/browser/cookie-policy.html?optout=1 link], their browser cookies will contain the value '''TOTAL_OPTOUT'''. This will prevent a redirect to our data provider from occurring
* Users can opt back in via this [https://priv-policy.imrworldwide.com/priv/browser/cookie-policy.html?optout=0 link]. When a user selects that link, their opt-out cookie will be deleted and they will be able to be measured moving forward.
 
The following paragraph is a template for a Privacy Statement.
<blockquote>
The properties may feature Nielsen proprietary measurement software, allowing users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices concerning it, please see the Nielsen Digital Measurement Privacy Policy at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=sv
</blockquote>

==== User Opt Back In ====
Once users have opted-out, they can choose to opt back into Nielsen Measurement at any time 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.

=== Turning off the First Party ID for Opt-out Users during the SDK Initialization ===
The First Party ID(FPID) is enabled by default in the Browser SDK. For Opt-out users, the First Party ID can be turned off during the initialization of the SDK Instance, i.e. the parameter enableFpid can be set to "false" (FPID disabled) or "true" (FPID enabled). See [[#Initialization Global Parameters|SDK Initialization Global Parameters]].

=== Setting the SDK global optout Flag for Opt-out Users during the SDK Initialization ===
The optout Flag is set by default to "false" in the Browser SDK. For Opt-out users, the optout Flag can be set to "true" during the initialization of the SDK Instance, i.e. the parameter optout can be set to "true" (opted out) or "false" (opted in or NOT opted out). See [[#Initialization Global Parameters|SDK Initialization Global Parameters]].

== Certification ==

While Nielsen is working on adding Support to the Certification Tool for DOM-less SDK in the future, the Certification process for the DOM-less will require detailed SDK Logs from a MMS Client integrating Nielsen DOM-less SDK. In this regard, a client will execute test cases locally and share logs for each test case with a Nielsen Technical Account Manager in charge of the Certification.

== Going Live ==
Following Nielsen testing, disable Nielsen SDK logging by adjusting the Nielsen SDK Initialization Call, this will ensure that the App or Website 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:

<syntaxhighlight lang="javascript">
const instance = new BsdkInstance(
nsdkConfig.app_id,
nsdkConfig.instance_name,
{
appName: 'BSDK RN Sample App',
domlessEnv: '1'// "1" for React Native | "2" for Amazon | "3" for NodeJS | "4" for Custom
// reference SDK interface documentation
// for additional metadata properties
},
implementationHooks
);
</syntaxhighlight>

'''Note''': before going live you have to inform Nielsen - this is necessary, because 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 Cloud API

2026-04-22T07:55:45Z

MichelFodjo: /* Disclose Nielsen Privacy Statement */ new sub-section "Nielsen Cloud API payload for Opt-out Users in your App "

{{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.nmrodam.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.nmrodam.com/nmapi/v2/</code>
*Production: <code>https://capi-dmk.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====
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 First Party ID===
* An First Party ID <code>[fpid]</code> must be created and stored on the device. It is re-used until expiration date or if the user has deleted it on 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.

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

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": "SHA-256 value of the Device ID",
"apn": "AppName",
"apv": "1.0",
"fpid": "First Party ID",
"fpcrtm": "Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)"
},

// 3.2 Configure Payload: metadata
"metadata": {
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2", //ad load flag
"subbrand": "c05", // channel ID or subrand provided by Nielsen
"stationId": "TESTXXYYSSWWLL",
"islivestn": "y",
"pbstarttm": "1631098029"
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000", //unix timestamp in milliseconds
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}
</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 || ✓
|-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": "SHA-256 value of the Device ID",
"apn": "AppName",
"apv": "1.0",
"fpid": "First Party ID",
"fpcrtm": "Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)"
},
</syntaxhighlight>

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

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

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

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

'''Example Content Object'''
<syntaxhighlight lang='json'>// create content object
"content": {
"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",
"stationId": "TESTXXYYSSWWLL",
"islivestn": "y",
"pbstarttm": "1631098029"
}</syntaxhighlight>

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

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "unique_preroll_ad_id"
}
</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 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.nmrodam.com/nmapi/v2/[appid]/[sessionID]/a?b=

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "SHA-256 value of the Device ID",
"apn": "AppName",
"apv": "1.0",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000"
},

// 3.2 Configure Payload: metadata
"metadata": {
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "VIDEO-ID123", // unique ID for video
"isfullepisode": "y", // full episode flag
"program": "Program Name", // program name
"title": "Episode Title S3 - EP1", // episode name
"length": "1800", // content duration in seconds
"airdate": "20161013 20:00:00", // airdate
"adloadtype": "2" // ad load flag,
"subbrand": "c05",
"stationId": "TESTXXYYSSWWLL",
"islivestn": "y",
"pbstarttm": "1631098029",
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123" // unique ID for ad
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000", //unix timestamp in milliseconds
"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
|}

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

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 .

=== Nielsen Cloud API payload for Opt-out Users in your App ===

The First Party ID(fpid) and the Device ID(devId) fields can remain empty for '''opt-out users'''.

==== First Party ID(fpid) ====

"devInfo": {
...,
"apn": "AppName",
"apv": "1.0",
"fpid": "",
"fpcrtm": "",
...
}
==== Device ID(devId) ====

"devInfo": {
...,
"devId": "",
"apn": "AppName",
"apv": "1.0",
...
}

== 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://capi-dmk.nmrodam.com/nmapi/v2/</code>

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

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

DCR Germany Video S2S

2026-04-07T09:28:54Z

MichelFodjo: /* Description */

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

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

This guide shows you how to integrate the Nielsen S2S (Server to Server) to enable Digital Content Ratings (DCR), and fuel other measurement products on your Apps.

<pre style="color: orange"; font-weight: bold;>
PLease note that you have to use the Staging S2S Endpoint(<env>=stage)until you get the green light to move to Production, you will then get the Production S2S Endpoint!
</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
|-style="background-color:#d0f6f8;"
|| '''Integration ID (IntID)''' || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| Provided by Nielsen
|}

==Introduction==
This interface specification depicts the file format that needs to be used to supply Nielsen with
end-user viewing data captured by a “Server-to-Server” method for the Nielsen Digital Content
Ratings (DCR) product and Tuning data for the Digital Ads Rating (DAR) products.
* The specification is defined using a JSON schema, with each file ideally containing all the
viewing that has been captured within an hour.
* In the case of a stream that has one version with blackouts and one without, one with
mobile and one non-mobile, each stream would have its own unique asset id.
* The Asset Metadata file should arrive before the viewing data file for the same hour.

==SLA==
The files must be delivered into the proper S3 bucket '''immediately after each hour of viewing on a device''', but '''latest within 3 hours of the start of that hourly viewing file interval'''. For example, files from '''2:00 AM to 3:00 AM''' must be delivered latest before '''5 AM'''.

'''When SLA for receiving an exposure file for date xx/xx, UTC hour xx has expired. The system will continue to wait for 60 min, after which it will skip the missing file and continue processing subsequent files. Any reprocessing of the missed SLA data will require an explicit request from AGF.'''

==Accuracy of the Measurement==

====Send Viewing Time (Video Player Events) At Least Each 10 Seconds To Your Backend====
Capture content viewing time each second and send the aggregated viewing time at least each 10 seconds to your backend:
* referencestart : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* referenceend : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* playheadstart : Content position start time in seconds
* playheadend : Content position end time in seconds

====Send Viewing Time When The Video Playback Is Interrupted====
Send the aggregated viewing time to your backend when the video playback is interrupted, i.e. paused.

====Capture Accurately Each Second The Viewing Time When The Network Is Lost And The Video Playback Continues====
Capture accurately each second the viewing time when the network is lost.
Send the aggregated viewing time to your backend when the network is back.

====Send The Viewing Time Early On Browser Refreshed/Closed====
Capture and send the viewing time to your backend by implementing the 2 WINDOWS EVENTS:

''' Please include a logic to make sure that only one of the 2 following event handler is executed '''
<syntaxhighlight lang="javascript">
window.addEventListener("pagehide", function (e) {
// SEND THE VIEWING TIME TO YOUR BACKEND
});
window.addEventListener("beforeunload", function (e) {
// ONLY IF pagehide" was not triggered, SEND THE VIEWING TIME TO YOUR BACKEND
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered at a fixed cadence in a dedicated S3 bucket following the outlined in this spec prefix and object naming conventions and data formats.

* All prefix labels and file names should be lowercase except for app ids.
* Supported formats are:
** Uncompressed text files with utf-8 encoding in:
*** JSON format(.json);
*** PARQUET format(.parquet);
* All files should have extensions to indicate the file format (.json or .parquet)
* Data file can be partitioned into multiple parts with min size of 128MB - 256MB
* Data can be delivered separately in multiple splits(platforms), if needed due to organizational, technical or privacy requirements. This allows to permission s3 access separately, to process data independently and to persist data partitioned, within the limits of the S2S system;

===The 4 Different Files to deliver to Nielsen each hour===
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

Nielsen will move files to indicate they are being processed.

====S3 bucket and prefix(S3BucketPrefix) for all 4 Files====

All files should be delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| env || '''stage''' for Staging or '''prod''' for Production
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| Platform || '''ios''', '''browser''', '''android''', '''ott'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| yyyy/mm/dd/hh || UTC start of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023/02/12/05'''

|}
=====Examples for the iOS platform=====
======Asset Metadata File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====File Name(FileName) format for the Asset Metadata and Asset Viewing Files ====

Asset Metadata and Asset Viewing Files should be delivered to:
* <S3BucketPrefix>'''<FileName>'''

* '''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime><FileSuffix>

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| IntID || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.)
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || Nielsen provided server application identifier
|-
| StartTime || start date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| EndTime || end date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| yyyymmddhh || UTC time of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023021205'''

|-
| FileSuffix || Uncompressed json lines (no extension) - splittable, ideal for medium size files, '''less than 5 GB''', preferred for metadata.
'''supported:'''
* '''.json''' json file
* '''.parquet''' parquet file
|}

=====Examples for Asset Metadata and Asset Viewing Files=====
======Asset Metadata File======
Asset Metadata File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====Manifest File for the Asset Metadata and Asset Viewing Files====

The Manifest File should be delivered to: <S3BucketPrefix>'''<FileName>'''

'''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime>'''_manifest'''

A manifest contains metadata related to the uploaded file(s). It is a text file in json format that implements the AWS unload manifest file format. It follows the s3 objects naming notation, but has the _manifest suffix. Here’s an example of manifest file contents:

{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}

The manifest contains a complete list of all files provided for a given period and platform, as well as a meta data (a.k.a. header) which should include the following attributes:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, i.e. "S2SV1.7.0" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| record_count || Records Count in data file || Number: i.e. 55 || ✓
|}

If ‘entries’ array is not specified, or manifest file is not available, the system will still attempt to load all data file(s) (.json or .parquet) from the prefix location. Optionally the manifest file can contain the full schema of the data files as shown in the [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose manifest file format document ].

=====Example for the Manifest File=====

======Manifest File for the Asset Metadata File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======Manifest File for the Asset Viewing File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

===Success File: Indication of a data delivery for a particular hour===

An Empty _SUCCESS file should be provided to indicate that data delivery for a particular hour and platform is completed successfully. This file should be uploaded last (after all other files). If there is no data data for a particular hour and platform, the _SUCCESS file is still required to indicate that the delivery process for the hour is completed and no data files are expected. This file is only required for integrations that support data partitioned into multiple parts. The name of the file is configurable.

====Example for Asset Viewing Delivery Files====

'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

====Example for Asset Metadata Delivery Files====
'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

====Data Delivery Example for hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):====
=====Asset Metadata Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

</code>
=====Asset Viewing Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0000.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0001.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0002.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0003.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

</code>

===Asset Metadata Delivery Optimization===

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day(00:00:00 AM UTC to 00:59:59 PM UTC) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 11 , referencing to the Asset Metadata File for HOUR 00'''

=====Asset Metadata File for the hour 11:00:00 AM UTC to 11:59:59 PM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 00):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS
</code>

=====Asset Metadata File for the hour 00:00:00 AM UTC to 00:59:59 PM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653436800",
"end_time": "1653440399",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day(00:00:00 AM UTC to 00:59:59 PM UTC) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 11 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 11:00:00 AM UTC to 11:59:59 PM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 00:00:00 AM UTC to 00:59:59 PM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653436800",
"end_time": "1653440399",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/_SUCCESS
</code>

== S2S Metadata Specifications for the Asset Metadata and Asset Viewing Files ==

=== Asset Metadata File ===

The Asset Metadata File contains 1 Header Record followed by Body Records

====Header Record====

=====Description=====

'''Parameter Description'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.09" || ✓
|-
| mvpdid || mvpd ID specified ny Nielsen || String, i.e. "NLSN" || ✓
|-
| creationtime || File creation time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓

|-
| recordcount || Records Count in body of file ||String, i.e. "1" for only 1 Record || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.09",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || 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)|| ✓
|-
|islivestn || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Sendungsteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || 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 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || not in use || leave blank "", reserved for AGF ||
|-style="background-color:#d0f6f8;"
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || not in use || leave blank "", reserved for AGF ||
|-style="background-color:#d0f6f8;"
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== Asset Viewing File ===

The Asset Viewing File contains 1 Header Record followed by Body Records
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.0" || ✓
|-
| appid || Nielsen provided server application identifier || String, i.e. "P47C2495B-XXXX-56DE-BE99-14758F92F034" || ✓
|-
| type || Type of the data || String, "content" || ✓
|-
| producttype || Product Type || String, "DCR" || ✓
|-
| starttime || Viewing Data Start Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓
|-
| endtime || Viewing Data End Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473791507"|| ✓
|-
| recordcount || Records Count in body of file || String, i.e. "100" for only 100 Records || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.0",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apn || app name || i.e. "BestAppIOS" || ✓
|-
| apv || app build version || i.e. "1.3" || ✓
|-
| sessionid || Unique, client generated value that represents the start of a user session. Must match sessionid in Audit Ping. || created using the UUID Generator code provided || ✓
|-
| streamid || streamid ID for every new instance of an asset || created using the UUID Generator code provided || ✓
|-
| streamended || Stream is known to have ended in this file ||
* "1" (stream will continue in next file)
* "2" (stream closed)
|| ✓
|-
| secondscr || Second Screen Indicator. For Mirroring & Extended Screen via OTT device scenarios ||
* "" (empty String if viewed directly on the device)
* "MIR" (Mirroring)
* "OTT" (Extended Screen via OTT device)
|| ✓
|-
| assetid || Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''Description:'''
* '''referencestart''' : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* '''referenceend''' : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* '''playheadstart''' : Content position start time in seconds
* '''playheadend''' : Content position end time in seconds

'''For Content position start and end time(playheadstart, playheadend):'''
* For VoD stream use the player position for Content as the playhead position in seconds. At playback start of a content from the begin, playheads will then be 0,1,2,3,....
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position in seconds.

'''Additional Notes:'''
* For viewing gaps < than 1 second, the gap can be smoothed over
* For playouts that are abandoned before the first whole second of viewing is rendered, a position record of zero duration should be created. IF an audit ping has already been fired See below for additional details on position array parameters
|| ✓
|-
| device_id || '''ONLY for''' '''android''' platform, DO NOT pass device_id for '''ios''', '''browser''' and '''ott''' platforms. Mobile Ad ID , 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" - OPTIONAL if passed in the Audit Ping|| i.e "12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8" || ✓
|-
| xdua || Device HTTP raw User Agent string - OPTIONAL if passed in the Audit Ping|| Example: "Apple-iPhone1C2/801.293" || ✓
|-
| xff || IP address - OPTIONAL if passed in the Audit Ping|| Format: "xxx.xxx.xxx.xxx" or "xxx.xxx.xxx.000"
Examples :
* IPV4: "4.12.345.67"
* IPV6: "2600:6c58:7900:33f2:2505:42b9:5a34:0000"
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // create and pass a unique streamid for each video play using UUID Generator code provided
"streamended": "1",
"assetid": "VA12345",
"secondscr": "MIR",
"position": [
{
"referencestart": "1628735452",
"referenceend": "1628736052",
"playheadstart": "0",
"playheadend": "600"
}
],
"xdua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130Safari/537.36",
"xff": "4.12.345.67"
}

</syntaxhighlight>

===== Android Platform : Example Metadata with "device_id" =====

====== "device_id" available ======
<syntaxhighlight lang="javascript">
{
"device_id": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826"
}
</syntaxhighlight>

====== "device_id" not available ======
<syntaxhighlight lang="javascript">
{
"device_id": ""
}
</syntaxhighlight>

==OTT, Mirroring, and Casting==

For apps native to the OTT device (i.e. downloading and viewing a streaming app to an Apple
TV, audit ping should fire from OTT device, and Viewing data should reside in OTT Viewing file.
For mirroring, where video playback occurs on the mobile device and OTT device, only one
Viewing file row is necessary where, if possible to determine, set: "secondscr":"MIR" and
include in respective mobile platform Viewing file.

For a casting scenario where content is controlled via the mobile device, but displayed only on
the OTT device such as an AppleTV or Chromecast, an audit ping must fire from the mobile
device before the casting occurs and at the end of playback from the mobile device only.
Viewing data resides in the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx123",
"referenceend": "xxxxxxx183",
'''"playheadstart": "0",'''
'''"playheadend": "60"'''
},
{
"referencestart": "xxxxxxx243",
"referenceend": "xxxxxxx303",
'''"playheadstart": "120",'''
'''"playheadend": "180"'''
}
]
}

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx183",
"referenceend": "xxxxxxx243",
'''"playheadstart": "60",'''
'''"playheadend": "120"'''
}
],
'''"secondscr": "OTT"'''
}

==S2S Audit Ping Specifications==

=== Introduction ===
The Nielsen server to server solution needs audit pings to validate audience reach and video viewing duration, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.

'''start audit ping(“Startstream = 1”)'''
* A start audit ping is sent when the stream starts(playback start).
* Also a new start audit ping is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
'''end audit ping(“Endstream = 3”)'''
* An end audit ping is sent when the stream ends(either playback completed or switch to another stream).
* Also an end audit ping is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.

=== Ping Structure ===
Ping should be named with following convention structure:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(Please note that this URL could change as we respond to security upgrades in the market.)
The Start Audit Ping will carry all parameters in the matrix below. The End Audit Ping will carry a subset of the parameters in the matrix below as denoted in the mandatory column.
Under normal operating circumstances, the Nielsen collection system will return return codes:
* For security reasons, downstream servers reject cross-origin HTTP requests with preflight. To ensure that audit ping requests are accepted, allowable Content-Types like "text/plain" in simple GET requests ensure that preflight requests are not invoked, which is the preferred behavior.
* 200: The ping was successfully received, inspect traffic to ensure no CORS errors

=== Ping Session & Stream Details ===

==== Sessions ====
* a) When a new player is created a session id is also created.
* b) If you have more than one video player within the same App (e.g. picture in picture) you must use a different session id for each.

==== Streams ====
* a) The Distributor must generate a new UNIQUE stream id with every video stream playback.
* b) If two people watch the same show, they would have different stream id's as Nielsen would expect the stream id(“streamid”) to be a random GUId generated by the client device.
* c) If one person watches a show, and FF, rewind, playout, pause, play, RW, play - they would keep the same stream id(“streamid”) throughout the entire playout of that video asset (stream).
* d) If a stream play out is suspended for 30 mins or more (paused or background):
** An end audit ping(“Endstream = 3”) is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.
** A new start audit ping(“Startstream = 1”) is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
* e) If the user reaches the very end of the stream (content complete), and then starts to play again (replay from anywhere in the stream), then a new “streamid” should be created and a start audit ping should be sent. Also an end audit should be sent when the stream replay is completed or the user switches to another stream.

====Audit Pings ====
* a) Audit pings should be fired at the '''beginning''' and '''end''' of a stream. These will be referred to as the Audit Start Ping and the Audit End Ping.

==== query param list ====

Example:

'''Required S2S Audit Ping Query String Parameters - Note: All parameters are case sensitive'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || Unique ID assigned to the player/site and configured by your Nielsen Technical Account Manager.
|| Example: '''FC984EC1-E044-B465-E040-070AAD3173A1''' || ✓
|-
| intid || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || || ✓
|-
| sessionid || Unique, client-generated value that represents the start of a user browsing session. Must match sessionid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| streamid || Unique Id for every new instance of a client video asset playout. Must match streamid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| pingtype || pingtype Indicator for state type: “start” or “end” audit ping & if the ping is for a stream ||
* Startstream = 1
* Startsession=0
* Endstream = 3
* Endsession=2
|| ✓
|-
| product || Indicates which Nielsen product the audit ping corresponds to. || dcr || ✓
|-
| createtm || Time the ping was fired: utc (in seconds) If server time available, use it instead of device time || || ✓
|-
| devid || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

'''Generic Ping Format:'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=<App id>&intid=<Integration ID>&sessionid=<Session Id>&streamid=<Stream Id>&pingtype=<Ping Type>&product=<dcr or dtvr>&createtm=<Session Start or End time>&devid=<Android ADID>'''
</nowiki></code>

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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>

DCR Germany Video S2S

2026-04-07T09:28:23Z

MichelFodjo: /* Description */

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

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

This guide shows you how to integrate the Nielsen S2S (Server to Server) to enable Digital Content Ratings (DCR), and fuel other measurement products on your Apps.

<pre style="color: orange"; font-weight: bold;>
PLease note that you have to use the Staging S2S Endpoint(<env>=stage)until you get the green light to move to Production, you will then get the Production S2S Endpoint!
</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
|-style="background-color:#d0f6f8;"
|| '''Integration ID (IntID)''' || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| Provided by Nielsen
|}

==Introduction==
This interface specification depicts the file format that needs to be used to supply Nielsen with
end-user viewing data captured by a “Server-to-Server” method for the Nielsen Digital Content
Ratings (DCR) product and Tuning data for the Digital Ads Rating (DAR) products.
* The specification is defined using a JSON schema, with each file ideally containing all the
viewing that has been captured within an hour.
* In the case of a stream that has one version with blackouts and one without, one with
mobile and one non-mobile, each stream would have its own unique asset id.
* The Asset Metadata file should arrive before the viewing data file for the same hour.

==SLA==
The files must be delivered into the proper S3 bucket '''immediately after each hour of viewing on a device''', but '''latest within 3 hours of the start of that hourly viewing file interval'''. For example, files from '''2:00 AM to 3:00 AM''' must be delivered latest before '''5 AM'''.

'''When SLA for receiving an exposure file for date xx/xx, UTC hour xx has expired. The system will continue to wait for 60 min, after which it will skip the missing file and continue processing subsequent files. Any reprocessing of the missed SLA data will require an explicit request from AGF.'''

==Accuracy of the Measurement==

====Send Viewing Time (Video Player Events) At Least Each 10 Seconds To Your Backend====
Capture content viewing time each second and send the aggregated viewing time at least each 10 seconds to your backend:
* referencestart : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* referenceend : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* playheadstart : Content position start time in seconds
* playheadend : Content position end time in seconds

====Send Viewing Time When The Video Playback Is Interrupted====
Send the aggregated viewing time to your backend when the video playback is interrupted, i.e. paused.

====Capture Accurately Each Second The Viewing Time When The Network Is Lost And The Video Playback Continues====
Capture accurately each second the viewing time when the network is lost.
Send the aggregated viewing time to your backend when the network is back.

====Send The Viewing Time Early On Browser Refreshed/Closed====
Capture and send the viewing time to your backend by implementing the 2 WINDOWS EVENTS:

''' Please include a logic to make sure that only one of the 2 following event handler is executed '''
<syntaxhighlight lang="javascript">
window.addEventListener("pagehide", function (e) {
// SEND THE VIEWING TIME TO YOUR BACKEND
});
window.addEventListener("beforeunload", function (e) {
// ONLY IF pagehide" was not triggered, SEND THE VIEWING TIME TO YOUR BACKEND
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered at a fixed cadence in a dedicated S3 bucket following the outlined in this spec prefix and object naming conventions and data formats.

* All prefix labels and file names should be lowercase except for app ids.
* Supported formats are:
** Uncompressed text files with utf-8 encoding in:
*** JSON format(.json);
*** PARQUET format(.parquet);
* All files should have extensions to indicate the file format (.json or .parquet)
* Data file can be partitioned into multiple parts with min size of 128MB - 256MB
* Data can be delivered separately in multiple splits(platforms), if needed due to organizational, technical or privacy requirements. This allows to permission s3 access separately, to process data independently and to persist data partitioned, within the limits of the S2S system;

===The 4 Different Files to deliver to Nielsen each hour===
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

Nielsen will move files to indicate they are being processed.

====S3 bucket and prefix(S3BucketPrefix) for all 4 Files====

All files should be delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| env || '''stage''' for Staging or '''prod''' for Production
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| Platform || '''ios''', '''browser''', '''android''', '''ott'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| yyyy/mm/dd/hh || UTC start of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023/02/12/05'''

|}
=====Examples for the iOS platform=====
======Asset Metadata File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====File Name(FileName) format for the Asset Metadata and Asset Viewing Files ====

Asset Metadata and Asset Viewing Files should be delivered to:
* <S3BucketPrefix>'''<FileName>'''

* '''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime><FileSuffix>

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| IntID || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.)
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || Nielsen provided server application identifier
|-
| StartTime || start date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| EndTime || end date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| yyyymmddhh || UTC time of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023021205'''

|-
| FileSuffix || Uncompressed json lines (no extension) - splittable, ideal for medium size files, '''less than 5 GB''', preferred for metadata.
'''supported:'''
* '''.json''' json file
* '''.parquet''' parquet file
|}

=====Examples for Asset Metadata and Asset Viewing Files=====
======Asset Metadata File======
Asset Metadata File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====Manifest File for the Asset Metadata and Asset Viewing Files====

The Manifest File should be delivered to: <S3BucketPrefix>'''<FileName>'''

'''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime>'''_manifest'''

A manifest contains metadata related to the uploaded file(s). It is a text file in json format that implements the AWS unload manifest file format. It follows the s3 objects naming notation, but has the _manifest suffix. Here’s an example of manifest file contents:

{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}

The manifest contains a complete list of all files provided for a given period and platform, as well as a meta data (a.k.a. header) which should include the following attributes:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, i.e. "S2SV1.7.0" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| record_count || Records Count in data file || Number: i.e. 55 || ✓
|}

If ‘entries’ array is not specified, or manifest file is not available, the system will still attempt to load all data file(s) (.json or .parquet) from the prefix location. Optionally the manifest file can contain the full schema of the data files as shown in the [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose manifest file format document ].

=====Example for the Manifest File=====

======Manifest File for the Asset Metadata File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======Manifest File for the Asset Viewing File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

===Success File: Indication of a data delivery for a particular hour===

An Empty _SUCCESS file should be provided to indicate that data delivery for a particular hour and platform is completed successfully. This file should be uploaded last (after all other files). If there is no data data for a particular hour and platform, the _SUCCESS file is still required to indicate that the delivery process for the hour is completed and no data files are expected. This file is only required for integrations that support data partitioned into multiple parts. The name of the file is configurable.

====Example for Asset Viewing Delivery Files====

'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

====Example for Asset Metadata Delivery Files====
'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

====Data Delivery Example for hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):====
=====Asset Metadata Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

</code>
=====Asset Viewing Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0000.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0001.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0002.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0003.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

</code>

===Asset Metadata Delivery Optimization===

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day(00:00:00 AM UTC to 00:59:59 PM UTC) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 11 , referencing to the Asset Metadata File for HOUR 00'''

=====Asset Metadata File for the hour 11:00:00 AM UTC to 11:59:59 PM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 00):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS
</code>

=====Asset Metadata File for the hour 00:00:00 AM UTC to 00:59:59 PM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653436800",
"end_time": "1653440399",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day(00:00:00 AM UTC to 00:59:59 PM UTC) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 11 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 11:00:00 AM UTC to 11:59:59 PM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 00:00:00 AM UTC to 00:59:59 PM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653436800",
"end_time": "1653440399",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/_SUCCESS
</code>

== S2S Metadata Specifications for the Asset Metadata and Asset Viewing Files ==

=== Asset Metadata File ===

The Asset Metadata File contains 1 Header Record followed by Body Records

====Header Record====

=====Description=====

'''Parameter Description'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.09" || ✓
|-
| mvpdid || mvpd ID specified ny Nielsen || String, i.e. "NLSN" || ✓
|-
| creationtime || File creation time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓

|-
| recordcount || Records Count in body of file ||String, i.e. "1" for only 1 Record || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.09",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || 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)|| ✓
|-
|islivestn || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Sendungsteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || 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 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || not in use || leave blank "", reserved for AGF ||
|-style="background-color:#d0f6f8;"
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || not in use || leave blank "", reserved for AGF ||
|-style="background-color:#d0f6f8;"
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== Asset Viewing File ===

The Asset Viewing File contains 1 Header Record followed by Body Records
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.0" || ✓
|-
| appid || Nielsen provided server application identifier || String, i.e. "P47C2495B-XXXX-56DE-BE99-14758F92F034" || ✓
|-
| type || Type of the data || String, "content" || ✓
|-
| producttype || Product Type || String, "DCR" || ✓
|-
| starttime || Viewing Data Start Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓
|-
| endtime || Viewing Data End Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473791507"|| ✓
|-
| recordcount || Records Count in body of file || String, i.e. "100" for only 100 Records || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.0",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apn || app name || i.e. "BestAppIOS" || ✓
|-
| apv || app build version || i.e. "1.3" || ✓
|-
| sessionid || Unique, client generated value that represents the start of a user session. Must match sessionid in Audit Ping. || created using the UUID Generator code provided || ✓
|-
| streamid || streamid ID for every new instance of an asset || created using the UUID Generator code provided || ✓
|-
| streamended || Stream is known to have ended in this file ||
* "1" (stream will continue in next file)
* "2" (stream closed)
|| ✓
|-
| secondscr || Second Screen Indicator. For Mirroring & Extended Screen via OTT device scenarios ||
* "" (empty String if viewed directly on the device)
* "MIR" (Mirroring)
* "OTT" (Extended Screen via OTT device)
|| ✓
|-
| assetid || Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c10) separated by an underscore character ('''<c7_c10>''').
||
* custom (no [[Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''Description:'''
* '''referencestart''' : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* '''referenceend''' : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* '''playheadstart''' : Content position start time in seconds
* '''playheadend''' : Content position end time in seconds

'''For Content position start and end time(playheadstart, playheadend):'''
* For VoD stream use the player position for Content as the playhead position in seconds. At playback start of a content from the begin, playheads will then be 0,1,2,3,....
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position in seconds.

'''Additional Notes:'''
* For viewing gaps < than 1 second, the gap can be smoothed over
* For playouts that are abandoned before the first whole second of viewing is rendered, a position record of zero duration should be created. IF an audit ping has already been fired See below for additional details on position array parameters
|| ✓
|-
| device_id || '''ONLY for''' '''android''' platform, DO NOT pass device_id for '''ios''', '''browser''' and '''ott''' platforms. Mobile Ad ID , 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" - OPTIONAL if passed in the Audit Ping|| i.e "12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8" || ✓
|-
| xdua || Device HTTP raw User Agent string - OPTIONAL if passed in the Audit Ping|| Example: "Apple-iPhone1C2/801.293" || ✓
|-
| xff || IP address - OPTIONAL if passed in the Audit Ping|| Format: "xxx.xxx.xxx.xxx" or "xxx.xxx.xxx.000"
Examples :
* IPV4: "4.12.345.67"
* IPV6: "2600:6c58:7900:33f2:2505:42b9:5a34:0000"
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // create and pass a unique streamid for each video play using UUID Generator code provided
"streamended": "1",
"assetid": "VA12345",
"secondscr": "MIR",
"position": [
{
"referencestart": "1628735452",
"referenceend": "1628736052",
"playheadstart": "0",
"playheadend": "600"
}
],
"xdua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130Safari/537.36",
"xff": "4.12.345.67"
}

</syntaxhighlight>

===== Android Platform : Example Metadata with "device_id" =====

====== "device_id" available ======
<syntaxhighlight lang="javascript">
{
"device_id": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826"
}
</syntaxhighlight>

====== "device_id" not available ======
<syntaxhighlight lang="javascript">
{
"device_id": ""
}
</syntaxhighlight>

==OTT, Mirroring, and Casting==

For apps native to the OTT device (i.e. downloading and viewing a streaming app to an Apple
TV, audit ping should fire from OTT device, and Viewing data should reside in OTT Viewing file.
For mirroring, where video playback occurs on the mobile device and OTT device, only one
Viewing file row is necessary where, if possible to determine, set: "secondscr":"MIR" and
include in respective mobile platform Viewing file.

For a casting scenario where content is controlled via the mobile device, but displayed only on
the OTT device such as an AppleTV or Chromecast, an audit ping must fire from the mobile
device before the casting occurs and at the end of playback from the mobile device only.
Viewing data resides in the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx123",
"referenceend": "xxxxxxx183",
'''"playheadstart": "0",'''
'''"playheadend": "60"'''
},
{
"referencestart": "xxxxxxx243",
"referenceend": "xxxxxxx303",
'''"playheadstart": "120",'''
'''"playheadend": "180"'''
}
]
}

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx183",
"referenceend": "xxxxxxx243",
'''"playheadstart": "60",'''
'''"playheadend": "120"'''
}
],
'''"secondscr": "OTT"'''
}

==S2S Audit Ping Specifications==

=== Introduction ===
The Nielsen server to server solution needs audit pings to validate audience reach and video viewing duration, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.

'''start audit ping(“Startstream = 1”)'''
* A start audit ping is sent when the stream starts(playback start).
* Also a new start audit ping is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
'''end audit ping(“Endstream = 3”)'''
* An end audit ping is sent when the stream ends(either playback completed or switch to another stream).
* Also an end audit ping is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.

=== Ping Structure ===
Ping should be named with following convention structure:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(Please note that this URL could change as we respond to security upgrades in the market.)
The Start Audit Ping will carry all parameters in the matrix below. The End Audit Ping will carry a subset of the parameters in the matrix below as denoted in the mandatory column.
Under normal operating circumstances, the Nielsen collection system will return return codes:
* For security reasons, downstream servers reject cross-origin HTTP requests with preflight. To ensure that audit ping requests are accepted, allowable Content-Types like "text/plain" in simple GET requests ensure that preflight requests are not invoked, which is the preferred behavior.
* 200: The ping was successfully received, inspect traffic to ensure no CORS errors

=== Ping Session & Stream Details ===

==== Sessions ====
* a) When a new player is created a session id is also created.
* b) If you have more than one video player within the same App (e.g. picture in picture) you must use a different session id for each.

==== Streams ====
* a) The Distributor must generate a new UNIQUE stream id with every video stream playback.
* b) If two people watch the same show, they would have different stream id's as Nielsen would expect the stream id(“streamid”) to be a random GUId generated by the client device.
* c) If one person watches a show, and FF, rewind, playout, pause, play, RW, play - they would keep the same stream id(“streamid”) throughout the entire playout of that video asset (stream).
* d) If a stream play out is suspended for 30 mins or more (paused or background):
** An end audit ping(“Endstream = 3”) is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.
** A new start audit ping(“Startstream = 1”) is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
* e) If the user reaches the very end of the stream (content complete), and then starts to play again (replay from anywhere in the stream), then a new “streamid” should be created and a start audit ping should be sent. Also an end audit should be sent when the stream replay is completed or the user switches to another stream.

====Audit Pings ====
* a) Audit pings should be fired at the '''beginning''' and '''end''' of a stream. These will be referred to as the Audit Start Ping and the Audit End Ping.

==== query param list ====

Example:

'''Required S2S Audit Ping Query String Parameters - Note: All parameters are case sensitive'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || Unique ID assigned to the player/site and configured by your Nielsen Technical Account Manager.
|| Example: '''FC984EC1-E044-B465-E040-070AAD3173A1''' || ✓
|-
| intid || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || || ✓
|-
| sessionid || Unique, client-generated value that represents the start of a user browsing session. Must match sessionid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| streamid || Unique Id for every new instance of a client video asset playout. Must match streamid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| pingtype || pingtype Indicator for state type: “start” or “end” audit ping & if the ping is for a stream ||
* Startstream = 1
* Startsession=0
* Endstream = 3
* Endsession=2
|| ✓
|-
| product || Indicates which Nielsen product the audit ping corresponds to. || dcr || ✓
|-
| createtm || Time the ping was fired: utc (in seconds) If server time available, use it instead of device time || || ✓
|-
| devid || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

'''Generic Ping Format:'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=<App id>&intid=<Integration ID>&sessionid=<Session Id>&streamid=<Stream Id>&pingtype=<Ping Type>&product=<dcr or dtvr>&createtm=<Session Start or End time>&devid=<Android ADID>'''
</nowiki></code>

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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>

DCR Germany Video Cloud API

2026-04-07T09:27:37Z

MichelFodjo: /* Description of Content metadata */

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

= DCR Integration Utilizing Cloud API =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a Cloud API Integration!
</pre>
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"; font-weight: bold;>
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 ====
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,",
"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,",
"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.

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| 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) || ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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 || custom variable || custom ||
|-
| nol_c14 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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.

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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 the Ad asset corresponding to the AGF custom variable '''c11'''.
||
* custom (no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters])
* Preroll: <c11>
* Midroll: <c11>
* Postroll: <c11>
|| ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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 current video asset playback is terminated or completed,
* at the end of the current stream playback when the user switches to another piece of content or when the App is closed.
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 Germany Video App SDK

2026-04-07T09:27:09Z

MichelFodjo: /* Description of Content 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 ===

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

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c0) separated by an underscore character ('''<c7_c0>''').
||
* custom (no [[Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| 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) || ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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 || custom variable || custom ||
|-
| nol_c14 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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,",
@"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,")
.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.

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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 the Ad asset corresponding to the AGF custom variable '''c11'''.
||
* custom (no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters])
* Preroll: <c11>
* Midroll: <c11>
* Postroll: <c11>
|| ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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,",
@"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,")
.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

2026-04-07T09:25:54Z

MichelFodjo: /* Description of Content metadata */

DCR Germany Video S2S

2026-04-07T08:42:25Z

MichelFodjo: /* Body Record */

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

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

This guide shows you how to integrate the Nielsen S2S (Server to Server) to enable Digital Content Ratings (DCR), and fuel other measurement products on your Apps.

<pre style="color: orange"; font-weight: bold;>
PLease note that you have to use the Staging S2S Endpoint(<env>=stage)until you get the green light to move to Production, you will then get the Production S2S Endpoint!
</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
|-style="background-color:#d0f6f8;"
|| '''Integration ID (IntID)''' || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| Provided by Nielsen
|}

==Introduction==
This interface specification depicts the file format that needs to be used to supply Nielsen with
end-user viewing data captured by a “Server-to-Server” method for the Nielsen Digital Content
Ratings (DCR) product and Tuning data for the Digital Ads Rating (DAR) products.
* The specification is defined using a JSON schema, with each file ideally containing all the
viewing that has been captured within an hour.
* In the case of a stream that has one version with blackouts and one without, one with
mobile and one non-mobile, each stream would have its own unique asset id.
* The Asset Metadata file should arrive before the viewing data file for the same hour.

==SLA==
The files must be delivered into the proper S3 bucket '''immediately after each hour of viewing on a device''', but '''latest within 3 hours of the start of that hourly viewing file interval'''. For example, files from '''2:00 AM to 3:00 AM''' must be delivered latest before '''5 AM'''.

'''When SLA for receiving an exposure file for date xx/xx, UTC hour xx has expired. The system will continue to wait for 60 min, after which it will skip the missing file and continue processing subsequent files. Any reprocessing of the missed SLA data will require an explicit request from AGF.'''

==Accuracy of the Measurement==

====Send Viewing Time (Video Player Events) At Least Each 10 Seconds To Your Backend====
Capture content viewing time each second and send the aggregated viewing time at least each 10 seconds to your backend:
* referencestart : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* referenceend : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* playheadstart : Content position start time in seconds
* playheadend : Content position end time in seconds

====Send Viewing Time When The Video Playback Is Interrupted====
Send the aggregated viewing time to your backend when the video playback is interrupted, i.e. paused.

====Capture Accurately Each Second The Viewing Time When The Network Is Lost And The Video Playback Continues====
Capture accurately each second the viewing time when the network is lost.
Send the aggregated viewing time to your backend when the network is back.

====Send The Viewing Time Early On Browser Refreshed/Closed====
Capture and send the viewing time to your backend by implementing the 2 WINDOWS EVENTS:

''' Please include a logic to make sure that only one of the 2 following event handler is executed '''
<syntaxhighlight lang="javascript">
window.addEventListener("pagehide", function (e) {
// SEND THE VIEWING TIME TO YOUR BACKEND
});
window.addEventListener("beforeunload", function (e) {
// ONLY IF pagehide" was not triggered, SEND THE VIEWING TIME TO YOUR BACKEND
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered at a fixed cadence in a dedicated S3 bucket following the outlined in this spec prefix and object naming conventions and data formats.

* All prefix labels and file names should be lowercase except for app ids.
* Supported formats are:
** Uncompressed text files with utf-8 encoding in:
*** JSON format(.json);
*** PARQUET format(.parquet);
* All files should have extensions to indicate the file format (.json or .parquet)
* Data file can be partitioned into multiple parts with min size of 128MB - 256MB
* Data can be delivered separately in multiple splits(platforms), if needed due to organizational, technical or privacy requirements. This allows to permission s3 access separately, to process data independently and to persist data partitioned, within the limits of the S2S system;

===The 4 Different Files to deliver to Nielsen each hour===
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

Nielsen will move files to indicate they are being processed.

====S3 bucket and prefix(S3BucketPrefix) for all 4 Files====

All files should be delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| env || '''stage''' for Staging or '''prod''' for Production
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| Platform || '''ios''', '''browser''', '''android''', '''ott'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| yyyy/mm/dd/hh || UTC start of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023/02/12/05'''

|}
=====Examples for the iOS platform=====
======Asset Metadata File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====File Name(FileName) format for the Asset Metadata and Asset Viewing Files ====

Asset Metadata and Asset Viewing Files should be delivered to:
* <S3BucketPrefix>'''<FileName>'''

* '''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime><FileSuffix>

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| IntID || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.)
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || Nielsen provided server application identifier
|-
| StartTime || start date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| EndTime || end date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| yyyymmddhh || UTC time of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023021205'''

|-
| FileSuffix || Uncompressed json lines (no extension) - splittable, ideal for medium size files, '''less than 5 GB''', preferred for metadata.
'''supported:'''
* '''.json''' json file
* '''.parquet''' parquet file
|}

=====Examples for Asset Metadata and Asset Viewing Files=====
======Asset Metadata File======
Asset Metadata File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====Manifest File for the Asset Metadata and Asset Viewing Files====

The Manifest File should be delivered to: <S3BucketPrefix>'''<FileName>'''

'''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime>'''_manifest'''

A manifest contains metadata related to the uploaded file(s). It is a text file in json format that implements the AWS unload manifest file format. It follows the s3 objects naming notation, but has the _manifest suffix. Here’s an example of manifest file contents:

{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}

The manifest contains a complete list of all files provided for a given period and platform, as well as a meta data (a.k.a. header) which should include the following attributes:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, i.e. "S2SV1.7.0" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| record_count || Records Count in data file || Number: i.e. 55 || ✓
|}

If ‘entries’ array is not specified, or manifest file is not available, the system will still attempt to load all data file(s) (.json or .parquet) from the prefix location. Optionally the manifest file can contain the full schema of the data files as shown in the [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose manifest file format document ].

=====Example for the Manifest File=====

======Manifest File for the Asset Metadata File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======Manifest File for the Asset Viewing File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

===Success File: Indication of a data delivery for a particular hour===

An Empty _SUCCESS file should be provided to indicate that data delivery for a particular hour and platform is completed successfully. This file should be uploaded last (after all other files). If there is no data data for a particular hour and platform, the _SUCCESS file is still required to indicate that the delivery process for the hour is completed and no data files are expected. This file is only required for integrations that support data partitioned into multiple parts. The name of the file is configurable.

====Example for Asset Viewing Delivery Files====

'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

====Example for Asset Metadata Delivery Files====
'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

====Data Delivery Example for hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):====
=====Asset Metadata Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

</code>
=====Asset Viewing Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0000.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0001.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0002.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0003.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

</code>

===Asset Metadata Delivery Optimization===

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day(00:00:00 AM UTC to 00:59:59 PM UTC) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 11 , referencing to the Asset Metadata File for HOUR 00'''

=====Asset Metadata File for the hour 11:00:00 AM UTC to 11:59:59 PM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 00):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS
</code>

=====Asset Metadata File for the hour 00:00:00 AM UTC to 00:59:59 PM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653436800",
"end_time": "1653440399",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day(00:00:00 AM UTC to 00:59:59 PM UTC) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 11 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 11:00:00 AM UTC to 11:59:59 PM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 00:00:00 AM UTC to 00:59:59 PM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653436800",
"end_time": "1653440399",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/_SUCCESS
</code>

== S2S Metadata Specifications for the Asset Metadata and Asset Viewing Files ==

=== Asset Metadata File ===

The Asset Metadata File contains 1 Header Record followed by Body Records

====Header Record====

=====Description=====

'''Parameter Description'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.09" || ✓
|-
| mvpdid || mvpd ID specified ny Nielsen || String, i.e. "NLSN" || ✓
|-
| creationtime || File creation time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓

|-
| recordcount || Records Count in body of file ||String, i.e. "1" for only 1 Record || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.09",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c10) separated by an underscore character ('''<c7_c10>''').
||
* custom (no [[Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || 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)|| ✓
|-
|islivestn || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Sendungsteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || 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 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || not in use || leave blank "", reserved for AGF ||
|-style="background-color:#d0f6f8;"
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || not in use || leave blank "", reserved for AGF ||
|-style="background-color:#d0f6f8;"
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== Asset Viewing File ===

The Asset Viewing File contains 1 Header Record followed by Body Records
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.0" || ✓
|-
| appid || Nielsen provided server application identifier || String, i.e. "P47C2495B-XXXX-56DE-BE99-14758F92F034" || ✓
|-
| type || Type of the data || String, "content" || ✓
|-
| producttype || Product Type || String, "DCR" || ✓
|-
| starttime || Viewing Data Start Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓
|-
| endtime || Viewing Data End Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473791507"|| ✓
|-
| recordcount || Records Count in body of file || String, i.e. "100" for only 100 Records || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.0",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apn || app name || i.e. "BestAppIOS" || ✓
|-
| apv || app build version || i.e. "1.3" || ✓
|-
| sessionid || Unique, client generated value that represents the start of a user session. Must match sessionid in Audit Ping. || created using the UUID Generator code provided || ✓
|-
| streamid || streamid ID for every new instance of an asset || created using the UUID Generator code provided || ✓
|-
| streamended || Stream is known to have ended in this file ||
* "1" (stream will continue in next file)
* "2" (stream closed)
|| ✓
|-
| secondscr || Second Screen Indicator. For Mirroring & Extended Screen via OTT device scenarios ||
* "" (empty String if viewed directly on the device)
* "MIR" (Mirroring)
* "OTT" (Extended Screen via OTT device)
|| ✓
|-
| assetid || Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c10) separated by an underscore character ('''<c7_c10>''').
||
* custom (no [[Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''Description:'''
* '''referencestart''' : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* '''referenceend''' : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* '''playheadstart''' : Content position start time in seconds
* '''playheadend''' : Content position end time in seconds

'''For Content position start and end time(playheadstart, playheadend):'''
* For VoD stream use the player position for Content as the playhead position in seconds. At playback start of a content from the begin, playheads will then be 0,1,2,3,....
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position in seconds.

'''Additional Notes:'''
* For viewing gaps < than 1 second, the gap can be smoothed over
* For playouts that are abandoned before the first whole second of viewing is rendered, a position record of zero duration should be created. IF an audit ping has already been fired See below for additional details on position array parameters
|| ✓
|-
| device_id || '''ONLY for''' '''android''' platform, DO NOT pass device_id for '''ios''', '''browser''' and '''ott''' platforms. Mobile Ad ID , 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" - OPTIONAL if passed in the Audit Ping|| i.e "12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8" || ✓
|-
| xdua || Device HTTP raw User Agent string - OPTIONAL if passed in the Audit Ping|| Example: "Apple-iPhone1C2/801.293" || ✓
|-
| xff || IP address - OPTIONAL if passed in the Audit Ping|| Format: "xxx.xxx.xxx.xxx" or "xxx.xxx.xxx.000"
Examples :
* IPV4: "4.12.345.67"
* IPV6: "2600:6c58:7900:33f2:2505:42b9:5a34:0000"
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // create and pass a unique streamid for each video play using UUID Generator code provided
"streamended": "1",
"assetid": "VA12345",
"secondscr": "MIR",
"position": [
{
"referencestart": "1628735452",
"referenceend": "1628736052",
"playheadstart": "0",
"playheadend": "600"
}
],
"xdua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130Safari/537.36",
"xff": "4.12.345.67"
}

</syntaxhighlight>

===== Android Platform : Example Metadata with "device_id" =====

====== "device_id" available ======
<syntaxhighlight lang="javascript">
{
"device_id": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826"
}
</syntaxhighlight>

====== "device_id" not available ======
<syntaxhighlight lang="javascript">
{
"device_id": ""
}
</syntaxhighlight>

==OTT, Mirroring, and Casting==

For apps native to the OTT device (i.e. downloading and viewing a streaming app to an Apple
TV, audit ping should fire from OTT device, and Viewing data should reside in OTT Viewing file.
For mirroring, where video playback occurs on the mobile device and OTT device, only one
Viewing file row is necessary where, if possible to determine, set: "secondscr":"MIR" and
include in respective mobile platform Viewing file.

For a casting scenario where content is controlled via the mobile device, but displayed only on
the OTT device such as an AppleTV or Chromecast, an audit ping must fire from the mobile
device before the casting occurs and at the end of playback from the mobile device only.
Viewing data resides in the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx123",
"referenceend": "xxxxxxx183",
'''"playheadstart": "0",'''
'''"playheadend": "60"'''
},
{
"referencestart": "xxxxxxx243",
"referenceend": "xxxxxxx303",
'''"playheadstart": "120",'''
'''"playheadend": "180"'''
}
]
}

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx183",
"referenceend": "xxxxxxx243",
'''"playheadstart": "60",'''
'''"playheadend": "120"'''
}
],
'''"secondscr": "OTT"'''
}

==S2S Audit Ping Specifications==

=== Introduction ===
The Nielsen server to server solution needs audit pings to validate audience reach and video viewing duration, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.

'''start audit ping(“Startstream = 1”)'''
* A start audit ping is sent when the stream starts(playback start).
* Also a new start audit ping is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
'''end audit ping(“Endstream = 3”)'''
* An end audit ping is sent when the stream ends(either playback completed or switch to another stream).
* Also an end audit ping is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.

=== Ping Structure ===
Ping should be named with following convention structure:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(Please note that this URL could change as we respond to security upgrades in the market.)
The Start Audit Ping will carry all parameters in the matrix below. The End Audit Ping will carry a subset of the parameters in the matrix below as denoted in the mandatory column.
Under normal operating circumstances, the Nielsen collection system will return return codes:
* For security reasons, downstream servers reject cross-origin HTTP requests with preflight. To ensure that audit ping requests are accepted, allowable Content-Types like "text/plain" in simple GET requests ensure that preflight requests are not invoked, which is the preferred behavior.
* 200: The ping was successfully received, inspect traffic to ensure no CORS errors

=== Ping Session & Stream Details ===

==== Sessions ====
* a) When a new player is created a session id is also created.
* b) If you have more than one video player within the same App (e.g. picture in picture) you must use a different session id for each.

==== Streams ====
* a) The Distributor must generate a new UNIQUE stream id with every video stream playback.
* b) If two people watch the same show, they would have different stream id's as Nielsen would expect the stream id(“streamid”) to be a random GUId generated by the client device.
* c) If one person watches a show, and FF, rewind, playout, pause, play, RW, play - they would keep the same stream id(“streamid”) throughout the entire playout of that video asset (stream).
* d) If a stream play out is suspended for 30 mins or more (paused or background):
** An end audit ping(“Endstream = 3”) is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.
** A new start audit ping(“Startstream = 1”) is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
* e) If the user reaches the very end of the stream (content complete), and then starts to play again (replay from anywhere in the stream), then a new “streamid” should be created and a start audit ping should be sent. Also an end audit should be sent when the stream replay is completed or the user switches to another stream.

====Audit Pings ====
* a) Audit pings should be fired at the '''beginning''' and '''end''' of a stream. These will be referred to as the Audit Start Ping and the Audit End Ping.

==== query param list ====

Example:

'''Required S2S Audit Ping Query String Parameters - Note: All parameters are case sensitive'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || Unique ID assigned to the player/site and configured by your Nielsen Technical Account Manager.
|| Example: '''FC984EC1-E044-B465-E040-070AAD3173A1''' || ✓
|-
| intid || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || || ✓
|-
| sessionid || Unique, client-generated value that represents the start of a user browsing session. Must match sessionid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| streamid || Unique Id for every new instance of a client video asset playout. Must match streamid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| pingtype || pingtype Indicator for state type: “start” or “end” audit ping & if the ping is for a stream ||
* Startstream = 1
* Startsession=0
* Endstream = 3
* Endsession=2
|| ✓
|-
| product || Indicates which Nielsen product the audit ping corresponds to. || dcr || ✓
|-
| createtm || Time the ping was fired: utc (in seconds) If server time available, use it instead of device time || || ✓
|-
| devid || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

'''Generic Ping Format:'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=<App id>&intid=<Integration ID>&sessionid=<Session Id>&streamid=<Stream Id>&pingtype=<Ping Type>&product=<dcr or dtvr>&createtm=<Session Start or End time>&devid=<Android ADID>'''
</nowiki></code>

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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>

DCR Germany Video S2S

2026-04-07T08:39:20Z

MichelFodjo: /* Description */

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

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

This guide shows you how to integrate the Nielsen S2S (Server to Server) to enable Digital Content Ratings (DCR), and fuel other measurement products on your Apps.

<pre style="color: orange"; font-weight: bold;>
PLease note that you have to use the Staging S2S Endpoint(<env>=stage)until you get the green light to move to Production, you will then get the Production S2S Endpoint!
</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
|-style="background-color:#d0f6f8;"
|| '''Integration ID (IntID)''' || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| Provided by Nielsen
|}

==Introduction==
This interface specification depicts the file format that needs to be used to supply Nielsen with
end-user viewing data captured by a “Server-to-Server” method for the Nielsen Digital Content
Ratings (DCR) product and Tuning data for the Digital Ads Rating (DAR) products.
* The specification is defined using a JSON schema, with each file ideally containing all the
viewing that has been captured within an hour.
* In the case of a stream that has one version with blackouts and one without, one with
mobile and one non-mobile, each stream would have its own unique asset id.
* The Asset Metadata file should arrive before the viewing data file for the same hour.

==SLA==
The files must be delivered into the proper S3 bucket '''immediately after each hour of viewing on a device''', but '''latest within 3 hours of the start of that hourly viewing file interval'''. For example, files from '''2:00 AM to 3:00 AM''' must be delivered latest before '''5 AM'''.

'''When SLA for receiving an exposure file for date xx/xx, UTC hour xx has expired. The system will continue to wait for 60 min, after which it will skip the missing file and continue processing subsequent files. Any reprocessing of the missed SLA data will require an explicit request from AGF.'''

==Accuracy of the Measurement==

====Send Viewing Time (Video Player Events) At Least Each 10 Seconds To Your Backend====
Capture content viewing time each second and send the aggregated viewing time at least each 10 seconds to your backend:
* referencestart : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* referenceend : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* playheadstart : Content position start time in seconds
* playheadend : Content position end time in seconds

====Send Viewing Time When The Video Playback Is Interrupted====
Send the aggregated viewing time to your backend when the video playback is interrupted, i.e. paused.

====Capture Accurately Each Second The Viewing Time When The Network Is Lost And The Video Playback Continues====
Capture accurately each second the viewing time when the network is lost.
Send the aggregated viewing time to your backend when the network is back.

====Send The Viewing Time Early On Browser Refreshed/Closed====
Capture and send the viewing time to your backend by implementing the 2 WINDOWS EVENTS:

''' Please include a logic to make sure that only one of the 2 following event handler is executed '''
<syntaxhighlight lang="javascript">
window.addEventListener("pagehide", function (e) {
// SEND THE VIEWING TIME TO YOUR BACKEND
});
window.addEventListener("beforeunload", function (e) {
// ONLY IF pagehide" was not triggered, SEND THE VIEWING TIME TO YOUR BACKEND
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered at a fixed cadence in a dedicated S3 bucket following the outlined in this spec prefix and object naming conventions and data formats.

* All prefix labels and file names should be lowercase except for app ids.
* Supported formats are:
** Uncompressed text files with utf-8 encoding in:
*** JSON format(.json);
*** PARQUET format(.parquet);
* All files should have extensions to indicate the file format (.json or .parquet)
* Data file can be partitioned into multiple parts with min size of 128MB - 256MB
* Data can be delivered separately in multiple splits(platforms), if needed due to organizational, technical or privacy requirements. This allows to permission s3 access separately, to process data independently and to persist data partitioned, within the limits of the S2S system;

===The 4 Different Files to deliver to Nielsen each hour===
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

Nielsen will move files to indicate they are being processed.

====S3 bucket and prefix(S3BucketPrefix) for all 4 Files====

All files should be delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| env || '''stage''' for Staging or '''prod''' for Production
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| Platform || '''ios''', '''browser''', '''android''', '''ott'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| yyyy/mm/dd/hh || UTC start of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023/02/12/05'''

|}
=====Examples for the iOS platform=====
======Asset Metadata File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====File Name(FileName) format for the Asset Metadata and Asset Viewing Files ====

Asset Metadata and Asset Viewing Files should be delivered to:
* <S3BucketPrefix>'''<FileName>'''

* '''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime><FileSuffix>

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| IntID || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.)
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || Nielsen provided server application identifier
|-
| StartTime || start date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| EndTime || end date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| yyyymmddhh || UTC time of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023021205'''

|-
| FileSuffix || Uncompressed json lines (no extension) - splittable, ideal for medium size files, '''less than 5 GB''', preferred for metadata.
'''supported:'''
* '''.json''' json file
* '''.parquet''' parquet file
|}

=====Examples for Asset Metadata and Asset Viewing Files=====
======Asset Metadata File======
Asset Metadata File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====Manifest File for the Asset Metadata and Asset Viewing Files====

The Manifest File should be delivered to: <S3BucketPrefix>'''<FileName>'''

'''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime>'''_manifest'''

A manifest contains metadata related to the uploaded file(s). It is a text file in json format that implements the AWS unload manifest file format. It follows the s3 objects naming notation, but has the _manifest suffix. Here’s an example of manifest file contents:

{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}

The manifest contains a complete list of all files provided for a given period and platform, as well as a meta data (a.k.a. header) which should include the following attributes:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, i.e. "S2SV1.7.0" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| record_count || Records Count in data file || Number: i.e. 55 || ✓
|}

If ‘entries’ array is not specified, or manifest file is not available, the system will still attempt to load all data file(s) (.json or .parquet) from the prefix location. Optionally the manifest file can contain the full schema of the data files as shown in the [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose manifest file format document ].

=====Example for the Manifest File=====

======Manifest File for the Asset Metadata File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======Manifest File for the Asset Viewing File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

===Success File: Indication of a data delivery for a particular hour===

An Empty _SUCCESS file should be provided to indicate that data delivery for a particular hour and platform is completed successfully. This file should be uploaded last (after all other files). If there is no data data for a particular hour and platform, the _SUCCESS file is still required to indicate that the delivery process for the hour is completed and no data files are expected. This file is only required for integrations that support data partitioned into multiple parts. The name of the file is configurable.

====Example for Asset Viewing Delivery Files====

'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

====Example for Asset Metadata Delivery Files====
'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

====Data Delivery Example for hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):====
=====Asset Metadata Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

</code>
=====Asset Viewing Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0000.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0001.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0002.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0003.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

</code>

===Asset Metadata Delivery Optimization===

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day(00:00:00 AM UTC to 00:59:59 PM UTC) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 11 , referencing to the Asset Metadata File for HOUR 00'''

=====Asset Metadata File for the hour 11:00:00 AM UTC to 11:59:59 PM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 00):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS
</code>

=====Asset Metadata File for the hour 00:00:00 AM UTC to 00:59:59 PM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653436800",
"end_time": "1653440399",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day(00:00:00 AM UTC to 00:59:59 PM UTC) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 11 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 11:00:00 AM UTC to 11:59:59 PM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 00:00:00 AM UTC to 00:59:59 PM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653436800",
"end_time": "1653440399",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/_SUCCESS
</code>

== S2S Metadata Specifications for the Asset Metadata and Asset Viewing Files ==

=== Asset Metadata File ===

The Asset Metadata File contains 1 Header Record followed by Body Records

====Header Record====

=====Description=====

'''Parameter Description'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.09" || ✓
|-
| mvpdid || mvpd ID specified ny Nielsen || String, i.e. "NLSN" || ✓
|-
| creationtime || File creation time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓

|-
| recordcount || Records Count in body of file ||String, i.e. "1" for only 1 Record || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.09",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| Unique ID assigned to the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c10) separated by an underscore character ('''<c7_c10>''').
||
* custom (no [[Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || 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)|| ✓
|-
|islivestn || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Sendungsteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || 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 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || not in use || leave blank "", reserved for AGF ||
|-style="background-color:#d0f6f8;"
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || not in use || leave blank "", reserved for AGF ||
|-style="background-color:#d0f6f8;"
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== Asset Viewing File ===

The Asset Viewing File contains 1 Header Record followed by Body Records
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.0" || ✓
|-
| appid || Nielsen provided server application identifier || String, i.e. "P47C2495B-XXXX-56DE-BE99-14758F92F034" || ✓
|-
| type || Type of the data || String, "content" || ✓
|-
| producttype || Product Type || String, "DCR" || ✓
|-
| starttime || Viewing Data Start Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓
|-
| endtime || Viewing Data End Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473791507"|| ✓
|-
| recordcount || Records Count in body of file || String, i.e. "100" for only 100 Records || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.0",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apn || app name || i.e. "BestAppIOS" || ✓
|-
| apv || app build version || i.e. "1.3" || ✓
|-
| sessionid || Unique, client generated value that represents the start of a user session. Must match sessionid in Audit Ping. || created using the UUID Generator code provided || ✓
|-
| streamid || streamid ID for every new instance of an asset || created using the UUID Generator code provided || ✓
|-
| streamended || Stream is known to have ended in this file ||
* "1" (stream will continue in next file)
* "2" (stream closed)
|| ✓
|-
| secondscr || Second Screen Indicator. For Mirroring & Extended Screen via OTT device scenarios ||
* "" (empty String if viewed directly on the device)
* "MIR" (Mirroring)
* "OTT" (Extended Screen via OTT device)
|| ✓
|-
| assetid || unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''Description:'''
* '''referencestart''' : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* '''referenceend''' : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* '''playheadstart''' : Content position start time in seconds
* '''playheadend''' : Content position end time in seconds

'''For Content position start and end time(playheadstart, playheadend):'''
* For VoD stream use the player position for Content as the playhead position in seconds. At playback start of a content from the begin, playheads will then be 0,1,2,3,....
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position in seconds.

'''Additional Notes:'''
* For viewing gaps < than 1 second, the gap can be smoothed over
* For playouts that are abandoned before the first whole second of viewing is rendered, a position record of zero duration should be created. IF an audit ping has already been fired See below for additional details on position array parameters
|| ✓
|-
| device_id || '''ONLY for''' '''android''' platform, DO NOT pass device_id for '''ios''', '''browser''' and '''ott''' platforms. Mobile Ad ID , 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" - OPTIONAL if passed in the Audit Ping|| i.e "12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8" || ✓
|-
| xdua || Device HTTP raw User Agent string - OPTIONAL if passed in the Audit Ping|| Example: "Apple-iPhone1C2/801.293" || ✓
|-
| xff || IP address - OPTIONAL if passed in the Audit Ping|| Format: "xxx.xxx.xxx.xxx" or "xxx.xxx.xxx.000"
Examples :
* IPV4: "4.12.345.67"
* IPV6: "2600:6c58:7900:33f2:2505:42b9:5a34:0000"
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // create and pass a unique streamid for each video play using UUID Generator code provided
"streamended": "1",
"assetid": "VA12345",
"secondscr": "MIR",
"position": [
{
"referencestart": "1628735452",
"referenceend": "1628736052",
"playheadstart": "0",
"playheadend": "600"
}
],
"xdua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130Safari/537.36",
"xff": "4.12.345.67"
}

</syntaxhighlight>

===== Android Platform : Example Metadata with "device_id" =====

====== "device_id" available ======
<syntaxhighlight lang="javascript">
{
"device_id": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826"
}
</syntaxhighlight>

====== "device_id" not available ======
<syntaxhighlight lang="javascript">
{
"device_id": ""
}
</syntaxhighlight>

==OTT, Mirroring, and Casting==

For apps native to the OTT device (i.e. downloading and viewing a streaming app to an Apple
TV, audit ping should fire from OTT device, and Viewing data should reside in OTT Viewing file.
For mirroring, where video playback occurs on the mobile device and OTT device, only one
Viewing file row is necessary where, if possible to determine, set: "secondscr":"MIR" and
include in respective mobile platform Viewing file.

For a casting scenario where content is controlled via the mobile device, but displayed only on
the OTT device such as an AppleTV or Chromecast, an audit ping must fire from the mobile
device before the casting occurs and at the end of playback from the mobile device only.
Viewing data resides in the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx123",
"referenceend": "xxxxxxx183",
'''"playheadstart": "0",'''
'''"playheadend": "60"'''
},
{
"referencestart": "xxxxxxx243",
"referenceend": "xxxxxxx303",
'''"playheadstart": "120",'''
'''"playheadend": "180"'''
}
]
}

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx183",
"referenceend": "xxxxxxx243",
'''"playheadstart": "60",'''
'''"playheadend": "120"'''
}
],
'''"secondscr": "OTT"'''
}

==S2S Audit Ping Specifications==

=== Introduction ===
The Nielsen server to server solution needs audit pings to validate audience reach and video viewing duration, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.

'''start audit ping(“Startstream = 1”)'''
* A start audit ping is sent when the stream starts(playback start).
* Also a new start audit ping is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
'''end audit ping(“Endstream = 3”)'''
* An end audit ping is sent when the stream ends(either playback completed or switch to another stream).
* Also an end audit ping is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.

=== Ping Structure ===
Ping should be named with following convention structure:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(Please note that this URL could change as we respond to security upgrades in the market.)
The Start Audit Ping will carry all parameters in the matrix below. The End Audit Ping will carry a subset of the parameters in the matrix below as denoted in the mandatory column.
Under normal operating circumstances, the Nielsen collection system will return return codes:
* For security reasons, downstream servers reject cross-origin HTTP requests with preflight. To ensure that audit ping requests are accepted, allowable Content-Types like "text/plain" in simple GET requests ensure that preflight requests are not invoked, which is the preferred behavior.
* 200: The ping was successfully received, inspect traffic to ensure no CORS errors

=== Ping Session & Stream Details ===

==== Sessions ====
* a) When a new player is created a session id is also created.
* b) If you have more than one video player within the same App (e.g. picture in picture) you must use a different session id for each.

==== Streams ====
* a) The Distributor must generate a new UNIQUE stream id with every video stream playback.
* b) If two people watch the same show, they would have different stream id's as Nielsen would expect the stream id(“streamid”) to be a random GUId generated by the client device.
* c) If one person watches a show, and FF, rewind, playout, pause, play, RW, play - they would keep the same stream id(“streamid”) throughout the entire playout of that video asset (stream).
* d) If a stream play out is suspended for 30 mins or more (paused or background):
** An end audit ping(“Endstream = 3”) is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.
** A new start audit ping(“Startstream = 1”) is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
* e) If the user reaches the very end of the stream (content complete), and then starts to play again (replay from anywhere in the stream), then a new “streamid” should be created and a start audit ping should be sent. Also an end audit should be sent when the stream replay is completed or the user switches to another stream.

====Audit Pings ====
* a) Audit pings should be fired at the '''beginning''' and '''end''' of a stream. These will be referred to as the Audit Start Ping and the Audit End Ping.

==== query param list ====

Example:

'''Required S2S Audit Ping Query String Parameters - Note: All parameters are case sensitive'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || Unique ID assigned to the player/site and configured by your Nielsen Technical Account Manager.
|| Example: '''FC984EC1-E044-B465-E040-070AAD3173A1''' || ✓
|-
| intid || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || || ✓
|-
| sessionid || Unique, client-generated value that represents the start of a user browsing session. Must match sessionid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| streamid || Unique Id for every new instance of a client video asset playout. Must match streamid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| pingtype || pingtype Indicator for state type: “start” or “end” audit ping & if the ping is for a stream ||
* Startstream = 1
* Startsession=0
* Endstream = 3
* Endsession=2
|| ✓
|-
| product || Indicates which Nielsen product the audit ping corresponds to. || dcr || ✓
|-
| createtm || Time the ping was fired: utc (in seconds) If server time available, use it instead of device time || || ✓
|-
| devid || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

'''Generic Ping Format:'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=<App id>&intid=<Integration ID>&sessionid=<Session Id>&streamid=<Stream Id>&pingtype=<Ping Type>&product=<dcr or dtvr>&createtm=<Session Start or End time>&devid=<Android ADID>'''
</nowiki></code>

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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>

DCR Germany Video Cloud API

2026-04-07T08:37:59Z

MichelFodjo: /* Description of Ad metadata */

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

= DCR Integration Utilizing Cloud API =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a Cloud API Integration!
</pre>
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"; font-weight: bold;>
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 ====
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,",
"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,",
"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.

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c10) separated by an underscore character ('''<c7_c10>''').
||
* custom (no [[Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| 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) || ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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 || custom variable || custom ||
|-
| nol_c14 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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.

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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 the Ad asset corresponding to the AGF custom variable '''c11'''.
||
* custom (no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters])
* Preroll: <c11>
* Midroll: <c11>
* Postroll: <c11>
|| ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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 current video asset playback is terminated or completed,
* at the end of the current stream playback when the user switches to another piece of content or when the App is closed.
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 Germany Video Cloud API

2026-04-07T08:37:21Z

MichelFodjo: /* Description of Content metadata */

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

= DCR Integration Utilizing Cloud API =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a Cloud API Integration!
</pre>
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"; font-weight: bold;>
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 ====
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,",
"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,",
"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.

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c10) separated by an underscore character ('''<c7_c10>''').
||
* custom (no [[Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| 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) || ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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 || custom variable || custom ||
|-
| nol_c14 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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.

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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])
* Preroll: <c11>
* Midroll: <c11>
* Postroll: <c11>
|| ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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 current video asset playback is terminated or completed,
* at the end of the current stream playback when the user switches to another piece of content or when the App is closed.
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 Germany Video App SDK

2026-04-07T08:30:05Z

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

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

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c10) separated by an underscore character ('''<c7_c10>''').
||
* custom (no [[Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| 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) || ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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 || custom variable || custom ||
|-
| nol_c14 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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,",
@"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,")
.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.

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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 the Ad asset corresponding to the AGF custom variable '''c11'''.
||
* custom (no [https://engineeringportal.nielsen.com/docs/Special_Characters Special Characters])
* Preroll: <c11>
* Midroll: <c11>
* Postroll: <c11>
|| ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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,",
@"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,")
.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 App SDK

2026-04-07T08:29:08Z

MichelFodjo: /* Description of Content 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 ===

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

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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 the video asset corresponding to the combination of the 2 AGF custom variables (c7 and c10) separated by an underscore character ('''<c7_c10>''').
||
* custom (no [[Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| 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) || ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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 || custom variable || custom ||
|-
| nol_c14 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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,",
@"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,")
.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.

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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])
* Preroll: <c11>
* Midroll: <c11>
* Postroll: <c11>
|| ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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,",
@"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,")
.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

2026-04-07T08:00:42Z

MichelFodjo: /* Description of Content metadata */

DCR Germany Video Browser SDK

2026-04-07T07:59:24Z

MichelFodjo: /* Description of Ad metadata */

DCR Germany Video S2S

2026-04-02T11:54:35Z

MichelFodjo: /* Description */

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

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

This guide shows you how to integrate the Nielsen S2S (Server to Server) to enable Digital Content Ratings (DCR), and fuel other measurement products on your Apps.

<pre style="color: orange"; font-weight: bold;>
PLease note that you have to use the Staging S2S Endpoint(<env>=stage)until you get the green light to move to Production, you will then get the Production S2S Endpoint!
</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
|-style="background-color:#d0f6f8;"
|| '''Integration ID (IntID)''' || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| Provided by Nielsen
|}

==Introduction==
This interface specification depicts the file format that needs to be used to supply Nielsen with
end-user viewing data captured by a “Server-to-Server” method for the Nielsen Digital Content
Ratings (DCR) product and Tuning data for the Digital Ads Rating (DAR) products.
* The specification is defined using a JSON schema, with each file ideally containing all the
viewing that has been captured within an hour.
* In the case of a stream that has one version with blackouts and one without, one with
mobile and one non-mobile, each stream would have its own unique asset id.
* The Asset Metadata file should arrive before the viewing data file for the same hour.

==SLA==
The files must be delivered into the proper S3 bucket '''immediately after each hour of viewing on a device''', but '''latest within 3 hours of the start of that hourly viewing file interval'''. For example, files from '''2:00 AM to 3:00 AM''' must be delivered latest before '''5 AM'''.

'''When SLA for receiving an exposure file for date xx/xx, UTC hour xx has expired. The system will continue to wait for 60 min, after which it will skip the missing file and continue processing subsequent files. Any reprocessing of the missed SLA data will require an explicit request from AGF.'''

==Accuracy of the Measurement==

====Send Viewing Time (Video Player Events) At Least Each 10 Seconds To Your Backend====
Capture content viewing time each second and send the aggregated viewing time at least each 10 seconds to your backend:
* referencestart : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* referenceend : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* playheadstart : Content position start time in seconds
* playheadend : Content position end time in seconds

====Send Viewing Time When The Video Playback Is Interrupted====
Send the aggregated viewing time to your backend when the video playback is interrupted, i.e. paused.

====Capture Accurately Each Second The Viewing Time When The Network Is Lost And The Video Playback Continues====
Capture accurately each second the viewing time when the network is lost.
Send the aggregated viewing time to your backend when the network is back.

====Send The Viewing Time Early On Browser Refreshed/Closed====
Capture and send the viewing time to your backend by implementing the 2 WINDOWS EVENTS:

''' Please include a logic to make sure that only one of the 2 following event handler is executed '''
<syntaxhighlight lang="javascript">
window.addEventListener("pagehide", function (e) {
// SEND THE VIEWING TIME TO YOUR BACKEND
});
window.addEventListener("beforeunload", function (e) {
// ONLY IF pagehide" was not triggered, SEND THE VIEWING TIME TO YOUR BACKEND
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered at a fixed cadence in a dedicated S3 bucket following the outlined in this spec prefix and object naming conventions and data formats.

* All prefix labels and file names should be lowercase except for app ids.
* Supported formats are:
** Uncompressed text files with utf-8 encoding in:
*** JSON format(.json);
*** PARQUET format(.parquet);
* All files should have extensions to indicate the file format (.json or .parquet)
* Data file can be partitioned into multiple parts with min size of 128MB - 256MB
* Data can be delivered separately in multiple splits(platforms), if needed due to organizational, technical or privacy requirements. This allows to permission s3 access separately, to process data independently and to persist data partitioned, within the limits of the S2S system;

===The 4 Different Files to deliver to Nielsen each hour===
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

Nielsen will move files to indicate they are being processed.

====S3 bucket and prefix(S3BucketPrefix) for all 4 Files====

All files should be delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| env || '''stage''' for Staging or '''prod''' for Production
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| Platform || '''ios''', '''browser''', '''android''', '''ott'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| yyyy/mm/dd/hh || UTC start of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023/02/12/05'''

|}
=====Examples for the iOS platform=====
======Asset Metadata File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====File Name(FileName) format for the Asset Metadata and Asset Viewing Files ====

Asset Metadata and Asset Viewing Files should be delivered to:
* <S3BucketPrefix>'''<FileName>'''

* '''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime><FileSuffix>

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| IntID || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.)
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || Nielsen provided server application identifier
|-
| StartTime || start date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| EndTime || end date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| yyyymmddhh || UTC time of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023021205'''

|-
| FileSuffix || Uncompressed json lines (no extension) - splittable, ideal for medium size files, '''less than 5 GB''', preferred for metadata.
'''supported:'''
* '''.json''' json file
* '''.parquet''' parquet file
|}

=====Examples for Asset Metadata and Asset Viewing Files=====
======Asset Metadata File======
Asset Metadata File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====Manifest File for the Asset Metadata and Asset Viewing Files====

The Manifest File should be delivered to: <S3BucketPrefix>'''<FileName>'''

'''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime>'''_manifest'''

A manifest contains metadata related to the uploaded file(s). It is a text file in json format that implements the AWS unload manifest file format. It follows the s3 objects naming notation, but has the _manifest suffix. Here’s an example of manifest file contents:

{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}

The manifest contains a complete list of all files provided for a given period and platform, as well as a meta data (a.k.a. header) which should include the following attributes:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, i.e. "S2SV1.7.0" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| record_count || Records Count in data file || Number: i.e. 55 || ✓
|}

If ‘entries’ array is not specified, or manifest file is not available, the system will still attempt to load all data file(s) (.json or .parquet) from the prefix location. Optionally the manifest file can contain the full schema of the data files as shown in the [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose manifest file format document ].

=====Example for the Manifest File=====

======Manifest File for the Asset Metadata File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======Manifest File for the Asset Viewing File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

===Success File: Indication of a data delivery for a particular hour===

An Empty _SUCCESS file should be provided to indicate that data delivery for a particular hour and platform is completed successfully. This file should be uploaded last (after all other files). If there is no data data for a particular hour and platform, the _SUCCESS file is still required to indicate that the delivery process for the hour is completed and no data files are expected. This file is only required for integrations that support data partitioned into multiple parts. The name of the file is configurable.

====Example for Asset Viewing Delivery Files====

'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

====Example for Asset Metadata Delivery Files====
'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

====Data Delivery Example for hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):====
=====Asset Metadata Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

</code>
=====Asset Viewing Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0000.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0001.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0002.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0003.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

</code>

===Asset Metadata Delivery Optimization===

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day(00:00:00 AM UTC to 00:59:59 PM UTC) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 11 , referencing to the Asset Metadata File for HOUR 00'''

=====Asset Metadata File for the hour 11:00:00 AM UTC to 11:59:59 PM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 00):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS
</code>

=====Asset Metadata File for the hour 00:00:00 AM UTC to 00:59:59 PM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653436800",
"end_time": "1653440399",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day(00:00:00 AM UTC to 00:59:59 PM UTC) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 11 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 11:00:00 AM UTC to 11:59:59 PM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 00:00:00 AM UTC to 00:59:59 PM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653436800",
"end_time": "1653440399",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/_SUCCESS
</code>

== S2S Metadata Specifications for the Asset Metadata and Asset Viewing Files ==

=== Asset Metadata File ===

The Asset Metadata File contains 1 Header Record followed by Body Records

====Header Record====

=====Description=====

'''Parameter Description'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.09" || ✓
|-
| mvpdid || mvpd ID specified ny Nielsen || String, i.e. "NLSN" || ✓
|-
| creationtime || File creation time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓

|-
| recordcount || Records Count in body of file ||String, i.e. "1" for only 1 Record || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.09",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| unique ID assigned to asset
||
* custom (no [[Special Characters]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || 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)|| ✓
|-
|islivestn || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Sendungsteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || 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 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || not in use || leave blank "", reserved for AGF ||
|-style="background-color:#d0f6f8;"
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || not in use || leave blank "", reserved for AGF ||
|-style="background-color:#d0f6f8;"
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== Asset Viewing File ===

The Asset Viewing File contains 1 Header Record followed by Body Records
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.0" || ✓
|-
| appid || Nielsen provided server application identifier || String, i.e. "P47C2495B-XXXX-56DE-BE99-14758F92F034" || ✓
|-
| type || Type of the data || String, "content" || ✓
|-
| producttype || Product Type || String, "DCR" || ✓
|-
| starttime || Viewing Data Start Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓
|-
| endtime || Viewing Data End Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473791507"|| ✓
|-
| recordcount || Records Count in body of file || String, i.e. "100" for only 100 Records || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.0",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apn || app name || i.e. "BestAppIOS" || ✓
|-
| apv || app build version || i.e. "1.3" || ✓
|-
| sessionid || Unique, client generated value that represents the start of a user session. Must match sessionid in Audit Ping. || created using the UUID Generator code provided || ✓
|-
| streamid || streamid ID for every new instance of an asset || created using the UUID Generator code provided || ✓
|-
| streamended || Stream is known to have ended in this file ||
* "1" (stream will continue in next file)
* "2" (stream closed)
|| ✓
|-
| secondscr || Second Screen Indicator. For Mirroring & Extended Screen via OTT device scenarios ||
* "" (empty String if viewed directly on the device)
* "MIR" (Mirroring)
* "OTT" (Extended Screen via OTT device)
|| ✓
|-
| assetid || unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''Description:'''
* '''referencestart''' : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* '''referenceend''' : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* '''playheadstart''' : Content position start time in seconds
* '''playheadend''' : Content position end time in seconds

'''For Content position start and end time(playheadstart, playheadend):'''
* For VoD stream use the player position for Content as the playhead position in seconds. At playback start of a content from the begin, playheads will then be 0,1,2,3,....
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position in seconds.

'''Additional Notes:'''
* For viewing gaps < than 1 second, the gap can be smoothed over
* For playouts that are abandoned before the first whole second of viewing is rendered, a position record of zero duration should be created. IF an audit ping has already been fired See below for additional details on position array parameters
|| ✓
|-
| device_id || '''ONLY for''' '''android''' platform, DO NOT pass device_id for '''ios''', '''browser''' and '''ott''' platforms. Mobile Ad ID , 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" - OPTIONAL if passed in the Audit Ping|| i.e "12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8" || ✓
|-
| xdua || Device HTTP raw User Agent string - OPTIONAL if passed in the Audit Ping|| Example: "Apple-iPhone1C2/801.293" || ✓
|-
| xff || IP address - OPTIONAL if passed in the Audit Ping|| Format: "xxx.xxx.xxx.xxx" or "xxx.xxx.xxx.000"
Examples :
* IPV4: "4.12.345.67"
* IPV6: "2600:6c58:7900:33f2:2505:42b9:5a34:0000"
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // create and pass a unique streamid for each video play using UUID Generator code provided
"streamended": "1",
"assetid": "VA12345",
"secondscr": "MIR",
"position": [
{
"referencestart": "1628735452",
"referenceend": "1628736052",
"playheadstart": "0",
"playheadend": "600"
}
],
"xdua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130Safari/537.36",
"xff": "4.12.345.67"
}

</syntaxhighlight>

===== Android Platform : Example Metadata with "device_id" =====

====== "device_id" available ======
<syntaxhighlight lang="javascript">
{
"device_id": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826"
}
</syntaxhighlight>

====== "device_id" not available ======
<syntaxhighlight lang="javascript">
{
"device_id": ""
}
</syntaxhighlight>

==OTT, Mirroring, and Casting==

For apps native to the OTT device (i.e. downloading and viewing a streaming app to an Apple
TV, audit ping should fire from OTT device, and Viewing data should reside in OTT Viewing file.
For mirroring, where video playback occurs on the mobile device and OTT device, only one
Viewing file row is necessary where, if possible to determine, set: "secondscr":"MIR" and
include in respective mobile platform Viewing file.

For a casting scenario where content is controlled via the mobile device, but displayed only on
the OTT device such as an AppleTV or Chromecast, an audit ping must fire from the mobile
device before the casting occurs and at the end of playback from the mobile device only.
Viewing data resides in the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx123",
"referenceend": "xxxxxxx183",
'''"playheadstart": "0",'''
'''"playheadend": "60"'''
},
{
"referencestart": "xxxxxxx243",
"referenceend": "xxxxxxx303",
'''"playheadstart": "120",'''
'''"playheadend": "180"'''
}
]
}

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx183",
"referenceend": "xxxxxxx243",
'''"playheadstart": "60",'''
'''"playheadend": "120"'''
}
],
'''"secondscr": "OTT"'''
}

==S2S Audit Ping Specifications==

=== Introduction ===
The Nielsen server to server solution needs audit pings to validate audience reach and video viewing duration, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.

'''start audit ping(“Startstream = 1”)'''
* A start audit ping is sent when the stream starts(playback start).
* Also a new start audit ping is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
'''end audit ping(“Endstream = 3”)'''
* An end audit ping is sent when the stream ends(either playback completed or switch to another stream).
* Also an end audit ping is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.

=== Ping Structure ===
Ping should be named with following convention structure:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(Please note that this URL could change as we respond to security upgrades in the market.)
The Start Audit Ping will carry all parameters in the matrix below. The End Audit Ping will carry a subset of the parameters in the matrix below as denoted in the mandatory column.
Under normal operating circumstances, the Nielsen collection system will return return codes:
* For security reasons, downstream servers reject cross-origin HTTP requests with preflight. To ensure that audit ping requests are accepted, allowable Content-Types like "text/plain" in simple GET requests ensure that preflight requests are not invoked, which is the preferred behavior.
* 200: The ping was successfully received, inspect traffic to ensure no CORS errors

=== Ping Session & Stream Details ===

==== Sessions ====
* a) When a new player is created a session id is also created.
* b) If you have more than one video player within the same App (e.g. picture in picture) you must use a different session id for each.

==== Streams ====
* a) The Distributor must generate a new UNIQUE stream id with every video stream playback.
* b) If two people watch the same show, they would have different stream id's as Nielsen would expect the stream id(“streamid”) to be a random GUId generated by the client device.
* c) If one person watches a show, and FF, rewind, playout, pause, play, RW, play - they would keep the same stream id(“streamid”) throughout the entire playout of that video asset (stream).
* d) If a stream play out is suspended for 30 mins or more (paused or background):
** An end audit ping(“Endstream = 3”) is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.
** A new start audit ping(“Startstream = 1”) is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
* e) If the user reaches the very end of the stream (content complete), and then starts to play again (replay from anywhere in the stream), then a new “streamid” should be created and a start audit ping should be sent. Also an end audit should be sent when the stream replay is completed or the user switches to another stream.

====Audit Pings ====
* a) Audit pings should be fired at the '''beginning''' and '''end''' of a stream. These will be referred to as the Audit Start Ping and the Audit End Ping.

==== query param list ====

Example:

'''Required S2S Audit Ping Query String Parameters - Note: All parameters are case sensitive'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || Unique ID assigned to the player/site and configured by your Nielsen Technical Account Manager.
|| Example: '''FC984EC1-E044-B465-E040-070AAD3173A1''' || ✓
|-
| intid || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || || ✓
|-
| sessionid || Unique, client-generated value that represents the start of a user browsing session. Must match sessionid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| streamid || Unique Id for every new instance of a client video asset playout. Must match streamid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| pingtype || pingtype Indicator for state type: “start” or “end” audit ping & if the ping is for a stream ||
* Startstream = 1
* Startsession=0
* Endstream = 3
* Endsession=2
|| ✓
|-
| product || Indicates which Nielsen product the audit ping corresponds to. || dcr || ✓
|-
| createtm || Time the ping was fired: utc (in seconds) If server time available, use it instead of device time || || ✓
|-
| devid || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

'''Generic Ping Format:'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=<App id>&intid=<Integration ID>&sessionid=<Session Id>&streamid=<Stream Id>&pingtype=<Ping Type>&product=<dcr or dtvr>&createtm=<Session Start or End time>&devid=<Android ADID>'''
</nowiki></code>

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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>

DCR Germany Video Cloud API

2026-04-02T11:51:35Z

MichelFodjo: /* Description of Content metadata */

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

= DCR Integration Utilizing Cloud API =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a Cloud API Integration!
</pre>
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"; font-weight: bold;>
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 ====
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,",
"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,",
"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.

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| 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) || ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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 || custom variable || custom ||
|-
| nol_c14 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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.

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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])
* Preroll: <c11>
* Midroll: <c11>
* Postroll: <c11>
|| ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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 current video asset playback is terminated or completed,
* at the end of the current stream playback when the user switches to another piece of content or when the App is closed.
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 Germany Video Cloud API

2026-04-02T11:50:45Z

MichelFodjo: /* Description of Ad metadata */

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

= DCR Integration Utilizing Cloud API =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a Cloud API Integration!
</pre>
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"; font-weight: bold;>
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 ====
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,",
"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,",
"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.

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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) || ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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 || custom variable || custom ||
|-
| nol_c14 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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.

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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])
* Preroll: <c11>
* Midroll: <c11>
* Postroll: <c11>
|| ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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 current video asset playback is terminated or completed,
* at the end of the current stream playback when the user switches to another piece of content or when the App is closed.
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 Germany Video App SDK

2026-04-02T11:49:58Z

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

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

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| 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) || ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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 || custom variable || custom ||
|-
| nol_c14 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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,",
@"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,")
.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.

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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])
* Preroll: <c11>
* Midroll: <c11>
* Postroll: <c11>
|| ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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,",
@"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,")
.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 App SDK

2026-04-02T11:48:49Z

MichelFodjo: /* Description of Content 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 ===

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

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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]])
* 24/7 livestream: <c7_c0>
* Event livestream: <c7_c0>
* Video on demand: <c7_c0>
* Trailer: <c7_c0>
|| ✓
|-
| 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) || ✓
|-
| 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") || ✓
|-
| nol_c5 || page URL || custom ||
|-
| nol_c7 || Video ID || custom || ✓
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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 || custom variable || custom ||
|-
| nol_c14 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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,",
@"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,")
.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.

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, 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 || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N") ||
|-
| nol_c4 || form of advertising || 'preroll','midroll', 'postroll', 'pre-split', 'sponsor' ||
|-
| nol_c8 || not in use || leave blank, reserved for AGF ||
|-
| 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,",
"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,",
@"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,")
.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

2026-04-02T11:44:00Z

MichelFodjo: /* Description of Ad metadata */

DCR Germany Video Browser SDK

2026-04-02T11:42:19Z

MichelFodjo: /* Description of Content metadata */

DCR Sweden Domless SDK

2026-03-18T10:54:50Z

MichelFodjo: /* Setting the SDK global optout Flag for Opt-out Users during the SDK Initialization */

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

==License==
Nielsen SDK contains material that is protected by copyright laws, patent laws, trade secret laws, and by international treaty provisions and is Copyright © 2025 The Nielsen Company (US) LLC. All intellectual property rights and licenses therein are reserved by The Nielsen Company (US) LLC and its licensors. Please read the license agreement presented [https://engineeringportal.nielsen.com/wiki/Special:ClickThrough here], which must be accepted in order to download the Nielsen SDKs. For more information, reach out to your Nielsen Technical Account Manager(TAM).

== Overview ==

The Nielsen DOM-less SDK is a Javascript based cross-platform library that provides APIs that allows our clients to integrate the Nielsen SDK in DOM-less environments, e.g. ReactNative, NodeJS, etc. The new Amazon Vega/Kepler OS was certified by Nielsen for the DOM-less SDK Integration.

The Nielsen DOM-less SDK can be used for '''Video''' and '''Static''' measurements.

The Digital Content Ratings (DCR) Video product provides content consumption measurement on client mobile apps or webpages. This measurement includes insight into the total time a user spent watching the tracked content, video player events, and much more. This guide also includes a link to [[#Sample DOM-less SDK Implementation| github sample implementation]] with steps to implement the DCR Video product in a sample NodeJS app. It includes:
* DOM-less SDK Initialization
* DCR Video Metadata: information about the content being tracked
* DCR Video Events/API calls

==DOM-less SDK Initialization==

===Obtain the Nielsen Application ID (apid)===
The Nielsen <code>apid</code> is required to enable SDK functionality. A Technical Account Manager(TAM) will provide an apid for each player configuration.DOM-less SDK can support URLs that use any of the protocols – HTTPS and HTTP.

===Configure the DOM-less SDK===

====Installation====
Install with <code>npm install <nowiki>https://github.com/NielsenDigitalSDK/bsdk-domless</nowiki></code>
 and import the <code>BsdkInstance</code> into video player component <code> import { BsdkInstance } from 'bsdk-domless' </code>

======status.ok()======

Initialization of the instance can be done with <code>status.ok()</code> function or use Promise handling approach

<syntaxhighlight lang="javascript">
const instance = await new BsdkInstance(appID, instanceName, instanceMetadata, implementationHooks);
if (instance && instance.status.ok()) {
expect(instance).not.toBe(undefined);
expect(instance.status.ok()).toBe(true);
}
</syntaxhighlight>

Note: Implementation Hooks are mandatory for the DOM-less SDK instance. Please refer to the Implementation Hooks section below for details.

====Exposed Interface====
The exposed interface is as follows:

1. <code>`ggPM`</code> - method to send messages to the Nielsen SDK

2. <code>`processEvent`</code> - method to send app state to the Nielsen SDK, e.g., focus, blur, appclose

===Initialization Global Parameters===
{| class="wikitable"
|+
!'''Parameter'''
!'''Description'''
!'''Required'''
!'''Value'''
|-
|apid
|UniqueID assigned to player/site.
|Yes
|'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
|instanceName
|Name of SDK instance
|Yes
|"any string value"
|-
|domlessEnv
|Type of DOM-less environment like ReactNative, Node, etc.
|Yes
|"domlessEnv": "1", // For ReactNative
"domlessEnv": "2", // For Amazon

"domlessEnv": "3", // For NodeJS

“domlessEnv”: “4”, // For Custom
|-
|hem_unknown || Hashed email using SHA512. This email is used by the MMS reach model.|| Required if login feature || <syntaxhighlight lang="javascript">
{hem_unknown: "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..."}
</syntaxhighlight>
|-
|optout
|OptOut global parameter. This optout will be maintained through the session of the SDK instance
|Yes
|"true" for opted out, "false" for NOT opted out or opted in. The default value is "false".
|-
|enableFpid
|Optional:turn on or off the First Party ID
|No
|"true" for turn on, "false" for turn off. The default value is "true".
|-
|nol_sdkDebug
|Enables Nielsen console logging. Only required for testing
|No
|"{nol_sdkDebug: "debug"}"
|-
|}

=== Implementation Hooks ===
This object captures the required entities for the DOM-less SDK to operate correctly. These are normally platform dependent and are expected to be passed on to the DOM-less SDK as part of its initialization. See below for the descriptions of each key.

==== '''log''' ====
Log the DOM-less SDK messages to an external stream, e.g. the browser console, stdout.

e.g. Log.debug('debug', 'NIELSEN TAGS EXPECTED TO FIRE:')

===== Methods =====
<blockquote>info()

Log.info(label: string, ...message: string[]): void

debug()

Log.debug(label: string, ...message: string[]): void

warn()

Log.warn(label: string, ...message: string[]): void

error()

Log.error(label: string, ...message: string[]): void</blockquote>

===== Parameters =====
<blockquote>label Required

● string - severity type, e.g. info, debug, warn, error or custom label

message Required

● string - message that will be output to the console</blockquote>

==== storage ====
Persistent storage of key/values, similar in behavior to browser localStorage.

e.g. storage.set('nol_lsid', 'umy3w4ik9usw2ppqmw2vkecckxfob1697308388')

===== Methods =====
<blockquote>set()

storage.set(key: string, value: string)

get()

storage.get(key: string)

remove()

storage.remove(key: string)

clear()

storage.clear()</blockquote>

==== fetch ====
Function to fetch resources from the network. Required for the transmission of the DOM-less SDK requests (pings) to the Nielsen endpoints.

e.g. Fetch(resource: string, options: object)

===== Parameters =====
<blockquote>resource Required

● A string that provides the URL of the resource to fetch

options Optional Object containing settings to apply to the request:

method

● string - request method: "GET", "POST". If one is not provided SDK will default to "GET"

headers

● object - headers to add to the outgoing request, an object literal with String values

body

● string - body to add to the request; SDK will send out string

mode

● string - mode for request: cors, no-cors, same-origin

referrer

● string - a string specifying the referrer of the request</blockquote>

====='''''<pre style="color: green; font-weight: bold; font-size: 20px">Note: Implementation Hooks are mandatory for the DOM-less SDK to function as expected.</pre>'''''=====

== DOM-less SDK API to send app state to the Nielsen SDK, e.g., focus, blur, appclose==

The method for calling events is <code>processEvent()</code>.

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

* <code>`blur`</code> - This event should be passed to processEvent when the app goes to the background.

<syntaxhighlight lang="javascript">
instance.processEvent({ type: 'blur', timestamp: Date.now() });
</syntaxhighlight>

* <code>`focus`</code> - This event should be passed to processEvent when the app goes to the foreground.

<syntaxhighlight lang="javascript">
instance.processEvent({ type: 'focus', timestamp: Date.now() });
</syntaxhighlight>

* <code>`appclose`</code> - This event should be passed prior to closing the app.

<syntaxhighlight lang="javascript">
instance.processEvent({ type: 'appclose', timestamp: Date.now() });
</syntaxhighlight>

== DOM-less SDK API to send messages to the Nielsen SDK==

=== Video Measurement ===

The method for calling events is ggPM().

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

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event name !! Values to pass !! Description !!Event #
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each content/ad metadata object and after stop event when resuming '''video content''' (not after pausing and resuming an ad). ''[[DCR Sweden Video Browser SDK#Create Metadata Objects|See details on how to create MMS metadata for content and ad]]''
||15
|-
| 'setPlayheadPosition'
||
* 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 (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
||49
|-
| 'stop' || playhead position in seconds || Call when ads complete playing and on pause event (when resume will be available). The playhead position must be passed when calling stop
||7
|-
| 'end' || playhead position in seconds || This event has to be called once for the current video asset at the end of the playback.
At the end of the content stream, if the user switches to another piece of content or when the browser is refreshed or closed.
||57
|}

'''Note:''' Playhead position as integer

'''Note:''' 'setPlayheadPosition' has to be called every second

==== Example Events ====

*'''Event:''' loadMetadata | '''Value Pass ( Object ):''' Content Metadata Object

<syntaxhighlight lang="javascript">
instance.ggPM('loadMetadata', contentMetadataObject);
</syntaxhighlight>

*'''Event:''' loadMetadata | '''Value Pass ( Object ):''' Pre-roll AD Metadata Object

<syntaxhighlight lang="javascript">
instance.ggPM('loadMetadata', prerollMetadataObject);
</syntaxhighlight>

*'''Event:''' setPlayheadPosition | '''Value Pass ( Integer ):''' playheadPosition

<syntaxhighlight lang="javascript">
instance.ggPM('setPlayheadPosition', playheadPosition);
</syntaxhighlight>

*'''Event:''' stop | '''Value Pass ( Integer ):''' stopPlayheadPosition

<syntaxhighlight lang="javascript">
instance.ggPM('stop', stopPlayheadPosition);
</syntaxhighlight>

*'''Event:''' end | '''Value Pass ( Integer ):''' endPlayheadPosition

<syntaxhighlight lang="javascript">
instance.ggPM('end', endPlayheadPosition);
</syntaxhighlight>

==== Sample DOM-less SDK Implementation ====

* Sample Implementation on github [https://github.com/NielsenDigitalSDK/bsdk-domless here].

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

==== Review SDK Interrupt Scenarios ====
* [[DCR Sweden Video Browser SDK#Handle Video Playback Interruption|Handle Video Playback Interruption]]

==== Review SDK Event Lifecycle ====
* [[DCR Sweden Video Browser SDK#SDK Call Sequence |SDK Call Sequence ]]

== Privacy and Opt-Out ==

The site must provide a means for the user to opt-out of, or opt back into, Nielsen Measurement. Users can opt out if they prefer not to participate in any Nielsen online measurement research. To implement the User Opt-Out option, include the following two items in your privacy policy.
*A notice that the player (or page in relation to static measurement) includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings).
*A link to the Nielsen Digital Measurement Privacy Policy at https://www.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=sv (or for English: https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=en-se)
*We have two separate entities registered with the IAB TCF, Nielsen Marketing Cloud and Nielsen LLC. The one that is relevant to Swedish measurement is Nielsen LLC (ID: 812) and not NMC. 

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 via this [https://priv-policy.imrworldwide.com/priv/browser/cookie-policy.html?optout=1 link], their browser cookies will contain the value '''TOTAL_OPTOUT'''. This will prevent a redirect to our data provider from occurring
* Users can opt back in via this [https://priv-policy.imrworldwide.com/priv/browser/cookie-policy.html?optout=0 link]. When a user selects that link, their opt-out cookie will be deleted and they will be able to be measured moving forward.
 
The following paragraph is a template for a Privacy Statement.
<blockquote>
The properties may feature Nielsen proprietary measurement software, allowing users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices concerning it, please see the Nielsen Digital Measurement Privacy Policy at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=sv
</blockquote>

==== User Opt Back In ====
Once users have opted-out, they can choose to opt back into Nielsen Measurement at any time 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.

=== Turning off the First Party ID for Opt-out Users during the SDK Initializazion ===
The First Party ID(FPID) is enabled by default in the Browser SDK. For Opt-out users, the First Party ID can be turned off during the initialization of the SDK Instance, i.e. the parameter enableFpid can be set to "false" (FPID disabled) or "true" (FPID enabled). See [[#Initialization Global Parameters|SDK Initialization Global Parameters]].

=== Setting the SDK global optout Flag for Opt-out Users during the SDK Initialization ===
The optout Flag is set by default to "false" in the Browser SDK. For Opt-out users, the optout Flag can be set to "true" during the initialization of the SDK Instance, i.e. the parameter optout can be set to "true" (opted out) or "false" (opted in or NOT opted out). See [[#Initialization Global Parameters|SDK Initialization Global Parameters]].

== Certification ==

While Nielsen is working on adding Support to the Certification Tool for DOM-less SDK in the future, the Certification process for the DOM-less will require detailed SDK Logs from a MMS Client integrating Nielsen DOM-less SDK. In this regard, a client will execute test cases locally and share logs for each test case with a Nielsen Technical Account Manager in charge of the Certification.

== Going Live ==
Following Nielsen testing, disable Nielsen SDK logging by adjusting the Nielsen SDK Initialization Call, this will ensure that the App or Website 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:

<syntaxhighlight lang="javascript">
const instance = new BsdkInstance(
nsdkConfig.app_id,
nsdkConfig.instance_name,
{
appName: 'BSDK RN Sample App',
domlessEnv: '1'// "1" for React Native | "2" for Amazon | "3" for NodeJS | "4" for Custom
// reference SDK interface documentation
// for additional metadata properties
},
implementationHooks
);
</syntaxhighlight>

'''Note''': before going live you have to inform Nielsen - this is necessary, because 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 Sweden Domless SDK

2026-03-18T10:54:25Z

MichelFodjo: first Version uploaded

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

==License==
Nielsen SDK contains material that is protected by copyright laws, patent laws, trade secret laws, and by international treaty provisions and is Copyright © 2025 The Nielsen Company (US) LLC. All intellectual property rights and licenses therein are reserved by The Nielsen Company (US) LLC and its licensors. Please read the license agreement presented [https://engineeringportal.nielsen.com/wiki/Special:ClickThrough here], which must be accepted in order to download the Nielsen SDKs. For more information, reach out to your Nielsen Technical Account Manager(TAM).

== Overview ==

The Nielsen DOM-less SDK is a Javascript based cross-platform library that provides APIs that allows our clients to integrate the Nielsen SDK in DOM-less environments, e.g. ReactNative, NodeJS, etc. The new Amazon Vega/Kepler OS was certified by Nielsen for the DOM-less SDK Integration.

The Nielsen DOM-less SDK can be used for '''Video''' and '''Static''' measurements.

The Digital Content Ratings (DCR) Video product provides content consumption measurement on client mobile apps or webpages. This measurement includes insight into the total time a user spent watching the tracked content, video player events, and much more. This guide also includes a link to [[#Sample DOM-less SDK Implementation| github sample implementation]] with steps to implement the DCR Video product in a sample NodeJS app. It includes:
* DOM-less SDK Initialization
* DCR Video Metadata: information about the content being tracked
* DCR Video Events/API calls

==DOM-less SDK Initialization==

===Obtain the Nielsen Application ID (apid)===
The Nielsen <code>apid</code> is required to enable SDK functionality. A Technical Account Manager(TAM) will provide an apid for each player configuration.DOM-less SDK can support URLs that use any of the protocols – HTTPS and HTTP.

===Configure the DOM-less SDK===

====Installation====
Install with <code>npm install <nowiki>https://github.com/NielsenDigitalSDK/bsdk-domless</nowiki></code>
 and import the <code>BsdkInstance</code> into video player component <code> import { BsdkInstance } from 'bsdk-domless' </code>

======status.ok()======

Initialization of the instance can be done with <code>status.ok()</code> function or use Promise handling approach

<syntaxhighlight lang="javascript">
const instance = await new BsdkInstance(appID, instanceName, instanceMetadata, implementationHooks);
if (instance && instance.status.ok()) {
expect(instance).not.toBe(undefined);
expect(instance.status.ok()).toBe(true);
}
</syntaxhighlight>

Note: Implementation Hooks are mandatory for the DOM-less SDK instance. Please refer to the Implementation Hooks section below for details.

====Exposed Interface====
The exposed interface is as follows:

1. <code>`ggPM`</code> - method to send messages to the Nielsen SDK

2. <code>`processEvent`</code> - method to send app state to the Nielsen SDK, e.g., focus, blur, appclose

===Initialization Global Parameters===
{| class="wikitable"
|+
!'''Parameter'''
!'''Description'''
!'''Required'''
!'''Value'''
|-
|apid
|UniqueID assigned to player/site.
|Yes
|'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'
|-
|instanceName
|Name of SDK instance
|Yes
|"any string value"
|-
|domlessEnv
|Type of DOM-less environment like ReactNative, Node, etc.
|Yes
|"domlessEnv": "1", // For ReactNative
"domlessEnv": "2", // For Amazon

"domlessEnv": "3", // For NodeJS

“domlessEnv”: “4”, // For Custom
|-
|hem_unknown || Hashed email using SHA512. This email is used by the MMS reach model.|| Required if login feature || <syntaxhighlight lang="javascript">
{hem_unknown: "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..."}
</syntaxhighlight>
|-
|optout
|OptOut global parameter. This optout will be maintained through the session of the SDK instance
|Yes
|"true" for opted out, "false" for NOT opted out or opted in. The default value is "false".
|-
|enableFpid
|Optional:turn on or off the First Party ID
|No
|"true" for turn on, "false" for turn off. The default value is "true".
|-
|nol_sdkDebug
|Enables Nielsen console logging. Only required for testing
|No
|"{nol_sdkDebug: "debug"}"
|-
|}

=== Implementation Hooks ===
This object captures the required entities for the DOM-less SDK to operate correctly. These are normally platform dependent and are expected to be passed on to the DOM-less SDK as part of its initialization. See below for the descriptions of each key.

==== '''log''' ====
Log the DOM-less SDK messages to an external stream, e.g. the browser console, stdout.

e.g. Log.debug('debug', 'NIELSEN TAGS EXPECTED TO FIRE:')

===== Methods =====
<blockquote>info()

Log.info(label: string, ...message: string[]): void

debug()

Log.debug(label: string, ...message: string[]): void

warn()

Log.warn(label: string, ...message: string[]): void

error()

Log.error(label: string, ...message: string[]): void</blockquote>

===== Parameters =====
<blockquote>label Required

● string - severity type, e.g. info, debug, warn, error or custom label

message Required

● string - message that will be output to the console</blockquote>

==== storage ====
Persistent storage of key/values, similar in behavior to browser localStorage.

e.g. storage.set('nol_lsid', 'umy3w4ik9usw2ppqmw2vkecckxfob1697308388')

===== Methods =====
<blockquote>set()

storage.set(key: string, value: string)

get()

storage.get(key: string)

remove()

storage.remove(key: string)

clear()

storage.clear()</blockquote>

==== fetch ====
Function to fetch resources from the network. Required for the transmission of the DOM-less SDK requests (pings) to the Nielsen endpoints.

e.g. Fetch(resource: string, options: object)

===== Parameters =====
<blockquote>resource Required

● A string that provides the URL of the resource to fetch

options Optional Object containing settings to apply to the request:

method

● string - request method: "GET", "POST". If one is not provided SDK will default to "GET"

headers

● object - headers to add to the outgoing request, an object literal with String values

body

● string - body to add to the request; SDK will send out string

mode

● string - mode for request: cors, no-cors, same-origin

referrer

● string - a string specifying the referrer of the request</blockquote>

====='''''<pre style="color: green; font-weight: bold; font-size: 20px">Note: Implementation Hooks are mandatory for the DOM-less SDK to function as expected.</pre>'''''=====

== DOM-less SDK API to send app state to the Nielsen SDK, e.g., focus, blur, appclose==

The method for calling events is <code>processEvent()</code>.

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

* <code>`blur`</code> - This event should be passed to processEvent when the app goes to the background.

<syntaxhighlight lang="javascript">
instance.processEvent({ type: 'blur', timestamp: Date.now() });
</syntaxhighlight>

* <code>`focus`</code> - This event should be passed to processEvent when the app goes to the foreground.

<syntaxhighlight lang="javascript">
instance.processEvent({ type: 'focus', timestamp: Date.now() });
</syntaxhighlight>

* <code>`appclose`</code> - This event should be passed prior to closing the app.

<syntaxhighlight lang="javascript">
instance.processEvent({ type: 'appclose', timestamp: Date.now() });
</syntaxhighlight>

== DOM-less SDK API to send messages to the Nielsen SDK==

=== Video Measurement ===

The method for calling events is ggPM().

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

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event name !! Values to pass !! Description !!Event #
|-
| 'loadMetadata' || content/ad metadata object || Needs to be called at the beginning of each content/ad metadata object and after stop event when resuming '''video content''' (not after pausing and resuming an ad). ''[[DCR Sweden Video Browser SDK#Create Metadata Objects|See details on how to create MMS metadata for content and ad]]''
||15
|-
| 'setPlayheadPosition'
||
* 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 (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
||49
|-
| 'stop' || playhead position in seconds || Call when ads complete playing and on pause event (when resume will be available). The playhead position must be passed when calling stop
||7
|-
| 'end' || playhead position in seconds || This event has to be called once for the current video asset at the end of the playback.
At the end of the content stream, if the user switches to another piece of content or when the browser is refreshed or closed.
||57
|}

'''Note:''' Playhead position as integer

'''Note:''' 'setPlayheadPosition' has to be called every second

==== Example Events ====

*'''Event:''' loadMetadata | '''Value Pass ( Object ):''' Content Metadata Object

<syntaxhighlight lang="javascript">
instance.ggPM('loadMetadata', contentMetadataObject);
</syntaxhighlight>

*'''Event:''' loadMetadata | '''Value Pass ( Object ):''' Pre-roll AD Metadata Object

<syntaxhighlight lang="javascript">
instance.ggPM('loadMetadata', prerollMetadataObject);
</syntaxhighlight>

*'''Event:''' setPlayheadPosition | '''Value Pass ( Integer ):''' playheadPosition

<syntaxhighlight lang="javascript">
instance.ggPM('setPlayheadPosition', playheadPosition);
</syntaxhighlight>

*'''Event:''' stop | '''Value Pass ( Integer ):''' stopPlayheadPosition

<syntaxhighlight lang="javascript">
instance.ggPM('stop', stopPlayheadPosition);
</syntaxhighlight>

*'''Event:''' end | '''Value Pass ( Integer ):''' endPlayheadPosition

<syntaxhighlight lang="javascript">
instance.ggPM('end', endPlayheadPosition);
</syntaxhighlight>

==== Sample DOM-less SDK Implementation ====

* Sample Implementation on github [https://github.com/NielsenDigitalSDK/bsdk-domless here].

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

==== Review SDK Interrupt Scenarios ====
* [[DCR Sweden Video Browser SDK#Handle Video Playback Interruption|Handle Video Playback Interruption]]

==== Review SDK Event Lifecycle ====
* [[DCR Sweden Video Browser SDK#SDK Call Sequence |SDK Call Sequence ]]

== Privacy and Opt-Out ==

The site must provide a means for the user to opt-out of, or opt back into, Nielsen Measurement. Users can opt out if they prefer not to participate in any Nielsen online measurement research. To implement the User Opt-Out option, include the following two items in your privacy policy.
*A notice that the player (or page in relation to static measurement) includes proprietary measurement software that allows users to contribute to market research (such as Nielsen TV Ratings).
*A link to the Nielsen Digital Measurement Privacy Policy at https://www.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=sv (or for English: https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=en-se)
*We have two separate entities registered with the IAB TCF, Nielsen Marketing Cloud and Nielsen LLC. The one that is relevant to Swedish measurement is Nielsen LLC (ID: 812) and not NMC. 

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 via this [https://priv-policy.imrworldwide.com/priv/browser/cookie-policy.html?optout=1 link], their browser cookies will contain the value '''TOTAL_OPTOUT'''. This will prevent a redirect to our data provider from occurring
* Users can opt back in via this [https://priv-policy.imrworldwide.com/priv/browser/cookie-policy.html?optout=0 link]. When a user selects that link, their opt-out cookie will be deleted and they will be able to be measured moving forward.
 
The following paragraph is a template for a Privacy Statement.
<blockquote>
The properties may feature Nielsen proprietary measurement software, allowing users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices concerning it, please see the Nielsen Digital Measurement Privacy Policy at https://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=sv
</blockquote>

==== User Opt Back In ====
Once users have opted-out, they can choose to opt back into Nielsen Measurement at any time 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.

=== Turning off the First Party ID for Opt-out Users during the SDK Initializazion ===
The First Party ID(FPID) is enabled by default in the Browser SDK. For Opt-out users, the First Party ID can be turned off during the initialization of the SDK Instance, i.e. the parameter enableFpid can be set to "false" (FPID disabled) or "true" (FPID enabled). See [[#Initialization Global Parameters|SDK Initialization Global Parameters]].

=== Setting the SDK global optout Flag for Opt-out Users during the SDK Initialization ===
The optout Flag is set by default to "false" in the Browser SDK. For Opt-out users, the optout Flag can be set to "true" during the initialization of the SDK Instance, i.e. the parameter Optout can be set to "true" (opted out) or "false" (opted in or NOT opted out). See [[#Initialization Global Parameters|SDK Initialization Global Parameters]].

== Certification ==

While Nielsen is working on adding Support to the Certification Tool for DOM-less SDK in the future, the Certification process for the DOM-less will require detailed SDK Logs from a MMS Client integrating Nielsen DOM-less SDK. In this regard, a client will execute test cases locally and share logs for each test case with a Nielsen Technical Account Manager in charge of the Certification.

== Going Live ==
Following Nielsen testing, disable Nielsen SDK logging by adjusting the Nielsen SDK Initialization Call, this will ensure that the App or Website 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:

<syntaxhighlight lang="javascript">
const instance = new BsdkInstance(
nsdkConfig.app_id,
nsdkConfig.instance_name,
{
appName: 'BSDK RN Sample App',
domlessEnv: '1'// "1" for React Native | "2" for Amazon | "3" for NodeJS | "4" for Custom
// reference SDK interface documentation
// for additional metadata properties
},
implementationHooks
);
</syntaxhighlight>

'''Note''': before going live you have to inform Nielsen - this is necessary, because 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 France Video Browser SDK

2026-03-18T10:52:53Z

MichelFodjo: /* Setting the SDK global optout Flag for Opt-out Users during the SDK Initialization */

DCR France Video Browser SDK

2026-03-18T10:44:22Z

MichelFodjo: /* Turning off the First Party ID for Opt-out Users during the SDK Initializazion */

DCR France Video Browser SDK

2026-03-18T10:43:45Z

MichelFodjo: /* Setting the SDK global optout Flag for Opt-out Users during the SDK Initializazion */

DCR Sweden Domless SDK

2026-03-18T08:45:58Z

MichelFodjo: start

TBD

DCR Sweden Video Android SDK

2026-03-18T08:40:38Z

MichelFodjo: /* Create SDK Instance */ YES added for optout as for other params

{{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 || '''value is automatically populated through App Name included in the App Resource File''' || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || '''value is automatically populated through App Version included in the App Resource File''' || 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>
|-
|optout || OptOut global parameter. This optout will be maintained through the session of the SDK instance || Nielsen-specified || YES || "true" for opted out, "false" for NOT opted out or opted in. The default value is "false".
|}
 

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;
.put("optout", "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;
.put("optout", "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 ====
playhead position as integer 
* VOD: current position in seconds for Content and Ad. 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 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="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> || // content paused before switching to midroll
|-
| rowspan="3" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midroll starts, 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> || // 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 current 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 Denmark Video Android SDK

2026-03-06T13:48:46Z

MichelFodjo: /* Step 7 : Disclose Nielsen Privacy Statement */ add enableFPID API for compatibility with BSDK

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{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 version 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.

 
<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 ===
<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("stationId", "TESTXXYYSSWWLL")
.put("islivestn", "y")
.put("pbstarttm", "1631098029");

JSONObject adMetadata = new JSONObject()
.put("assetid", "unique_postroll_ad_id")
.put("type", "postroll"
.put("subbrand", "c05")
.put("stationId", "TESTXXYYSSWWLL")
.put("islivestn", "y")
.put("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.

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

==== sendID3 ====
Needs to be called when ID3 Tags are included in the Video Stream.
<syntaxhighlight lang="Java">mAppSdk..sendID3(String 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

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

=== Turning off the First Party ID for Opt-out Users during the SDK Initialization ===
The First Party ID(FPID) is enabled by default in the Android AppSDK. For Opt-out users, the First Party ID can be turned off during the initialization of the AppSDK Instance, i.e. the parameter enableFpid can be set to "false" (FPID disabled) or "true" (FPID enabled).

===== Example of SDK Initialization with enableFpid =====

====== First Party ID turned on ======
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("enableFpid", "true")
// ...
// 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>

====== First Party ID turned off ======
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("enableFpid", "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>

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

2026-03-06T13:46:48Z

MichelFodjo: /* Turning off the First Party ID for Opt-out Users */ title same for iOS and Android

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{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 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
|}

__TOC__

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

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

===== 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",
stationId: "TESTXXYYSSWWLL",
islivestn: "y",
pbstarttm: "1631098029"
};
</syntaxhighlight>

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

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
var adMetadataObject =
{
type: "preroll",
assetid: "unique_preroll_ad_id",
subbrand: "c05",
stationId: "TESTXXYYSSWWLL",
islivestn: "y",
pbstarttm: "1631098029"
};
</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>

=== 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
|--style="background-color:#d0f6f8;
|"setPlayheadPosition" || playhead position as integer 
<pre style="background-color:#d0f6f8">
</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,... 
||
Pass playhead position every second during playback, the value passed should match the broadcast time for live channel.
|-
| "sendID3" || ID3 tag payload retrieved from the stream || Call when the video player has read ID3 tag in the stream
|-
| "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>

== Send ID3 Tags when available in the stream ==

<syntaxhighlight lang="javascript">
// ID3 Tag read from the stream (HLS or MPEG-DASH)
// pass ID3 Tag to SDK
//
nSdkInstance.ggPM("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>

== 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);
//
// pass ID3 Tag immediately when available in the Video Stream
nSdkInstance.ggPM("sendID3", id3);
//
// END OF STREAM
nSdkInstance.ggPM("end", playheadPosition);
</syntaxhighlight>

=== Ad Playback Call Sequence (Optional for DR) ===
<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 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]]

== 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" below the video player.

Start the Reference Implementation for DK [http://nielsenonlinesupport.com/dk/index.htm sdkRefImplDK].
<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://nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=da .

=== Turning off the First Party ID for Opt-out Users during the SDK Initialization ===
The First Party ID(FPID) is enabled by default in the Browser SDK. For Opt-out users, the First Party ID can be turned off during the initialization of the SDK Instance, i.e. the parameter enableFpid can be set to "false" (FPID disabled) or "true" (FPID enabled).

===== Example of SDK Initialization with enableFpid =====

====== First Party ID turned on ======
<syntaxhighlight lang="javascript">
nSdkInstance = NOLBUNDLE.nlsQ(appID, "videoSdkInstance", {
enableFpid: "true"
});
</syntaxhighlight>

====== First Party ID turned off ======
<syntaxhighlight lang="javascript">
nSdkInstance = NOLBUNDLE.nlsQ(appID, "videoSdkInstance", {
enableFpid: "false"
});
</syntaxhighlight>

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

== 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 Denmark Video iOS SDK

2026-03-06T13:44:21Z

MichelFodjo: /* Step 7 : Disclose Nielsen Privacy Statement */ add enableFPID API for compatibility with BSDK

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

=== Turning off the First Party ID for Opt-out Users during the SDK Initialization ===
The First Party ID(FPID) is enabled by default in the iOS AppSDK. For Opt-out users, the First Party ID can be turned off during the initialization of the AppSDK Instance, i.e. the parameter enableFpid can be set to "false" (FPID disabled) or "true" (FPID enabled).

==== Example of SDK Initialization with enableFpid ====

===== First Party ID turned on =====
====== 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",
@"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",
"enableFpid": "true"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>>

===== First Party ID turned off =====
====== 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",
@"enableFpid": @"false"
};
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",
"enableFpid": "false"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

== 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 France Video Android SDK

2026-03-06T13:39:07Z

MichelFodjo: /* Turning off the First Party ID for Opt-out Users during the SDK Initialization */ typo BSDK updated to AppSDK

{{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 Médiamétrie
|-style="background-color:#d0f6f8;"
|| ☑ || "Nielsen SDK" || The Nielsen Digital AppSDK which includes SDK frameworks and "sample implementation"; "See [[Android SDK Release Notes]]" || [[DCR France SDK Downloads|Download]]
|}

* <blockquote>'''Ad flavour of AppSDK''': <pre style="color: red">The Ad flavour of AppSDK should be downloaded for the french market! The AppSDK Version 10.1.0.0 or higher must be downloaded</pre>

== 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 version included in the App Resource File''' || || "1.0.2"
|-
|hem_sha1 || hashed (SHA256) value of member id || Nielsen-specified || || i.e. for the sample memberID "userMemberID123", the value to pass is "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826"
|-
|uid2 || hashed(SHA256) value of UID2 || Nielsen-specified || || i.e. for the sample UID2 "userUID2", the value to pass is "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05"
|-
|hem_sha256 || hashed(SHA256) value of the user email address || Nielsen-specified || || i.e. for the sample email address "useremail@company.com", the value to pass is "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969"
|-
|enableFpid || Optional:turn on or off the First Party ID || Nielsen-specified || || "true" for turn on, "false" for turn off. The default value is "true".
|-
|optout || OptOut global parameter. This optout will be maintained through the session of the SDK instance || Nielsen-specified || ✓ || "true" for opted out, "false" for NOT opted out or opted in. The default value is "false".
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || || "DEBUG"
|}
 

<blockquote> If the User consent changes while using the App, you have to delete the current SDK instance and create a new instance with the updated optout and enableFpid values.
</blockquote>

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("hem_sha1", "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826")
.put("uid2", "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05")
.put("hem_sha256", "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969")
.put("enableFpid", "true")
.put("optout", "false")
.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("enableFpid", "true")
.put("optout", "false")
.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.

 

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

JSONObject contentMetadata = new JSONObject()
.put("type", "content")
.put("assetid", "unique_content_id")
.put("program", "program name")
.put("title", "episode title")
.put("length", "length in seconds")
.put("islivestn", "y")
.put("subbrand", "c05")
.put("cli_md", "LIVE")
.put("cli_ch", "860")
.put("cli_cn", "customContentIdentifier")
.put("nol_p0", "p0,optionalValueP0")
.put("nol_p1", "p1,optionalValueP1")
// ...
.put("nol_p18", "p18,optionalValueP18")
.put("nol_p19", "p19,optionaValuelP19");

</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. 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 (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
* when a user pauses playback
* when an Ad Break starts during the Content 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]]

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

=== Initialization of the SDK based on User Consent in your App ===

In collaboration with Mediametrie, the following user consent use cases need to be implemented in your App.

==== The user explicitly accepts measurement ====
The SDK is initialized and all IDs are captured. The SDK Opt-in Flags have to be set accordingly, see:

* [[#User opted in|User opted in]]
* [[#First Party ID turned on|First Party ID turned on]]

==== The user explicitly refuses measurement ====
The SDK is NOT initialized and No Nielsen SDK measurement will occur.

==== The user did not explicitly give consent for the measurement(consent neither given nor refused) ====
The SDK is initialized and no IDs are captured. The SDK Opt-out Flags have to be set accordingly, see:
* [[#User opted out|User opted out]]
* [[#First Party ID turned off|First Party ID turned off]]

=== Turning off the First Party ID for Opt-out Users during the SDK Initialization ===
The First Party ID(FPID) is enabled by default in the Android AppSDK. For Opt-out users, the First Party ID can be turned off during the initialization of the AppSDK Instance, i.e. the parameter enableFpid can be set to "false" (FPID disabled) or "true" (FPID enabled).

===== Example of SDK Initialization with enableFpid =====

====== First Party ID turned on ======
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("enableFpid", "true")
// ...
// 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>

====== First Party ID turned off ======
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("enableFpid", "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>

=== Setting the SDK global optout Flag for Opt-out Users ===

The Optout Flag is set by default to "false" in the AppSDK.

For Opt-out users, the Optout Flag can be set accordingly while Initializing the SDK Instance.
* <blockquote>'''Ad flavour of AppSDK''': <pre style="color: red">The Ad flavour of AppSDK should be downloaded for the french market! The AppSDK Version 10.1.0.0 or higher must be downloaded</pre>

===== Example the Ouptout Flag =====

====== User opted out ======
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("optout", "true")
// ...
// 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>

====== User opted in======
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("optout", "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>

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

The Reference Implementation covers VoD and Live use cases.
The code also covers also DAI (Dynamic Ad Insertion) that should be ignored since No Ads are measured in France.

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 a request (https://portail-marqueurs.mediametrie.com) to Médiamétrie 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 France Video iOS SDK

2026-03-06T13:36:14Z

MichelFodjo: /* Turning off the First Party ID for Opt-out Users during the SDK Initializazion */ typo BSDK updated to AppSDK

{{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 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 Médiamétrie
|-style="background-color:#d0f6f8;"
|| ☑ || '''Nielsen SDK''' || The Nielsen Digital AppSDK which includes SDK frameworks and '''sample implementation'''; "See [[iOS SDK Release Notes]]" || [[DCR France SDK Downloads|Download]]
|}

* <blockquote>'''Ad flavour of AppSDK''': <pre style="color: red">The Ad flavour of AppSDK should be downloaded for the french market! The AppSDK Version 10.1.0.0 or higher must be downloaded</pre>

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

=== 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"
|-
|hem_sha1 || hashed (SHA256) value of member id || Nielsen-specified || || i.e. for the sample memberID "userMemberID123", the value to pass is "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826"
|-
|uid2 || hashed(SHA256) value of UID2 || Nielsen-specified || || i.e. for the sample UID2 "userUID2", the value to pass is "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05"
|-
|hem_sha256 || hashed(SHA256) value of the user email address || Nielsen-specified || || i.e. for the sample email address "useremail@company.com", the value to pass is "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969"
|-
|enableFpid || Optional:turn on or off the First Party ID || Nielsen-specified || || "true" for turn on, "false" for turn off. The default value is "true".
|-
|optout || OptOut global parameter. This optout will be maintained through the session of the SDK instance || Nielsen-specified || ✓ || "true" for opted out, "false" for NOT opted out or opted in. The default value is "false".
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || || "DEBUG"
|}
 

<blockquote> If the User consent changes while using the App, you have to delete the current SDK instance and create a new instance with the updated optout and enableFpid values.
</blockquote>

==== 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",
@"hem_sha1": @"7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
@"uid2": @"7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
@"hem_sha256": @"0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
@"enableFpid": @"true",
@"optout": @"false",
@"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",
"hem_sha1": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"uid2": "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
"hem_sha256": "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
"enableFpid": "true",
"optout": "false",
"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
## appDisableApi 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.

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.

=== 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",
@"islivestn" : @"y",
@"subbrand" : @"c05",
@"cli_md" : @"LIVE",
@"cli_ch" : @"860",
@"cli_cn" : @"customContentIdentifier",
@"nol_p0" : @"p0,optionalValueP0",
@"nol_p1" : @"p1,optionalValueP1",
// ...
@"nol_p18" : @"p18,optionalValueP18",
@"nol_p19" : @"p19,optionalValueP19"
}

</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",
"islivestn" : "y",
"subbrand" : "c05",
"cli_md" : "LIVE",
"cli_ch" : "860",
"cli_cn" : "customContentIdentifier",
"nol_p0" : "p0,optionalValueP0",
"nol_p1" : "p1,optionalValueP1",
// ...
"nol_p18" : "p18,optionalValueP18",
"nol_p19" : "p19,optionaValuelP19"
]

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

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* when an Ad Break starts during the Content 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
|-
| 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
* When an Ad Break starts during the Content Playback
* 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 current 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]]

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

=== Initialization of the SDK based on User Consent in your App ===

In collaboration with Mediametrie, the following user consent use cases need to be implemented in your App.

==== The user explicitly accepts measurement ====
The SDK is initialized and all IDs are captured. The SDK Opt-in Flags have to be set accordingly, see:

* [[#User opted in|User opted in]]
* [[#First Party ID turned on|First Party ID turned on]]

==== The user explicitly refuses measurement ====
The SDK is NOT initialized and No Nielsen SDK measurement will occur.

==== The user did not explicitly give consent for the measurement(consent neither given nor refused) ====
The SDK is initialized and no IDs are captured. The SDK Opt-out Flags have to be set accordingly, see:
* [[#User opted out|User opted out]]
* [[#First Party ID turned off|First Party ID turned off]]

=== Turning off the First Party ID for Opt-out Users during the SDK Initialization ===
The First Party ID(FPID) is enabled by default in the iOS AppSDK. For Opt-out users, the First Party ID can be turned off during the initialization of the AppSDK Instance, i.e. the parameter enableFpid can be set to "false" (FPID disabled) or "true" (FPID enabled).

==== Example of SDK Initialization with enableFpid ====

===== First Party ID turned on =====
====== 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",
@"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",
"enableFpid": "true"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>>

===== First Party ID turned off =====
====== 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",
@"enableFpid": @"false"
};
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",
"enableFpid": "false"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

=== Setting the SDK global optout Flag for Opt-out Users ===

The Optout Flag is set by default to "false" in the AppSDK.

For Opt-out users, the Optout Flag can be set accordingly while Initializing the SDK Instance.
* <blockquote>'''Ad flavour of AppSDK''': <pre style="color: red">The Ad flavour of AppSDK should be downloaded for the french market! The AppSDK Version 10.1.0.0 or higher must be downloaded</pre>

==== Example the Ouptout Flag ====

===== User opted out =====
====== 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",
@"optout": @"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",
"optout": "true"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

===== User opted in =====
====== 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",
@"optout": @"false"
};
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",
"optout": "false"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

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

The Reference Implementation covers VoD and Live use cases.
The code also covers also DAI (Dynamic Ad Insertion) that should be ignored since No Ads are measured in France.

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-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 a request (https://portail-marqueurs.mediametrie.com) to Médiamétrie 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 France Video S2S

2026-01-28T14:25:13Z

MichelFodjo: /* query param list */ ping examples updated

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

= DCR Integration Utilizing S2S =
This guide shows you how to integrate the Nielsen S2S(Server to Server) to enable Digital Content Ratings (DCR), and fuel other measurement products on your Apps.

<pre style="color: orange">
PLease note that you have to use the Staging S2S Endpoint(<env>=stage)until you get the green light to move to Production, you will then get the Production S2S Endpoint!
</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 (apid)''' || Unique ID assigned to the player/site and configured by product. || Contact Médiamétrie
|-style="background-color:#d0f6f8;"
|| '''Integration ID (IntID)''' || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.) || Contact Médiamétrie
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| Contact Médiamétrie
|}

==Introduction==
This interface specification depicts the file format that needs to be used to supply Nielsen with
end-user viewing data captured by a “Server-to-Server” method for the Nielsen Digital Content
Ratings (DCR) product and Tuning data for the Digital Ads Rating (DAR) products.
* The specification is defined using a JSON schema, with each file ideally containing all the
viewing that has been captured within an hour.
* In the case of a stream that has one version with blackouts and one without, one with
mobile and one non-mobile, each stream would have it’s own unique asset id.
* The Asset Metadata file should arrive before the viewing data file for the same hour.

==SLA==
The files must be delivered into the proper S3 bucket '''immediately after each hour of viewing on a device''', but latest within 3 hour of the start of that hourly
viewing file interval. For example files from 1:00 AM to 2:00 AM must be delivered latest before 4 AM.

'''When SLA for receiving exposure file for date xx/xx, UTC hour xx has expired. The system will continue to wait for 60 min, after which it will skip the missing file and continue processing subsequent files. Any reprocessing of the missed SLA data will require an explicite request from Médiamétrie.'''

==Accuracy of the Measurement==

====Send Viewing Time (Video Player Events) At Least Each 10 Seconds To Your Backend====
Capture content viewing time each second and send the aggregated viewing time at least each 10 seconds to your backend:
* referencestart : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* referenceend : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* playheadstart : Content position start time in seconds
* playheadend : Content position end time in seconds

====Send Viewing Time When The Video Playback Is Interrupted====
Send the aggregated viewing time to your backend when the video playback is interrupted, i.e. paused.

====Capture Accurately Each Second The Viewing Time When The Network Is Lost And The Video Playback Continues====
Capture accurately each second the viewing time when the network is lost.
Send the aggregated viewing time to your backend when the network is back.

====Send The Viewing Time Early On Browser Refreshed/Closed====
Capture and send the viewing time to your backend by implementing the 2 WINDOWS EVENTS:

''' Please include a logic to make sure that only one of the 2 following event handler is executed '''
<syntaxhighlight lang="javascript">
window.addEventListener("pagehide", function (e) {
// SEND THE VIEWING TIME TO YOUR BACKEND
});
window.addEventListener("beforeunload", function (e) {
// ONLY IF pagehide" was not triggered, SEND THE VIEWING TIME TO YOUR BACKEND
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered at a fixed cadence in a dedicated S3 bucket following the outlined in this spec prefix and object naming conventions and data formats.

* All prefix labels and file names should be lowercase except for app ids.
* Supported format are:
** Uncompressed text files with utf-8 encoding in:
*** JSON format(.json);
*** PARQUET format(.parquet);
* All files should have extensions to indicate the file format (.json or .parquet)
* Data file can be partitioned into multiple parts with min size of 128MB - 256MB
* Data can be delivered separately in multiple splits(platforms), if needed due to organizational, technical or privacy requirements. This allows to permission s3 access separately, to process data independently and to persist data partitioned, within the limits of the S2S system;

===The 4 Different Files to deliver to Nielsen each hour===
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

Nielsen will move files to indicate they are being processed.

====S3 bucket and prefix(S3BucketPrefix) for all 4 Files====

All files should be delived to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| env || '''stage''' for Staging or '''prod''' for Production
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| Platform || '''ios''', '''browser''', '''android''', '''ott'''
|-
| yyyy/mm/dd/hh || UTC start of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023/02/12/05'''

|}
=====Examples for the iOS platform=====
======Asset Metadata File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====File Name(FileName) format for the Asset Metadata and Asset Viewing Files ====

Asset Metadata and Asset Viewing Files should be delivered to:
* <S3BucketPrefix>'''<FileName>'''

* '''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime><FileSuffix>

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| IntID || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.)
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || Nielsen provided server application identifier
|-
| StartTime || start date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| EndTime || end date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| yyyymmddhh || UTC time of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023021205'''

|-
| FileSuffix || Uncompressed json lines (no extension) - splittable, ideal for medium size files, '''less than 5 GB''', preferred for metadata.
'''supported:'''
* '''.json''' json file
* '''.parquet''' parquet file
|}

=====Examples for Asset Metadata and Asset Viewing Files=====
======Asset Metadata File======
Asset Metadata File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====Manifest File for the Asset Metadata and Asset Viewing Files====

The Manifest File should be delivered to: <S3BucketPrefix>'''<FileName>'''

'''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime>'''_manifest'''

A manifest contains metadata related to the uploaded file(s). It is a text file in json format that implements the AWS unload manifest file format. It follows the s3 objects naming notation, but has the _manifest suffix. Here’s an example of manifest file contents:

{
"entries": [
{"url":"s3://bucket/prefix/0000_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0001_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0002_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0003_object_00.snappy.parquet", "mandatory":true}
],
"meta": {
"schema_version": "S2SV1.7.0",
"accreditation_status": "0",
"start_time": "1710154800",
"end_time": "1710158399",
"record_count": 55
}
}

The manifest contains a complete list of all files provided for a given period and platform, as well as a meta data (a.k.a. header) which should include the following attributes:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, i.e. "S2SV1.7.0" || ✓
|-
| data_start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1710154800" || ✓
|-
| data_start_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1710158399" || ✓
|-
| record_count || Records Count in data file || Number: i.e. 55 || ✓
|}

If ‘entries’ array is not specified, or manifest file is not available, the system will still attempt to load all data file(s) (.json or .parquet) from the prefix location. Optionally the manifest file can contain the full schema of the data files as shown in the [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose manifest file format document ].

=====Example for the Manifest File=====

======Manifest File for the Asset Metadata File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"schema_version": "S2SV1.7.0",
"accreditation_status": "0",
"start_time": "1710154800",
"end_time": "1710158399",
"record_count": 15
}
</syntaxhighlight>

======Manifest File for the Asset Viewing File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"schema_version": "S2SV1.7.0",
"accreditation_status": "0",
"start_time": "1710154800",
"end_time": "1710158399",
"record_count": 55
}
</syntaxhighlight>

===Success File: Indication of a data delivery for a particular hour===

An Empty _SUCCESS file should be provided to indicate that data delivery for a particular hour and platform is completed successfully. This file should be uploaded last (after all other files). If there is no data data for a particular hour and platform, the _SUCCESS file is still required to indicate that the delivery process for the hour is completed and no data files are expected. This file is only required for integrations that support data partitioned into multiple parts. The name of the file is configurable.

====Example for Asset Viewing Delivery Files====

'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

====Example for Asset Metadata Delivery Files====
'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

====Data Delivery Example for hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):====
=====Asset Metadata Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

</code>
=====Asset Viewing Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0000.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0001.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0002.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0003.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

</code>

== S2S Metadata Specifications for the Asset Metadata and Asset Viewing Files ==

=== Asset Metadata File ===

The Asset Metadata File contains 1 Header Record followed by Body Records

====Header Record====

=====Description=====

'''Parameter Description'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.09" || ✓
|-
| mvpdid || mvpd ID specified ny Nielsen || String, i.e. "NLSN" || ✓
|-
| creationtime || File creation time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓

|-
| recordcount || Records Count in body of file ||String, i.e. "1" for only 1 Record || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.09",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''. 
'''Note:''' ''' Do not include personal data '''in the content metadata. 

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| assetid || unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| programname || name of program || custom || ✓
|-
| episodetitle || episode name || custom || ✓
|-
| episodelen || 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)|| ✓
|-
|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
||
✓
|-
| cli_md || mode: allows to know the streaming type || possible values provided by Médiamétrie: "LIVE" "TIMESHIFTING" "TVOD" "VOD" "SVOD" "AOD"||
|-
| cli_ch || Channel identifier: values decided by Médiamétrie and provided to the broadcaster || sample value: "860" ||
|-
| cli_cn || content identifier as used / categorized by the publisher || custom ||
|-
| nol_p0 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p1 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p2 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p3 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p4 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p5 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p6 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p7 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p8 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p9 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p10 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p11 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p12 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p13 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p14 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p15 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p16 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p17 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p18 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p19 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"program" : "program name",
"title" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c05",
"cli_md": "LIVE",
"cli_ch": "860",
"cli_cn": "customCuntentIdentifier",
"nol_p0": "p0,optionalValueP0",
"nol_p1": "p1,optionalValueP1",
// ... continued - 20 custom variables
"nol_p18": "p18,optionalValueP18",
"nol_p19": "p19,optionaValuelP19"
}
</syntaxhighlight>

=== Asset Viewing File ===

The Asset Viewing File contains 1 Header Record followed by Body Records
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''.
<pre style="color: orange">
Please do not include ZERO DURATION viewing portion in the Asset Viewing File.
</pre>

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.0" || ✓
|-
| appid || Nielsen provided server application identifier || String, i.e. "P47C2495B-XXXX-56DE-BE99-14758F92F034" || ✓
|-
| type || Type of the data || String, "content" || ✓
|-
| producttype || Product Type || String, "DCR" || ✓
|-
| starttime || Viewing Data Start Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓
|-
| endtime || Viewing Data End Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473791507"|| ✓
|-
| recordcount || Records Count in body of file || String, i.e. "100" for only 100 Records || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.0",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apn || app name || i.e. "BestAppIOS" || ✓
|-
| apv || app build version || i.e. "1.3" || ✓
|-
| sessionid || Unique, client generated value that represents the start of a user session. Must match sessionid in Audit Ping. || created using the UUID Generator code provided || ✓
|-
| streamid || streamid ID for every new instance of an asset || created using the UUID Generator code provided || ✓
|-
| streamended || Stream is known to have ended in this file ||
* "1" (stream will continue in next file)
* "2" (stream closed)
|| ✓
|-
| secondscr || Second Screen Indicator. For Mirroring & Extended Screen via OTT device scenarios ||
* "" (empty String if viewed directly on the device)
* "MIR" (Mirroring)
* "OTT" (Extended Screen via OTT device)
|| ✓
|-
| assetid || unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''Description:'''
* '''referencestart''' : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* '''referenceend''' : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* '''playheadstart''' : Content position start time in seconds
* '''playheadend''' : Content position end time in seconds

'''For Content position start and end time(playheadstart, playheadend):'''
* For VoD stream use the player position for Content as the playhead position in seconds. At playback start of a content from the begin, playheads will then be 0,1,2,3,....
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position in seconds.

'''Additional Notes:'''
* For viewing gaps < than 1 second, the gap can be smoothed over
* For playouts that are abandoned before the first whole second of viewing is rendered, a position record of zero duration should be created. IF an audit ping has already been fired See below for additional details on position array parameters
|| ✓
|-
| device_id || '''MANDATORY ONLY for android platform.''' Mobile Ad ID IDFA,ADID, Connected Device ID 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" || i.e "12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8" || ✓
|-
| xdua || Device HTTP raw User Agent string - OPTIONAL if passed in the Audit Ping to the Nielsen Server|| Example: "Apple-iPhone1C2/801.293" || ✓
|-
| xff || IP address - OPTIONAL if passed in the Audit Ping to the Nielsen Server|| Format: "xxx.xxx.xxx.xxx" or "xxx.xxx.xxx.000"
Examples :
* IPV4: "4.12.345.67"
* IPV6: "2600:6c58:7900:33f2:2505:42b9:5a34:0000"
|| ✓
|-
| fpid || First Party ID || created using the UUID Generator code provided / validity time 180 days. ||
|-
| fpcrtm || Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds) || custom ||
|-
|hem_sha1 || hashed (SHA256) value of member id || i.e. for the sample memberID "userMemberID123", the value to pass is "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826" ||
|-
|uid2 || hashed(SHA256) value of UID2 || i.e. for the sample UID2 "userUID2", the value to pass is i.e. "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05" ||
|-
|hem_sha256 || hashed(SHA256) value of the user email address || i.e. for the sample email address "useremail@company.com", the value to pass is "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969" ||
|-
|uoo || device opt-out status || "true" for opted out, "false" for NOT opted out or opted in. || ✓

|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique streamid for each video play using UUID Generator code provided
"streamended": "1",
"assetid": "VA12345",
"secondscr": "MIR",
"position": [
{
"referencestart": "1628735452",
"referenceend": "1628736052",
"playheadstart": "0",
"playheadend": "600"
}
],
"xdua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130Safari/537.36",
"xff": "4.12.345.67",

"uid2": "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
"device_id": "8ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"hem_sha1": "9ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"hem_sha256": "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
"uoo": "false",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000",
}

</syntaxhighlight>

===== Metadata based on User Consent in your App =====

In collaboration with Mediametrie, the following user consent use cases need to be implemented in your App.

====== The user explicitly accepts measurement ======
All Device/User IDs are captured in the Nielsen S2S Metadata. The Opt-in Flag is set to "false" and all IDs have to be set accordingly:
<syntaxhighlight lang="javascript">
{
"device_id": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"hem_sha1": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"uid2": "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
"hem_sha256": "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
"uoo"": "false",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000"
}
</syntaxhighlight>

====== The user explicitly refuses measurement ======
The Nielsen S2S is NOT initiated and No Nielsen S2S measurement will occur.

======The user did not explicitly give consent for the measurement(consent neither given nor refused) ======
The Nielsen S2S is initiated and no IDs are captured. The Nielsen S2S Opt-out Flag is set to "true" and all Device/User IDs are empty:
<syntaxhighlight lang="javascript">
{
"device_id": "",
"hem_sha1": "",
"uid2": "",
"hem_sha256": "",
"uoo"": "true",
"fpid": "",
"fpcrtm": ""
}
</syntaxhighlight>

==OTT, Mirroring, and Casting==

For apps native to the OTT device (i.e. downloading and viewing a streaming app to an Apple
TV, audit ping should fire from OTT device, and Viewing data should reside in OTT Viewing file.
For mirroring, where video playback occurs on the mobile device and OTT device, only one
Viewing file row is necessary where, if possible to determine, set: "secondscr":"MIR" and
include in respective mobile platform Viewing file.

For a casting scenario where content is controlled via the mobile device, but displayed only on
the OTT device such as an AppleTV or Chromecast, an audit ping must fire from the mobile
device before the casting occurs and at the end of playback from the mobile device only.
Viewing data resides in respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx123",
"referenceend": "xxxxxxx183",
'''"playheadstart": "0",'''
'''"playheadend": "60"'''
},
{
"referencestart": "xxxxxxx243",
"referenceend": "xxxxxxx303",
'''"playheadstart": "120",'''
'''"playheadend": "180"'''
}
]
}

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx183",
"referenceend": "xxxxxxx243",
'''"playheadstart": "60",'''
'''"playheadend": "120"'''
}
],
'''"secondscr": "OTT"'''
}

==S2S Audit Ping Specifications==

=== Introduction ===
The Nielsen server to server solution needs audit pings to validate audience reach and video viewing duration, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.

'''start audit ping(“Startstream = 1”)'''
* A start audit ping is sent when the stream starts(playback start).
* Also a new start audit ping is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
'''end audit ping(“Endstream = 3”)'''
* An end audit ping is sent when the stream ends(either playback completed or switch to another stream).
* Also an end audit ping is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.

=== Ping Structure ===
Ping should be named with following convention structure:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(Please note that this URL could change as we respond to security upgrades in the market.)
The Start Audit Ping will carry all parameters in the matrix below. The End Audit Ping will carry a subset of the parameters in the matrix below as denoted in the mandatory column.
Under normal operating circumstances, the Nielsen collection system will return return codes:
* For security reasons, downstream servers reject cross-origin HTTP requests with preflight. To ensure that audit ping requests are accepted, allowable Content-Types like "text/plain" in simple GET requests ensure that preflight requests are not invoked, which is the preferred behavior.
* 200: The ping was successfully received, inspect traffic to ensure no CORS errors

=== Ping Session & Stream Details ===

==== Sessions ====
* a) When a new player is created a session id is also created.
* b) If you have more than one video player within the same App (e.g. picture in picture) you must use a different session id for each.

==== Streams ====
* a) The Distributor must generate a new UNIQUE stream id with every video stream playback.
* b) If two people watch the same show, they would have different stream id's as Nielsen would expect the stream id(“streamid”) to be a random GUId generated by the client device.
* c) If one person watches a show, and FF, rewind, playout, pause, play, RW, play - they would keep the same stream id(“streamid”) throughout the entire playout of that video asset (stream).
* d) If a stream play out is suspended for 30 mins or more (paused or background):
** An end audit ping(“Endstream = 3”) is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.
** A new start audit ping(“Startstream = 1”) is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
* e) If the user reaches the very end of the stream (content complete), and then starts to play again (replay from anywhere in the stream), then a new “streamid” should be created and a start audit ping should be sent. Also an end audit should be sent when the stream replay is completed or the user switches to another stream.

====Audit Pings ====
* a) Audit pings should be fired at the '''beginning''' and '''end''' of a stream. These will be referred to as the Audit Start Ping and the Audit End Ping.

==== query param list ====

Example:

'''Required S2S Audit Ping Query String Parameters - Note: All parameters are case sensitive'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || Unique ID assigned to the player/site and configured by your Nielsen Technical Account Manager.
|| Example: '''FC984EC1-E044-B465-E040-070AAD3173A1''' || ✓
|-
| intid || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || || ✓
|-
| sessionid || Unique, client-generated value that represents the start of a user browsing session. Must match sessionid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| streamid || Unique Id for every new instance of a client video asset playout. Must match streamid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| pingtype || pingtype Indicator for state type: “start” or “end” audit ping & if the ping is for a stream ||
* Startstream = 1
* Startsession=0
* Endstream = 3
* Endsession=2
|| ✓
|-
| product || Indicates which Nielsen product the audit ping corresponds to. || dcr || ✓
|-
| createtm || Time the ping was fired: utc (in seconds) If server time available, use it instead of device time || || ✓
|-
| devid || devid, SHA-256 value of Device Id (IDFA, ADID) - OPTIONAL is passed in the Asset Viewing File || || ✓
|-
| uoo || device opt-out status || "true" for opted out, "false" for NOT opted out or opted in.|| ✓
|}

'''Generic Ping Format:'''

<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=<App id>&intid=<Integration ID>&sessionid=<Session Id>&streamid=<Stream Id>&pingtype=<Ping Type>&uoo=<Optout Status >&product=<dcr or dtvr>&createtm=<Session Start or End time>&devid=<Android ADID>'''
</nowiki></code>

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&uoo=false&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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>

DCR France Video S2S

2026-01-23T15:31:41Z

MichelFodjo: /* query param list */ missing uoo added

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

= DCR Integration Utilizing S2S =
This guide shows you how to integrate the Nielsen S2S(Server to Server) to enable Digital Content Ratings (DCR), and fuel other measurement products on your Apps.

<pre style="color: orange">
PLease note that you have to use the Staging S2S Endpoint(<env>=stage)until you get the green light to move to Production, you will then get the Production S2S Endpoint!
</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 (apid)''' || Unique ID assigned to the player/site and configured by product. || Contact Médiamétrie
|-style="background-color:#d0f6f8;"
|| '''Integration ID (IntID)''' || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.) || Contact Médiamétrie
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| Contact Médiamétrie
|}

==Introduction==
This interface specification depicts the file format that needs to be used to supply Nielsen with
end-user viewing data captured by a “Server-to-Server” method for the Nielsen Digital Content
Ratings (DCR) product and Tuning data for the Digital Ads Rating (DAR) products.
* The specification is defined using a JSON schema, with each file ideally containing all the
viewing that has been captured within an hour.
* In the case of a stream that has one version with blackouts and one without, one with
mobile and one non-mobile, each stream would have it’s own unique asset id.
* The Asset Metadata file should arrive before the viewing data file for the same hour.

==SLA==
The files must be delivered into the proper S3 bucket '''immediately after each hour of viewing on a device''', but latest within 3 hour of the start of that hourly
viewing file interval. For example files from 1:00 AM to 2:00 AM must be delivered latest before 4 AM.

'''When SLA for receiving exposure file for date xx/xx, UTC hour xx has expired. The system will continue to wait for 60 min, after which it will skip the missing file and continue processing subsequent files. Any reprocessing of the missed SLA data will require an explicite request from Médiamétrie.'''

==Accuracy of the Measurement==

====Send Viewing Time (Video Player Events) At Least Each 10 Seconds To Your Backend====
Capture content viewing time each second and send the aggregated viewing time at least each 10 seconds to your backend:
* referencestart : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* referenceend : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* playheadstart : Content position start time in seconds
* playheadend : Content position end time in seconds

====Send Viewing Time When The Video Playback Is Interrupted====
Send the aggregated viewing time to your backend when the video playback is interrupted, i.e. paused.

====Capture Accurately Each Second The Viewing Time When The Network Is Lost And The Video Playback Continues====
Capture accurately each second the viewing time when the network is lost.
Send the aggregated viewing time to your backend when the network is back.

====Send The Viewing Time Early On Browser Refreshed/Closed====
Capture and send the viewing time to your backend by implementing the 2 WINDOWS EVENTS:

''' Please include a logic to make sure that only one of the 2 following event handler is executed '''
<syntaxhighlight lang="javascript">
window.addEventListener("pagehide", function (e) {
// SEND THE VIEWING TIME TO YOUR BACKEND
});
window.addEventListener("beforeunload", function (e) {
// ONLY IF pagehide" was not triggered, SEND THE VIEWING TIME TO YOUR BACKEND
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered at a fixed cadence in a dedicated S3 bucket following the outlined in this spec prefix and object naming conventions and data formats.

* All prefix labels and file names should be lowercase except for app ids.
* Supported format are:
** Uncompressed text files with utf-8 encoding in:
*** JSON format(.json);
*** PARQUET format(.parquet);
* All files should have extensions to indicate the file format (.json or .parquet)
* Data file can be partitioned into multiple parts with min size of 128MB - 256MB
* Data can be delivered separately in multiple splits(platforms), if needed due to organizational, technical or privacy requirements. This allows to permission s3 access separately, to process data independently and to persist data partitioned, within the limits of the S2S system;

===The 4 Different Files to deliver to Nielsen each hour===
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

Nielsen will move files to indicate they are being processed.

====S3 bucket and prefix(S3BucketPrefix) for all 4 Files====

All files should be delived to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| env || '''stage''' for Staging or '''prod''' for Production
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| Platform || '''ios''', '''browser''', '''android''', '''ott'''
|-
| yyyy/mm/dd/hh || UTC start of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023/02/12/05'''

|}
=====Examples for the iOS platform=====
======Asset Metadata File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====File Name(FileName) format for the Asset Metadata and Asset Viewing Files ====

Asset Metadata and Asset Viewing Files should be delivered to:
* <S3BucketPrefix>'''<FileName>'''

* '''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime><FileSuffix>

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| IntID || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.)
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || Nielsen provided server application identifier
|-
| StartTime || start date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| EndTime || end date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| yyyymmddhh || UTC time of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023021205'''

|-
| FileSuffix || Uncompressed json lines (no extension) - splittable, ideal for medium size files, '''less than 5 GB''', preferred for metadata.
'''supported:'''
* '''.json''' json file
* '''.parquet''' parquet file
|}

=====Examples for Asset Metadata and Asset Viewing Files=====
======Asset Metadata File======
Asset Metadata File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====Manifest File for the Asset Metadata and Asset Viewing Files====

The Manifest File should be delivered to: <S3BucketPrefix>'''<FileName>'''

'''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime>'''_manifest'''

A manifest contains metadata related to the uploaded file(s). It is a text file in json format that implements the AWS unload manifest file format. It follows the s3 objects naming notation, but has the _manifest suffix. Here’s an example of manifest file contents:

{
"entries": [
{"url":"s3://bucket/prefix/0000_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0001_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0002_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0003_object_00.snappy.parquet", "mandatory":true}
],
"meta": {
"schema_version": "S2SV1.7.0",
"accreditation_status": "0",
"start_time": "1710154800",
"end_time": "1710158399",
"record_count": 55
}
}

The manifest contains a complete list of all files provided for a given period and platform, as well as a meta data (a.k.a. header) which should include the following attributes:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, i.e. "S2SV1.7.0" || ✓
|-
| data_start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1710154800" || ✓
|-
| data_start_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1710158399" || ✓
|-
| record_count || Records Count in data file || Number: i.e. 55 || ✓
|}

If ‘entries’ array is not specified, or manifest file is not available, the system will still attempt to load all data file(s) (.json or .parquet) from the prefix location. Optionally the manifest file can contain the full schema of the data files as shown in the [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose manifest file format document ].

=====Example for the Manifest File=====

======Manifest File for the Asset Metadata File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"schema_version": "S2SV1.7.0",
"accreditation_status": "0",
"start_time": "1710154800",
"end_time": "1710158399",
"record_count": 15
}
</syntaxhighlight>

======Manifest File for the Asset Viewing File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"schema_version": "S2SV1.7.0",
"accreditation_status": "0",
"start_time": "1710154800",
"end_time": "1710158399",
"record_count": 55
}
</syntaxhighlight>

===Success File: Indication of a data delivery for a particular hour===

An Empty _SUCCESS file should be provided to indicate that data delivery for a particular hour and platform is completed successfully. This file should be uploaded last (after all other files). If there is no data data for a particular hour and platform, the _SUCCESS file is still required to indicate that the delivery process for the hour is completed and no data files are expected. This file is only required for integrations that support data partitioned into multiple parts. The name of the file is configurable.

====Example for Asset Viewing Delivery Files====

'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

====Example for Asset Metadata Delivery Files====
'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

====Data Delivery Example for hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):====
=====Asset Metadata Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

</code>
=====Asset Viewing Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0000.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0001.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0002.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0003.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

</code>

== S2S Metadata Specifications for the Asset Metadata and Asset Viewing Files ==

=== Asset Metadata File ===

The Asset Metadata File contains 1 Header Record followed by Body Records

====Header Record====

=====Description=====

'''Parameter Description'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.09" || ✓
|-
| mvpdid || mvpd ID specified ny Nielsen || String, i.e. "NLSN" || ✓
|-
| creationtime || File creation time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓

|-
| recordcount || Records Count in body of file ||String, i.e. "1" for only 1 Record || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.09",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''. 
'''Note:''' ''' Do not include personal data '''in the content metadata. 

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| assetid || unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| programname || name of program || custom || ✓
|-
| episodetitle || episode name || custom || ✓
|-
| episodelen || 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)|| ✓
|-
|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
||
✓
|-
| cli_md || mode: allows to know the streaming type || possible values provided by Médiamétrie: "LIVE" "TIMESHIFTING" "TVOD" "VOD" "SVOD" "AOD"||
|-
| cli_ch || Channel identifier: values decided by Médiamétrie and provided to the broadcaster || sample value: "860" ||
|-
| cli_cn || content identifier as used / categorized by the publisher || custom ||
|-
| nol_p0 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p1 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p2 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p3 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p4 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p5 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p6 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p7 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p8 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p9 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p10 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p11 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p12 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p13 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p14 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p15 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p16 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p17 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p18 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p19 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"program" : "program name",
"title" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c05",
"cli_md": "LIVE",
"cli_ch": "860",
"cli_cn": "customCuntentIdentifier",
"nol_p0": "p0,optionalValueP0",
"nol_p1": "p1,optionalValueP1",
// ... continued - 20 custom variables
"nol_p18": "p18,optionalValueP18",
"nol_p19": "p19,optionaValuelP19"
}
</syntaxhighlight>

=== Asset Viewing File ===

The Asset Viewing File contains 1 Header Record followed by Body Records
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''.
<pre style="color: orange">
Please do not include ZERO DURATION viewing portion in the Asset Viewing File.
</pre>

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.0" || ✓
|-
| appid || Nielsen provided server application identifier || String, i.e. "P47C2495B-XXXX-56DE-BE99-14758F92F034" || ✓
|-
| type || Type of the data || String, "content" || ✓
|-
| producttype || Product Type || String, "DCR" || ✓
|-
| starttime || Viewing Data Start Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓
|-
| endtime || Viewing Data End Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473791507"|| ✓
|-
| recordcount || Records Count in body of file || String, i.e. "100" for only 100 Records || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.0",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apn || app name || i.e. "BestAppIOS" || ✓
|-
| apv || app build version || i.e. "1.3" || ✓
|-
| sessionid || Unique, client generated value that represents the start of a user session. Must match sessionid in Audit Ping. || created using the UUID Generator code provided || ✓
|-
| streamid || streamid ID for every new instance of an asset || created using the UUID Generator code provided || ✓
|-
| streamended || Stream is known to have ended in this file ||
* "1" (stream will continue in next file)
* "2" (stream closed)
|| ✓
|-
| secondscr || Second Screen Indicator. For Mirroring & Extended Screen via OTT device scenarios ||
* "" (empty String if viewed directly on the device)
* "MIR" (Mirroring)
* "OTT" (Extended Screen via OTT device)
|| ✓
|-
| assetid || unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''Description:'''
* '''referencestart''' : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* '''referenceend''' : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* '''playheadstart''' : Content position start time in seconds
* '''playheadend''' : Content position end time in seconds

'''For Content position start and end time(playheadstart, playheadend):'''
* For VoD stream use the player position for Content as the playhead position in seconds. At playback start of a content from the begin, playheads will then be 0,1,2,3,....
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position in seconds.

'''Additional Notes:'''
* For viewing gaps < than 1 second, the gap can be smoothed over
* For playouts that are abandoned before the first whole second of viewing is rendered, a position record of zero duration should be created. IF an audit ping has already been fired See below for additional details on position array parameters
|| ✓
|-
| device_id || '''MANDATORY ONLY for android platform.''' Mobile Ad ID IDFA,ADID, Connected Device ID 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" || i.e "12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8" || ✓
|-
| xdua || Device HTTP raw User Agent string - OPTIONAL if passed in the Audit Ping to the Nielsen Server|| Example: "Apple-iPhone1C2/801.293" || ✓
|-
| xff || IP address - OPTIONAL if passed in the Audit Ping to the Nielsen Server|| Format: "xxx.xxx.xxx.xxx" or "xxx.xxx.xxx.000"
Examples :
* IPV4: "4.12.345.67"
* IPV6: "2600:6c58:7900:33f2:2505:42b9:5a34:0000"
|| ✓
|-
| fpid || First Party ID || created using the UUID Generator code provided / validity time 180 days. ||
|-
| fpcrtm || Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds) || custom ||
|-
|hem_sha1 || hashed (SHA256) value of member id || i.e. for the sample memberID "userMemberID123", the value to pass is "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826" ||
|-
|uid2 || hashed(SHA256) value of UID2 || i.e. for the sample UID2 "userUID2", the value to pass is i.e. "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05" ||
|-
|hem_sha256 || hashed(SHA256) value of the user email address || i.e. for the sample email address "useremail@company.com", the value to pass is "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969" ||
|-
|uoo || device opt-out status || "true" for opted out, "false" for NOT opted out or opted in. || ✓

|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique streamid for each video play using UUID Generator code provided
"streamended": "1",
"assetid": "VA12345",
"secondscr": "MIR",
"position": [
{
"referencestart": "1628735452",
"referenceend": "1628736052",
"playheadstart": "0",
"playheadend": "600"
}
],
"xdua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130Safari/537.36",
"xff": "4.12.345.67",

"uid2": "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
"device_id": "8ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"hem_sha1": "9ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"hem_sha256": "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
"uoo": "false",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000",
}

</syntaxhighlight>

===== Metadata based on User Consent in your App =====

In collaboration with Mediametrie, the following user consent use cases need to be implemented in your App.

====== The user explicitly accepts measurement ======
All Device/User IDs are captured in the Nielsen S2S Metadata. The Opt-in Flag is set to "false" and all IDs have to be set accordingly:
<syntaxhighlight lang="javascript">
{
"device_id": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"hem_sha1": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"uid2": "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
"hem_sha256": "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
"uoo"": "false",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000"
}
</syntaxhighlight>

====== The user explicitly refuses measurement ======
The Nielsen S2S is NOT initiated and No Nielsen S2S measurement will occur.

======The user did not explicitly give consent for the measurement(consent neither given nor refused) ======
The Nielsen S2S is initiated and no IDs are captured. The Nielsen S2S Opt-out Flag is set to "true" and all Device/User IDs are empty:
<syntaxhighlight lang="javascript">
{
"device_id": "",
"hem_sha1": "",
"uid2": "",
"hem_sha256": "",
"uoo"": "true",
"fpid": "",
"fpcrtm": ""
}
</syntaxhighlight>

==OTT, Mirroring, and Casting==

For apps native to the OTT device (i.e. downloading and viewing a streaming app to an Apple
TV, audit ping should fire from OTT device, and Viewing data should reside in OTT Viewing file.
For mirroring, where video playback occurs on the mobile device and OTT device, only one
Viewing file row is necessary where, if possible to determine, set: "secondscr":"MIR" and
include in respective mobile platform Viewing file.

For a casting scenario where content is controlled via the mobile device, but displayed only on
the OTT device such as an AppleTV or Chromecast, an audit ping must fire from the mobile
device before the casting occurs and at the end of playback from the mobile device only.
Viewing data resides in respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx123",
"referenceend": "xxxxxxx183",
'''"playheadstart": "0",'''
'''"playheadend": "60"'''
},
{
"referencestart": "xxxxxxx243",
"referenceend": "xxxxxxx303",
'''"playheadstart": "120",'''
'''"playheadend": "180"'''
}
]
}

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx183",
"referenceend": "xxxxxxx243",
'''"playheadstart": "60",'''
'''"playheadend": "120"'''
}
],
'''"secondscr": "OTT"'''
}

==S2S Audit Ping Specifications==

=== Introduction ===
The Nielsen server to server solution needs audit pings to validate audience reach and video viewing duration, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.

'''start audit ping(“Startstream = 1”)'''
* A start audit ping is sent when the stream starts(playback start).
* Also a new start audit ping is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
'''end audit ping(“Endstream = 3”)'''
* An end audit ping is sent when the stream ends(either playback completed or switch to another stream).
* Also an end audit ping is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.

=== Ping Structure ===
Ping should be named with following convention structure:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(Please note that this URL could change as we respond to security upgrades in the market.)
The Start Audit Ping will carry all parameters in the matrix below. The End Audit Ping will carry a subset of the parameters in the matrix below as denoted in the mandatory column.
Under normal operating circumstances, the Nielsen collection system will return return codes:
* For security reasons, downstream servers reject cross-origin HTTP requests with preflight. To ensure that audit ping requests are accepted, allowable Content-Types like "text/plain" in simple GET requests ensure that preflight requests are not invoked, which is the preferred behavior.
* 200: The ping was successfully received, inspect traffic to ensure no CORS errors

=== Ping Session & Stream Details ===

==== Sessions ====
* a) When a new player is created a session id is also created.
* b) If you have more than one video player within the same App (e.g. picture in picture) you must use a different session id for each.

==== Streams ====
* a) The Distributor must generate a new UNIQUE stream id with every video stream playback.
* b) If two people watch the same show, they would have different stream id's as Nielsen would expect the stream id(“streamid”) to be a random GUId generated by the client device.
* c) If one person watches a show, and FF, rewind, playout, pause, play, RW, play - they would keep the same stream id(“streamid”) throughout the entire playout of that video asset (stream).
* d) If a stream play out is suspended for 30 mins or more (paused or background):
** An end audit ping(“Endstream = 3”) is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.
** A new start audit ping(“Startstream = 1”) is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
* e) If the user reaches the very end of the stream (content complete), and then starts to play again (replay from anywhere in the stream), then a new “streamid” should be created and a start audit ping should be sent. Also an end audit should be sent when the stream replay is completed or the user switches to another stream.

====Audit Pings ====
* a) Audit pings should be fired at the '''beginning''' and '''end''' of a stream. These will be referred to as the Audit Start Ping and the Audit End Ping.

==== query param list ====

Example:

'''Required S2S Audit Ping Query String Parameters - Note: All parameters are case sensitive'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || Unique ID assigned to the player/site and configured by your Nielsen Technical Account Manager.
|| Example: '''FC984EC1-E044-B465-E040-070AAD3173A1''' || ✓
|-
| intid || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || || ✓
|-
| sessionid || Unique, client-generated value that represents the start of a user browsing session. Must match sessionid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| streamid || Unique Id for every new instance of a client video asset playout. Must match streamid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| pingtype || pingtype Indicator for state type: “start” or “end” audit ping & if the ping is for a stream ||
* Startstream = 1
* Startsession=0
* Endstream = 3
* Endsession=2
|| ✓
|-
| product || Indicates which Nielsen product the audit ping corresponds to. || dcr || ✓
|-
| createtm || Time the ping was fired: utc (in seconds) If server time available, use it instead of device time || || ✓
|-
| devid || devid, SHA-256 value of Device Id (IDFA, ADID) - OPTIONAL is passed in the Asset Viewing File || || ✓
|-
| uoo || device opt-out status || "true" for opted out, "false" for NOT opted out or opted in.|| ✓
|}

'''Generic Ping Format:'''

<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=<App id>&sessionid=<Session Id>&streamid=<Stream Id>&pingtype=<Ping Type>&product=<dcr or dtvr>&sup=<suppress demo look-up>&uoo=<Optout Status >&createtm=<Session Start or End time>&devid=<IDFA/ADID>'''
</nowiki></code>

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&sessionid=2576459933726989&streamid=3679422587354472&pingtype=false&product=dcr&sup=0&uoo=1&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8'
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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>

DCR Italy Static Google AMP Cloud API

2026-01-22T10:08:54Z

MichelFodjo: /* Metadata Keys */ ui minor fix

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

This guide will show you how to enable Digital Content Ratings (DCR) Static measurement on Google AMP.

== Import AMP Analytics Javascript Library ==
If you have not already, you will need to import the AMP JS library in the <code><head></code> of your webpage in order to make an AMP page:
<syntaxhighlight lang="html"><script async src="https://cdn.ampproject.org/v0.js"></script></syntaxhighlight>

Next, please ensure that the following line is included in the <code><head></code> of the webpage:
<syntaxhighlight lang="html"><script async custom-element="amp-analytics" src="https://cdn.ampproject.org/v0/amp-analytics-0.1.js"></script></syntaxhighlight>
<blockquote>'''Note''': AMP pages require all traffic to be using HTTPS, including the webpage itself</blockquote>

== Specify the Analytics Provider ==
DCR measurement can be added to your AMP pages through the AMP-Analytics element:
<syntaxhighlight lang="html"><amp-analytics type="nielsen">

</amp-analytics></syntaxhighlight>

For more information on the Analytics type, you can refer to the [https://www.ampproject.org/docs/analytics/analytics-vendors Analytics vendors] section of Google's AMP Developer Documentation.

== Configure Metadata ==
You will need to match the metadata fields on your AMP page with those of your non-AMP page.

=== Metadata Keys ===
The Nielsen reserved keys are:
{| class="wikitable"
|-
! Key !! Description !! Example Value !! Required
|-
| apid || unique ID assigned by Nielsen || <code>XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</code> || ✓
|-
| prefix || URL prefix to allow EU data collection|| <code>eu-</code> || ✓
|-
| apv || current version of the Nielsen implementation || <code>1.0</code> || ✓
|-
| apn || name of the website || <code>My AMP Website</code> || ✓
|-
| section || section of the site to be measured || <code>EntityName_AMP</code> || ✓
|-
| segA || custom segment to be used to break out reporting || <code>NA</code> || ✓
|-
| segB || custom segment to be used to break out reporting || <code>NA</code> || ✓
|-
| segC || Reserved custom segment for Google AMP || <code>Google AMP</code> || ✓
|-
| uoo || opt-out parameter, it must be set to true when the user does not explicitly give consent otherwise do not include this uoo parameter in the "vars " section || <code>"uoo":"true"</code> || ✓
|}

The values passed through the Nielsen keys will determine the breakouts you will see in reporting. If you decide not to use custom segments A and B, then you do not need to pass a value in these keys. It is suggested you use the same segments used in non-AMP pages.
<blockquote>'''Note''': The value for the 'apid' you pass for AMP measurement should not include the 'P' prefix that is otherwise present on other SDK-related implementations</blockquote>

=== Metadata for Reporting ===
You can reference the table to determine how the metadata you pass is used to define your reporting structure:
{| class="wikitable"
|-
! Reporting Level !! Key !! Description
|-
| Brand/Sub-brand || apid || brand and sub-brand are determined by assigned App ID passed during initialization
|-
| Section || section || section or category for the AMP page
|-
| Custom Segment A || segA || available segment for custom reporting. Custom segments will roll into the sub-brand
|-
| Custom Segment B || segB || available segment for custom reporting. Custom segments will roll into the sub-brand
|-
| Custom Segment C || segC || Custom segment C is reserved for reporting ‘Google AMP’. The Google AMP custom segment will be available under sub-brand and will include the total metrics for all your AMP pages
|}

If you would like your AMP pages to report into the same reporting structure as your website, we recommend passing the same dynamic metadata in Section, Custom Segment A, and Custom Segment B as you are on your website. This way your AMP pageviews contribute to those aggregations.

== Example Implementation ==
The below is an example implementation of Nielsen measurement on an AMP page:
<syntaxhighlight lang="html"><amp-analytics type="nielsen">
<script type="application/json">
{
"vars": {
"apid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"prefix": "eu-",
"apv": "1.0",
"apn": "My AMP Website",
"section": "EntityName_AMP",
"segA": "NA",
"segB": "NA",
"segC": "Google AMP"
}
}
</script>
</amp-analytics></syntaxhighlight>

You can find more information about dynamic variables on [https://github.com/ampproject/amphtml/blob/master/spec/amp-var-substitutions.md#page-and-content Google's AMP documentation].

<blockquote>'''Note''': append <code>#development=1</code> at the end of your URL to see AMP debug logs in the console. This can be helpful when troubleshooting</blockquote>

=== Static Measurement on Google AMP based on User Consent ===

This document addresses the handling of personal data collected through the Google AMP Nielsen integration for Audicom in Italy. The document has a specific focus on the implementation of the user consent use cases to collect personal identifiers (IDs) through Google AMP Nielsen measurement based on the user's privacy choice.

==== Consent granted: the user explicitly accepts ====

====== User opted in ======
<syntaxhighlight lang="html"><amp-analytics type="nielsen">
<script type="application/json">
{
"vars": {
"apid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"prefix": "eu-",
"apv": "1.0",
"apn": "My AMP Website",
"section": "EntityName_AMP",
"segA": "NA",
"segB": "NA",
"segC": "Google AMP"
}
}
</script>
</amp-analytics></syntaxhighlight>

==== Consent denied: the user does not explicitly give consent ====
Should a Nielsen third party cookie (IMRID) already exist, the browser will send that automatically with the ping; in such a case, the flags would instruct the Nielsen backend to drop the cookie information and make no use of it.
The client needs to add the '''''uoo''''' parameter with its value equal to '''''true''''' in the '''''"vars"''''' section and the request call in the '''''"requests"''''' section. Please do not modify the request call.

'''Request call:'''
<syntaxhighlight lang="html">

"requests": {
"cloudapi": "https://${prefix}cloudapi.imrworldwide.com/nmapi/v2/${apid}/${sessionId}_${pageViewId}/a?b=%7B%22devInfo%22%3A%7B%22devId%22%3A%22${sessionId}_${pageViewId}%22%2C%22apn%22%3A%22${apn}%22%2C%22apv%22%3A%22${apv}%22%2C%22apid%22%3A%22${apid}%22%2C%22uoo%22%3A%22${uoo}%22%7D%2C%22metadata%22%3A%7B%22static%22%3A%7B%22type%22%3A%22static%22%2C%22section%22%3A%22${section}%22%2C%22assetid%22%3A%22${pageViewId}%22%2C%22segA%22%3A%22${segA}%22%2C%22segB%22%3A%22${segB}%22%2C%22segC%22%3A%22${segC}%22%2C%22adModel%22%3A%220%22%2C%22dataSrc%22%3A%22cms%22%7D%2C%22content%22%3A%7B%7D%2C%22ad%22%3A%7B%7D%7D%2C%22event%22%3A%22playhead%22%2C%22position%22%3A%22${timestamp}%22%2C%22data%22%3A%7B%22hidden%22%3A%22${backgroundState}%22%2C%22blur%22%3A%22${backgroundState}%22%2C%22position%22%3A%22${timestamp}%22%7D%2C%22type%22%3A%22static%22%2C%22utc%22%3A%22${timestamp}%22%2C%22index%22%3A%22${requestCount}%22%2C%22pageURL%22%3A%22${ampdocUrl}%22%7D"

}
</syntaxhighlight>

====== User opted out ======
<syntaxhighlight lang="html"><amp-analytics type="nielsen">
<script type="application/json">
{
"vars": {
"apid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"prefix": "eu-",
"apv": "1.0",
"apn": "My site",
"section": "EntityName_AMP",
"segA": "NA",
"segB": "NA",
"segC": "Google AMP",
"uoo" : "true"
},
"requests": {
"cloudapi": "https://${prefix}cloudapi.imrworldwide.com/nmapi/v2/${apid}/${sessionId}_${pageViewId}/a?b=%7B%22devInfo%22%3A%7B%22devId%22%3A%22${sessionId}_${pageViewId}%22%2C%22apn%22%3A%22${apn}%22%2C%22apv%22%3A%22${apv}%22%2C%22apid%22%3A%22${apid}%22%2C%22uoo%22%3A%22${uoo}%22%7D%2C%22metadata%22%3A%7B%22static%22%3A%7B%22type%22%3A%22static%22%2C%22section%22%3A%22${section}%22%2C%22assetid%22%3A%22${pageViewId}%22%2C%22segA%22%3A%22${segA}%22%2C%22segB%22%3A%22${segB}%22%2C%22segC%22%3A%22${segC}%22%2C%22adModel%22%3A%220%22%2C%22dataSrc%22%3A%22cms%22%7D%2C%22content%22%3A%7B%7D%2C%22ad%22%3A%7B%7D%7D%2C%22event%22%3A%22playhead%22%2C%22position%22%3A%22${timestamp}%22%2C%22data%22%3A%7B%22hidden%22%3A%22${backgroundState}%22%2C%22blur%22%3A%22${backgroundState}%22%2C%22position%22%3A%22${timestamp}%22%7D%2C%22type%22%3A%22static%22%2C%22utc%22%3A%22${timestamp}%22%2C%22index%22%3A%22${requestCount}%22%2C%22pageURL%22%3A%22${ampdocUrl}%22%7D"

}
}

</script>
</amp-analytics></syntaxhighlight>

====== Sample Google AMP page ======
Here is a sample AMP page for Google AMP Nielsen implementation that uses the AMP Consent component.

https://nielsenonlinesupport.com/wilson/ampstatic

AMP Consent component:
<syntaxhighlight lang="html"><script async custom-element="amp-consent" src="https://cdn.ampproject.org/v0/amp-consent-0.1.js"></script></syntaxhighlight>

== Privacy Policy ==
Nielsen uses cookies for browser measurement. In order to comply with our privacy restrictions, we ask that you make a link to our Digital Privacy Policy available on your site. You can find our privacy policy here: https://global.nielsen.com/legal/privacy-principles/digital-measurement-privacy-statement/?lang=it

DCR France Video S2S

2026-01-21T11:30:29Z

MichelFodjo: /* query param list */ missing "product" added as it was present only in the examples

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

= DCR Integration Utilizing S2S =
This guide shows you how to integrate the Nielsen S2S(Server to Server) to enable Digital Content Ratings (DCR), and fuel other measurement products on your Apps.

<pre style="color: orange">
PLease note that you have to use the Staging S2S Endpoint(<env>=stage)until you get the green light to move to Production, you will then get the Production S2S Endpoint!
</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 (apid)''' || Unique ID assigned to the player/site and configured by product. || Contact Médiamétrie
|-style="background-color:#d0f6f8;"
|| '''Integration ID (IntID)''' || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.) || Contact Médiamétrie
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| Contact Médiamétrie
|}

==Introduction==
This interface specification depicts the file format that needs to be used to supply Nielsen with
end-user viewing data captured by a “Server-to-Server” method for the Nielsen Digital Content
Ratings (DCR) product and Tuning data for the Digital Ads Rating (DAR) products.
* The specification is defined using a JSON schema, with each file ideally containing all the
viewing that has been captured within an hour.
* In the case of a stream that has one version with blackouts and one without, one with
mobile and one non-mobile, each stream would have it’s own unique asset id.
* The Asset Metadata file should arrive before the viewing data file for the same hour.

==SLA==
The files must be delivered into the proper S3 bucket '''immediately after each hour of viewing on a device''', but latest within 3 hour of the start of that hourly
viewing file interval. For example files from 1:00 AM to 2:00 AM must be delivered latest before 4 AM.

'''When SLA for receiving exposure file for date xx/xx, UTC hour xx has expired. The system will continue to wait for 60 min, after which it will skip the missing file and continue processing subsequent files. Any reprocessing of the missed SLA data will require an explicite request from Médiamétrie.'''

==Accuracy of the Measurement==

====Send Viewing Time (Video Player Events) At Least Each 10 Seconds To Your Backend====
Capture content viewing time each second and send the aggregated viewing time at least each 10 seconds to your backend:
* referencestart : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* referenceend : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* playheadstart : Content position start time in seconds
* playheadend : Content position end time in seconds

====Send Viewing Time When The Video Playback Is Interrupted====
Send the aggregated viewing time to your backend when the video playback is interrupted, i.e. paused.

====Capture Accurately Each Second The Viewing Time When The Network Is Lost And The Video Playback Continues====
Capture accurately each second the viewing time when the network is lost.
Send the aggregated viewing time to your backend when the network is back.

====Send The Viewing Time Early On Browser Refreshed/Closed====
Capture and send the viewing time to your backend by implementing the 2 WINDOWS EVENTS:

''' Please include a logic to make sure that only one of the 2 following event handler is executed '''
<syntaxhighlight lang="javascript">
window.addEventListener("pagehide", function (e) {
// SEND THE VIEWING TIME TO YOUR BACKEND
});
window.addEventListener("beforeunload", function (e) {
// ONLY IF pagehide" was not triggered, SEND THE VIEWING TIME TO YOUR BACKEND
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered at a fixed cadence in a dedicated S3 bucket following the outlined in this spec prefix and object naming conventions and data formats.

* All prefix labels and file names should be lowercase except for app ids.
* Supported format are:
** Uncompressed text files with utf-8 encoding in:
*** JSON format(.json);
*** PARQUET format(.parquet);
* All files should have extensions to indicate the file format (.json or .parquet)
* Data file can be partitioned into multiple parts with min size of 128MB - 256MB
* Data can be delivered separately in multiple splits(platforms), if needed due to organizational, technical or privacy requirements. This allows to permission s3 access separately, to process data independently and to persist data partitioned, within the limits of the S2S system;

===The 4 Different Files to deliver to Nielsen each hour===
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

Nielsen will move files to indicate they are being processed.

====S3 bucket and prefix(S3BucketPrefix) for all 4 Files====

All files should be delived to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| env || '''stage''' for Staging or '''prod''' for Production
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| Platform || '''ios''', '''browser''', '''android''', '''ott'''
|-
| yyyy/mm/dd/hh || UTC start of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023/02/12/05'''

|}
=====Examples for the iOS platform=====
======Asset Metadata File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====File Name(FileName) format for the Asset Metadata and Asset Viewing Files ====

Asset Metadata and Asset Viewing Files should be delivered to:
* <S3BucketPrefix>'''<FileName>'''

* '''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime><FileSuffix>

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| IntID || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.)
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || Nielsen provided server application identifier
|-
| StartTime || start date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| EndTime || end date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| yyyymmddhh || UTC time of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023021205'''

|-
| FileSuffix || Uncompressed json lines (no extension) - splittable, ideal for medium size files, '''less than 5 GB''', preferred for metadata.
'''supported:'''
* '''.json''' json file
* '''.parquet''' parquet file
|}

=====Examples for Asset Metadata and Asset Viewing Files=====
======Asset Metadata File======
Asset Metadata File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====Manifest File for the Asset Metadata and Asset Viewing Files====

The Manifest File should be delivered to: <S3BucketPrefix>'''<FileName>'''

'''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime>'''_manifest'''

A manifest contains metadata related to the uploaded file(s). It is a text file in json format that implements the AWS unload manifest file format. It follows the s3 objects naming notation, but has the _manifest suffix. Here’s an example of manifest file contents:

{
"entries": [
{"url":"s3://bucket/prefix/0000_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0001_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0002_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0003_object_00.snappy.parquet", "mandatory":true}
],
"meta": {
"schema_version": "S2SV1.7.0",
"accreditation_status": "0",
"start_time": "1710154800",
"end_time": "1710158399",
"record_count": 55
}
}

The manifest contains a complete list of all files provided for a given period and platform, as well as a meta data (a.k.a. header) which should include the following attributes:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, i.e. "S2SV1.7.0" || ✓
|-
| data_start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1710154800" || ✓
|-
| data_start_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1710158399" || ✓
|-
| record_count || Records Count in data file || Number: i.e. 55 || ✓
|}

If ‘entries’ array is not specified, or manifest file is not available, the system will still attempt to load all data file(s) (.json or .parquet) from the prefix location. Optionally the manifest file can contain the full schema of the data files as shown in the [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose manifest file format document ].

=====Example for the Manifest File=====

======Manifest File for the Asset Metadata File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"schema_version": "S2SV1.7.0",
"accreditation_status": "0",
"start_time": "1710154800",
"end_time": "1710158399",
"record_count": 15
}
</syntaxhighlight>

======Manifest File for the Asset Viewing File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"schema_version": "S2SV1.7.0",
"accreditation_status": "0",
"start_time": "1710154800",
"end_time": "1710158399",
"record_count": 55
}
</syntaxhighlight>

===Success File: Indication of a data delivery for a particular hour===

An Empty _SUCCESS file should be provided to indicate that data delivery for a particular hour and platform is completed successfully. This file should be uploaded last (after all other files). If there is no data data for a particular hour and platform, the _SUCCESS file is still required to indicate that the delivery process for the hour is completed and no data files are expected. This file is only required for integrations that support data partitioned into multiple parts. The name of the file is configurable.

====Example for Asset Viewing Delivery Files====

'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

====Example for Asset Metadata Delivery Files====
'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

====Data Delivery Example for hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):====
=====Asset Metadata Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

</code>
=====Asset Viewing Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0000.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0001.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0002.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0003.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

</code>

== S2S Metadata Specifications for the Asset Metadata and Asset Viewing Files ==

=== Asset Metadata File ===

The Asset Metadata File contains 1 Header Record followed by Body Records

====Header Record====

=====Description=====

'''Parameter Description'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.09" || ✓
|-
| mvpdid || mvpd ID specified ny Nielsen || String, i.e. "NLSN" || ✓
|-
| creationtime || File creation time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓

|-
| recordcount || Records Count in body of file ||String, i.e. "1" for only 1 Record || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.09",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''. 
'''Note:''' ''' Do not include personal data '''in the content metadata. 

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| assetid || unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| programname || name of program || custom || ✓
|-
| episodetitle || episode name || custom || ✓
|-
| episodelen || 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)|| ✓
|-
|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
||
✓
|-
| cli_md || mode: allows to know the streaming type || possible values provided by Médiamétrie: "LIVE" "TIMESHIFTING" "TVOD" "VOD" "SVOD" "AOD"||
|-
| cli_ch || Channel identifier: values decided by Médiamétrie and provided to the broadcaster || sample value: "860" ||
|-
| cli_cn || content identifier as used / categorized by the publisher || custom ||
|-
| nol_p0 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p1 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p2 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p3 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p4 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p5 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p6 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p7 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p8 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p9 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p10 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p11 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p12 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p13 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p14 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p15 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p16 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p17 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p18 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p19 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"program" : "program name",
"title" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c05",
"cli_md": "LIVE",
"cli_ch": "860",
"cli_cn": "customCuntentIdentifier",
"nol_p0": "p0,optionalValueP0",
"nol_p1": "p1,optionalValueP1",
// ... continued - 20 custom variables
"nol_p18": "p18,optionalValueP18",
"nol_p19": "p19,optionaValuelP19"
}
</syntaxhighlight>

=== Asset Viewing File ===

The Asset Viewing File contains 1 Header Record followed by Body Records
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''.
<pre style="color: orange">
Please do not include ZERO DURATION viewing portion in the Asset Viewing File.
</pre>

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.0" || ✓
|-
| appid || Nielsen provided server application identifier || String, i.e. "P47C2495B-XXXX-56DE-BE99-14758F92F034" || ✓
|-
| type || Type of the data || String, "content" || ✓
|-
| producttype || Product Type || String, "DCR" || ✓
|-
| starttime || Viewing Data Start Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓
|-
| endtime || Viewing Data End Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473791507"|| ✓
|-
| recordcount || Records Count in body of file || String, i.e. "100" for only 100 Records || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.0",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apn || app name || i.e. "BestAppIOS" || ✓
|-
| apv || app build version || i.e. "1.3" || ✓
|-
| sessionid || Unique, client generated value that represents the start of a user session. Must match sessionid in Audit Ping. || created using the UUID Generator code provided || ✓
|-
| streamid || streamid ID for every new instance of an asset || created using the UUID Generator code provided || ✓
|-
| streamended || Stream is known to have ended in this file ||
* "1" (stream will continue in next file)
* "2" (stream closed)
|| ✓
|-
| secondscr || Second Screen Indicator. For Mirroring & Extended Screen via OTT device scenarios ||
* "" (empty String if viewed directly on the device)
* "MIR" (Mirroring)
* "OTT" (Extended Screen via OTT device)
|| ✓
|-
| assetid || unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''Description:'''
* '''referencestart''' : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* '''referenceend''' : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* '''playheadstart''' : Content position start time in seconds
* '''playheadend''' : Content position end time in seconds

'''For Content position start and end time(playheadstart, playheadend):'''
* For VoD stream use the player position for Content as the playhead position in seconds. At playback start of a content from the begin, playheads will then be 0,1,2,3,....
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position in seconds.

'''Additional Notes:'''
* For viewing gaps < than 1 second, the gap can be smoothed over
* For playouts that are abandoned before the first whole second of viewing is rendered, a position record of zero duration should be created. IF an audit ping has already been fired See below for additional details on position array parameters
|| ✓
|-
| device_id || '''MANDATORY ONLY for android platform.''' Mobile Ad ID IDFA,ADID, Connected Device ID 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" || i.e "12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8" || ✓
|-
| xdua || Device HTTP raw User Agent string - OPTIONAL if passed in the Audit Ping to the Nielsen Server|| Example: "Apple-iPhone1C2/801.293" || ✓
|-
| xff || IP address - OPTIONAL if passed in the Audit Ping to the Nielsen Server|| Format: "xxx.xxx.xxx.xxx" or "xxx.xxx.xxx.000"
Examples :
* IPV4: "4.12.345.67"
* IPV6: "2600:6c58:7900:33f2:2505:42b9:5a34:0000"
|| ✓
|-
| fpid || First Party ID || created using the UUID Generator code provided / validity time 180 days. ||
|-
| fpcrtm || Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds) || custom ||
|-
|hem_sha1 || hashed (SHA256) value of member id || i.e. for the sample memberID "userMemberID123", the value to pass is "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826" ||
|-
|uid2 || hashed(SHA256) value of UID2 || i.e. for the sample UID2 "userUID2", the value to pass is i.e. "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05" ||
|-
|hem_sha256 || hashed(SHA256) value of the user email address || i.e. for the sample email address "useremail@company.com", the value to pass is "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969" ||
|-
|uoo || device opt-out status || "true" for opted out, "false" for NOT opted out or opted in. || ✓

|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique streamid for each video play using UUID Generator code provided
"streamended": "1",
"assetid": "VA12345",
"secondscr": "MIR",
"position": [
{
"referencestart": "1628735452",
"referenceend": "1628736052",
"playheadstart": "0",
"playheadend": "600"
}
],
"xdua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130Safari/537.36",
"xff": "4.12.345.67",

"uid2": "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
"device_id": "8ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"hem_sha1": "9ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"hem_sha256": "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
"uoo": "false",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000",
}

</syntaxhighlight>

===== Metadata based on User Consent in your App =====

In collaboration with Mediametrie, the following user consent use cases need to be implemented in your App.

====== The user explicitly accepts measurement ======
All Device/User IDs are captured in the Nielsen S2S Metadata. The Opt-in Flag is set to "false" and all IDs have to be set accordingly:
<syntaxhighlight lang="javascript">
{
"device_id": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"hem_sha1": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"uid2": "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
"hem_sha256": "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
"uoo"": "false",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000"
}
</syntaxhighlight>

====== The user explicitly refuses measurement ======
The Nielsen S2S is NOT initiated and No Nielsen S2S measurement will occur.

======The user did not explicitly give consent for the measurement(consent neither given nor refused) ======
The Nielsen S2S is initiated and no IDs are captured. The Nielsen S2S Opt-out Flag is set to "true" and all Device/User IDs are empty:
<syntaxhighlight lang="javascript">
{
"device_id": "",
"hem_sha1": "",
"uid2": "",
"hem_sha256": "",
"uoo"": "true",
"fpid": "",
"fpcrtm": ""
}
</syntaxhighlight>

==OTT, Mirroring, and Casting==

For apps native to the OTT device (i.e. downloading and viewing a streaming app to an Apple
TV, audit ping should fire from OTT device, and Viewing data should reside in OTT Viewing file.
For mirroring, where video playback occurs on the mobile device and OTT device, only one
Viewing file row is necessary where, if possible to determine, set: "secondscr":"MIR" and
include in respective mobile platform Viewing file.

For a casting scenario where content is controlled via the mobile device, but displayed only on
the OTT device such as an AppleTV or Chromecast, an audit ping must fire from the mobile
device before the casting occurs and at the end of playback from the mobile device only.
Viewing data resides in respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx123",
"referenceend": "xxxxxxx183",
'''"playheadstart": "0",'''
'''"playheadend": "60"'''
},
{
"referencestart": "xxxxxxx243",
"referenceend": "xxxxxxx303",
'''"playheadstart": "120",'''
'''"playheadend": "180"'''
}
]
}

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx183",
"referenceend": "xxxxxxx243",
'''"playheadstart": "60",'''
'''"playheadend": "120"'''
}
],
'''"secondscr": "OTT"'''
}

==S2S Audit Ping Specifications==

=== Introduction ===
The Nielsen server to server solution needs audit pings to validate audience reach and video viewing duration, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.

'''start audit ping(“Startstream = 1”)'''
* A start audit ping is sent when the stream starts(playback start).
* Also a new start audit ping is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
'''end audit ping(“Endstream = 3”)'''
* An end audit ping is sent when the stream ends(either playback completed or switch to another stream).
* Also an end audit ping is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.

=== Ping Structure ===
Ping should be named with following convention structure:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(Please note that this URL could change as we respond to security upgrades in the market.)
The Start Audit Ping will carry all parameters in the matrix below. The End Audit Ping will carry a subset of the parameters in the matrix below as denoted in the mandatory column.
Under normal operating circumstances, the Nielsen collection system will return return codes:
* For security reasons, downstream servers reject cross-origin HTTP requests with preflight. To ensure that audit ping requests are accepted, allowable Content-Types like "text/plain" in simple GET requests ensure that preflight requests are not invoked, which is the preferred behavior.
* 200: The ping was successfully received, inspect traffic to ensure no CORS errors

=== Ping Session & Stream Details ===

==== Sessions ====
* a) When a new player is created a session id is also created.
* b) If you have more than one video player within the same App (e.g. picture in picture) you must use a different session id for each.

==== Streams ====
* a) The Distributor must generate a new UNIQUE stream id with every video stream playback.
* b) If two people watch the same show, they would have different stream id's as Nielsen would expect the stream id(“streamid”) to be a random GUId generated by the client device.
* c) If one person watches a show, and FF, rewind, playout, pause, play, RW, play - they would keep the same stream id(“streamid”) throughout the entire playout of that video asset (stream).
* d) If a stream play out is suspended for 30 mins or more (paused or background):
** An end audit ping(“Endstream = 3”) is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.
** A new start audit ping(“Startstream = 1”) is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
* e) If the user reaches the very end of the stream (content complete), and then starts to play again (replay from anywhere in the stream), then a new “streamid” should be created and a start audit ping should be sent. Also an end audit should be sent when the stream replay is completed or the user switches to another stream.

====Audit Pings ====
* a) Audit pings should be fired at the '''beginning''' and '''end''' of a stream. These will be referred to as the Audit Start Ping and the Audit End Ping.

==== query param list ====

Example:

'''Required S2S Audit Ping Query String Parameters - Note: All parameters are case sensitive'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || Unique ID assigned to the player/site and configured by your Nielsen Technical Account Manager.
|| Example: '''FC984EC1-E044-B465-E040-070AAD3173A1''' || ✓
|-
| intid || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || || ✓
|-
| sessionid || Unique, client-generated value that represents the start of a user browsing session. Must match sessionid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| streamid || Unique Id for every new instance of a client video asset playout. Must match streamid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| pingtype || pingtype Indicator for state type: “start” or “end” audit ping & if the ping is for a stream ||
* Startstream = 1
* Startsession=0
* Endstream = 3
* Endsession=2
|| ✓
|-
| product || Indicates which Nielsen product the audit ping corresponds to. || dcr || ✓
|-
| createtm || Time the ping was fired: utc (in seconds) If server time available, use it instead of device time || || ✓
|-
| devid || devid, SHA-256 value of Device Id (IDFA, ADID) - OPTIONAL is passed in the Asset Viewing File || || ✓
|}

'''Generic Ping Format:'''

<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=<App id>&sessionid=<Session Id>&streamid=<Stream Id>&pingtype=<Ping Type>&product=<dcr or dtvr>&sup=<suppress demo look-up>&uoo=<Optout Status >&createtm=<Session Start or End time>&devid=<IDFA/ADID>'''
</nowiki></code>

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&sup=0&uoo=1&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8'
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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>

DCR Germany Video S2S

2026-01-21T11:27:55Z

MichelFodjo: /* query param list */ missing "product" field added , it was present in the examples but missing in the description

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

= DCR Integration Utilizing S2S =
<pre style="color: red"; font-weight: bold;>
Please contact AGF before you start working on a S2S Integration!
</pre>

This guide shows you how to integrate the Nielsen S2S (Server to Server) to enable Digital Content Ratings (DCR), and fuel other measurement products on your Apps.

<pre style="color: orange"; font-weight: bold;>
PLease note that you have to use the Staging S2S Endpoint(<env>=stage)until you get the green light to move to Production, you will then get the Production S2S Endpoint!
</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
|-style="background-color:#d0f6f8;"
|| '''Integration ID (IntID)''' || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || Provided by Nielsen
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| Provided by Nielsen
|}

==Introduction==
This interface specification depicts the file format that needs to be used to supply Nielsen with
end-user viewing data captured by a “Server-to-Server” method for the Nielsen Digital Content
Ratings (DCR) product and Tuning data for the Digital Ads Rating (DAR) products.
* The specification is defined using a JSON schema, with each file ideally containing all the
viewing that has been captured within an hour.
* In the case of a stream that has one version with blackouts and one without, one with
mobile and one non-mobile, each stream would have its own unique asset id.
* The Asset Metadata file should arrive before the viewing data file for the same hour.

==SLA==
The files must be delivered into the proper S3 bucket '''immediately after each hour of viewing on a device''', but '''latest within 3 hours of the start of that hourly viewing file interval'''. For example, files from '''2:00 AM to 3:00 AM''' must be delivered latest before '''5 AM'''.

'''When SLA for receiving an exposure file for date xx/xx, UTC hour xx has expired. The system will continue to wait for 60 min, after which it will skip the missing file and continue processing subsequent files. Any reprocessing of the missed SLA data will require an explicit request from AGF.'''

==Accuracy of the Measurement==

====Send Viewing Time (Video Player Events) At Least Each 10 Seconds To Your Backend====
Capture content viewing time each second and send the aggregated viewing time at least each 10 seconds to your backend:
* referencestart : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* referenceend : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* playheadstart : Content position start time in seconds
* playheadend : Content position end time in seconds

====Send Viewing Time When The Video Playback Is Interrupted====
Send the aggregated viewing time to your backend when the video playback is interrupted, i.e. paused.

====Capture Accurately Each Second The Viewing Time When The Network Is Lost And The Video Playback Continues====
Capture accurately each second the viewing time when the network is lost.
Send the aggregated viewing time to your backend when the network is back.

====Send The Viewing Time Early On Browser Refreshed/Closed====
Capture and send the viewing time to your backend by implementing the 2 WINDOWS EVENTS:

''' Please include a logic to make sure that only one of the 2 following event handler is executed '''
<syntaxhighlight lang="javascript">
window.addEventListener("pagehide", function (e) {
// SEND THE VIEWING TIME TO YOUR BACKEND
});
window.addEventListener("beforeunload", function (e) {
// ONLY IF pagehide" was not triggered, SEND THE VIEWING TIME TO YOUR BACKEND
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered at a fixed cadence in a dedicated S3 bucket following the outlined in this spec prefix and object naming conventions and data formats.

* All prefix labels and file names should be lowercase except for app ids.
* Supported formats are:
** Uncompressed text files with utf-8 encoding in:
*** JSON format(.json);
*** PARQUET format(.parquet);
* All files should have extensions to indicate the file format (.json or .parquet)
* Data file can be partitioned into multiple parts with min size of 128MB - 256MB
* Data can be delivered separately in multiple splits(platforms), if needed due to organizational, technical or privacy requirements. This allows to permission s3 access separately, to process data independently and to persist data partitioned, within the limits of the S2S system;

===The 4 Different Files to deliver to Nielsen each hour===
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

Nielsen will move files to indicate they are being processed.

====S3 bucket and prefix(S3BucketPrefix) for all 4 Files====

All files should be delivered to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| env || '''stage''' for Staging or '''prod''' for Production
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| Platform || '''ios''', '''browser''', '''android''', '''ott'''. Only for the Asset Metadata Optimization use case, '''all''' is used additionally, see [[#Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day|Optimization for all Platforms]]
|-
| yyyy/mm/dd/hh || UTC start of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023/02/12/05'''

|}
=====Examples for the iOS platform=====
======Asset Metadata File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====File Name(FileName) format for the Asset Metadata and Asset Viewing Files ====

Asset Metadata and Asset Viewing Files should be delivered to:
* <S3BucketPrefix>'''<FileName>'''

* '''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime><FileSuffix>

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| IntID || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.)
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || Nielsen provided server application identifier
|-
| StartTime || start date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| EndTime || end date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| yyyymmddhh || UTC time of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023021205'''

|-
| FileSuffix || Uncompressed json lines (no extension) - splittable, ideal for medium size files, '''less than 5 GB''', preferred for metadata.
'''supported:'''
* '''.json''' json file
* '''.parquet''' parquet file
|}

=====Examples for Asset Metadata and Asset Viewing Files=====
======Asset Metadata File======
Asset Metadata File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====Manifest File for the Asset Metadata and Asset Viewing Files====

The Manifest File should be delivered to: <S3BucketPrefix>'''<FileName>'''

'''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime>'''_manifest'''

A manifest contains metadata related to the uploaded file(s). It is a text file in json format that implements the AWS unload manifest file format. It follows the s3 objects naming notation, but has the _manifest suffix. Here’s an example of manifest file contents:

{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}

The manifest contains a complete list of all files provided for a given period and platform, as well as a meta data (a.k.a. header) which should include the following attributes:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, i.e. "S2SV1.7.0" || ✓
|-
| start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653476400" || ✓
|-
| end_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1653479999" || ✓
|-
| record_count || Records Count in data file || Number: i.e. 55 || ✓
|}

If ‘entries’ array is not specified, or manifest file is not available, the system will still attempt to load all data file(s) (.json or .parquet) from the prefix location. Optionally the manifest file can contain the full schema of the data files as shown in the [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose manifest file format document ].

=====Example for the Manifest File=====

======Manifest File for the Asset Metadata File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

======Manifest File for the Asset Viewing File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"uploaded file url",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

===Success File: Indication of a data delivery for a particular hour===

An Empty _SUCCESS file should be provided to indicate that data delivery for a particular hour and platform is completed successfully. This file should be uploaded last (after all other files). If there is no data data for a particular hour and platform, the _SUCCESS file is still required to indicate that the delivery process for the hour is completed and no data files are expected. This file is only required for integrations that support data partitioned into multiple parts. The name of the file is configurable.

====Example for Asset Viewing Delivery Files====

'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

====Example for Asset Metadata Delivery Files====
'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

====Data Delivery Example for hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):====
=====Asset Metadata Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

</code>
=====Asset Viewing Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0000.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0001.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0002.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0003.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

</code>

===Asset Metadata Delivery Optimization===

====Optimization when the Asset Metadata File remains unchanged during the whole day per platform====

When the Asset Metadata File remains unchanged during the whole day per platform, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location per platform.

The File could then be delivered at the first hour of the day(00:00:00 AM UTC to 00:59:59 PM UTC) and it will be referenced in the manifest file for the following 23 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 11 , referencing to the Asset Metadata File for HOUR 00'''

=====Asset Metadata File for the hour 11:00:00 AM UTC to 11:59:59 PM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the Asset Metadata File for HOUR 00):'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json",
"mandatory":true
}
],
"meta": {
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS
</code>

=====Asset Metadata File for the hour 00:00:00 AM UTC to 00:59:59 PM UTC=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json
</code>

'''Manifest File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653436800",
"end_time": "1653440399",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/00/_SUCCESS
</code>

====Optimization for all Platforms when the Asset Metadata File remains unchanged for all platforms during the whole day====

When the Asset Metadata File remains unchanged for all platforms during the whole day, the hourly manifest File of the Asset Metadata File can be used to link to the Asset Metadata File Location for all platforms.

The Asset Metadata File could then be delivered at the first hour of the day(00:00:00 AM UTC to 00:59:59 PM UTC) and it will be referenced hourly in the manifest file for all the 24 hours of the day.

'''The Example below illustrates the use of the manifest file for HOUR 11 , referencing to the global Asset Metadata File'''

=====Asset Metadata File for the hour 11:00:00 AM UTC to 11:59:59 PM UTC=====

'''Manifest File for the Asset Metadata File (referencing to the global Asset Metadata File):'''

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653476400",
"end_time": "1653479999",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS
</code>

=====Global Asset Metadata File for the hour 00:00:00 AM UTC to 00:59:59 PM UTC for all Platforms=====

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json
</code>

'''Manifest File for the global Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501_manifest
</code>

'''Manifest File Content:'''
<syntaxhighlight lang="javascript">
{
"entries": [
{
"url":"euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_2022052500_2022052501.json",
"mandatory":true
}
],
"schema_version": "S2SV1.7.0",
"start_time": "1653436800",
"end_time": "1653440399",
"record_count": 55
}
</syntaxhighlight>

'''Success File for the Asset Metadata File:'''

<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/all/2022/05/25/00/_SUCCESS
</code>

== S2S Metadata Specifications for the Asset Metadata and Asset Viewing Files ==

=== Asset Metadata File ===

The Asset Metadata File contains 1 Header Record followed by Body Records

====Header Record====

=====Description=====

'''Parameter Description'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.09" || ✓
|-
| mvpdid || mvpd ID specified ny Nielsen || String, i.e. "NLSN" || ✓
|-
| creationtime || File creation time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓

|-
| recordcount || Records Count in body of file ||String, i.e. "1" for only 1 Record || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.09",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====

'''<pre style="color: red">NOTE:</pre>'''
* All metadata values should be passed as '''UTF-8 strings'''.
* '''For the correct filling of the metadata fields and custom variables, please make sure to follow the detailed information and specifications regarding the permitted characters and formats, field length and other limitations in the AGF metadata convention for video measurement, see:'''
** '''[[AGF Metadata Convention#Video Measurement|AGF Metadata Convention for Video Measurement]]'''

{| class="wikitable"
|-
! Keys !! AGF Metadata Convention Name - <pre style="color: orange">
Only for your Reference
</pre> !! Description !! Values !! Required
|-
| assetid || assetid|| unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| programname || program || name of program || custom || ✓
|-
| episodetitle || title || episode name || custom - no backslash allowed in string (because of 3rd party data processing) || ✓
|-
| episodelen || 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)|| ✓
|-
|islivestn || N/A|| Indicates if a stream is playing on a live channel
||
:
* "y" playing on a live channel
* "n" otherwise i.e. VoD
||
✓
|-
| subbrand || subbrand (vcid) || 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
||

|-
| nol_c0 || nol_c0 || number of episode part (Sendungsteilenummer) || custom, if a content is not divided into several episode parts, set "0" as value. || ✓
|-
| nol_c2 || nol_c2 || web only || custom. The custom variable "web-only" specifies whether the streaming content is made available exclusively on the internet (web-only, "Y") or also made available on linear TV (web-only, "N")|| ✓
|-
| nol_c5 || nol_c5 || page URL || custom, The “Page URL” custom variable is reserved for sending the video’s server address. ||
|-
| nol_c7 || nol_c7 || Video ID. This variable is applicable in case the video asset is broken into multiple files each with their own asset ID. If a client has a single asset for a given episode/program, the value here should be identical to the assetid already provided in the viewership file.
|| custom || ✓
|-
| nol_c9 || nol_c9 || episode title || custom - no backslash allowed in string (because of 3rd party data processing). if no further differentiation, then use "episodetitle" || ✓
|-
| nol_c10 || nol_c10 || publisher || custom, used to differentiate different publishers || ✓
|-
| nol_c12 || nol_c12 || type of asset || "Trailer" or "Content" || ✓
|-
| nol_c15 || nol_c15 || format ID || If nol_c2 is always Yes, then it can stay blank "" ||
|-
| nol_c16 || 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 || nol_c18 || is a live stream || "Y" for live stream otherwise "N" || ✓
|-style="background-color:#d0f6f8;"
| nol_c8 || nol_c8 || not in use || leave blank "", reserved for AGF ||
|-style="background-color:#d0f6f8;"
| nol_c13 || nol_c13 || custom variable || custom ||
|-style="background-color:#d0f6f8;"
| nol_c14 || nol_c14 || not in use || leave blank "", reserved for AGF ||
|-style="background-color:#d0f6f8;"
| nol_c19 || nol_c19 || custom variable || custom ||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"programname" : "program name",
"episodetitle" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c02",
"nol_c0": "p0,3",
"nol_c2": "p2,Y",
"nol_c7": "p7,videoid123",
"nol_c9": "p9,VideoTitle123",
"nol_c10": "p10,publisherName",
"nol_c12": "p12,Content",
"nol_c18": "p18,N"
}
</syntaxhighlight>

=== Asset Viewing File ===

The Asset Viewing File contains 1 Header Record followed by Body Records
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''.

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.0" || ✓
|-
| appid || Nielsen provided server application identifier || String, i.e. "P47C2495B-XXXX-56DE-BE99-14758F92F034" || ✓
|-
| type || Type of the data || String, "content" || ✓
|-
| producttype || Product Type || String, "DCR" || ✓
|-
| starttime || Viewing Data Start Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓
|-
| endtime || Viewing Data End Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473791507"|| ✓
|-
| recordcount || Records Count in body of file || String, i.e. "100" for only 100 Records || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.0",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apn || app name || i.e. "BestAppIOS" || ✓
|-
| apv || app build version || i.e. "1.3" || ✓
|-
| sessionid || Unique, client generated value that represents the start of a user session. Must match sessionid in Audit Ping. || created using the UUID Generator code provided || ✓
|-
| streamid || streamid ID for every new instance of an asset || created using the UUID Generator code provided || ✓
|-
| streamended || Stream is known to have ended in this file ||
* "1" (stream will continue in next file)
* "2" (stream closed)
|| ✓
|-
| secondscr || Second Screen Indicator. For Mirroring & Extended Screen via OTT device scenarios ||
* "" (empty String if viewed directly on the device)
* "MIR" (Mirroring)
* "OTT" (Extended Screen via OTT device)
|| ✓
|-
| assetid || unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''Description:'''
* '''referencestart''' : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* '''referenceend''' : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* '''playheadstart''' : Content position start time in seconds
* '''playheadend''' : Content position end time in seconds

'''For Content position start and end time(playheadstart, playheadend):'''
* For VoD stream use the player position for Content as the playhead position in seconds. At playback start of a content from the begin, playheads will then be 0,1,2,3,....
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position in seconds.

'''Additional Notes:'''
* For viewing gaps < than 1 second, the gap can be smoothed over
* For playouts that are abandoned before the first whole second of viewing is rendered, a position record of zero duration should be created. IF an audit ping has already been fired See below for additional details on position array parameters
|| ✓
|-
| device_id || '''ONLY for''' '''android''' platform, DO NOT pass device_id for '''ios''', '''browser''' and '''ott''' platforms. Mobile Ad ID , 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" - OPTIONAL if passed in the Audit Ping|| i.e "12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8" || ✓
|-
| xdua || Device HTTP raw User Agent string - OPTIONAL if passed in the Audit Ping|| Example: "Apple-iPhone1C2/801.293" || ✓
|-
| xff || IP address - OPTIONAL if passed in the Audit Ping|| Format: "xxx.xxx.xxx.xxx" or "xxx.xxx.xxx.000"
Examples :
* IPV4: "4.12.345.67"
* IPV6: "2600:6c58:7900:33f2:2505:42b9:5a34:0000"
|| ✓
|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638655", // create and pass a unique streamid for each video play using UUID Generator code provided
"streamended": "1",
"assetid": "VA12345",
"secondscr": "MIR",
"position": [
{
"referencestart": "1628735452",
"referenceend": "1628736052",
"playheadstart": "0",
"playheadend": "600"
}
],
"xdua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130Safari/537.36",
"xff": "4.12.345.67"
}

</syntaxhighlight>

===== Android Platform : Example Metadata with "device_id" =====

====== "device_id" available ======
<syntaxhighlight lang="javascript">
{
"device_id": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826"
}
</syntaxhighlight>

====== "device_id" not available ======
<syntaxhighlight lang="javascript">
{
"device_id": ""
}
</syntaxhighlight>

==OTT, Mirroring, and Casting==

For apps native to the OTT device (i.e. downloading and viewing a streaming app to an Apple
TV, audit ping should fire from OTT device, and Viewing data should reside in OTT Viewing file.
For mirroring, where video playback occurs on the mobile device and OTT device, only one
Viewing file row is necessary where, if possible to determine, set: "secondscr":"MIR" and
include in respective mobile platform Viewing file.

For a casting scenario where content is controlled via the mobile device, but displayed only on
the OTT device such as an AppleTV or Chromecast, an audit ping must fire from the mobile
device before the casting occurs and at the end of playback from the mobile device only.
Viewing data resides in the respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx123",
"referenceend": "xxxxxxx183",
'''"playheadstart": "0",'''
'''"playheadend": "60"'''
},
{
"referencestart": "xxxxxxx243",
"referenceend": "xxxxxxx303",
'''"playheadstart": "120",'''
'''"playheadend": "180"'''
}
]
}

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx183",
"referenceend": "xxxxxxx243",
'''"playheadstart": "60",'''
'''"playheadend": "120"'''
}
],
'''"secondscr": "OTT"'''
}

==S2S Audit Ping Specifications==

=== Introduction ===
The Nielsen server to server solution needs audit pings to validate audience reach and video viewing duration, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.

'''start audit ping(“Startstream = 1”)'''
* A start audit ping is sent when the stream starts(playback start).
* Also a new start audit ping is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
'''end audit ping(“Endstream = 3”)'''
* An end audit ping is sent when the stream ends(either playback completed or switch to another stream).
* Also an end audit ping is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.

=== Ping Structure ===
Ping should be named with following convention structure:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(Please note that this URL could change as we respond to security upgrades in the market.)
The Start Audit Ping will carry all parameters in the matrix below. The End Audit Ping will carry a subset of the parameters in the matrix below as denoted in the mandatory column.
Under normal operating circumstances, the Nielsen collection system will return return codes:
* For security reasons, downstream servers reject cross-origin HTTP requests with preflight. To ensure that audit ping requests are accepted, allowable Content-Types like "text/plain" in simple GET requests ensure that preflight requests are not invoked, which is the preferred behavior.
* 200: The ping was successfully received, inspect traffic to ensure no CORS errors

=== Ping Session & Stream Details ===

==== Sessions ====
* a) When a new player is created a session id is also created.
* b) If you have more than one video player within the same App (e.g. picture in picture) you must use a different session id for each.

==== Streams ====
* a) The Distributor must generate a new UNIQUE stream id with every video stream playback.
* b) If two people watch the same show, they would have different stream id's as Nielsen would expect the stream id(“streamid”) to be a random GUId generated by the client device.
* c) If one person watches a show, and FF, rewind, playout, pause, play, RW, play - they would keep the same stream id(“streamid”) throughout the entire playout of that video asset (stream).
* d) If a stream play out is suspended for 30 mins or more (paused or background):
** An end audit ping(“Endstream = 3”) is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.
** A new start audit ping(“Startstream = 1”) is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
* e) If the user reaches the very end of the stream (content complete), and then starts to play again (replay from anywhere in the stream), then a new “streamid” should be created and a start audit ping should be sent. Also an end audit should be sent when the stream replay is completed or the user switches to another stream.

====Audit Pings ====
* a) Audit pings should be fired at the '''beginning''' and '''end''' of a stream. These will be referred to as the Audit Start Ping and the Audit End Ping.

==== query param list ====

Example:

'''Required S2S Audit Ping Query String Parameters - Note: All parameters are case sensitive'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || Unique ID assigned to the player/site and configured by your Nielsen Technical Account Manager.
|| Example: '''FC984EC1-E044-B465-E040-070AAD3173A1''' || ✓
|-
| intid || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || || ✓
|-
| sessionid || Unique, client-generated value that represents the start of a user browsing session. Must match sessionid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| streamid || Unique Id for every new instance of a client video asset playout. Must match streamid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| pingtype || pingtype Indicator for state type: “start” or “end” audit ping & if the ping is for a stream ||
* Startstream = 1
* Startsession=0
* Endstream = 3
* Endsession=2
|| ✓
|-
| product || Indicates which Nielsen product the audit ping corresponds to. || dcr || ✓
|-
| createtm || Time the ping was fired: utc (in seconds) If server time available, use it instead of device time || || ✓
|-
| devid || '''ONLY for''' '''android''' platform, DO NOT pass devid for '''ios''', '''browser''' and '''ott''' platforms. devid, SHA-256 value of Device Id (ADID) - OPTIONAL if passed in the Asset Viewing File || || ✓
|}

'''Generic Ping Format:'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=<App id>&intid=<Integration ID>&sessionid=<Session Id>&streamid=<Stream Id>&pingtype=<Ping Type>&product=<dcr or dtvr>&createtm=<Session Start or End time>&devid=<Android ADID>'''
</nowiki></code>

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&&intid=xxxxxxxx&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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>

DCR France Video S2S

2025-12-18T15:45:09Z

MichelFodjo: /* Description */ fpid and fpcrtm are now optional ; device_id is marked as mandatory only for Android as it is a current Nielsen requirement for all countries.

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

= DCR Integration Utilizing S2S =
This guide shows you how to integrate the Nielsen S2S(Server to Server) to enable Digital Content Ratings (DCR), and fuel other measurement products on your Apps.

<pre style="color: orange">
PLease note that you have to use the Staging S2S Endpoint(<env>=stage)until you get the green light to move to Production, you will then get the Production S2S Endpoint!
</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 (apid)''' || Unique ID assigned to the player/site and configured by product. || Contact Médiamétrie
|-style="background-color:#d0f6f8;"
|| '''Integration ID (IntID)''' || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.) || Contact Médiamétrie
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| Contact Médiamétrie
|}

==Introduction==
This interface specification depicts the file format that needs to be used to supply Nielsen with
end-user viewing data captured by a “Server-to-Server” method for the Nielsen Digital Content
Ratings (DCR) product and Tuning data for the Digital Ads Rating (DAR) products.
* The specification is defined using a JSON schema, with each file ideally containing all the
viewing that has been captured within an hour.
* In the case of a stream that has one version with blackouts and one without, one with
mobile and one non-mobile, each stream would have it’s own unique asset id.
* The Asset Metadata file should arrive before the viewing data file for the same hour.

==SLA==
The files must be delivered into the proper S3 bucket '''immediately after each hour of viewing on a device''', but latest within 3 hour of the start of that hourly
viewing file interval. For example files from 1:00 AM to 2:00 AM must be delivered latest before 4 AM.

'''When SLA for receiving exposure file for date xx/xx, UTC hour xx has expired. The system will continue to wait for 60 min, after which it will skip the missing file and continue processing subsequent files. Any reprocessing of the missed SLA data will require an explicite request from Médiamétrie.'''

==Accuracy of the Measurement==

====Send Viewing Time (Video Player Events) At Least Each 10 Seconds To Your Backend====
Capture content viewing time each second and send the aggregated viewing time at least each 10 seconds to your backend:
* referencestart : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* referenceend : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* playheadstart : Content position start time in seconds
* playheadend : Content position end time in seconds

====Send Viewing Time When The Video Playback Is Interrupted====
Send the aggregated viewing time to your backend when the video playback is interrupted, i.e. paused.

====Capture Accurately Each Second The Viewing Time When The Network Is Lost And The Video Playback Continues====
Capture accurately each second the viewing time when the network is lost.
Send the aggregated viewing time to your backend when the network is back.

====Send The Viewing Time Early On Browser Refreshed/Closed====
Capture and send the viewing time to your backend by implementing the 2 WINDOWS EVENTS:

''' Please include a logic to make sure that only one of the 2 following event handler is executed '''
<syntaxhighlight lang="javascript">
window.addEventListener("pagehide", function (e) {
// SEND THE VIEWING TIME TO YOUR BACKEND
});
window.addEventListener("beforeunload", function (e) {
// ONLY IF pagehide" was not triggered, SEND THE VIEWING TIME TO YOUR BACKEND
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered at a fixed cadence in a dedicated S3 bucket following the outlined in this spec prefix and object naming conventions and data formats.

* All prefix labels and file names should be lowercase except for app ids.
* Supported format are:
** Uncompressed text files with utf-8 encoding in:
*** JSON format(.json);
*** PARQUET format(.parquet);
* All files should have extensions to indicate the file format (.json or .parquet)
* Data file can be partitioned into multiple parts with min size of 128MB - 256MB
* Data can be delivered separately in multiple splits(platforms), if needed due to organizational, technical or privacy requirements. This allows to permission s3 access separately, to process data independently and to persist data partitioned, within the limits of the S2S system;

===The 4 Different Files to deliver to Nielsen each hour===
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

Nielsen will move files to indicate they are being processed.

====S3 bucket and prefix(S3BucketPrefix) for all 4 Files====

All files should be delived to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| env || '''stage''' for Staging or '''prod''' for Production
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| Platform || '''ios''', '''browser''', '''android''', '''ott'''
|-
| yyyy/mm/dd/hh || UTC start of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023/02/12/05'''

|}
=====Examples for the iOS platform=====
======Asset Metadata File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====File Name(FileName) format for the Asset Metadata and Asset Viewing Files ====

Asset Metadata and Asset Viewing Files should be delivered to:
* <S3BucketPrefix>'''<FileName>'''

* '''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime><FileSuffix>

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| IntID || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.)
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || Nielsen provided server application identifier
|-
| StartTime || start date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| EndTime || end date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| yyyymmddhh || UTC time of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023021205'''

|-
| FileSuffix || Uncompressed json lines (no extension) - splittable, ideal for medium size files, '''less than 5 GB''', preferred for metadata.
'''supported:'''
* '''.json''' json file
* '''.parquet''' parquet file
|}

=====Examples for Asset Metadata and Asset Viewing Files=====
======Asset Metadata File======
Asset Metadata File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====Manifest File for the Asset Metadata and Asset Viewing Files====

The Manifest File should be delivered to: <S3BucketPrefix>'''<FileName>'''

'''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime>'''_manifest'''

A manifest contains metadata related to the uploaded file(s). It is a text file in json format that implements the AWS unload manifest file format. It follows the s3 objects naming notation, but has the _manifest suffix. Here’s an example of manifest file contents:

{
"entries": [
{"url":"s3://bucket/prefix/0000_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0001_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0002_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0003_object_00.snappy.parquet", "mandatory":true}
],
"meta": {
"schema_version": "S2SV1.7.0",
"accreditation_status": "0",
"start_time": "1710154800",
"end_time": "1710158399",
"record_count": 55
}
}

The manifest contains a complete list of all files provided for a given period and platform, as well as a meta data (a.k.a. header) which should include the following attributes:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, i.e. "S2SV1.7.0" || ✓
|-
| data_start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1710154800" || ✓
|-
| data_start_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1710158399" || ✓
|-
| record_count || Records Count in data file || Number: i.e. 55 || ✓
|}

If ‘entries’ array is not specified, or manifest file is not available, the system will still attempt to load all data file(s) (.json or .parquet) from the prefix location. Optionally the manifest file can contain the full schema of the data files as shown in the [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose manifest file format document ].

=====Example for the Manifest File=====

======Manifest File for the Asset Metadata File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"schema_version": "S2SV1.7.0",
"accreditation_status": "0",
"start_time": "1710154800",
"end_time": "1710158399",
"record_count": 15
}
</syntaxhighlight>

======Manifest File for the Asset Viewing File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"schema_version": "S2SV1.7.0",
"accreditation_status": "0",
"start_time": "1710154800",
"end_time": "1710158399",
"record_count": 55
}
</syntaxhighlight>

===Success File: Indication of a data delivery for a particular hour===

An Empty _SUCCESS file should be provided to indicate that data delivery for a particular hour and platform is completed successfully. This file should be uploaded last (after all other files). If there is no data data for a particular hour and platform, the _SUCCESS file is still required to indicate that the delivery process for the hour is completed and no data files are expected. This file is only required for integrations that support data partitioned into multiple parts. The name of the file is configurable.

====Example for Asset Viewing Delivery Files====

'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

====Example for Asset Metadata Delivery Files====
'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

====Data Delivery Example for hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):====
=====Asset Metadata Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

</code>
=====Asset Viewing Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0000.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0001.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0002.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0003.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

</code>

== S2S Metadata Specifications for the Asset Metadata and Asset Viewing Files ==

=== Asset Metadata File ===

The Asset Metadata File contains 1 Header Record followed by Body Records

====Header Record====

=====Description=====

'''Parameter Description'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.09" || ✓
|-
| mvpdid || mvpd ID specified ny Nielsen || String, i.e. "NLSN" || ✓
|-
| creationtime || File creation time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓

|-
| recordcount || Records Count in body of file ||String, i.e. "1" for only 1 Record || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.09",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''. 
'''Note:''' ''' Do not include personal data '''in the content metadata. 

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| assetid || unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| programname || name of program || custom || ✓
|-
| episodetitle || episode name || custom || ✓
|-
| episodelen || 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)|| ✓
|-
|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
||
✓
|-
| cli_md || mode: allows to know the streaming type || possible values provided by Médiamétrie: "LIVE" "TIMESHIFTING" "TVOD" "VOD" "SVOD" "AOD"||
|-
| cli_ch || Channel identifier: values decided by Médiamétrie and provided to the broadcaster || sample value: "860" ||
|-
| cli_cn || content identifier as used / categorized by the publisher || custom ||
|-
| nol_p0 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p1 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p2 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p3 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p4 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p5 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p6 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p7 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p8 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p9 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p10 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p11 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p12 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p13 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p14 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p15 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p16 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p17 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p18 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p19 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"program" : "program name",
"title" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c05",
"cli_md": "LIVE",
"cli_ch": "860",
"cli_cn": "customCuntentIdentifier",
"nol_p0": "p0,optionalValueP0",
"nol_p1": "p1,optionalValueP1",
// ... continued - 20 custom variables
"nol_p18": "p18,optionalValueP18",
"nol_p19": "p19,optionaValuelP19"
}
</syntaxhighlight>

=== Asset Viewing File ===

The Asset Viewing File contains 1 Header Record followed by Body Records
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''.
<pre style="color: orange">
Please do not include ZERO DURATION viewing portion in the Asset Viewing File.
</pre>

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.0" || ✓
|-
| appid || Nielsen provided server application identifier || String, i.e. "P47C2495B-XXXX-56DE-BE99-14758F92F034" || ✓
|-
| type || Type of the data || String, "content" || ✓
|-
| producttype || Product Type || String, "DCR" || ✓
|-
| starttime || Viewing Data Start Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓
|-
| endtime || Viewing Data End Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473791507"|| ✓
|-
| recordcount || Records Count in body of file || String, i.e. "100" for only 100 Records || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.0",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apn || app name || i.e. "BestAppIOS" || ✓
|-
| apv || app build version || i.e. "1.3" || ✓
|-
| sessionid || Unique, client generated value that represents the start of a user session. Must match sessionid in Audit Ping. || created using the UUID Generator code provided || ✓
|-
| streamid || streamid ID for every new instance of an asset || created using the UUID Generator code provided || ✓
|-
| streamended || Stream is known to have ended in this file ||
* "1" (stream will continue in next file)
* "2" (stream closed)
|| ✓
|-
| secondscr || Second Screen Indicator. For Mirroring & Extended Screen via OTT device scenarios ||
* "" (empty String if viewed directly on the device)
* "MIR" (Mirroring)
* "OTT" (Extended Screen via OTT device)
|| ✓
|-
| assetid || unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''Description:'''
* '''referencestart''' : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* '''referenceend''' : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* '''playheadstart''' : Content position start time in seconds
* '''playheadend''' : Content position end time in seconds

'''For Content position start and end time(playheadstart, playheadend):'''
* For VoD stream use the player position for Content as the playhead position in seconds. At playback start of a content from the begin, playheads will then be 0,1,2,3,....
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position in seconds.

'''Additional Notes:'''
* For viewing gaps < than 1 second, the gap can be smoothed over
* For playouts that are abandoned before the first whole second of viewing is rendered, a position record of zero duration should be created. IF an audit ping has already been fired See below for additional details on position array parameters
|| ✓
|-
| device_id || '''MANDATORY ONLY for android platform.''' Mobile Ad ID IDFA,ADID, Connected Device ID 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" || i.e "12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8" || ✓
|-
| xdua || Device HTTP raw User Agent string - OPTIONAL if passed in the Audit Ping to the Nielsen Server|| Example: "Apple-iPhone1C2/801.293" || ✓
|-
| xff || IP address - OPTIONAL if passed in the Audit Ping to the Nielsen Server|| Format: "xxx.xxx.xxx.xxx" or "xxx.xxx.xxx.000"
Examples :
* IPV4: "4.12.345.67"
* IPV6: "2600:6c58:7900:33f2:2505:42b9:5a34:0000"
|| ✓
|-
| fpid || First Party ID || created using the UUID Generator code provided / validity time 180 days. ||
|-
| fpcrtm || Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds) || custom ||
|-
|hem_sha1 || hashed (SHA256) value of member id || i.e. for the sample memberID "userMemberID123", the value to pass is "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826" ||
|-
|uid2 || hashed(SHA256) value of UID2 || i.e. for the sample UID2 "userUID2", the value to pass is i.e. "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05" ||
|-
|hem_sha256 || hashed(SHA256) value of the user email address || i.e. for the sample email address "useremail@company.com", the value to pass is "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969" ||
|-
|uoo || device opt-out status || "true" for opted out, "false" for NOT opted out or opted in. || ✓

|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique streamid for each video play using UUID Generator code provided
"streamended": "1",
"assetid": "VA12345",
"secondscr": "MIR",
"position": [
{
"referencestart": "1628735452",
"referenceend": "1628736052",
"playheadstart": "0",
"playheadend": "600"
}
],
"xdua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130Safari/537.36",
"xff": "4.12.345.67",

"uid2": "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
"device_id": "8ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"hem_sha1": "9ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"hem_sha256": "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
"uoo": "false",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000",
}

</syntaxhighlight>

===== Metadata based on User Consent in your App =====

In collaboration with Mediametrie, the following user consent use cases need to be implemented in your App.

====== The user explicitly accepts measurement ======
All Device/User IDs are captured in the Nielsen S2S Metadata. The Opt-in Flag is set to "false" and all IDs have to be set accordingly:
<syntaxhighlight lang="javascript">
{
"device_id": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"hem_sha1": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"uid2": "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
"hem_sha256": "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
"uoo"": "false",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000"
}
</syntaxhighlight>

====== The user explicitly refuses measurement ======
The Nielsen S2S is NOT initiated and No Nielsen S2S measurement will occur.

======The user did not explicitly give consent for the measurement(consent neither given nor refused) ======
The Nielsen S2S is initiated and no IDs are captured. The Nielsen S2S Opt-out Flag is set to "true" and all Device/User IDs are empty:
<syntaxhighlight lang="javascript">
{
"device_id": "",
"hem_sha1": "",
"uid2": "",
"hem_sha256": "",
"uoo"": "true",
"fpid": "",
"fpcrtm": ""
}
</syntaxhighlight>

==OTT, Mirroring, and Casting==

For apps native to the OTT device (i.e. downloading and viewing a streaming app to an Apple
TV, audit ping should fire from OTT device, and Viewing data should reside in OTT Viewing file.
For mirroring, where video playback occurs on the mobile device and OTT device, only one
Viewing file row is necessary where, if possible to determine, set: "secondscr":"MIR" and
include in respective mobile platform Viewing file.

For a casting scenario where content is controlled via the mobile device, but displayed only on
the OTT device such as an AppleTV or Chromecast, an audit ping must fire from the mobile
device before the casting occurs and at the end of playback from the mobile device only.
Viewing data resides in respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx123",
"referenceend": "xxxxxxx183",
'''"playheadstart": "0",'''
'''"playheadend": "60"'''
},
{
"referencestart": "xxxxxxx243",
"referenceend": "xxxxxxx303",
'''"playheadstart": "120",'''
'''"playheadend": "180"'''
}
]
}

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx183",
"referenceend": "xxxxxxx243",
'''"playheadstart": "60",'''
'''"playheadend": "120"'''
}
],
'''"secondscr": "OTT"'''
}

==S2S Audit Ping Specifications==

=== Introduction ===
The Nielsen server to server solution needs audit pings to validate audience reach and video viewing duration, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.

'''start audit ping(“Startstream = 1”)'''
* A start audit ping is sent when the stream starts(playback start).
* Also a new start audit ping is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
'''end audit ping(“Endstream = 3”)'''
* An end audit ping is sent when the stream ends(either playback completed or switch to another stream).
* Also an end audit ping is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.

=== Ping Structure ===
Ping should be named with following convention structure:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(Please note that this URL could change as we respond to security upgrades in the market.)
The Start Audit Ping will carry all parameters in the matrix below. The End Audit Ping will carry a subset of the parameters in the matrix below as denoted in the mandatory column.
Under normal operating circumstances, the Nielsen collection system will return return codes:
* For security reasons, downstream servers reject cross-origin HTTP requests with preflight. To ensure that audit ping requests are accepted, allowable Content-Types like "text/plain" in simple GET requests ensure that preflight requests are not invoked, which is the preferred behavior.
* 200: The ping was successfully received, inspect traffic to ensure no CORS errors

=== Ping Session & Stream Details ===

==== Sessions ====
* a) When a new player is created a session id is also created.
* b) If you have more than one video player within the same App (e.g. picture in picture) you must use a different session id for each.

==== Streams ====
* a) The Distributor must generate a new UNIQUE stream id with every video stream playback.
* b) If two people watch the same show, they would have different stream id's as Nielsen would expect the stream id(“streamid”) to be a random GUId generated by the client device.
* c) If one person watches a show, and FF, rewind, playout, pause, play, RW, play - they would keep the same stream id(“streamid”) throughout the entire playout of that video asset (stream).
* d) If a stream play out is suspended for 30 mins or more (paused or background):
** An end audit ping(“Endstream = 3”) is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.
** A new start audit ping(“Startstream = 1”) is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
* e) If the user reaches the very end of the stream (content complete), and then starts to play again (replay from anywhere in the stream), then a new “streamid” should be created and a start audit ping should be sent. Also an end audit should be sent when the stream replay is completed or the user switches to another stream.

====Audit Pings ====
* a) Audit pings should be fired at the '''beginning''' and '''end''' of a stream. These will be referred to as the Audit Start Ping and the Audit End Ping.

==== query param list ====

Example:

'''Required S2S Audit Ping Query String Parameters - Note: All parameters are case sensitive'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || Unique ID assigned to the player/site and configured by your Nielsen Technical Account Manager.
|| Example: '''FC984EC1-E044-B465-E040-070AAD3173A1''' || ✓
|-
| intid || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || || ✓
|-
| sessionid || Unique, client-generated value that represents the start of a user browsing session. Must match sessionid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| streamid || Unique Id for every new instance of a client video asset playout. Must match streamid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| pingtype || pingtype Indicator for state type: “start” or “end” audit ping & if the ping is for a stream ||
* Startstream = 1
* Startsession=0
* Endstream = 3
* Endsession=2
|| ✓
|-
| createtm || Time the ping was fired: utc (in seconds) If server time available, use it instead of device time || || ✓
|-
| devid || devid, SHA-256 value of Device Id (IDFA, ADID) - OPTIONAL is passed in the Asset Viewing File || || ✓
|}

'''Generic Ping Format:'''

<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=<App id>&sessionid=<Session Id>&streamid=<Stream Id>&pingtype=<Ping Type>&product=<dcr or dtvr>&sup=<suppress demo look-up>&uoo=<Optout Status >&createtm=<Session Start or End time>&devid=<IDFA/ADID>'''
</nowiki></code>

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&sup=0&uoo=1&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8'
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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>

DCR France Video S2S

2025-12-18T11:38:06Z

MichelFodjo: improvements from AGF S2S Integration Guide added; additional IDs(i.e. memberid, uid2 and hashed email marked as optional as from today's request from MM; )

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

= DCR Integration Utilizing S2S =
This guide shows you how to integrate the Nielsen S2S(Server to Server) to enable Digital Content Ratings (DCR), and fuel other measurement products on your Apps.

<pre style="color: orange">
PLease note that you have to use the Staging S2S Endpoint(<env>=stage)until you get the green light to move to Production, you will then get the Production S2S Endpoint!
</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 (apid)''' || Unique ID assigned to the player/site and configured by product. || Contact Médiamétrie
|-style="background-color:#d0f6f8;"
|| '''Integration ID (IntID)''' || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.) || Contact Médiamétrie
|-style="background-color:#d0f6f8;"
|| '''Partner ID (PartnerID)''' || Partner id provided by Nielsen. Used for the client specific S3 bucket .
<pre style="color: orange">
Please note that the sample PartnerID 'acme' used in all examples is a placeholder to be replaced with your PartnerID.
</pre>
|| Contact Médiamétrie
|}

==Introduction==
This interface specification depicts the file format that needs to be used to supply Nielsen with
end-user viewing data captured by a “Server-to-Server” method for the Nielsen Digital Content
Ratings (DCR) product and Tuning data for the Digital Ads Rating (DAR) products.
* The specification is defined using a JSON schema, with each file ideally containing all the
viewing that has been captured within an hour.
* In the case of a stream that has one version with blackouts and one without, one with
mobile and one non-mobile, each stream would have it’s own unique asset id.
* The Asset Metadata file should arrive before the viewing data file for the same hour.

==SLA==
The files must be delivered into the proper S3 bucket '''immediately after each hour of viewing on a device''', but latest within 3 hour of the start of that hourly
viewing file interval. For example files from 1:00 AM to 2:00 AM must be delivered latest before 4 AM.

'''When SLA for receiving exposure file for date xx/xx, UTC hour xx has expired. The system will continue to wait for 60 min, after which it will skip the missing file and continue processing subsequent files. Any reprocessing of the missed SLA data will require an explicite request from Médiamétrie.'''

==Accuracy of the Measurement==

====Send Viewing Time (Video Player Events) At Least Each 10 Seconds To Your Backend====
Capture content viewing time each second and send the aggregated viewing time at least each 10 seconds to your backend:
* referencestart : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* referenceend : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* playheadstart : Content position start time in seconds
* playheadend : Content position end time in seconds

====Send Viewing Time When The Video Playback Is Interrupted====
Send the aggregated viewing time to your backend when the video playback is interrupted, i.e. paused.

====Capture Accurately Each Second The Viewing Time When The Network Is Lost And The Video Playback Continues====
Capture accurately each second the viewing time when the network is lost.
Send the aggregated viewing time to your backend when the network is back.

====Send The Viewing Time Early On Browser Refreshed/Closed====
Capture and send the viewing time to your backend by implementing the 2 WINDOWS EVENTS:

''' Please include a logic to make sure that only one of the 2 following event handler is executed '''
<syntaxhighlight lang="javascript">
window.addEventListener("pagehide", function (e) {
// SEND THE VIEWING TIME TO YOUR BACKEND
});
window.addEventListener("beforeunload", function (e) {
// ONLY IF pagehide" was not triggered, SEND THE VIEWING TIME TO YOUR BACKEND
});
</syntaxhighlight>

==File Naming Convention and Delivery Specification==

Files should be delivered at a fixed cadence in a dedicated S3 bucket following the outlined in this spec prefix and object naming conventions and data formats.

* All prefix labels and file names should be lowercase except for app ids.
* Supported format are:
** Uncompressed text files with utf-8 encoding in:
*** JSON format(.json);
*** PARQUET format(.parquet);
* All files should have extensions to indicate the file format (.json or .parquet)
* Data file can be partitioned into multiple parts with min size of 128MB - 256MB
* Data can be delivered separately in multiple splits(platforms), if needed due to organizational, technical or privacy requirements. This allows to permission s3 access separately, to process data independently and to persist data partitioned, within the limits of the S2S system;

===The 4 Different Files to deliver to Nielsen each hour===
* [Asset Metadata File]
* [Asset Viewing File]
* [Manifest File]
* [Success File: Indication of a data delivery for a particular hour]

Nielsen will move files to indicate they are being processed.

====S3 bucket and prefix(S3BucketPrefix) for all 4 Files====

All files should be delived to:
'''<S3BucketPrefix>:''' euwest1-nlsn-w-dig-sei-'''<PartnerID>'''-feeds-'''<env>'''/ProducType>/<Platform>/yyyy/mm/dd/hh/

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| env || '''stage''' for Staging or '''prod''' for Production
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| Platform || '''ios''', '''browser''', '''android''', '''ott'''
|-
| yyyy/mm/dd/hh || UTC start of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023/02/12/05'''

|}
=====Examples for the iOS platform=====
======Asset Metadata File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/</code>
======Asset Viewing File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Manifest File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>
======Success File======
<code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/</code>

====File Name(FileName) format for the Asset Metadata and Asset Viewing Files ====

Asset Metadata and Asset Viewing Files should be delivered to:
* <S3BucketPrefix>'''<FileName>'''

* '''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime><FileSuffix>

'''Parameter Description'''
{| class="wikitable"
|-
! Parameter !! Description
|-
| PartnerID || Publisher abbreviation provided by Nielsen for each Publisher or Provider
|-
| IntID || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewsership pipelines (dar, dtvr, dcr, etc.)
|-
| ProductType || '''dcr-exposure''' for Asset Viewing File, '''dcr-metadata''' for Asset Metadata File
|-
| AppID || Nielsen provided server application identifier
|-
| StartTime || start date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| EndTime || end date and hour of the data in the file in GMT: '''yyyymmddhh'''
|-
| yyyymmddhh || UTC time of the period of the data in file

* yyyy = Year
* mm = Month
* dd = Date padded with 0 example 01, 02,..., 31
* hh = Hour padded with 0 example 00, 02,..., 23

example: '''2023021205'''

|-
| FileSuffix || Uncompressed json lines (no extension) - splittable, ideal for medium size files, '''less than 5 GB''', preferred for metadata.
'''supported:'''
* '''.json''' json file
* '''.parquet''' parquet file
|}

=====Examples for Asset Metadata and Asset Viewing Files=====
======Asset Metadata File======
Asset Metadata File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

======Asset Viewing File======
Asset Viewing File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:
* <code>euwest1-nlsn-w-dig-sei-acme-feeds-stage/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495BBBBA56DEBE9914758F92F034_2022052511_2022052512.json</code>

====Manifest File for the Asset Metadata and Asset Viewing Files====

The Manifest File should be delivered to: <S3BucketPrefix>'''<FileName>'''

'''<FileName>''' : <PartnerID>_<ProductType>_<IntID>_<AppID>_<StartTime>_<EndTime>'''_manifest'''

A manifest contains metadata related to the uploaded file(s). It is a text file in json format that implements the AWS unload manifest file format. It follows the s3 objects naming notation, but has the _manifest suffix. Here’s an example of manifest file contents:

{
"entries": [
{"url":"s3://bucket/prefix/0000_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0001_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0002_object_00.snappy.parquet", "mandatory":true},
{"url":"s3://bucket/prefix/0003_object_00.snappy.parquet", "mandatory":true}
],
"meta": {
"schema_version": "S2SV1.7.0",
"accreditation_status": "0",
"start_time": "1710154800",
"end_time": "1710158399",
"record_count": 55
}
}

The manifest contains a complete list of all files provided for a given period and platform, as well as a meta data (a.k.a. header) which should include the following attributes:

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schema_version || Schema Version || String, i.e. "S2SV1.7.0" || ✓
|-
| data_start_time || Data Start UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1710154800" || ✓
|-
| data_start_time || Data End UTC Time (max), 32-bit unsigned int Unix time in seconds || String, i.e. "1710158399" || ✓
|-
| record_count || Records Count in data file || Number: i.e. 55 || ✓
|}

If ‘entries’ array is not specified, or manifest file is not available, the system will still attempt to load all data file(s) (.json or .parquet) from the prefix location. Optionally the manifest file can contain the full schema of the data files as shown in the [https://docs.aws.amazon.com/redshift/latest/dg/r_UNLOAD_command_examples.html#unload-examples-manifest-verbose manifest file format document ].

=====Example for the Manifest File=====

======Manifest File for the Asset Metadata File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"schema_version": "S2SV1.7.0",
"accreditation_status": "0",
"start_time": "1710154800",
"end_time": "1710158399",
"record_count": 15
}
</syntaxhighlight>

======Manifest File for the Asset Viewing File======
The Manifest File for 11:00:00 AM UTC to 11:59:59 PM UTC the file name would be:

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

<syntaxhighlight lang="javascript">
{
"schema_version": "S2SV1.7.0",
"accreditation_status": "0",
"start_time": "1710154800",
"end_time": "1710158399",
"record_count": 55
}
</syntaxhighlight>

===Success File: Indication of a data delivery for a particular hour===

An Empty _SUCCESS file should be provided to indicate that data delivery for a particular hour and platform is completed successfully. This file should be uploaded last (after all other files). If there is no data data for a particular hour and platform, the _SUCCESS file is still required to indicate that the delivery process for the hour is completed and no data files are expected. This file is only required for integrations that support data partitioned into multiple parts. The name of the file is configurable.

====Example for Asset Viewing Delivery Files====

'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

====Example for Asset Metadata Delivery Files====
'''For hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):'''
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

====Data Delivery Example for hour 11 (11:00:00 AM UTC to 11:59:59 PM UTC):====
=====Asset Metadata Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/acme_dcr-metadata_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-metadata/ios/2022/05/25/11/_SUCCESS

</code>
=====Asset Viewing Delivery Files=====
<code>
euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0000.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0001.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0002.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_0003.json

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/acme_dcr-exposure_a9ddf15ea054ea415718767ea6_P47C2495B-BBBA-56DE-BE99-14758F92F034_2022052511_2022052512_manifest

euwest1-nlsn-w-dig-sei-acme-feeds-prod/dcr-exposure/ios/2022/05/25/11/_SUCCESS

</code>

== S2S Metadata Specifications for the Asset Metadata and Asset Viewing Files ==

=== Asset Metadata File ===

The Asset Metadata File contains 1 Header Record followed by Body Records

====Header Record====

=====Description=====

'''Parameter Description'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SAssetMetaDataDCRV2.09" || ✓
|-
| mvpdid || mvpd ID specified ny Nielsen || String, i.e. "NLSN" || ✓
|-
| creationtime || File creation time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓

|-
| recordcount || Records Count in body of file ||String, i.e. "1" for only 1 Record || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SAssetMetaDataDCRV2.09",
"mvpdid": "NLSN",
"creationtime": "1473781507",
"recordcount": "1"
}
</syntaxhighlight>

====Body Record====

=====Description=====
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''. 
'''Note:''' ''' Do not include personal data '''in the content metadata. 

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| assetid || unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| programname || name of program || custom || ✓
|-
| episodetitle || episode name || custom || ✓
|-
| episodelen || 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)|| ✓
|-
|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
||
✓
|-
| cli_md || mode: allows to know the streaming type || possible values provided by Médiamétrie: "LIVE" "TIMESHIFTING" "TVOD" "VOD" "SVOD" "AOD"||
|-
| cli_ch || Channel identifier: values decided by Médiamétrie and provided to the broadcaster || sample value: "860" ||
|-
| cli_cn || content identifier as used / categorized by the publisher || custom ||
|-
| nol_p0 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p1 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p2 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p3 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p4 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p5 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p6 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p7 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p8 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p9 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p10 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p11 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p12 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p13 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p14 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p15 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p16 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p17 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p18 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|-
| nol_p19 || optional custom field available to publishers to pass client-defined variable || custom The following characters are not allowed: 
* <nowiki>|</nowiki> ( bar character ) 
* ~ ( tilde character )
||
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"assetid": "VA12345",
"program" : "program name",
"title" : "episode title",
"length" : "length in seconds",
"islivestn": "y",
"subbrand": "c05",
"cli_md": "LIVE",
"cli_ch": "860",
"cli_cn": "customCuntentIdentifier",
"nol_p0": "p0,optionalValueP0",
"nol_p1": "p1,optionalValueP1",
// ... continued - 20 custom variables
"nol_p18": "p18,optionalValueP18",
"nol_p19": "p19,optionaValuelP19"
}
</syntaxhighlight>

=== Asset Viewing File ===

The Asset Viewing File contains 1 Header Record followed by Body Records
'''Note:''' All metadata values should be passed as '''UTF-8 strings'''.
<pre style="color: orange">
Please do not include ZERO DURATION viewing portion in the Asset Viewing File.
</pre>

====Header Record====

=====Description=====

'''Parameter Description'''

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| schemaversion || Json Schema Version || String, "S2SViewingDataV1.7.0" || ✓
|-
| appid || Nielsen provided server application identifier || String, i.e. "P47C2495B-XXXX-56DE-BE99-14758F92F034" || ✓
|-
| type || Type of the data || String, "content" || ✓
|-
| producttype || Product Type || String, "DCR" || ✓
|-
| starttime || Viewing Data Start Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473781507"|| ✓
|-
| endtime || Viewing Data End Time (UTC time in 32-bit unsigned int UTC in seconds) || String, i.e. "1473791507"|| ✓
|-
| recordcount || Records Count in body of file || String, i.e. "100" for only 100 Records || ✓
|}

=====Example=====

<syntaxhighlight lang="javascript">
{
"schemaversion": "S2SViewingDataV1.7.0",
"appid": "P47C2495B-XXXX-56DE-BE99-14758F92F034",
"type": "content",
"producttype": "DCR",
"starttime": "1473781507",
"endtime": "1473791507",
"recordcount": "100"
}
</syntaxhighlight>

====Body Record====

=====Description=====
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apn || app name || i.e. "BestAppIOS" || ✓
|-
| apv || app build version || i.e. "1.3" || ✓
|-
| sessionid || Unique, client generated value that represents the start of a user session. Must match sessionid in Audit Ping. || created using the UUID Generator code provided || ✓
|-
| streamid || streamid ID for every new instance of an asset || created using the UUID Generator code provided || ✓
|-
| streamended || Stream is known to have ended in this file ||
* "1" (stream will continue in next file)
* "2" (stream closed)
|| ✓
|-
| secondscr || Second Screen Indicator. For Mirroring & Extended Screen via OTT device scenarios ||
* "" (empty String if viewed directly on the device)
* "MIR" (Mirroring)
* "OTT" (Extended Screen via OTT device)
|| ✓
|-
| assetid || unique ID assigned to asset || custom (no [[Special Characters]]) || ✓
|-
| position || Array of contiguous content viewing in utc (UTC time in 32-bit unsigned int in seconds) ||
<code>
[{
"referencestart":"utc time",
"referenceend":"utc time",
"playheadstart":"playhead start position",
"playheadend":"playhead end position"
}]
</code>

'''Description:'''
* '''referencestart''' : Wall clock reference start time (In UTC time, 32-bit unsigned int in seconds)
* '''referenceend''' : Wall clock reference end time (In UTC time, 32-bit unsigned int in seconds)
* '''playheadstart''' : Content position start time in seconds
* '''playheadend''' : Content position end time in seconds

'''For Content position start and end time(playheadstart, playheadend):'''
* For VoD stream use the player position for Content as the playhead position in seconds. At playback start of a content from the begin, playheads will then be 0,1,2,3,....
* For Live streams, use Unix Time (in seconds) matching the broadcast time as the playhead position in seconds.

'''Additional Notes:'''
* For viewing gaps < than 1 second, the gap can be smoothed over
* For playouts that are abandoned before the first whole second of viewing is rendered, a position record of zero duration should be created. IF an audit ping has already been fired See below for additional details on position array parameters
|| ✓
|-
| device_id || Mobile Ad ID IDFA,ADID, Connected Device ID 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" || i.e "12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8" || ✓
|-
| xdua || Device HTTP raw User Agent string - OPTIONAL if passed in the Audit Ping to the Nielsen Server|| Example: "Apple-iPhone1C2/801.293" || ✓
|-
| xff || IP address - OPTIONAL if passed in the Audit Ping to the Nielsen Server|| Format: "xxx.xxx.xxx.xxx" or "xxx.xxx.xxx.000"
Examples :
* IPV4: "4.12.345.67"
* IPV6: "2600:6c58:7900:33f2:2505:42b9:5a34:0000"
|| ✓
|-
| fpid || First Party ID || created using the UUID Generator code provided / validity time 180 days. || ✓
|-
| fpcrtm || Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds) || custom || ✓
|-
|hem_sha1 || hashed (SHA256) value of member id || i.e. for the sample memberID "userMemberID123", the value to pass is "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826" ||
|-
|uid2 || hashed(SHA256) value of UID2 || i.e. for the sample UID2 "userUID2", the value to pass is i.e. "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05" ||
|-
|hem_sha256 || hashed(SHA256) value of the user email address || i.e. for the sample email address "useremail@company.com", the value to pass is "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969" ||
|-
|uoo || device opt-out status || "true" for opted out, "false" for NOT opted out or opted in. || ✓

|}

=====Example=====
<syntaxhighlight lang="javascript">
{
"apn": "BestAppiOS",
"apv": "1.3",
"sessionid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique sessid for each video play using UUID Generator code provided
"streamid": "xxxsavd6wzirm93xb95uxjy1ac5wu1627638609", // create and pass a unique streamid for each video play using UUID Generator code provided
"streamended": "1",
"assetid": "VA12345",
"secondscr": "MIR",
"position": [
{
"referencestart": "1628735452",
"referenceend": "1628736052",
"playheadstart": "0",
"playheadend": "600"
}
],
"xdua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)AppleWebKit/537.36 (KHTML, like Gecko) Chrome/79.0.3945.130Safari/537.36",
"xff": "4.12.345.67",

"uid2": "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
"device_id": "8ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"hem_sha1": "9ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"hem_sha256": "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
"uoo": "false",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000",
}

</syntaxhighlight>

===== Metadata based on User Consent in your App =====

In collaboration with Mediametrie, the following user consent use cases need to be implemented in your App.

====== The user explicitly accepts measurement ======
All Device/User IDs are captured in the Nielsen S2S Metadata. The Opt-in Flag is set to "false" and all IDs have to be set accordingly:
<syntaxhighlight lang="javascript">
{
"device_id": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"hem_sha1": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"uid2": "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
"hem_sha256": "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
"uoo"": "false",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000"
}
</syntaxhighlight>

====== The user explicitly refuses measurement ======
The Nielsen S2S is NOT initiated and No Nielsen S2S measurement will occur.

======The user did not explicitly give consent for the measurement(consent neither given nor refused) ======
The Nielsen S2S is initiated and no IDs are captured. The Nielsen S2S Opt-out Flag is set to "true" and all Device/User IDs are empty:
<syntaxhighlight lang="javascript">
{
"device_id": "",
"hem_sha1": "",
"uid2": "",
"hem_sha256": "",
"uoo"": "true",
"fpid": "",
"fpcrtm": ""
}
</syntaxhighlight>

==OTT, Mirroring, and Casting==

For apps native to the OTT device (i.e. downloading and viewing a streaming app to an Apple
TV, audit ping should fire from OTT device, and Viewing data should reside in OTT Viewing file.
For mirroring, where video playback occurs on the mobile device and OTT device, only one
Viewing file row is necessary where, if possible to determine, set: "secondscr":"MIR" and
include in respective mobile platform Viewing file.

For a casting scenario where content is controlled via the mobile device, but displayed only on
the OTT device such as an AppleTV or Chromecast, an audit ping must fire from the mobile
device before the casting occurs and at the end of playback from the mobile device only.
Viewing data resides in respective mobile platform Viewing file.

Casting Viewing file example:

[[File:France MM S2S casting example.png|France MM S2S casting example.png]]

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx123",
"referenceend": "xxxxxxx183",
'''"playheadstart": "0",'''
'''"playheadend": "60"'''
},
{
"referencestart": "xxxxxxx243",
"referenceend": "xxxxxxx303",
'''"playheadstart": "120",'''
'''"playheadend": "180"'''
}
]
}

{ // ...
"sessionid": "xx..xxxABC",
"streamid": "xx..xxxDEF",
"position": [
{
"referencestart": "xxxxxxx183",
"referenceend": "xxxxxxx243",
'''"playheadstart": "60",'''
'''"playheadend": "120"'''
}
],
'''"secondscr": "OTT"'''
}

==S2S Audit Ping Specifications==

=== Introduction ===
The Nielsen server to server solution needs audit pings to validate audience reach and video viewing duration, one '''start''' and one '''end''' for each video stream playback. These pings will go from the end user device to Nielsen Collections servers.

'''start audit ping(“Startstream = 1”)'''
* A start audit ping is sent when the stream starts(playback start).
* Also a new start audit ping is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
'''end audit ping(“Endstream = 3”)'''
* An end audit ping is sent when the stream ends(either playback completed or switch to another stream).
* Also an end audit ping is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.

=== Ping Structure ===
Ping should be named with following convention structure:
<code><nowiki>https://audit.nmrodam.com/cgi-bin/gn?prd=audit& query param list (see table below)</nowiki></code>

<pre style="color: orange">
Please note that you have to send the Audit Ping in real time on the device running your App.
</pre>

(Please note that this URL could change as we respond to security upgrades in the market.)
The Start Audit Ping will carry all parameters in the matrix below. The End Audit Ping will carry a subset of the parameters in the matrix below as denoted in the mandatory column.
Under normal operating circumstances, the Nielsen collection system will return return codes:
* For security reasons, downstream servers reject cross-origin HTTP requests with preflight. To ensure that audit ping requests are accepted, allowable Content-Types like "text/plain" in simple GET requests ensure that preflight requests are not invoked, which is the preferred behavior.
* 200: The ping was successfully received, inspect traffic to ensure no CORS errors

=== Ping Session & Stream Details ===

==== Sessions ====
* a) When a new player is created a session id is also created.
* b) If you have more than one video player within the same App (e.g. picture in picture) you must use a different session id for each.

==== Streams ====
* a) The Distributor must generate a new UNIQUE stream id with every video stream playback.
* b) If two people watch the same show, they would have different stream id's as Nielsen would expect the stream id(“streamid”) to be a random GUId generated by the client device.
* c) If one person watches a show, and FF, rewind, playout, pause, play, RW, play - they would keep the same stream id(“streamid”) throughout the entire playout of that video asset (stream).
* d) If a stream play out is suspended for 30 mins or more (paused or background):
** An end audit ping(“Endstream = 3”) is sent when the stream playback after a playback interruption for more than 30 minutes, typically playback paused.
** A new start audit ping(“Startstream = 1”) is sent when the stream playback resumes after a playback interruption for more than 30 minutes, typically playback paused. PLEASE note that a new “streamid” parameter has to be created before sending a new start audit ping.
* e) If the user reaches the very end of the stream (content complete), and then starts to play again (replay from anywhere in the stream), then a new “streamid” should be created and a start audit ping should be sent. Also an end audit should be sent when the stream replay is completed or the user switches to another stream.

====Audit Pings ====
* a) Audit pings should be fired at the '''beginning''' and '''end''' of a stream. These will be referred to as the Audit Start Ping and the Audit End Ping.

==== query param list ====

Example:

'''Required S2S Audit Ping Query String Parameters - Note: All parameters are case sensitive'''
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| apid || Unique ID assigned to the player/site and configured by your Nielsen Technical Account Manager.
|| Example: '''FC984EC1-E044-B465-E040-070AAD3173A1''' || ✓
|-
| intid || Integration id provided by Nielsen. Used to link different integration inputs, ex. associate single audit ping integration with different viewership pipelines (dar, dtvr, dcr, etc.) || || ✓
|-
| sessionid || Unique, client-generated value that represents the start of a user browsing session. Must match sessionid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| streamid || Unique Id for every new instance of a client video asset playout. Must match streamid in the Exposure file. || created using the UUID Generator code provided || ✓
|-
| pingtype || pingtype Indicator for state type: “start” or “end” audit ping & if the ping is for a stream ||
* Startstream = 1
* Startsession=0
* Endstream = 3
* Endsession=2
|| ✓
|-
| createtm || Time the ping was fired: utc (in seconds) If server time available, use it instead of device time || || ✓
|-
| devid || devid, SHA-256 value of Device Id (IDFA, ADID) - OPTIONAL is passed in the Asset Viewing File || || ✓
|}

'''Generic Ping Format:'''

<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=<App id>&sessionid=<Session Id>&streamid=<Stream Id>&pingtype=<Ping Type>&product=<dcr or dtvr>&sup=<suppress demo look-up>&uoo=<Optout Status >&createtm=<Session Start or End time>&devid=<IDFA/ADID>'''
</nowiki></code>

'''Audit Ping Examples:'''

* '''End Audit Ping Example (Startsession)'''
<code><nowiki>
https://audit.nmrodam.com/cgi-bin/gn?prd=audit&apid=FC984EC1-E044-B465-E040-070AAD3173A1&sessionid=2576459933726989&streamid=3679422587354472&pingtype=0&product=dcr&sup=0&uoo=1&createtm=1476459970&devid=12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8'
</nowiki></code>

== UUID Generator Code ==

/ ID example: LsTYTmZQPwdchsNZkdtJp9lErjgAp1632729088

''' Create random GUID'''
<syntaxhighlight lang="javascript">
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>

Mediametrie Implementation Documentation

2025-12-17T13:56:18Z

MichelFodjo: new page DCR France Domless SDK added to the landing page

{{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="6" | {{SmallIcon|FRFlag.png}}
| rowspan="5" | {{SmallIcon|SDKIcon.png}}
| rowspan="6" | {{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]]'''
|
|-
| {{OSIcon|BrowserIcon.png}}
| '''[[DCR France Domless SDK|DCR France Video Domless SDK]]'''
|
|-
| {{SmallIcon|CloudAPIIcon.png}}
| {{OSIcon|APIIcon.png}}
| '''[[DCR France Video Cloud API]]'''
|
|}

DCR France Video iOS SDK

2025-12-08T13:40:08Z

MichelFodjo: /* Using Swift */ </syntaxhighlight>> replaced with </syntaxhighlight>

{{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 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 Médiamétrie
|-style="background-color:#d0f6f8;"
|| ☑ || '''Nielsen SDK''' || The Nielsen Digital AppSDK which includes SDK frameworks and '''sample implementation'''; "See [[iOS SDK Release Notes]]" || [[DCR France SDK Downloads|Download]]
|}

* <blockquote>'''Ad flavour of AppSDK''': <pre style="color: red">The Ad flavour of AppSDK should be downloaded for the french market! The AppSDK Version 10.1.0.0 or higher must be downloaded</pre>

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

=== 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"
|-
|hem_sha1 || hashed (SHA256) value of member id || Nielsen-specified || || i.e. for the sample memberID "userMemberID123", the value to pass is "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826"
|-
|uid2 || hashed(SHA256) value of UID2 || Nielsen-specified || || i.e. for the sample UID2 "userUID2", the value to pass is "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05"
|-
|hem_sha256 || hashed(SHA256) value of the user email address || Nielsen-specified || || i.e. for the sample email address "useremail@company.com", the value to pass is "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969"
|-
|enableFpid || Optional:turn on or off the First Party ID || Nielsen-specified || || "true" for turn on, "false" for turn off. The default value is "true".
|-
|optout || OptOut global parameter. This optout will be maintained through the session of the SDK instance || Nielsen-specified || ✓ || "true" for opted out, "false" for NOT opted out or opted in. The default value is "false".
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || || "DEBUG"
|}
 

<blockquote> If the User consent changes while using the App, you have to delete the current SDK instance and create a new instance with the updated optout and enableFpid values.
</blockquote>

==== 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",
@"hem_sha1": @"7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
@"uid2": @"7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
@"hem_sha256": @"0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
@"enableFpid": @"true",
@"optout": @"false",
@"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",
"hem_sha1": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"uid2": "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
"hem_sha256": "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
"enableFpid": "true",
"optout": "false",
"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
## appDisableApi 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.

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.

=== 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",
@"islivestn" : @"y",
@"subbrand" : @"c05",
@"cli_md" : @"LIVE",
@"cli_ch" : @"860",
@"cli_cn" : @"customContentIdentifier",
@"nol_p0" : @"p0,optionalValueP0",
@"nol_p1" : @"p1,optionalValueP1",
// ...
@"nol_p18" : @"p18,optionalValueP18",
@"nol_p19" : @"p19,optionalValueP19"
}

</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",
"islivestn" : "y",
"subbrand" : "c05",
"cli_md" : "LIVE",
"cli_ch" : "860",
"cli_cn" : "customContentIdentifier",
"nol_p0" : "p0,optionalValueP0",
"nol_p1" : "p1,optionalValueP1",
// ...
"nol_p18" : "p18,optionalValueP18",
"nol_p19" : "p19,optionaValuelP19"
]

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

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* when an Ad Break starts during the Content 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
|-
| 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
* When an Ad Break starts during the Content Playback
* 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 current 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]]

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

=== Initialization of the SDK based on User Consent in your App ===

In collaboration with Mediametrie, the following user consent use cases need to be implemented in your App.

==== The user explicitly accepts measurement ====
The SDK is initialized and all IDs are captured. The SDK Opt-in Flags have to be set accordingly, see:

* [[#User opted in|User opted in]]
* [[#First Party ID turned on|First Party ID turned on]]

==== The user explicitly refuses measurement ====
The SDK is NOT initialized and No Nielsen SDK measurement will occur.

==== The user did not explicitly give consent for the measurement(consent neither given nor refused) ====
The SDK is initialized and no IDs are captured. The SDK Opt-out Flags have to be set accordingly, see:
* [[#User opted out|User opted out]]
* [[#First Party ID turned off|First Party ID turned off]]

=== Turning off the First Party ID for Opt-out Users during the SDK Initializazion ===
The First Party ID(FPID) is enabled by default in the Browser SDK. For Opt-out users, the First Party ID can be turned off during the initialization of the SDK Instance, i.e. the parameter enableFpid can be set to "false" (FPID disabled) or "true" (FPID enabled).

==== Example of SDK Initialization with enableFpid ====

===== First Party ID turned on =====
====== 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",
@"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",
"enableFpid": "true"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>>

===== First Party ID turned off =====
====== 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",
@"enableFpid": @"false"
};
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",
"enableFpid": "false"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

=== Setting the SDK global optout Flag for Opt-out Users ===

The Optout Flag is set by default to "false" in the AppSDK.

For Opt-out users, the Optout Flag can be set accordingly while Initializing the SDK Instance.
* <blockquote>'''Ad flavour of AppSDK''': <pre style="color: red">The Ad flavour of AppSDK should be downloaded for the french market! The AppSDK Version 10.1.0.0 or higher must be downloaded</pre>

==== Example the Ouptout Flag ====

===== User opted out =====
====== 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",
@"optout": @"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",
"optout": "true"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

===== User opted in =====
====== 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",
@"optout": @"false"
};
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",
"optout": "false"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

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

The Reference Implementation covers VoD and Live use cases.
The code also covers also DAI (Dynamic Ad Insertion) that should be ignored since No Ads are measured in France.

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-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 a request (https://portail-marqueurs.mediametrie.com) to Médiamétrie 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 France Video iOS SDK

2025-12-08T13:35:54Z

MichelFodjo: update minimum AppSDK version from 9.4 to 10.1

{{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 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 Médiamétrie
|-style="background-color:#d0f6f8;"
|| ☑ || '''Nielsen SDK''' || The Nielsen Digital AppSDK which includes SDK frameworks and '''sample implementation'''; "See [[iOS SDK Release Notes]]" || [[DCR France SDK Downloads|Download]]
|}

* <blockquote>'''Ad flavour of AppSDK''': <pre style="color: red">The Ad flavour of AppSDK should be downloaded for the french market! The AppSDK Version 10.1.0.0 or higher must be downloaded</pre>

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

=== 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"
|-
|hem_sha1 || hashed (SHA256) value of member id || Nielsen-specified || || i.e. for the sample memberID "userMemberID123", the value to pass is "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826"
|-
|uid2 || hashed(SHA256) value of UID2 || Nielsen-specified || || i.e. for the sample UID2 "userUID2", the value to pass is "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05"
|-
|hem_sha256 || hashed(SHA256) value of the user email address || Nielsen-specified || || i.e. for the sample email address "useremail@company.com", the value to pass is "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969"
|-
|enableFpid || Optional:turn on or off the First Party ID || Nielsen-specified || || "true" for turn on, "false" for turn off. The default value is "true".
|-
|optout || OptOut global parameter. This optout will be maintained through the session of the SDK instance || Nielsen-specified || ✓ || "true" for opted out, "false" for NOT opted out or opted in. The default value is "false".
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || || "DEBUG"
|}
 

<blockquote> If the User consent changes while using the App, you have to delete the current SDK instance and create a new instance with the updated optout and enableFpid values.
</blockquote>

==== 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",
@"hem_sha1": @"7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
@"uid2": @"7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
@"hem_sha256": @"0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
@"enableFpid": @"true",
@"optout": @"false",
@"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",
"hem_sha1": "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826",
"uid2": "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05",
"hem_sha256": "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969",
"enableFpid": "true",
"optout": "false",
"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
## appDisableApi 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.

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.

=== 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",
@"islivestn" : @"y",
@"subbrand" : @"c05",
@"cli_md" : @"LIVE",
@"cli_ch" : @"860",
@"cli_cn" : @"customContentIdentifier",
@"nol_p0" : @"p0,optionalValueP0",
@"nol_p1" : @"p1,optionalValueP1",
// ...
@"nol_p18" : @"p18,optionalValueP18",
@"nol_p19" : @"p19,optionalValueP19"
}

</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",
"islivestn" : "y",
"subbrand" : "c05",
"cli_md" : "LIVE",
"cli_ch" : "860",
"cli_cn" : "customContentIdentifier",
"nol_p0" : "p0,optionalValueP0",
"nol_p1" : "p1,optionalValueP1",
// ...
"nol_p18" : "p18,optionalValueP18",
"nol_p19" : "p19,optionaValuelP19"
]

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

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* when an Ad Break starts during the Content 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
|-
| 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
* When an Ad Break starts during the Content Playback
* 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 current 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]]

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

=== Initialization of the SDK based on User Consent in your App ===

In collaboration with Mediametrie, the following user consent use cases need to be implemented in your App.

==== The user explicitly accepts measurement ====
The SDK is initialized and all IDs are captured. The SDK Opt-in Flags have to be set accordingly, see:

* [[#User opted in|User opted in]]
* [[#First Party ID turned on|First Party ID turned on]]

==== The user explicitly refuses measurement ====
The SDK is NOT initialized and No Nielsen SDK measurement will occur.

==== The user did not explicitly give consent for the measurement(consent neither given nor refused) ====
The SDK is initialized and no IDs are captured. The SDK Opt-out Flags have to be set accordingly, see:
* [[#User opted out|User opted out]]
* [[#First Party ID turned off|First Party ID turned off]]

=== Turning off the First Party ID for Opt-out Users during the SDK Initializazion ===
The First Party ID(FPID) is enabled by default in the Browser SDK. For Opt-out users, the First Party ID can be turned off during the initialization of the SDK Instance, i.e. the parameter enableFpid can be set to "false" (FPID disabled) or "true" (FPID enabled).

==== Example of SDK Initialization with enableFpid ====

===== First Party ID turned on =====
====== 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",
@"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",
"enableFpid": "true"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>>

===== First Party ID turned off =====
====== 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",
@"enableFpid": @"false"
};
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",
"enableFpid": "false"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>>

=== Setting the SDK global optout Flag for Opt-out Users ===

The Optout Flag is set by default to "false" in the AppSDK.

For Opt-out users, the Optout Flag can be set accordingly while Initializing the SDK Instance.
* <blockquote>'''Ad flavour of AppSDK''': <pre style="color: red">The Ad flavour of AppSDK should be downloaded for the french market! The AppSDK Version 10.1.0.0 or higher must be downloaded</pre>

==== Example the Ouptout Flag ====

===== User opted out =====
====== 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",
@"optout": @"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",
"optout": "true"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

===== User opted in =====
====== 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",
@"optout": @"false"
};
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",
"optout": "false"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

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

The Reference Implementation covers VoD and Live use cases.
The code also covers also DAI (Dynamic Ad Insertion) that should be ignored since No Ads are measured in France.

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-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 a request (https://portail-marqueurs.mediametrie.com) to Médiamétrie 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 France Video Android SDK

2025-12-08T13:34:57Z

MichelFodjo: update minimum AppSDK version from 9.4 to 10.1

{{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 Médiamétrie
|-style="background-color:#d0f6f8;"
|| ☑ || "Nielsen SDK" || The Nielsen Digital AppSDK which includes SDK frameworks and "sample implementation"; "See [[Android SDK Release Notes]]" || [[DCR France SDK Downloads|Download]]
|}

* <blockquote>'''Ad flavour of AppSDK''': <pre style="color: red">The Ad flavour of AppSDK should be downloaded for the french market! The AppSDK Version 10.1.0.0 or higher must be downloaded</pre>

== 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 version included in the App Resource File''' || || "1.0.2"
|-
|hem_sha1 || hashed (SHA256) value of member id || Nielsen-specified || || i.e. for the sample memberID "userMemberID123", the value to pass is "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826"
|-
|uid2 || hashed(SHA256) value of UID2 || Nielsen-specified || || i.e. for the sample UID2 "userUID2", the value to pass is "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05"
|-
|hem_sha256 || hashed(SHA256) value of the user email address || Nielsen-specified || || i.e. for the sample email address "useremail@company.com", the value to pass is "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969"
|-
|enableFpid || Optional:turn on or off the First Party ID || Nielsen-specified || || "true" for turn on, "false" for turn off. The default value is "true".
|-
|optout || OptOut global parameter. This optout will be maintained through the session of the SDK instance || Nielsen-specified || ✓ || "true" for opted out, "false" for NOT opted out or opted in. The default value is "false".
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || || "DEBUG"
|}
 

<blockquote> If the User consent changes while using the App, you have to delete the current SDK instance and create a new instance with the updated optout and enableFpid values.
</blockquote>

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("hem_sha1", "7ed2155ee9964d69ca425b0aceccda25d5462e06228a40d0da4dce5a4eb3e826")
.put("uid2", "7b733f363eb756046bf72bf476d24611e931e763222a7e89537477261f7bae05")
.put("hem_sha256", "0da83f9ab3bf59e3638f96d83409878fb507d3edd4d3637ca5eae4ddda5bb969")
.put("enableFpid", "true")
.put("optout", "false")
.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("enableFpid", "true")
.put("optout", "false")
.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.

 

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

JSONObject contentMetadata = new JSONObject()
.put("type", "content")
.put("assetid", "unique_content_id")
.put("program", "program name")
.put("title", "episode title")
.put("length", "length in seconds")
.put("islivestn", "y")
.put("subbrand", "c05")
.put("cli_md", "LIVE")
.put("cli_ch", "860")
.put("cli_cn", "customContentIdentifier")
.put("nol_p0", "p0,optionalValueP0")
.put("nol_p1", "p1,optionalValueP1")
// ...
.put("nol_p18", "p18,optionalValueP18")
.put("nol_p19", "p19,optionaValuelP19");

</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. 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 (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
* when a user pauses playback
* when an Ad Break starts during the Content 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]]

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

=== Initialization of the SDK based on User Consent in your App ===

In collaboration with Mediametrie, the following user consent use cases need to be implemented in your App.

==== The user explicitly accepts measurement ====
The SDK is initialized and all IDs are captured. The SDK Opt-in Flags have to be set accordingly, see:

* [[#User opted in|User opted in]]
* [[#First Party ID turned on|First Party ID turned on]]

==== The user explicitly refuses measurement ====
The SDK is NOT initialized and No Nielsen SDK measurement will occur.

==== The user did not explicitly give consent for the measurement(consent neither given nor refused) ====
The SDK is initialized and no IDs are captured. The SDK Opt-out Flags have to be set accordingly, see:
* [[#User opted out|User opted out]]
* [[#First Party ID turned off|First Party ID turned off]]

=== Turning off the First Party ID for Opt-out Users during the SDK Initializazion ===
The First Party ID(FPID) is enabled by default in the Browser SDK. For Opt-out users, the First Party ID can be turned off during the initialization of the SDK Instance, i.e. the parameter enableFpid can be set to "false" (FPID disabled) or "true" (FPID enabled).

===== Example of SDK Initialization with enableFpid =====

====== First Party ID turned on ======
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("enableFpid", "true")
// ...
// 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>

====== First Party ID turned off ======
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("enableFpid", "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>

=== Setting the SDK global optout Flag for Opt-out Users ===

The Optout Flag is set by default to "false" in the AppSDK.

For Opt-out users, the Optout Flag can be set accordingly while Initializing the SDK Instance.
* <blockquote>'''Ad flavour of AppSDK''': <pre style="color: red">The Ad flavour of AppSDK should be downloaded for the french market! The AppSDK Version 10.1.0.0 or higher must be downloaded</pre>

===== Example the Ouptout Flag =====

====== User opted out ======
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("optout", "true")
// ...
// 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>

====== User opted in======
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("optout", "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>

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

The Reference Implementation covers VoD and Live use cases.
The code also covers also DAI (Dynamic Ad Insertion) that should be ignored since No Ads are measured in France.

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 a request (https://portail-marqueurs.mediametrie.com) to Médiamétrie 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.

AGF Specific Implementation Guidelines for Video Measurement

2025-11-26T10:33:44Z

MichelFodjo: original uploaded pdf file url used for handbook

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

''' AGF SDK Specific Implementation Guidelines for Video Measurement '''

Please be sure that the Nielsen Technical Account Managers(TAMs) test all the player functionalities.
Here are the most common (and basic) player features that are checked during the certification process:
* appID
* Loadmetadata (content, ads)
* pause
* scrub forward, backward
* scrub to the start of a particular video (VOD)
* scrub almost to the end of a video (VOD) /to make sure an END event is called/
* slow internet connection (throttling) (STBs are an exception as the connection is usually stable/
* subtitles on/off
* fullscreen on/off
* audio change
* playback speed
* video playback quality
* any specific features like “highlights”, “key points” or similar
* download functionality (the measurement should keep running if there is no network and the user plays an offline content)
* “Live button” (in case of livestreams of course)
* [mobile devices]: lock the screen
* [mobile devices]: move the app to background and then back to foreground
* [mobile devices]: alarm clock going off
* [mobile devices]: flight mode
* [mobile devices]: close/kill the app

The test cases depend on the particular player and device type.
Please note that further features can be tested if necessary.
If there is any specific player feature not available in each video, please let the Nielsen TAMs know about it.

'''Please see details on all Test Cases [https://mywikis-wiki-media.s3.us-central-1.wasabisys.com/nielsen/Handbook-AGF-EN.pdf here]'''.

AGF Metadata Convention

2025-11-26T09:51:26Z

MichelFodjo: new section "SDK specific Guidelines" as per AGF request from Jonas

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

In order to avoid incorrect / implausible filling of individual STATIC metadata and custom-variables please refer to the following additional AGF assistance:
* '''[https://engineeringportal.nielsen.com/wiki/File:250807_AGF_Metadata_Static-Display_v.1.0_english.pdf Guide for STATIC metadata & custom variables (english version)]'''
* '''[https://engineeringportal.nielsen.com/wiki/File:250807_AGF_Metadata_Static-Display_v.1.0_deutsch.pdf Guide for STATIC metadata & custom variables (german version)]'''

== Video Measurement ==

Please refer to this AGF Metadata Document for Video:
* '''[https://nielsendownloads-blue.digitalengsdk.com/digital/AGF_Video_Measure_June132024/240304_AGF+Custom+Variables+and+Metadata+DCR+SDK++v1.10_english.pdf Metadata and custom-Variables Document for Video (english version)]'''
* '''[https://nielsendownloads-blue.digitalengsdk.com/digital/AGF_Video_Measure_June132024/240304_AGF%20Custom%20Variables%20and%20Metadata%20DCR%20SDK%20v.1.10_deutsch.pdf Metadata and custom-Variables Document for Video (german version)]'''

In order to avoid incorrect / implausible filling of individual metadata and custom-variables please refer to the following additional assistance:
* '''[https://nielsendownloads-blue.digitalengsdk.com/digital/AGF_Video_Measure_June132024/20240606%20guide%20metadata%20&%20custom%20variables%20-%20english.pdf Guide for metadata & custom variables (english version)]'''
* '''[https://nielsendownloads-blue.digitalengsdk.com/digital/AGF_Video_Measure_June132024/20240606%20guide%20metadata%20&%20custom%20variables%20-%20deutsch.pdf Guide for metadata & custom variables (german version)]'''

=== SDK specific Guidelines ===
Please refer to this '''[[AGF Specific Implementation Guidelines for Video Measurement|AGF Specific Implementation Guidelines regarding SDK integrations]]'''.

AGF Specific Implementation Guidelines for Video Measurement

2025-11-26T09:49:26Z

MichelFodjo: version updated with AGF text sent by Jonas

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

''' AGF SDK Specific Implementation Guidelines for Video Measurement '''

Please be sure that the Nielsen Technical Account Managers(TAMs) test all the player functionalities.
Here are the most common (and basic) player features that are checked during the certification process:
* appID
* Loadmetadata (content, ads)
* pause
* scrub forward, backward
* scrub to the start of a particular video (VOD)
* scrub almost to the end of a video (VOD) /to make sure an END event is called/
* slow internet connection (throttling) (STBs are an exception as the connection is usually stable/
* subtitles on/off
* fullscreen on/off
* audio change
* playback speed
* video playback quality
* any specific features like “highlights”, “key points” or similar
* download functionality (the measurement should keep running if there is no network and the user plays an offline content)
* “Live button” (in case of livestreams of course)
* [mobile devices]: lock the screen
* [mobile devices]: move the app to background and then back to foreground
* [mobile devices]: alarm clock going off
* [mobile devices]: flight mode
* [mobile devices]: close/kill the app

The test cases depend on the particular player and device type.
Please note that further features can be tested if necessary.
If there is any specific player feature not available in each video, please let the Nielsen TAMs know about it.

'''Please see details on all Test Cases [https://engineeringportal.nielsen.com/wiki/File:Handbook-AGF-EN.pdf here]'''.

File:Handbook-AGF-EN.pdf

2025-11-26T09:47:20Z

MichelFodjo: Handbook AGF english

== Summary ==
Handbook AGF english