Engineering Client Portal - User contributions [en]

DCR Norway Audio Browser SDK

2018-08-06T14:27:46Z

NielsSedat: vcid->subbrand

DCR Norway Audio App SDK

2018-08-06T14:26:27Z

NielsSedat: /* Content metadata */

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

== Overview ==
The Nielsen software development kit (SDK) is one of multiple frameworks that Nielsen provides to enable measuring linear (live) and on-demand audio and video viewing using desktop computers, mobile devices, OTT 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 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.
* '''sfcode:''' Unique identifier for the environment that the SDK should point to.
* '''Nielsen SDK:''' The Nielsen SDK package contains a variety of sample players for your reference.
If you do not have any of these prerequisites or if you have any questions, please contact our SDK sales support team.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

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

== Setting up your Development Environment ==
{{ExampleCode|
xCode|
<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
* 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

<blockquote>'''Example'''
* Extract “NielsenAppApi.Framework” from the Nielsen App SDK sample app and copy it to 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
<br />
<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 <br />
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] <br />
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.
<br />
|Android =
<big>'''Configuring Android 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 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 Nielsen App SDK 1.2 library is composed of two parts:
* The Java AppSdk.jar library that 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 the Google Play support to work properly.
Ensure to 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_COARSE_LOCATION" android:required="false" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details to handle 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 there is a Google service available and updated.
* If not available or updated, App SDK will not use this service when executing its functions and will make reference to 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.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;
}}

== 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 prior to version 5.1.1. (Version 4.0 for Android)

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

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

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || ✓ || PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| appversion || Release version of the client app. Not needed anymore.|| custom || || 0.1.1
|-
| sfcode || Nielsen collection facility to which the SDK should connect.
'''Norway RAM integrations'''
* "nor"
|| Nielsen-specified || ✓ || "nor"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || required until cretification/going live || "DEBUG"
|}
<br />
==== Sample SDK Initialization Code ====
{{ExampleCode|
|Swift =
Swift 4.0 Example:
<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"sfcode": "nor",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
<br />
<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": "nor",
@"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 =

[[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", "nor")
.put("nol_devDebug", "DEBUG"); // only for debug builds

// 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>sfcode</code>) the App passes to the Nielsen App SDK via a JSON string. The appid is obtained from Nielsen operational support and is unique to the app.

The integration of Nielsen App SDK will depend on type of client app.<br />
* 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 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 handles 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 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, 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.
{{ExampleCode|
|Swift =
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"isAudio": "true",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode": "n",
"adloadtype": "2",
"program": "Program Name",
"length": "3600",
"airdate": "20171020 10:05:00",
];
</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @{
@"type": @"content",
@"isAudio": @"true",
@"assetid": [NSString stringWithFormat:@"ProgramAssetId-%d", i],
@"length": @"3600",
@"program", "Program Name",
@"title": @"Program S3, EP1",
@"isfullepisode": @"y",
@"adloadtype": "2",
@"airdate": "20161013 20:00:00",
}
</syntaxhighlight>
|Android = <syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname", "My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
//SDK Metadata
.put("type", "content")
.put("isAudio", "true")
.put("assetid", "vid345-67483")
.put("program", "Program Name")
.put("title", "Program S3, EP1")
.put("length", "3600")
.put("isfullepisode", "y")
.put("adloadtype", "2")
.put("airdate", "20161013 20:00:00")
</syntaxhighlight>
}}

=== Configure metadata ===
When starting a streaming session a channel info metadata object needs to be passed to the SDK containing a channelName. The name should remain constant throughout the completion of an episode or live stream.
<br />
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}
<br/>

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

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required/Obligatory
|-
| type || type of asset || <code>"content"</code> || ✓
|-
| isAudio || indicate measurement of audio ads or audio content || <code>"true"</code> || ✓
|-
| assetid || unique ID assigned to asset (64 character limit)|| custom <br>(no [[Special Characters]]) || ✓
|-
| program ||(string) name of program (254 character limit) || custom || ✓
|-
| title ||(string) episode title (max 254 characters) || custom || ✓
|-
| length || length of content in seconds || <code>seconds</code> ('86400' for 24/7 Livestream if only one assetid is used for the whole stream. If reporting on program level, length of the program. For Event-Livestreams planned length. For on-demand stream length) || ✓
|-
| airdate || the airdate in the linear over-the-air broadcast || Supported formats are:

YYYY-MM-DDTHH:MI:SS

YYYY-MM-DDHH:MI:SS

YYYY-MM-DDTHH:MI:SS+xx:xx

YYYY-MM-DDTHH:MI:SS-xx:xx

YYYYMMDDHH:MI:SS

MM-DD-YYYY

MM/DD/YYYY
|| ✓
|-
| scheduledEndDate || the airdate when this particular asset ended in the linear over-the-air broadcast || should be same format as airdate || ✓
|-
| isfullepisode || full episode flag || <code>"y"</code>- full episode, <code>"n"</code>- non full episode || ✓
|-
| adloadtype || type of ad load:
<code>"1"</code> Linear – matches over-the-air ad load

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || ✓
|-
| stationType || OTA station flag and/or OTA station type
||
<code>"0"</code> Custom station built per user

<code>"1"</code> OTA streaming station with the same adload

<code>"2"</code> OTA station with a different ad load

<code>"3"</code> Multicast eRadio or online station

<code>"4"</code> On Demand Audio(podcasting)
||
✓
|-
| stationId || (string) name of the channel || custom||✓
|-
| clientid ||
parent ID – value is automatically populated through provided App ID.<br/>
In order to override the brand configured to the App ID, pass parent <br/>
value here and the sub-brand ID associated to that brand in the subbrand <br/>
key (e.g. multiple brands in App)
||
provided by Nielsen
||
|-
| subbrand || vcid/sub-brand ID – value is automatically populated through provided<br/>
App ID. In order to override the sub-brand configured to the App ID, value can <br/>
be passed here (e.g. multiple sub-brands in App). clientId does not need to be provided.
||
provided by Nielsen
||
|-
| progen || (string) genre information (max 254 characters)
||
custom
||
|}
<br />

=== Ad Metadata ===
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
<br/>
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}

== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
|On App Start||<code>[nielsenMeter loadMetadata: contentMetadata];</code> || // contentMetadata Object contains the JSON metadata for the impression
|-
| rowspan="2" | Start of stream || <code>[nielsenMeter play: channelInfo];</code> || // channelInfo contains JSON metadata of channel 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 is processing 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>

<blockquote>'''Note:''' The App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.

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

=== API Call sequence ===
==== Use Case 1: Content has no Advertisements ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "My Channel Name 1"
}</syntaxhighlight>

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"isAudio": "true",
"assetid": "stream345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>

Call [[setPlayheadPosition()]] every one second until a pause / stop.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelInfo); </code> || // channelInfo contains JSON metadata of channel name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Advertisements ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "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 / stop / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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

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

=== Sequence of Calls ===

=== play ===
Use [[play]] to pass the channel information containing the channelName parameter when the streaming session starts.
{{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(channelInfo);</syntaxhighlight>
}}

=== loadMetadata ===
The loadMetadata function is used to inform the SDK about new content. The contentMetadata object passed in should contain the values as described above.
{{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 ===
Use playheadPosition to tell the SDK about the current position in the stream. For live content this should be the UTC timestamp in seconds, for on-demand content simply the second in the stream.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">
– (void) playheadPosition: (long long) playheadPos;
</syntaxhighlight>

==== Sending playheadposition for content ====
<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 ===
Tell the SDK that content playback has stopped.
{{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 ===
When content stop is initiated and content cannot be resumed from the same position. For example when the stream has reached its end or in situations where it can only be restarted from the beginning.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">- (void) end;</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void end();</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.end();</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 (For Audio players only if audio stops playing)
* App going in the Background/Foreground (For Audio players only if audio stops playing)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call [[stop]] immediately (except when content is buffering) and withhold sending playhead position.
* Start sending pings – [[loadMetadata]] and [[playheadPosition]] for the new viewing session, once the playback resumes.
Please see the [[Digital Measurement FAQ]] for more details

== Privacy and Opt-Out ==
{{ExampleCode|

iOS|
== iOS Opt-Out Implementation ==
To opt out, users must have access to the page referenced by the opt-out url provided by the SDK. User can click this page from app settings screen.

Include '''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.
*URL for the Nielsen Privacy web page should be retrieved from the optOutURL property of the SDK object <code>optOutURL</code> and opened in 'WebView' / External browser.
*If the App SDK returns NULL in the optOutURL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the [[optOutStatus]] method.



The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:App optout en1.png|link=]]

*URL to this web page should be called from SDK and opened in 'WebView' / External browser.
*If the App SDK returns NULL as Opt-Out URL, handle this case and retry later.
*To retrieve the current Opt-Out status, use the [[optOutStatus]] property from Nielsen's SDK API.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

Users can opt out or opt back into Nielsen Measurement. Opt-Out feature relies on iOS' system setting – "Limit Ad Tracking". The setting can be accessed in the Settings application on any iOS device: '''Settings → Privacy → Advertising → Limit Ad Tracking'''.

User is opted out of Nielsen online measurement research when the "Limit Ad Tracking" setting is enabled.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''Note:''' The App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

|Android =
== Android Opt-Out Implementation ==
To opt out, users must have access to page referenced by the opt-out url provided by the SDK. User can click this page from app settings screen.

Include '''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.
*URL to this web page should be called from SDK by invoking <code>userOptOutURLString()</code> and opened in 'WebView' / External browser.
<syntaxhighlight lang="java">
public String userOptOutURLString()
</syntaxhighlight>

*If the App SDK returns NULL as Opt-Out URL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the <code> getOptOutStatus() </code> method.
<syntaxhighlight lang="java">
public boolean getOptOutStatus()
</syntaxhighlight>

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
optOutUrl = mAppSdk.userOptOutURLString();
if(optOutUrl !=null)
{
mWebView = (WebView) findViewById(R.id.webView);
mWebView.getSettings().setJavaScriptEnabled(true);
mWebView.getSettings().setBuiltInZoomControls(true);
mWebView.getSettings().setDisplayZoomControls(false);
mWebView.getSettings().setLoadWithOverviewMode(true);
mWebView.getSettings().setUseWideViewPort(true);
mWebView.setWebViewClient(new MonitorWebView());
mWebView.setWebChromeClient(new WebChromeClient());
mWebView.loadUrl(optOutUrl);
}
else
{
//Handle it gracefully and Retry later
}
</syntaxhighlight>

The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy App.png|link=]]

<blockquote>'''Note:''' When ‘WebView’ / External browser is closed, do not pass the status returned from ‘WebView’ / External browser to the SDK within the app, as the new Opt-Out page will not return any response.</blockquote>

<blockquote>'''Note:''' App SDK manages the user’s choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

Note:
*SDK will be sending the data pings to census even though the user opted out. However, all the outgoing pings will have the parameter uoo=true using which backend can ignore this data.
*Current Opt-Out page is now updated to have no hyperlinks for Opt-Out / Opt-In operations. SDK Opt-Out has to be done via
'''Google Settings → Ads → Opt out of Ads Personalization'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''Note:''' The App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

== Opt-Out Implementation for Amazon Devices ==
Amazon device users can opt out or opt back into Nielsen Measurement, any time using the device’s setting – 'Limit Ad Tracking' (Interest-based ads).

User is opted out of Nielsen Online Measurement when ‘Limit Ad Tracking’ is enabled.

'''For devices running on Fire OS 5.1 and above, retrieve the Ad tracking value.'''
=== Retrieving Ad tracking Value ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

*Returns limit_ad_tracking value "0" if enabled
*Returns limit_ad_tracking value "1" if disabled
*Returns limit_ad_tracking value "2" if ad tracking is not supported (below Fire OS 5.1).

<blockquote>'''Note:''' Google Play Services are not needed to retrieve ad tracking state on Amazon devices. Limit Ad Tracking can be accessed through '''Settings → Apps & Games → Advertising ID'''.</blockquote>

}}

== 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_devDebug: '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": "nor"
// 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", "nor")
// Remove Flag: "nol_devDebug": "DEBUG"

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

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

DCR Norway Audio Browser SDK

2018-06-11T14:46:07Z

NielsSedat:

DCR Norway Audio Browser SDK

2018-06-11T14:45:53Z

NielsSedat:

DCR Norway Audio Browser SDK

2018-06-11T14:44:56Z

NielsSedat:

DCR Norway Audio App SDK

2018-06-06T10:16:23Z

NielsSedat:

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

== Overview ==
The Nielsen software development kit (SDK) is one of multiple frameworks that Nielsen provides to enable measuring linear (live) and on-demand audio and video viewing using desktop computers, mobile devices, OTT 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 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.
* '''sfcode:''' Unique identifier for the environment that the SDK should point to.
* '''Nielsen SDK:''' The Nielsen SDK package contains a variety of sample players for your reference.
If you do not have any of these prerequisites or if you have any questions, please contact our SDK sales support team.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

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

== Setting up your Development Environment ==
{{ExampleCode|
xCode|
<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
* 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

<blockquote>'''Example'''
* Extract “NielsenAppApi.Framework” from the Nielsen App SDK sample app and copy it to 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
<br />
<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 <br />
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] <br />
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.
<br />
|Android =
<big>'''Configuring Android 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 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 Nielsen App SDK 1.2 library is composed of two parts:
* The Java AppSdk.jar library that 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 the Google Play support to work properly.
Ensure to 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_COARSE_LOCATION" android:required="false" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details to handle 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 there is a Google service available and updated.
* If not available or updated, App SDK will not use this service when executing its functions and will make reference to 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.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;
}}

== 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 prior to version 5.1.1. (Version 4.0 for Android)

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

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

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || ✓ || PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
|-
| appversion || Release version of the client app. Not needed anymore.|| custom || || 0.1.1
|-
| sfcode || Nielsen collection facility to which the SDK should connect.
'''Norway RAM integrations'''
* "nor"
|| Nielsen-specified || ✓ || "nor"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || required until cretification/going live || "DEBUG"
|}
<br />
==== Sample SDK Initialization Code ====
{{ExampleCode|
|Swift =
Swift 4.0 Example:
<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"sfcode": "nor",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
<br />
<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": "nor",
@"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 =

[[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", "nor")
.put("nol_devDebug", "DEBUG"); // only for debug builds

// 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>sfcode</code>) the App passes to the Nielsen App SDK via a JSON string. The appid is obtained from Nielsen operational support and is unique to the app.

The integration of Nielsen App SDK will depend on type of client app.<br />
* 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 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 handles 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 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, 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.
{{ExampleCode|
|Swift =
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"isAudio": "true",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode": "n",
"adloadtype": "2",
"program": "Program Name",
"length": "3600",
"airdate": "20171020 10:05:00",
];
</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @{
@"type": @"content",
@"isAudio": @"true",
@"assetid": [NSString stringWithFormat:@"ProgramAssetId-%d", i],
@"length": @"3600",
@"program", "Program Name",
@"title": @"Program S3, EP1",
@"isfullepisode": @"y",
@"adloadtype": "2",
@"airdate": "20161013 20:00:00",
}
</syntaxhighlight>
|Android = <syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname", "My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
//SDK Metadata
.put("type", "content")
.put("isAudio", "true")
.put("assetid", "vid345-67483")
.put("program", "Program Name")
.put("title", "Program S3, EP1")
.put("length", "3600")
.put("isfullepisode", "y")
.put("adloadtype", "2")
.put("airdate", "20161013 20:00:00")
</syntaxhighlight>
}}

=== Configure metadata ===
When starting a streaming session a channel info metadata object needs to be passed to the SDK containing a channelName. The name should remain constant throughout the completion of an episode or live stream.
<br />
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}
<br/>

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

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required/Obligatory
|-
| type || type of asset || <code>"content"</code> || ✓
|-
| isAudio || indicate measurement of audio ads or audio content || <code>"true"</code> || ✓
|-
| assetid || unique ID assigned to asset (64 character limit)|| custom || ✓
|-
| program ||(string) name of program (254 character limit) || custom || ✓
|-
| title ||(string) episode title (max 254 characters) || custom || ✓
|-
| length || length of content in seconds || <code>seconds</code> ('86400' for 24/7 Livestream if only one assetid is used for the whole stream. If reporting on program level, length of the program. For Event-Livestreams planned length. For on-demand stream length) || ✓
|-
| airdate || the airdate in the linear over-the-air broadcast || Supported formats are:

YYYY-MM-DDTHH:MI:SS

YYYY-MM-DDHH:MI:SS

YYYY-MM-DDTHH:MI:SS+xx:xx

YYYY-MM-DDTHH:MI:SS-xx:xx

YYYYMMDDHH:MI:SS

MM-DD-YYYY

MM/DD/YYYY
|| ✓
|-
| scheduledEndDate || the airdate when this particular asset ended in the linear over-the-air broadcast || should be same format as airdate || ✓
|-
| isfullepisode || full episode flag || <code>"y"</code>- full episode, <code>"n"</code>- non full episode || ✓
|-
| adloadtype || type of ad load:
<code>"1"</code> Linear – matches over-the-air ad load

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || ✓
|-
| stationType || OTA station flag and/or OTA station type
||
<code>"0"</code> Custom station built per user

<code>"1"</code> OTA streaming station with the same adload

<code>"2"</code> OTA station with a different ad load

<code>"3"</code> Multicast eRadio or online station

<code>"4"</code> On Demand Audio(podcasting)
||
✓
|-
| stationId || (string) name of the channel || custom||✓
|-
| clientid ||
parent ID – value is automatically populated through provided App ID.<br/>
In order to override the brand configured to the App ID, pass parent <br/>
value here and the sub-brand ID associated to that brand in the subbrand <br/>
key (e.g. multiple brands in App)
||
provided by Nielsen
||
|-
| vcid || vcid/sub-brand ID – value is automatically populated through provided<br/>
App ID. In order to override the sub-brand configured to the App ID, value can <br/>
be passed here (e.g. multiple sub-brands in App). clientId does not need to be provided.
||
provided by Nielsen
||
|-
| progen || (string) genre information (max 254 characters)
||
custom
||
|}
<br />

=== Ad Metadata ===
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
<br/>
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}

== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
|On App Start||<code>[nielsenMeter loadMetadata: contentMetadata];</code> || // contentMetadata Object contains the JSON metadata for the impression
|-
| rowspan="2" | Start of stream || <code>[nielsenMeter play: channelInfo];</code> || // channelInfo contains JSON metadata of channel 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 is processing 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>

<blockquote>'''Note:''' The App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.

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

=== API Call sequence ===
==== Use Case 1: Content has no Advertisements ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "My Channel Name 1"
}</syntaxhighlight>

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"isAudio": "true",
"assetid": "stream345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>

Call [[setPlayheadPosition()]] every one second until a pause / stop.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelInfo); </code> || // channelInfo contains JSON metadata of channel name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Advertisements ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "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 / stop / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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

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

=== Sequence of Calls ===

=== play ===
Use [[play]] to pass the channel information containing the channelName parameter when the streaming session starts.
{{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(channelInfo);</syntaxhighlight>
}}

=== loadMetadata ===
The loadMetadata function is used to inform the SDK about new content. The contentMetadata object passed in should contain the values as described above.
{{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 ===
Use playheadPosition to tell the SDK about the current position in the stream. For live content this should be the UTC timestamp in seconds, for on-demand content simply the second in the stream.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">
– (void) playheadPosition: (long long) playheadPos;
</syntaxhighlight>

==== Sending playheadposition for content ====
<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 ===
Tell the SDK that content playback has stopped.
{{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 ===
When content stop is initiated and content cannot be resumed from the same position. For example when the stream has reached its end or in situations where it can only be restarted from the beginning.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c">- (void) end;</syntaxhighlight>
|Android = <syntaxhighlight lang="java">public void end();</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">self.nielsenAppApi?.end();</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 (For Audio players only if audio stops playing)
* App going in the Background/Foreground (For Audio players only if audio stops playing)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call [[stop]] immediately (except when content is buffering) and withhold sending playhead position.
* Start sending pings – [[loadMetadata]] and [[playheadPosition]] for the new viewing session, once the playback resumes.
Please see the [[Digital Measurement FAQ]] for more details

== Privacy and Opt-Out ==
{{ExampleCode|

iOS|
== iOS Opt-Out Implementation ==
To opt out, users must have access to the page referenced by the opt-out url provided by the SDK. User can click this page from app settings screen.

Include '''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.
*URL for the Nielsen Privacy web page should be retrieved from the optOutURL property of the SDK object <code>optOutURL</code> and opened in 'WebView' / External browser.
*If the App SDK returns NULL in the optOutURL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the [[optOutStatus]] method.



The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:App optout en1.png|link=]]

*URL to this web page should be called from SDK and opened in 'WebView' / External browser.
*If the App SDK returns NULL as Opt-Out URL, handle this case and retry later.
*To retrieve the current Opt-Out status, use the [[optOutStatus]] property from Nielsen's SDK API.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

Users can opt out or opt back into Nielsen Measurement. Opt-Out feature relies on iOS' system setting – "Limit Ad Tracking". The setting can be accessed in the Settings application on any iOS device: '''Settings → Privacy → Advertising → Limit Ad Tracking'''.

User is opted out of Nielsen online measurement research when the "Limit Ad Tracking" setting is enabled.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''Note:''' The App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

|Android =
== Android Opt-Out Implementation ==
To opt out, users must have access to page referenced by the opt-out url provided by the SDK. User can click this page from app settings screen.

Include '''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.
*URL to this web page should be called from SDK by invoking <code>userOptOutURLString()</code> and opened in 'WebView' / External browser.
<syntaxhighlight lang="java">
public String userOptOutURLString()
</syntaxhighlight>

*If the App SDK returns NULL as Opt-Out URL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the <code> getOptOutStatus() </code> method.
<syntaxhighlight lang="java">
public boolean getOptOutStatus()
</syntaxhighlight>

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
optOutUrl = mAppSdk.userOptOutURLString();
if(optOutUrl !=null)
{
mWebView = (WebView) findViewById(R.id.webView);
mWebView.getSettings().setJavaScriptEnabled(true);
mWebView.getSettings().setBuiltInZoomControls(true);
mWebView.getSettings().setDisplayZoomControls(false);
mWebView.getSettings().setLoadWithOverviewMode(true);
mWebView.getSettings().setUseWideViewPort(true);
mWebView.setWebViewClient(new MonitorWebView());
mWebView.setWebChromeClient(new WebChromeClient());
mWebView.loadUrl(optOutUrl);
}
else
{
//Handle it gracefully and Retry later
}
</syntaxhighlight>

The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy App.png|link=]]

<blockquote>'''Note:''' When ‘WebView’ / External browser is closed, do not pass the status returned from ‘WebView’ / External browser to the SDK within the app, as the new Opt-Out page will not return any response.</blockquote>

<blockquote>'''Note:''' App SDK manages the user’s choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

Note:
*SDK will be sending the data pings to census even though the user opted out. However, all the outgoing pings will have the parameter uoo=true using which backend can ignore this data.
*Current Opt-Out page is now updated to have no hyperlinks for Opt-Out / Opt-In operations. SDK Opt-Out has to be done via
'''Google Settings → Ads → Opt out of Ads Personalization'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''Note:''' The App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

== Opt-Out Implementation for Amazon Devices ==
Amazon device users can opt out or opt back into Nielsen Measurement, any time using the device’s setting – 'Limit Ad Tracking' (Interest-based ads).

User is opted out of Nielsen Online Measurement when ‘Limit Ad Tracking’ is enabled.

'''For devices running on Fire OS 5.1 and above, retrieve the Ad tracking value.'''
=== Retrieving Ad tracking Value ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

*Returns limit_ad_tracking value "0" if enabled
*Returns limit_ad_tracking value "1" if disabled
*Returns limit_ad_tracking value "2" if ad tracking is not supported (below Fire OS 5.1).

<blockquote>'''Note:''' Google Play Services are not needed to retrieve ad tracking state on Amazon devices. Limit Ad Tracking can be accessed through '''Settings → Apps & Games → Advertising ID'''.</blockquote>

}}

== 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_devDebug: '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": "nor"
// 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", "nor")
// Remove Flag: "nol_devDebug": "DEBUG"

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

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

DCR React Native Integration

2018-05-08T08:32:52Z

NielsSedat: /* SDK Initialization */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International}} {{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 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 app was running
*Time of viewing a sub section / page in the application.

This guide will show how to use the Nielsen SDK in React Native applications on Android and iOS devices. We will not go into detail about what React Native is or how to create Apps with this Framework. If you are looking for information on this, please read the [http://facebook.github.io/react-native/ React-Native] documentation.

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

For more detail on the native SDKs please refer to the App integration guides available on this portal.

== Implementation ==
This guide covers implementation covers

* the implementation of React-Native bridges for iOS and Android
* the usage of the exposed Javascript API

What we will not cover is the general setup of React-Native applications. If you are new to React-Native please refer to [https://facebook.github.io/react-native/ React-Native] for documentation.

For simplicity we have focused on implementing a single instance of the Nielsen SDK. Should there be the need for multiple instances developers have to add some logic for that.

== Setting up your Environment ==
<div class="section-container auto" data-section>
<div class="section">
<p class="title" data-section-title>iOS</p>
<div class="content" data-section-content>

The first step is to ensure that the following frameworks and libraries are imported into the Frameworks folder of the iOS Xcode project before working with the Nielsen SDK.

* 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 (Not applicable for International (Germany))
* CoreMedia.framework
* NielsenAppApi.framework

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

<br />
</div>
</div>
<div class="section">
<p class="title" data-section-title>Android</p>
<div class="content" data-section-content>
The first step is to add the AppSdk.jar library that runs on the Android’s Dalvik Virtual Machine to the libs folder (might have to be created) for the Android part of your project.

<code>android/app/libs</code>

The next step is to add the following permissions on the project’s ''AndroidManifest.xml'' file.
<syntaxhighlight lang="java"><uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:required="false" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details to handle 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 there is a Google service available and updated.
* If not available or updated, App SDK will not use this service when executing its functions and will make reference to missing imports and the app will not be compiled.

<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.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;
</div>
</div>
</div>

== Creating React-Native bridges for the Nielsen SDK ==
In order to be able to use Nielsens native SDKs React-Native bridges have to be implemented and added to the iOS and Android projects. The following shows implementations for both platforms, that provide the basic methods to start measuring the app. The source code can be copied from below to provide an easy start.

Please refer to the integration guides for Nielsens native SDKs to get a deeper understanding of the technical detail.

<div class="section-container auto" data-section>
<div class="section">
<p class="title" data-section-title>iOS</p>
<div class="content" data-section-content>

The iOS implementation of the bridge module consists of two files, a header and an implementation file, written in Objective-c. These two files need to be added to the iOS XCode project.

The header file is <code>NielsenReactBridge.h</code>
<syntaxhighlight lang="objective-c">
// Copyright <2018> <The Nielsen Company>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
// (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
// merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

#import <React/RCTBridgeModule.h>
#import <React/RCTEventEmitter.h>

@interface NielsenReactBridge : RCTEventEmitter <RCTBridgeModule>
@end
</syntaxhighlight>

The actual implementation of the module happens in <code>NielsenReactBridge.m</code>
<syntaxhighlight lang="objective-c">
// Copyright <2018> <The Nielsen Company>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
// (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
// merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

#import "NielsenReactBridge.h"
#import <NielsenAppApi/NielsenAppApi.h>

static NSString *const TAG = @"NielsenReactBridge";

@interface NielsenReactBridge() <NielsenAppApiDelegate>
@property (strong) NielsenAppApi* nlsSDk;
@end

@implementation NielsenReactBridge
RCT_EXPORT_MODULE();

/**
* Since we need to communicate the opt-out url to javascript via events
* we need to implement the following method
*/
- (NSArray<NSString *> *)supportedEvents
{
return @[@"OptOutUrl"];
}

/**
* A logging helper method
*/
void NLSLog(NSString* tag, NSString* format, ...)
{
va_list argList;
va_start(argList, format);
NSLog(@"%@", [[NSString alloc] initWithFormat:[NSString stringWithFormat:@"[%@]: %@", tag, format] arguments: argList]);
va_end(argList);
}

/**
* Init creates the SDK instance and passes on the provided metadata.
* appInfo is simply passed to initWithAppInfo since the SDK already
* performs error checking
*/
RCT_EXPORT_METHOD(init:(NSDictionary *)appInfo)
{
NLSLog(TAG, @"init called with metadat '%@''", appInfo);

if (!self.nlsSDk) {
self.nlsSDk= [[NielsenAppApi alloc] initWithAppInfo:appInfo delegate:self];
}
}

/**
* Wrapper for the SDK's play method. The provided metadata is
* simply passed on
*/
RCT_EXPORT_METHOD(play:(NSDictionary *)channelInfo)
{
NLSLog(TAG, @"play called with metadata '%@'", channelInfo);

if (self.nlsSDk) {
[self.nlsSDk play:channelInfo];
}
}

/**
* Wrapper for the SDK's loadMetadata method. The provided contentMetaData is
* simply passed on
*/
RCT_EXPORT_METHOD(loadMetadata:(NSDictionary *)contentMetaData)
{
NLSLog(TAG, @"loadMetadata called with '%@'", contentMetaData);

if (self.nlsSDk) {
[self.nlsSDk loadMetadata:contentMetaData];
}
}

/**
* Wrapper for the SDK's setPlayheadPosition method. The provided playhead is
* simply passed on to the SDK
*/
RCT_EXPORT_METHOD(setPlayheadPosition:(nonnull NSNumber *)ph)
{
NLSLog(TAG, @"setHeadPosition called with '%@'",ph);

if (self.nlsSDk) {
[self.nlsSDk playheadPosition:[ph longLongValue]];
}
}

/**
* Wrapper for the SDK's stop method.
*/
RCT_EXPORT_METHOD(stop)
{
NLSLog(TAG, @"stop called");

if (self.nlsSDk) {
[self.nlsSDk stop];
}
}

/**
* Wrapper for the SDK's end method.
*/
RCT_EXPORT_METHOD(end)
{
NLSLog(TAG, @"end called");

if (self.nlsSDk) {
[self.nlsSDk end];
}
}

/**
* optOutUrl retrieves the url from the SDK instance and fires off the
* OptOutUrl event, so the url can be captured
*/
RCT_EXPORT_METHOD(optOutUrl)
{
[self sendEventWithName:@"OptOutUrl" body:@{@"url": self.nlsSDk.optOutURL}];
}
@end
</syntaxhighlight>
</div>
</div>
<div class="section">
<p class="title" data-section-title>Android</p>
<div class="content" data-section-content>

The Android implementation of the bridge module consists of two files, an implementation of a NielsenPackage to announce the actual module and the implementation of NielsenReactBridge itself. The implementations have been put into the Java package

<code>com.nielsen.app.react</code>

The package implementation is in <code>com/nielsen/app/react/NielsenPackage.java</code>
<syntaxhighlight lang="java">
// Copyright <2018> <The Nielsen Company>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
// (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
// merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package com.nielsen.app.react;

import com.facebook.react.bridge.NativeModule;
import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.ReactPackage;
import com.facebook.react.uimanager.ViewManager;
import com.nielsen.app.react.NielsenReactBridge;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

/**
*/
public class NielsenPackage implements ReactPackage {

/**
* Override createNativeModules to return our bridge module
*/
@Override
public List<NativeModule> createNativeModules(ReactApplicationContext reactContext) {
List<NativeModule> modules = new ArrayList<>();
modules.add(new NielsenReactBridge(reactContext));

return modules;
}

/**
*/
@Override
public List<ViewManager> createViewManagers(ReactApplicationContext reactContext) {
return Collections.emptyList();
}
}
</syntaxhighlight>

<code>com/nielsen/app/react/NielsenReactBridge.java</code>
<syntaxhighlight lang="java">
// Copyright <2018> <The Nielsen Company>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
// (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
// merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package com.nielsen.app.react;

import android.util.Log;
import com.facebook.react.bridge.LifecycleEventListener;
import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.bridge.ReactContextBaseJavaModule;
import com.facebook.react.modules.core.DeviceEventManagerModule;
import com.facebook.react.bridge.ReactMethod;
import com.facebook.react.bridge.ReadableMap;
import com.facebook.react.bridge.WritableMap;
import com.facebook.react.bridge.Arguments;
import com.facebook.react.bridge.ReadableMapKeySetIterator;
import com.nielsen.app.sdk.AppSdk;
import com.nielsen.app.sdk.IAppNotifier;
import com.nielsen.app.sdk.AppLaunchMeasurementManager;
import org.json.JSONObject;
import org.json.JSONException;

/**
* NielsenReactBridge is the class briding between react JS code
* and the native Nielsen SDK.
*/
public class NielsenReactBridge extends ReactContextBaseJavaModule
implements IAppNotifier, LifecycleEventListener {

/**
*/
private static final String NIELSEN_TAG = "NielsenReactBridge";
private AppSdk mAppSdk = null; // the AppSdk main object

/**
* Constructor for the NielsenReactBridge
* Adds the new instance as LifeCycleEventListener for conttex
* @param context The react application context
*/
public NielsenReactBridge(ReactApplicationContext context) {
super(context);
context.addLifecycleEventListener(this);
}

/**
* Implements getName method from ReactContextBaseJavaModule
* @return The constant string 'NielsenReactBridge'
*/
@Override
public String getName() {
return "NielsenReactBridge";
}

/**
* Implements getName method from IAppNotifier
*/
@Override
public void onAppSdkEvent(long l, int i, String s) {}

/**
* Initializes the module for use
* @param obj An instance of ReadableMap (mapped JS object) containing
* initialization meta data
*/
@ReactMethod
public void init(final ReadableMap obj) {

Log.d(NIELSEN_TAG, "Called init");

if (null == mAppSdk) {
try {
JSONObject appSdkConfig = readableMapToJSONObject(obj);
mAppSdk = new AppSdk(getReactApplicationContext(), appSdkConfig, this);
if (!mAppSdk.isValid())
{
Log.e(NIELSEN_TAG, "SDK Init failed");
}
}
catch(Exception ex) {
}
}
}

/**
* Static method to convert ReadableMap instances to JSONObject instances
* (used by the Nielsen SDK)
* @param obj The ReadableMap instance to be converted
* @return An instance of JSONObject containing the mapped JS object
* values (if successful, empty otherwise)
*/
static private JSONObject readableMapToJSONObject(final ReadableMap obj) {

JSONObject ret = new JSONObject();

try {
ReadableMapKeySetIterator it = obj.keySetIterator();
while (it.hasNextKey()) {
String key = it.nextKey();
ret.put(key, obj.getDynamic(key).asString());
}
}
catch (JSONException ex) {
Log.e(NIELSEN_TAG, ex.getMessage());
}

return ret;
}

/**
* Wrapper for the Nielsen SDK play method. Simply forwards calls
* to the SDK.
* @param obj ReadableMap instance containing the mapped JS meta
* data object, e.g. {channelName: 'channel name here'}
*/
@ReactMethod
public void play(final ReadableMap obj) {

Log.d(NIELSEN_TAG, "Called play " + obj.toString());
if (null != mAppSdk) {
JSONObject playObject = readableMapToJSONObject(obj);
mAppSdk.play(playObject);
}
}

/**
* Wrapper for the Nielsen SDK loadMetadata method. Simply forwards calls
* to the SDK.
* @param obj ReadableMap instance containing the mapped JS meta
* data object
*/
@ReactMethod
public void loadMetadata(final ReadableMap obj) {

Log.d(NIELSEN_TAG,"Called loadMetadata");
if (null != mAppSdk) {
JSONObject contentMetadata = readableMapToJSONObject(obj);
mAppSdk.loadMetadata(contentMetadata);
}
}

/**
* Wrapper for the Nielsen SDK setPlayheadPosition method. Simply
* forwards calls to the SDK.
* @param ph The current playhead position
*/
@ReactMethod
public void setPlayheadPosition(final Double ph) {

Log.d(NIELSEN_TAG,"Called setPlayHeadPosition: " + " " + ph);
if (null != mAppSdk) {
mAppSdk.setPlayheadPosition(ph.longValue());
}
}

/**
* Wrapper for the Nielsen SDK stop method. Simply
* forwards calls to the SDK.
*/
@ReactMethod
public void stop() {
Log.d(NIELSEN_TAG, "Called stop");
if (null != mAppSdk) {
mAppSdk.stop();
}
}

/**
* Wrapper for the Nielsen SDK end method. Simply
* forwards calls to the SDK.
*/
@ReactMethod
public void end() {

Log.d(NIELSEN_TAG,"Called end");
if (null != mAppSdk) {
mAppSdk.end();
}
}

/**
* Wrapper to retrieve the optOutUrl from the Nielsen SDK.
* Emits a "OptOutUrl" event with the url as payload.
* Needs to be catched in JS
*/
@ReactMethod
public void optOutUrl() {

WritableMap params = Arguments.createMap();
if (null != mAppSdk) {
params.putString("url", mAppSdk.userOptOutURLString());
}

getReactApplicationContext()
.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
.emit("OptOutUrl", params);
}

/**
* Implements LifecycleEventListener's onHostResume method.
* Uses AppLaunchMeasurementManager.appInForeground to notify SDK about
* app coming to foreground again
*/
@Override
public void onHostResume() {

Log.d(NIELSEN_TAG,"Called onHostResume");
AppLaunchMeasurementManager.appInForeground(getReactApplicationContext());
}

/**
* Implements LifecycleEventListener's onHostPause method.
* Uses AppLaunchMeasurementManager.appInBackground to notify SDK about
* app going to background
*/
@Override
public void onHostPause() {

Log.d(NIELSEN_TAG,"Called onHostPause");
AppLaunchMeasurementManager.appInBackground(getReactApplicationContext());
}

/**
* Implements LifecycleEventListener's onHostDestroy method.
*/
@Override
public void onHostDestroy() {
Log.d(NIELSEN_TAG,"Called onHostDestroy");
}
}
</syntaxhighlight>
<br />

The package needs to be provided in the getPackages method of the MainApplication.java file. This file exists under the android folder in your react-native application directory. The path to this file is: android/app/src/main/java/com/your-app-name/MainApplication.java.
<br />

<syntaxhighlight lang="java">
import com.nielsen.app.react.NielsenPackage; //<-- Import the package in MainApplication.java
//...

protected List<ReactPackage> getPackages() {
return Arrays.<ReactPackage>asList(
//...,
new NielsenPackage()); // <-- Add the bridge package to the getPackages method.
}
</syntaxhighlight>
</div>
</div>

In order to import the bridges into the Javascript context, create a file
<code>NielsenModule.js</code>
<syntaxhighlight lang="javascript">
import { NativeModules } from 'react-native'

export default NativeModules.NielsenReactBridge
</syntaxhighlight>

== SDK Initialization ==
The bridge implementations above allow the usage of one instance of the Nielsen App SDK. The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. For more information on this please read the relevant App SDK Guide.

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? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || Yes || 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.
'''Italian Clients'''
* "it"
|| Nielsen-specified || Yes || "it"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || While not live || "DEBUG"
|}
<br />

==== Sample SDK Initialization Code ====
<syntaxhighlight lang="javascript">
import NielsenModule from './NielsenModule';

let appInformation = {"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"sfcode": "it",
"nol_devDebug": @"DEBUG"};
NielsenModule.init(appInformation);
</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.

== Configure Payload ==
All metadata is passed to the bridges in form of objects containing the in the following described properties. An example metadata object could look like
<syntaxhighlight lang="javascript">
let metadata = {
'type':'content',
'assetid':'asset12345',
'program':'My Program',
'title':'My Title',
'length':'42',
'airdate':'20180302 16:32:00',
'isfullepisode':'n',
'adloadtype':'2'
};
</syntaxhighlight>

The following section will explain the different values.

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

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

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>"content"</code> || Yes
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]]) || Yes
|-
| program ||name of program (25 character limit) || custom || Yes
|-
| title ||name of program (40 character limit) || custom || Yes
|-
| length || length of content in seconds || <code>seconds</code> (86400 for live stream) || Yes
|-
| airdate || the airdate in the linear TV; if not known set it to eg. "19700101 00:00:00" || YYYYMMDD HH24:MI:SS || Yes
|-
| isfullepisode || full episode flag || <code>"y"</code>- full episode, <code>"n"</code>- non full episode || Yes
|-
| adloadtype || type of ad load:
<code>"1"</code> Linear – matches TV ad load

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|}
<br />

=== Ad Metadata ===
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
<br/>
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}
<br />

=== Static Measurement ===
The Nielsen SDK is able to monitor Application launch events and how long your app has been running. Once the Nielsen module has been Initialized, pass a metadata object to loadMeta data that follows these rules:

{| class="wikitable"
|-
! Key !! Description !! Data Type !! Value !! Required?
|-
| type || asset type || fixed || <code>'static'</code> || Yes
|-
| assetid || Unique ID for each article || dynamic || custom || Yes
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values || dynamic || custom || Yes
|}
You only need to do this once upon app start.

== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
|On App Start||<code>NielsenModule.loadMetadata(contentMetadata);</code> || // contentMetadata Object contains the JSON metadata for the impression
|-
| rowspan="2" | Start of stream || <code>NielsenModule.play(channelName);</code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>NielsenModule.loadMetadata(contentMetadataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>NielsenModule.playheadPosition(position);</code> || // playheadPosition is position of the playhead while the content is being played
|-
| End of Stream || <code>NielsenModule.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 is processing playing information. [[DCR_Video_APP_SDK#play|play]] and [[DCR_Video_APP_SDK#loadMetadata|loadMetadata]] calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## [[DCR_Video_APP_SDK#playheadPosition|playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[DCR_Video_APP_SDK#stop|stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[DCR_Video_APP_SDK#end|end]] – SDK instance exits from Processing state when this API is called.

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.

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

=== Sequence of Calls ===
=== play ===
Use the play function to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player.
<syntaxhighlight lang="javascript"> NielsenModule.play(channelInfo);</syntaxhighlight>

=== loadMetadata ===
The loadMetadata function is used to inform the SDK about new content. The contentMetadata object passed in should contain the values as described above.
<syntaxhighlight lang="javascript"> NielsenModule.loadMetadata(contentMetadata);</syntaxhighlight>

=== playheadPosition ===
Use playheadPosition to tell the SDK about the current position in the video. For live content this should be the UTC timestamp in seconds, for on-demand content simply the second in the video.
<syntaxhighlight lang="javascript"> NielsenModule.playheadPosition(playheadPos);</syntaxhighlight>

=== stop ===
Tell the SDK that content playback has stopped.
<syntaxhighlight lang="javascript"> NielsenModule.stop();</syntaxhighlight>

=== end ===
When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
<syntaxhighlight lang="javascript"> NielsenModule.end();</syntaxhighlight>

== Privacy and Opt-Out ==

=== Opt-Out Implementation ===
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL for the Nielsen Privacy web page should be retrieved from via the <code>optOutURL()</code> method of the SDK bridge and opened in 'WebView' / External browser.
*If the returned value is null or empty, handle the exception gracefully and retry later.

Due to the limitation that native methods can't return values directly, the URL will be sent to the Javascript context as "OptOutUrl" event, with the url as the payload.

<syntaxhighlight lang="javascript">
const nielsen = new NativeEventEmitter(NielsenModule);

const subscription = nielsen.addListener(
'OptOutUrl',
(data) => {
//display data.url
}
);
NielsenModule.optOutUrl();
//...
subscription.remove(); // do not forget to unsubscribe
</syntaxhighlight>

The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy iOS.jpg|link=]]

*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

Users can opt out or opt back into Nielsen Measurement. Opt-Out feature relies on iOS' system setting – "Limit Ad Tracking". The setting can be accessed in the Settings application on any iOS device: '''Settings → Privacy → Advertising → Limit Ad Tracking'''.

User is opted out of Nielsen online measurement research when the "Limit Ad Tracking" setting is enabled.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

== 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_devDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:

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

<syntaxhighlight lang="javascript">
let appInformation = {
"appid": "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"sfcode": "it"
// Remove Flag: "nol_devDebug": "DEBUG"
};
NielsenModule.init(appInformation);
</syntaxhighlight>

DCR React Native Integration

2018-05-08T08:32:12Z

NielsSedat: /* Sample SDK Initialization Code */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International}} {{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 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 app was running
*Time of viewing a sub section / page in the application.

This guide will show how to use the Nielsen SDK in React Native applications on Android and iOS devices. We will not go into detail about what React Native is or how to create Apps with this Framework. If you are looking for information on this, please read the [http://facebook.github.io/react-native/ React-Native] documentation.

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

For more detail on the native SDKs please refer to the App integration guides available on this portal.

== Implementation ==
This guide covers implementation covers

* the implementation of React-Native bridges for iOS and Android
* the usage of the exposed Javascript API

What we will not cover is the general setup of React-Native applications. If you are new to React-Native please refer to [https://facebook.github.io/react-native/ React-Native] for documentation.

For simplicity we have focused on implementing a single instance of the Nielsen SDK. Should there be the need for multiple instances developers have to add some logic for that.

== Setting up your Environment ==
<div class="section-container auto" data-section>
<div class="section">
<p class="title" data-section-title>iOS</p>
<div class="content" data-section-content>

The first step is to ensure that the following frameworks and libraries are imported into the Frameworks folder of the iOS Xcode project before working with the Nielsen SDK.

* 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 (Not applicable for International (Germany))
* CoreMedia.framework
* NielsenAppApi.framework

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

<br />
</div>
</div>
<div class="section">
<p class="title" data-section-title>Android</p>
<div class="content" data-section-content>
The first step is to add the AppSdk.jar library that runs on the Android’s Dalvik Virtual Machine to the libs folder (might have to be created) for the Android part of your project.

<code>android/app/libs</code>

The next step is to add the following permissions on the project’s ''AndroidManifest.xml'' file.
<syntaxhighlight lang="java"><uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:required="false" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details to handle 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 there is a Google service available and updated.
* If not available or updated, App SDK will not use this service when executing its functions and will make reference to missing imports and the app will not be compiled.

<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.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;
</div>
</div>
</div>

== Creating React-Native bridges for the Nielsen SDK ==
In order to be able to use Nielsens native SDKs React-Native bridges have to be implemented and added to the iOS and Android projects. The following shows implementations for both platforms, that provide the basic methods to start measuring the app. The source code can be copied from below to provide an easy start.

Please refer to the integration guides for Nielsens native SDKs to get a deeper understanding of the technical detail.

<div class="section-container auto" data-section>
<div class="section">
<p class="title" data-section-title>iOS</p>
<div class="content" data-section-content>

The iOS implementation of the bridge module consists of two files, a header and an implementation file, written in Objective-c. These two files need to be added to the iOS XCode project.

The header file is <code>NielsenReactBridge.h</code>
<syntaxhighlight lang="objective-c">
// Copyright <2018> <The Nielsen Company>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
// (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
// merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

#import <React/RCTBridgeModule.h>
#import <React/RCTEventEmitter.h>

@interface NielsenReactBridge : RCTEventEmitter <RCTBridgeModule>
@end
</syntaxhighlight>

The actual implementation of the module happens in <code>NielsenReactBridge.m</code>
<syntaxhighlight lang="objective-c">
// Copyright <2018> <The Nielsen Company>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
// (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
// merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

#import "NielsenReactBridge.h"
#import <NielsenAppApi/NielsenAppApi.h>

static NSString *const TAG = @"NielsenReactBridge";

@interface NielsenReactBridge() <NielsenAppApiDelegate>
@property (strong) NielsenAppApi* nlsSDk;
@end

@implementation NielsenReactBridge
RCT_EXPORT_MODULE();

/**
* Since we need to communicate the opt-out url to javascript via events
* we need to implement the following method
*/
- (NSArray<NSString *> *)supportedEvents
{
return @[@"OptOutUrl"];
}

/**
* A logging helper method
*/
void NLSLog(NSString* tag, NSString* format, ...)
{
va_list argList;
va_start(argList, format);
NSLog(@"%@", [[NSString alloc] initWithFormat:[NSString stringWithFormat:@"[%@]: %@", tag, format] arguments: argList]);
va_end(argList);
}

/**
* Init creates the SDK instance and passes on the provided metadata.
* appInfo is simply passed to initWithAppInfo since the SDK already
* performs error checking
*/
RCT_EXPORT_METHOD(init:(NSDictionary *)appInfo)
{
NLSLog(TAG, @"init called with metadat '%@''", appInfo);

if (!self.nlsSDk) {
self.nlsSDk= [[NielsenAppApi alloc] initWithAppInfo:appInfo delegate:self];
}
}

/**
* Wrapper for the SDK's play method. The provided metadata is
* simply passed on
*/
RCT_EXPORT_METHOD(play:(NSDictionary *)channelInfo)
{
NLSLog(TAG, @"play called with metadata '%@'", channelInfo);

if (self.nlsSDk) {
[self.nlsSDk play:channelInfo];
}
}

/**
* Wrapper for the SDK's loadMetadata method. The provided contentMetaData is
* simply passed on
*/
RCT_EXPORT_METHOD(loadMetadata:(NSDictionary *)contentMetaData)
{
NLSLog(TAG, @"loadMetadata called with '%@'", contentMetaData);

if (self.nlsSDk) {
[self.nlsSDk loadMetadata:contentMetaData];
}
}

/**
* Wrapper for the SDK's setPlayheadPosition method. The provided playhead is
* simply passed on to the SDK
*/
RCT_EXPORT_METHOD(setPlayheadPosition:(nonnull NSNumber *)ph)
{
NLSLog(TAG, @"setHeadPosition called with '%@'",ph);

if (self.nlsSDk) {
[self.nlsSDk playheadPosition:[ph longLongValue]];
}
}

/**
* Wrapper for the SDK's stop method.
*/
RCT_EXPORT_METHOD(stop)
{
NLSLog(TAG, @"stop called");

if (self.nlsSDk) {
[self.nlsSDk stop];
}
}

/**
* Wrapper for the SDK's end method.
*/
RCT_EXPORT_METHOD(end)
{
NLSLog(TAG, @"end called");

if (self.nlsSDk) {
[self.nlsSDk end];
}
}

/**
* optOutUrl retrieves the url from the SDK instance and fires off the
* OptOutUrl event, so the url can be captured
*/
RCT_EXPORT_METHOD(optOutUrl)
{
[self sendEventWithName:@"OptOutUrl" body:@{@"url": self.nlsSDk.optOutURL}];
}
@end
</syntaxhighlight>
</div>
</div>
<div class="section">
<p class="title" data-section-title>Android</p>
<div class="content" data-section-content>

The Android implementation of the bridge module consists of two files, an implementation of a NielsenPackage to announce the actual module and the implementation of NielsenReactBridge itself. The implementations have been put into the Java package

<code>com.nielsen.app.react</code>

The package implementation is in <code>com/nielsen/app/react/NielsenPackage.java</code>
<syntaxhighlight lang="java">
// Copyright <2018> <The Nielsen Company>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
// (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
// merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package com.nielsen.app.react;

import com.facebook.react.bridge.NativeModule;
import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.ReactPackage;
import com.facebook.react.uimanager.ViewManager;
import com.nielsen.app.react.NielsenReactBridge;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

/**
*/
public class NielsenPackage implements ReactPackage {

/**
* Override createNativeModules to return our bridge module
*/
@Override
public List<NativeModule> createNativeModules(ReactApplicationContext reactContext) {
List<NativeModule> modules = new ArrayList<>();
modules.add(new NielsenReactBridge(reactContext));

return modules;
}

/**
*/
@Override
public List<ViewManager> createViewManagers(ReactApplicationContext reactContext) {
return Collections.emptyList();
}
}
</syntaxhighlight>

<code>com/nielsen/app/react/NielsenReactBridge.java</code>
<syntaxhighlight lang="java">
// Copyright <2018> <The Nielsen Company>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
// (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
// merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package com.nielsen.app.react;

import android.util.Log;
import com.facebook.react.bridge.LifecycleEventListener;
import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.bridge.ReactContextBaseJavaModule;
import com.facebook.react.modules.core.DeviceEventManagerModule;
import com.facebook.react.bridge.ReactMethod;
import com.facebook.react.bridge.ReadableMap;
import com.facebook.react.bridge.WritableMap;
import com.facebook.react.bridge.Arguments;
import com.facebook.react.bridge.ReadableMapKeySetIterator;
import com.nielsen.app.sdk.AppSdk;
import com.nielsen.app.sdk.IAppNotifier;
import com.nielsen.app.sdk.AppLaunchMeasurementManager;
import org.json.JSONObject;
import org.json.JSONException;

/**
* NielsenReactBridge is the class briding between react JS code
* and the native Nielsen SDK.
*/
public class NielsenReactBridge extends ReactContextBaseJavaModule
implements IAppNotifier, LifecycleEventListener {

/**
*/
private static final String NIELSEN_TAG = "NielsenReactBridge";
private AppSdk mAppSdk = null; // the AppSdk main object

/**
* Constructor for the NielsenReactBridge
* Adds the new instance as LifeCycleEventListener for conttex
* @param context The react application context
*/
public NielsenReactBridge(ReactApplicationContext context) {
super(context);
context.addLifecycleEventListener(this);
}

/**
* Implements getName method from ReactContextBaseJavaModule
* @return The constant string 'NielsenReactBridge'
*/
@Override
public String getName() {
return "NielsenReactBridge";
}

/**
* Implements getName method from IAppNotifier
*/
@Override
public void onAppSdkEvent(long l, int i, String s) {}

/**
* Initializes the module for use
* @param obj An instance of ReadableMap (mapped JS object) containing
* initialization meta data
*/
@ReactMethod
public void init(final ReadableMap obj) {

Log.d(NIELSEN_TAG, "Called init");

if (null == mAppSdk) {
try {
JSONObject appSdkConfig = readableMapToJSONObject(obj);
mAppSdk = new AppSdk(getReactApplicationContext(), appSdkConfig, this);
if (!mAppSdk.isValid())
{
Log.e(NIELSEN_TAG, "SDK Init failed");
}
}
catch(Exception ex) {
}
}
}

/**
* Static method to convert ReadableMap instances to JSONObject instances
* (used by the Nielsen SDK)
* @param obj The ReadableMap instance to be converted
* @return An instance of JSONObject containing the mapped JS object
* values (if successful, empty otherwise)
*/
static private JSONObject readableMapToJSONObject(final ReadableMap obj) {

JSONObject ret = new JSONObject();

try {
ReadableMapKeySetIterator it = obj.keySetIterator();
while (it.hasNextKey()) {
String key = it.nextKey();
ret.put(key, obj.getDynamic(key).asString());
}
}
catch (JSONException ex) {
Log.e(NIELSEN_TAG, ex.getMessage());
}

return ret;
}

/**
* Wrapper for the Nielsen SDK play method. Simply forwards calls
* to the SDK.
* @param obj ReadableMap instance containing the mapped JS meta
* data object, e.g. {channelName: 'channel name here'}
*/
@ReactMethod
public void play(final ReadableMap obj) {

Log.d(NIELSEN_TAG, "Called play " + obj.toString());
if (null != mAppSdk) {
JSONObject playObject = readableMapToJSONObject(obj);
mAppSdk.play(playObject);
}
}

/**
* Wrapper for the Nielsen SDK loadMetadata method. Simply forwards calls
* to the SDK.
* @param obj ReadableMap instance containing the mapped JS meta
* data object
*/
@ReactMethod
public void loadMetadata(final ReadableMap obj) {

Log.d(NIELSEN_TAG,"Called loadMetadata");
if (null != mAppSdk) {
JSONObject contentMetadata = readableMapToJSONObject(obj);
mAppSdk.loadMetadata(contentMetadata);
}
}

/**
* Wrapper for the Nielsen SDK setPlayheadPosition method. Simply
* forwards calls to the SDK.
* @param ph The current playhead position
*/
@ReactMethod
public void setPlayheadPosition(final Double ph) {

Log.d(NIELSEN_TAG,"Called setPlayHeadPosition: " + " " + ph);
if (null != mAppSdk) {
mAppSdk.setPlayheadPosition(ph.longValue());
}
}

/**
* Wrapper for the Nielsen SDK stop method. Simply
* forwards calls to the SDK.
*/
@ReactMethod
public void stop() {
Log.d(NIELSEN_TAG, "Called stop");
if (null != mAppSdk) {
mAppSdk.stop();
}
}

/**
* Wrapper for the Nielsen SDK end method. Simply
* forwards calls to the SDK.
*/
@ReactMethod
public void end() {

Log.d(NIELSEN_TAG,"Called end");
if (null != mAppSdk) {
mAppSdk.end();
}
}

/**
* Wrapper to retrieve the optOutUrl from the Nielsen SDK.
* Emits a "OptOutUrl" event with the url as payload.
* Needs to be catched in JS
*/
@ReactMethod
public void optOutUrl() {

WritableMap params = Arguments.createMap();
if (null != mAppSdk) {
params.putString("url", mAppSdk.userOptOutURLString());
}

getReactApplicationContext()
.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
.emit("OptOutUrl", params);
}

/**
* Implements LifecycleEventListener's onHostResume method.
* Uses AppLaunchMeasurementManager.appInForeground to notify SDK about
* app coming to foreground again
*/
@Override
public void onHostResume() {

Log.d(NIELSEN_TAG,"Called onHostResume");
AppLaunchMeasurementManager.appInForeground(getReactApplicationContext());
}

/**
* Implements LifecycleEventListener's onHostPause method.
* Uses AppLaunchMeasurementManager.appInBackground to notify SDK about
* app going to background
*/
@Override
public void onHostPause() {

Log.d(NIELSEN_TAG,"Called onHostPause");
AppLaunchMeasurementManager.appInBackground(getReactApplicationContext());
}

/**
* Implements LifecycleEventListener's onHostDestroy method.
*/
@Override
public void onHostDestroy() {
Log.d(NIELSEN_TAG,"Called onHostDestroy");
}
}
</syntaxhighlight>
<br />

The package needs to be provided in the getPackages method of the MainApplication.java file. This file exists under the android folder in your react-native application directory. The path to this file is: android/app/src/main/java/com/your-app-name/MainApplication.java.
<br />

<syntaxhighlight lang="java">
import com.nielsen.app.react.NielsenPackage; //<-- Import the package in MainApplication.java
//...

protected List<ReactPackage> getPackages() {
return Arrays.<ReactPackage>asList(
//...,
new NielsenPackage()); // <-- Add the bridge package to the getPackages method.
}
</syntaxhighlight>
</div>
</div>

In order to import the bridges into the Javascript context, create a file
<code>NielsenModule.js</code>
<syntaxhighlight lang="javascript">
import { NativeModules } from 'react-native'

export default NativeModules.NielsenReactBridge
</syntaxhighlight>

== SDK Initialization ==
The bridge implementations above allow the usage of one instance of the Nielsen App SDK. The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. For more information on this please read the relevant App SDK Guide.

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? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || Yes || 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.
'''Italian Clients'''
* "it"
|| Nielsen-specified || Yes || "it"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"
|}
<br />

==== Sample SDK Initialization Code ====
<syntaxhighlight lang="javascript">
import NielsenModule from './NielsenModule';

let appInformation = {"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"sfcode": "it",
"nol_devDebug": @"DEBUG"};
NielsenModule.init(appInformation);
</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.

== Configure Payload ==
All metadata is passed to the bridges in form of objects containing the in the following described properties. An example metadata object could look like
<syntaxhighlight lang="javascript">
let metadata = {
'type':'content',
'assetid':'asset12345',
'program':'My Program',
'title':'My Title',
'length':'42',
'airdate':'20180302 16:32:00',
'isfullepisode':'n',
'adloadtype':'2'
};
</syntaxhighlight>

The following section will explain the different values.

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

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

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>"content"</code> || Yes
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]]) || Yes
|-
| program ||name of program (25 character limit) || custom || Yes
|-
| title ||name of program (40 character limit) || custom || Yes
|-
| length || length of content in seconds || <code>seconds</code> (86400 for live stream) || Yes
|-
| airdate || the airdate in the linear TV; if not known set it to eg. "19700101 00:00:00" || YYYYMMDD HH24:MI:SS || Yes
|-
| isfullepisode || full episode flag || <code>"y"</code>- full episode, <code>"n"</code>- non full episode || Yes
|-
| adloadtype || type of ad load:
<code>"1"</code> Linear – matches TV ad load

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|}
<br />

=== Ad Metadata ===
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
<br/>
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}
<br />

=== Static Measurement ===
The Nielsen SDK is able to monitor Application launch events and how long your app has been running. Once the Nielsen module has been Initialized, pass a metadata object to loadMeta data that follows these rules:

{| class="wikitable"
|-
! Key !! Description !! Data Type !! Value !! Required?
|-
| type || asset type || fixed || <code>'static'</code> || Yes
|-
| assetid || Unique ID for each article || dynamic || custom || Yes
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values || dynamic || custom || Yes
|}
You only need to do this once upon app start.

== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
|On App Start||<code>NielsenModule.loadMetadata(contentMetadata);</code> || // contentMetadata Object contains the JSON metadata for the impression
|-
| rowspan="2" | Start of stream || <code>NielsenModule.play(channelName);</code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>NielsenModule.loadMetadata(contentMetadataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>NielsenModule.playheadPosition(position);</code> || // playheadPosition is position of the playhead while the content is being played
|-
| End of Stream || <code>NielsenModule.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 is processing playing information. [[DCR_Video_APP_SDK#play|play]] and [[DCR_Video_APP_SDK#loadMetadata|loadMetadata]] calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## [[DCR_Video_APP_SDK#playheadPosition|playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[DCR_Video_APP_SDK#stop|stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[DCR_Video_APP_SDK#end|end]] – SDK instance exits from Processing state when this API is called.

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.

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

=== Sequence of Calls ===
=== play ===
Use the play function to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player.
<syntaxhighlight lang="javascript"> NielsenModule.play(channelInfo);</syntaxhighlight>

=== loadMetadata ===
The loadMetadata function is used to inform the SDK about new content. The contentMetadata object passed in should contain the values as described above.
<syntaxhighlight lang="javascript"> NielsenModule.loadMetadata(contentMetadata);</syntaxhighlight>

=== playheadPosition ===
Use playheadPosition to tell the SDK about the current position in the video. For live content this should be the UTC timestamp in seconds, for on-demand content simply the second in the video.
<syntaxhighlight lang="javascript"> NielsenModule.playheadPosition(playheadPos);</syntaxhighlight>

=== stop ===
Tell the SDK that content playback has stopped.
<syntaxhighlight lang="javascript"> NielsenModule.stop();</syntaxhighlight>

=== end ===
When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
<syntaxhighlight lang="javascript"> NielsenModule.end();</syntaxhighlight>

== Privacy and Opt-Out ==

=== Opt-Out Implementation ===
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL for the Nielsen Privacy web page should be retrieved from via the <code>optOutURL()</code> method of the SDK bridge and opened in 'WebView' / External browser.
*If the returned value is null or empty, handle the exception gracefully and retry later.

Due to the limitation that native methods can't return values directly, the URL will be sent to the Javascript context as "OptOutUrl" event, with the url as the payload.

<syntaxhighlight lang="javascript">
const nielsen = new NativeEventEmitter(NielsenModule);

const subscription = nielsen.addListener(
'OptOutUrl',
(data) => {
//display data.url
}
);
NielsenModule.optOutUrl();
//...
subscription.remove(); // do not forget to unsubscribe
</syntaxhighlight>

The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy iOS.jpg|link=]]

*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

Users can opt out or opt back into Nielsen Measurement. Opt-Out feature relies on iOS' system setting – "Limit Ad Tracking". The setting can be accessed in the Settings application on any iOS device: '''Settings → Privacy → Advertising → Limit Ad Tracking'''.

User is opted out of Nielsen online measurement research when the "Limit Ad Tracking" setting is enabled.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

== 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_devDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:

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

<syntaxhighlight lang="javascript">
let appInformation = {
"appid": "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"sfcode": "it"
// Remove Flag: "nol_devDebug": "DEBUG"
};
NielsenModule.init(appInformation);
</syntaxhighlight>

DCR React Native Integration

2018-05-08T08:31:21Z

NielsSedat: /* Going Live */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International}} {{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 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 app was running
*Time of viewing a sub section / page in the application.

This guide will show how to use the Nielsen SDK in React Native applications on Android and iOS devices. We will not go into detail about what React Native is or how to create Apps with this Framework. If you are looking for information on this, please read the [http://facebook.github.io/react-native/ React-Native] documentation.

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

For more detail on the native SDKs please refer to the App integration guides available on this portal.

== Implementation ==
This guide covers implementation covers

* the implementation of React-Native bridges for iOS and Android
* the usage of the exposed Javascript API

What we will not cover is the general setup of React-Native applications. If you are new to React-Native please refer to [https://facebook.github.io/react-native/ React-Native] for documentation.

For simplicity we have focused on implementing a single instance of the Nielsen SDK. Should there be the need for multiple instances developers have to add some logic for that.

== Setting up your Environment ==
<div class="section-container auto" data-section>
<div class="section">
<p class="title" data-section-title>iOS</p>
<div class="content" data-section-content>

The first step is to ensure that the following frameworks and libraries are imported into the Frameworks folder of the iOS Xcode project before working with the Nielsen SDK.

* 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 (Not applicable for International (Germany))
* CoreMedia.framework
* NielsenAppApi.framework

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

<br />
</div>
</div>
<div class="section">
<p class="title" data-section-title>Android</p>
<div class="content" data-section-content>
The first step is to add the AppSdk.jar library that runs on the Android’s Dalvik Virtual Machine to the libs folder (might have to be created) for the Android part of your project.

<code>android/app/libs</code>

The next step is to add the following permissions on the project’s ''AndroidManifest.xml'' file.
<syntaxhighlight lang="java"><uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:required="false" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details to handle 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 there is a Google service available and updated.
* If not available or updated, App SDK will not use this service when executing its functions and will make reference to missing imports and the app will not be compiled.

<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.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;
</div>
</div>
</div>

== Creating React-Native bridges for the Nielsen SDK ==
In order to be able to use Nielsens native SDKs React-Native bridges have to be implemented and added to the iOS and Android projects. The following shows implementations for both platforms, that provide the basic methods to start measuring the app. The source code can be copied from below to provide an easy start.

Please refer to the integration guides for Nielsens native SDKs to get a deeper understanding of the technical detail.

<div class="section-container auto" data-section>
<div class="section">
<p class="title" data-section-title>iOS</p>
<div class="content" data-section-content>

The iOS implementation of the bridge module consists of two files, a header and an implementation file, written in Objective-c. These two files need to be added to the iOS XCode project.

The header file is <code>NielsenReactBridge.h</code>
<syntaxhighlight lang="objective-c">
// Copyright <2018> <The Nielsen Company>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
// (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
// merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

#import <React/RCTBridgeModule.h>
#import <React/RCTEventEmitter.h>

@interface NielsenReactBridge : RCTEventEmitter <RCTBridgeModule>
@end
</syntaxhighlight>

The actual implementation of the module happens in <code>NielsenReactBridge.m</code>
<syntaxhighlight lang="objective-c">
// Copyright <2018> <The Nielsen Company>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
// (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
// merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

#import "NielsenReactBridge.h"
#import <NielsenAppApi/NielsenAppApi.h>

static NSString *const TAG = @"NielsenReactBridge";

@interface NielsenReactBridge() <NielsenAppApiDelegate>
@property (strong) NielsenAppApi* nlsSDk;
@end

@implementation NielsenReactBridge
RCT_EXPORT_MODULE();

/**
* Since we need to communicate the opt-out url to javascript via events
* we need to implement the following method
*/
- (NSArray<NSString *> *)supportedEvents
{
return @[@"OptOutUrl"];
}

/**
* A logging helper method
*/
void NLSLog(NSString* tag, NSString* format, ...)
{
va_list argList;
va_start(argList, format);
NSLog(@"%@", [[NSString alloc] initWithFormat:[NSString stringWithFormat:@"[%@]: %@", tag, format] arguments: argList]);
va_end(argList);
}

/**
* Init creates the SDK instance and passes on the provided metadata.
* appInfo is simply passed to initWithAppInfo since the SDK already
* performs error checking
*/
RCT_EXPORT_METHOD(init:(NSDictionary *)appInfo)
{
NLSLog(TAG, @"init called with metadat '%@''", appInfo);

if (!self.nlsSDk) {
self.nlsSDk= [[NielsenAppApi alloc] initWithAppInfo:appInfo delegate:self];
}
}

/**
* Wrapper for the SDK's play method. The provided metadata is
* simply passed on
*/
RCT_EXPORT_METHOD(play:(NSDictionary *)channelInfo)
{
NLSLog(TAG, @"play called with metadata '%@'", channelInfo);

if (self.nlsSDk) {
[self.nlsSDk play:channelInfo];
}
}

/**
* Wrapper for the SDK's loadMetadata method. The provided contentMetaData is
* simply passed on
*/
RCT_EXPORT_METHOD(loadMetadata:(NSDictionary *)contentMetaData)
{
NLSLog(TAG, @"loadMetadata called with '%@'", contentMetaData);

if (self.nlsSDk) {
[self.nlsSDk loadMetadata:contentMetaData];
}
}

/**
* Wrapper for the SDK's setPlayheadPosition method. The provided playhead is
* simply passed on to the SDK
*/
RCT_EXPORT_METHOD(setPlayheadPosition:(nonnull NSNumber *)ph)
{
NLSLog(TAG, @"setHeadPosition called with '%@'",ph);

if (self.nlsSDk) {
[self.nlsSDk playheadPosition:[ph longLongValue]];
}
}

/**
* Wrapper for the SDK's stop method.
*/
RCT_EXPORT_METHOD(stop)
{
NLSLog(TAG, @"stop called");

if (self.nlsSDk) {
[self.nlsSDk stop];
}
}

/**
* Wrapper for the SDK's end method.
*/
RCT_EXPORT_METHOD(end)
{
NLSLog(TAG, @"end called");

if (self.nlsSDk) {
[self.nlsSDk end];
}
}

/**
* optOutUrl retrieves the url from the SDK instance and fires off the
* OptOutUrl event, so the url can be captured
*/
RCT_EXPORT_METHOD(optOutUrl)
{
[self sendEventWithName:@"OptOutUrl" body:@{@"url": self.nlsSDk.optOutURL}];
}
@end
</syntaxhighlight>
</div>
</div>
<div class="section">
<p class="title" data-section-title>Android</p>
<div class="content" data-section-content>

The Android implementation of the bridge module consists of two files, an implementation of a NielsenPackage to announce the actual module and the implementation of NielsenReactBridge itself. The implementations have been put into the Java package

<code>com.nielsen.app.react</code>

The package implementation is in <code>com/nielsen/app/react/NielsenPackage.java</code>
<syntaxhighlight lang="java">
// Copyright <2018> <The Nielsen Company>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
// (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
// merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package com.nielsen.app.react;

import com.facebook.react.bridge.NativeModule;
import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.ReactPackage;
import com.facebook.react.uimanager.ViewManager;
import com.nielsen.app.react.NielsenReactBridge;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

/**
*/
public class NielsenPackage implements ReactPackage {

/**
* Override createNativeModules to return our bridge module
*/
@Override
public List<NativeModule> createNativeModules(ReactApplicationContext reactContext) {
List<NativeModule> modules = new ArrayList<>();
modules.add(new NielsenReactBridge(reactContext));

return modules;
}

/**
*/
@Override
public List<ViewManager> createViewManagers(ReactApplicationContext reactContext) {
return Collections.emptyList();
}
}
</syntaxhighlight>

<code>com/nielsen/app/react/NielsenReactBridge.java</code>
<syntaxhighlight lang="java">
// Copyright <2018> <The Nielsen Company>
//
// Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files
// (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify,
// merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
// LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package com.nielsen.app.react;

import android.util.Log;
import com.facebook.react.bridge.LifecycleEventListener;
import com.facebook.react.bridge.ReactApplicationContext;
import com.facebook.react.bridge.ReactContextBaseJavaModule;
import com.facebook.react.modules.core.DeviceEventManagerModule;
import com.facebook.react.bridge.ReactMethod;
import com.facebook.react.bridge.ReadableMap;
import com.facebook.react.bridge.WritableMap;
import com.facebook.react.bridge.Arguments;
import com.facebook.react.bridge.ReadableMapKeySetIterator;
import com.nielsen.app.sdk.AppSdk;
import com.nielsen.app.sdk.IAppNotifier;
import com.nielsen.app.sdk.AppLaunchMeasurementManager;
import org.json.JSONObject;
import org.json.JSONException;

/**
* NielsenReactBridge is the class briding between react JS code
* and the native Nielsen SDK.
*/
public class NielsenReactBridge extends ReactContextBaseJavaModule
implements IAppNotifier, LifecycleEventListener {

/**
*/
private static final String NIELSEN_TAG = "NielsenReactBridge";
private AppSdk mAppSdk = null; // the AppSdk main object

/**
* Constructor for the NielsenReactBridge
* Adds the new instance as LifeCycleEventListener for conttex
* @param context The react application context
*/
public NielsenReactBridge(ReactApplicationContext context) {
super(context);
context.addLifecycleEventListener(this);
}

/**
* Implements getName method from ReactContextBaseJavaModule
* @return The constant string 'NielsenReactBridge'
*/
@Override
public String getName() {
return "NielsenReactBridge";
}

/**
* Implements getName method from IAppNotifier
*/
@Override
public void onAppSdkEvent(long l, int i, String s) {}

/**
* Initializes the module for use
* @param obj An instance of ReadableMap (mapped JS object) containing
* initialization meta data
*/
@ReactMethod
public void init(final ReadableMap obj) {

Log.d(NIELSEN_TAG, "Called init");

if (null == mAppSdk) {
try {
JSONObject appSdkConfig = readableMapToJSONObject(obj);
mAppSdk = new AppSdk(getReactApplicationContext(), appSdkConfig, this);
if (!mAppSdk.isValid())
{
Log.e(NIELSEN_TAG, "SDK Init failed");
}
}
catch(Exception ex) {
}
}
}

/**
* Static method to convert ReadableMap instances to JSONObject instances
* (used by the Nielsen SDK)
* @param obj The ReadableMap instance to be converted
* @return An instance of JSONObject containing the mapped JS object
* values (if successful, empty otherwise)
*/
static private JSONObject readableMapToJSONObject(final ReadableMap obj) {

JSONObject ret = new JSONObject();

try {
ReadableMapKeySetIterator it = obj.keySetIterator();
while (it.hasNextKey()) {
String key = it.nextKey();
ret.put(key, obj.getDynamic(key).asString());
}
}
catch (JSONException ex) {
Log.e(NIELSEN_TAG, ex.getMessage());
}

return ret;
}

/**
* Wrapper for the Nielsen SDK play method. Simply forwards calls
* to the SDK.
* @param obj ReadableMap instance containing the mapped JS meta
* data object, e.g. {channelName: 'channel name here'}
*/
@ReactMethod
public void play(final ReadableMap obj) {

Log.d(NIELSEN_TAG, "Called play " + obj.toString());
if (null != mAppSdk) {
JSONObject playObject = readableMapToJSONObject(obj);
mAppSdk.play(playObject);
}
}

/**
* Wrapper for the Nielsen SDK loadMetadata method. Simply forwards calls
* to the SDK.
* @param obj ReadableMap instance containing the mapped JS meta
* data object
*/
@ReactMethod
public void loadMetadata(final ReadableMap obj) {

Log.d(NIELSEN_TAG,"Called loadMetadata");
if (null != mAppSdk) {
JSONObject contentMetadata = readableMapToJSONObject(obj);
mAppSdk.loadMetadata(contentMetadata);
}
}

/**
* Wrapper for the Nielsen SDK setPlayheadPosition method. Simply
* forwards calls to the SDK.
* @param ph The current playhead position
*/
@ReactMethod
public void setPlayheadPosition(final Double ph) {

Log.d(NIELSEN_TAG,"Called setPlayHeadPosition: " + " " + ph);
if (null != mAppSdk) {
mAppSdk.setPlayheadPosition(ph.longValue());
}
}

/**
* Wrapper for the Nielsen SDK stop method. Simply
* forwards calls to the SDK.
*/
@ReactMethod
public void stop() {
Log.d(NIELSEN_TAG, "Called stop");
if (null != mAppSdk) {
mAppSdk.stop();
}
}

/**
* Wrapper for the Nielsen SDK end method. Simply
* forwards calls to the SDK.
*/
@ReactMethod
public void end() {

Log.d(NIELSEN_TAG,"Called end");
if (null != mAppSdk) {
mAppSdk.end();
}
}

/**
* Wrapper to retrieve the optOutUrl from the Nielsen SDK.
* Emits a "OptOutUrl" event with the url as payload.
* Needs to be catched in JS
*/
@ReactMethod
public void optOutUrl() {

WritableMap params = Arguments.createMap();
if (null != mAppSdk) {
params.putString("url", mAppSdk.userOptOutURLString());
}

getReactApplicationContext()
.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter.class)
.emit("OptOutUrl", params);
}

/**
* Implements LifecycleEventListener's onHostResume method.
* Uses AppLaunchMeasurementManager.appInForeground to notify SDK about
* app coming to foreground again
*/
@Override
public void onHostResume() {

Log.d(NIELSEN_TAG,"Called onHostResume");
AppLaunchMeasurementManager.appInForeground(getReactApplicationContext());
}

/**
* Implements LifecycleEventListener's onHostPause method.
* Uses AppLaunchMeasurementManager.appInBackground to notify SDK about
* app going to background
*/
@Override
public void onHostPause() {

Log.d(NIELSEN_TAG,"Called onHostPause");
AppLaunchMeasurementManager.appInBackground(getReactApplicationContext());
}

/**
* Implements LifecycleEventListener's onHostDestroy method.
*/
@Override
public void onHostDestroy() {
Log.d(NIELSEN_TAG,"Called onHostDestroy");
}
}
</syntaxhighlight>
<br />

The package needs to be provided in the getPackages method of the MainApplication.java file. This file exists under the android folder in your react-native application directory. The path to this file is: android/app/src/main/java/com/your-app-name/MainApplication.java.
<br />

<syntaxhighlight lang="java">
import com.nielsen.app.react.NielsenPackage; //<-- Import the package in MainApplication.java
//...

protected List<ReactPackage> getPackages() {
return Arrays.<ReactPackage>asList(
//...,
new NielsenPackage()); // <-- Add the bridge package to the getPackages method.
}
</syntaxhighlight>
</div>
</div>

In order to import the bridges into the Javascript context, create a file
<code>NielsenModule.js</code>
<syntaxhighlight lang="javascript">
import { NativeModules } from 'react-native'

export default NativeModules.NielsenReactBridge
</syntaxhighlight>

== SDK Initialization ==
The bridge implementations above allow the usage of one instance of the Nielsen App SDK. The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object, which can be used simultaneously without any issue. For more information on this please read the relevant App SDK Guide.

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? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || Yes || 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.
'''Italian Clients'''
* "it"
|| Nielsen-specified || Yes || "it"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"
|}
<br />

==== Sample SDK Initialization Code ====
<syntaxhighlight lang="javascript">
import NielsenModule from './NielsenModule';

let appInformation = {"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"appversion": "1.0",
"appname": "app name here",
"sfcode": "it",
"nol_devDebug": @"DEBUG"};
NielsenModule.init(appInformation);
</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.

== Configure Payload ==
All metadata is passed to the bridges in form of objects containing the in the following described properties. An example metadata object could look like
<syntaxhighlight lang="javascript">
let metadata = {
'type':'content',
'assetid':'asset12345',
'program':'My Program',
'title':'My Title',
'length':'42',
'airdate':'20180302 16:32:00',
'isfullepisode':'n',
'adloadtype':'2'
};
</syntaxhighlight>

The following section will explain the different values.

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

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

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of asset || <code>"content"</code> || Yes
|-
| assetid || unique ID assigned to asset || custom <br>(no [[Special Characters]]) || Yes
|-
| program ||name of program (25 character limit) || custom || Yes
|-
| title ||name of program (40 character limit) || custom || Yes
|-
| length || length of content in seconds || <code>seconds</code> (86400 for live stream) || Yes
|-
| airdate || the airdate in the linear TV; if not known set it to eg. "19700101 00:00:00" || YYYYMMDD HH24:MI:SS || Yes
|-
| isfullepisode || full episode flag || <code>"y"</code>- full episode, <code>"n"</code>- non full episode || Yes
|-
| adloadtype || type of ad load:
<code>"1"</code> Linear – matches TV ad load

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|}
<br />

=== Ad Metadata ===
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
<br/>
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}
<br />

=== Static Measurement ===
The Nielsen SDK is able to monitor Application launch events and how long your app has been running. Once the Nielsen module has been Initialized, pass a metadata object to loadMeta data that follows these rules:

{| class="wikitable"
|-
! Key !! Description !! Data Type !! Value !! Required?
|-
| type || asset type || fixed || <code>'static'</code> || Yes
|-
| assetid || Unique ID for each article || dynamic || custom || Yes
|-
| section || section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values || dynamic || custom || Yes
|}
You only need to do this once upon app start.

== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
|On App Start||<code>NielsenModule.loadMetadata(contentMetadata);</code> || // contentMetadata Object contains the JSON metadata for the impression
|-
| rowspan="2" | Start of stream || <code>NielsenModule.play(channelName);</code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>NielsenModule.loadMetadata(contentMetadataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>NielsenModule.playheadPosition(position);</code> || // playheadPosition is position of the playhead while the content is being played
|-
| End of Stream || <code>NielsenModule.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 is processing playing information. [[DCR_Video_APP_SDK#play|play]] and [[DCR_Video_APP_SDK#loadMetadata|loadMetadata]] calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## [[DCR_Video_APP_SDK#playheadPosition|playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[DCR_Video_APP_SDK#stop|stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[DCR_Video_APP_SDK#end|end]] – SDK instance exits from Processing state when this API is called.

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.

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

=== Sequence of Calls ===
=== play ===
Use the play function to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player.
<syntaxhighlight lang="javascript"> NielsenModule.play(channelInfo);</syntaxhighlight>

=== loadMetadata ===
The loadMetadata function is used to inform the SDK about new content. The contentMetadata object passed in should contain the values as described above.
<syntaxhighlight lang="javascript"> NielsenModule.loadMetadata(contentMetadata);</syntaxhighlight>

=== playheadPosition ===
Use playheadPosition to tell the SDK about the current position in the video. For live content this should be the UTC timestamp in seconds, for on-demand content simply the second in the video.
<syntaxhighlight lang="javascript"> NielsenModule.playheadPosition(playheadPos);</syntaxhighlight>

=== stop ===
Tell the SDK that content playback has stopped.
<syntaxhighlight lang="javascript"> NielsenModule.stop();</syntaxhighlight>

=== end ===
When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
<syntaxhighlight lang="javascript"> NielsenModule.end();</syntaxhighlight>

== Privacy and Opt-Out ==

=== Opt-Out Implementation ===
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL for the Nielsen Privacy web page should be retrieved from via the <code>optOutURL()</code> method of the SDK bridge and opened in 'WebView' / External browser.
*If the returned value is null or empty, handle the exception gracefully and retry later.

Due to the limitation that native methods can't return values directly, the URL will be sent to the Javascript context as "OptOutUrl" event, with the url as the payload.

<syntaxhighlight lang="javascript">
const nielsen = new NativeEventEmitter(NielsenModule);

const subscription = nielsen.addListener(
'OptOutUrl',
(data) => {
//display data.url
}
);
NielsenModule.optOutUrl();
//...
subscription.remove(); // do not forget to unsubscribe
</syntaxhighlight>

The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy iOS.jpg|link=]]

*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

Users can opt out or opt back into Nielsen Measurement. Opt-Out feature relies on iOS' system setting – "Limit Ad Tracking". The setting can be accessed in the Settings application on any iOS device: '''Settings → Privacy → Advertising → Limit Ad Tracking'''.

User is opted out of Nielsen online measurement research when the "Limit Ad Tracking" setting is enabled.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

== 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_devDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:

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

<syntaxhighlight lang="javascript">
let appInformation = {
"appid": "PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"sfcode": "it"
// Remove Flag: "nol_devDebug": "DEBUG"
};
NielsenModule.init(appInformation);
</syntaxhighlight>

International

2018-04-16T12:41:50Z

NielsSedat: remove "german" block (because of legal reasons for now) - can be redone by history

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
{{CategoryIcon|International.png|International}}

__NOTOC__

<blockquote>Please contact your Nielsen representative for documentation if the guides for your country aren't listed.</blockquote>

{| class="wikitable"
! colspan="3" | Downloads
|-
| style="width: 90px;" |{{SmallIcon|DownloadIcon.png|alt=Cloud API}}
|style="width: 90px;" | {{SmallIcon|SDKIcon.png}}
| '''[[Digital Downloads|SDK Downloads]]'''
|}

{| class="wikitable"
|-
! style="width: 90px;" | Italy
! style="width: 90px;" |
! style="width: 45px;" |
! style="width: 45px;" | OS
!| Guide
|-
| rowspan="7" | {{SmallIcon|ITFlagIcon.png}}
| rowspan="7" | {{SmallIcon|SDKIcon.png}}
| rowspan="3" | {{OSIcon|VideoIcon.png}}
| {{OSIcon|macOSIcon.png}}
<br><br>
{{OSIcon|AndroidIcon.png}}
| '''[[DCR Italy Video App SDK]]'''
|-
| rowspan="2" | {{OSIcon|BrowserIcon.png}}
| '''[[DCR Italy Video Browser SDK (6.0.0)]]'''
|-
| '''[[DCR Italy Video Browser SDK (6.0.1)]] Object Video only'''
|-
| rowspan="5" | {{OSIcon|StaticIcon.png}}
| {{OSIcon|macOSIcon.png}}
<br><br>
{{OSIcon|AndroidIcon.png}}
| '''[[DCR Italy Static App SDK]]'''
|-
| {{OSIcon|BrowserIcon.png}}
| '''[[DCR Italy Static Browser SDK]]'''
|-
| {{OSIcon|FacebookIcon.png|alt=Facebook Instant Articles}}
| '''[[DCR Italy Static Facebook Instant Articles Browser SDK]]'''
|-
| {{OSIcon|AMPIcon.png|alt=Google AMP}}
| '''[[DCR Italy Static Google AMP Cloud API]]'''
|}

DCR Italy Video Browser SDK (6.0.1)

2018-03-13T09:29:34Z

NielsSedat:

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

This guide will show how to integrate the Nielsen Software Development Kit (SDK) to enable Digital Content Ratings (DCR) video measurement on browser players.

== 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 is the framework for browsers developers to integrate Nielsen Measurement into their media player pages. 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 pages like:
*Site launch events and how long page is viewed
*Time of viewing a sub section / page.

== Prerequisites ==
To get started, an App ID, clientid and vcid is needed. These values are provided by Nielsen.

The App ID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration.
AppID: <syntaxhighlight lang="console">PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

The clientid is your 'parent# or companyid'
clientid: <syntaxhighlight lang="console">XX-XXXXXX"</syntaxhighlight> // eg. "it-123456"

The vcid is your channel id
vcid: <syntaxhighlight lang="console">"xXX"</syntaxhighlight> // eg. "c01"

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

=== Add Static Queue Snippet ===

Add the following script tag to the website:
<syntaxhighlight lang="html"><script>
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script></syntaxhighlight>

The static queue snippet allows the SDK APIs to be called while the actual SDK and configuration file are still being downloaded. As the queue can capture all API calls before the download completes, there is no wait time. Once the SDK is available, the API calls will transition from directing to the queue to the SDK seamlessly.

=== Create SDK Instance ===

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("<apid>", "<instanceName>",
{
clientid: "XX-XXXXXX", // eg. "it-123456"
vcid: "cXX", // eg. "c01"
nol_sdkDebug: "debug" // should be deleted when going live
}
)</syntaxhighlight>

When creating an instance, pass the following five values:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site || <code>"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"</code>
|-
| instanceName || Name of SDK instance || <code>"any string value"</code>
|-
| clientid || Brand value has to be passed in 3rd parameter object || Nielsen provided ||
|-
| vcid || VCID value has to be passed 3rd parameter object || Nielsen provided ||
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing. in 3rd parameter object || <code>{nol_sdkDebug: "debug"}</code>
|}

When the initialization call is made, a unique static configuration file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and will be cached on the user’s browser.

Once the configuration is downloaded, the SDK itself will be downloaded and initialized. All SDK modules are included in one file: “nlsSDK601.bundle.min.js”.

=== Example SDK Configuration ===

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:
<syntaxhighlight lang="html"><script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01", nol_sdkDebug: "DEBUG"});
</script></syntaxhighlight>

== Create Metadata Objects ==
There are two types of asset metadata:
* content: identify video
* ad: identify each ad ('''for Italy there is no need to tag ads''')
The metadata received for each asset is used for classification and reporting.

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

=== Content Metadata ===

Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required?
|-
| type ||
Type of measurement:
*video – <code>"content"</code>
|| <code>"content"</code> || ✓
|-
| assetid || Unique ID assigned to content (max. 40 characters) || custom || ✓
|-
| program || Program name (max. 254 characters) || custom || ✓
|-
| title || Episode title (max. 254 characters) || custom || ✓
|-
| length || Length of content in seconds for VOD. The estimated content length has to be passed for live content. || <code>seconds</code> (86400 for live stream) || ✓
|-
| airdate || Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || <code>YYYYMMDD hh:mm:ss</code> || ✓
|-
| isfullepisode || Full episode flag ||
<code>"y"</code> - full episode
<code>"n"</code> - non-full episode
|| ✓
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load "1"
#Dynamic - Dynamic Ad Insertion (DAI) "2"
|| <code>"1"</code> - Linear
<code>"2"</code> - Dynamic
|| ✓ (has to be "2" for DCR/Italy)
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || Nielsen provided ||
|-
| subbrand || subbrand/VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || Nielsen provided ||
|}

'''Example Content Object'''
... with all mandatory parameters - you may ignore the optional ones.

<syntaxhighlight lang="javascript">
//create content object
var contentMetadataObject =
{
type: "content",
assetid: "VID123-123456",
program: "program name",
title: "episode title",
length: "1020",
airdate: "19700101 00:00:00",
isfullepisode: "y",
adloadtype: "2"
};
</syntaxhighlight>

'''Note''': all parameters should be provided as strings (also length)

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

'''Attention:''' for Audiweb there is no need to tag ads in video stream ... you may ignore this paragraph. If there are ads in your stream, but not tagged than simply do nothing while ad is playing.

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

'''Example Ad Object'''
<syntaxhighlight lang="javascript">//create ad object
var adMetadataObject =
{
assetid: "AD-1",
type: "preroll"
};</syntaxhighlight>

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

== Call Nielsen APIs ==
The method for calling events is <code>ggPM()</code>.
<syntaxhighlight lang="javascript">nSdkInstance.ggPM('event', parameter, ...);</syntaxhighlight>

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event Number !! Values to pass !! Event Name || Description
|-
| <code>'3'</code> || content/ad metadata object || load content metadata || Load metadata event for content. Has to be called at the very first beginning of each stream.
|-
| <code>'5'</code> || playhead position || content play || Call when content or ads start playing or resumes from pause.
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'6'</code> || playhead position || pause || Call when content or ads is pausing. Use Event 5 to resume ...
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'7'</code> || playhead position || stop || Call when ads complete playing and at the very end of the stream. The playhead position must be passed when calling stop
|-
| <code>'8'</code> || playhead position from, playhead position to || seek || Call when scrubbing forward or backward with playhead position 'from' and 'to'
|-
| <code>'15'</code> || content/ad metadata object || load ad metadata || Call at the beginning of each ad, don’t use ‘play’ (event 5) if event 15 is used
|-
| <code>'49'</code> || playhead position || playhead position || '''VOD''': current position in seconds.
'''Live''': current unix timestamp (seconds since January 1st 1970).
Note: has to be called on a secondly basis.
For each ad the playheads starts with 0 (no Live unix timestamp for ads)
|-
| <code>'57'</code> || playhead position || end || 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.
|}

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

{{Examples|
without Ads|

<big>example '''without''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>

'''Note''': if there are ads played in stream simply use a pause (event 6) when ads start playing and a play (event 5) when content start playing.

|with Ads=
<big> example '''with''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream (even if 1st asset is preroll)

// Preroll
nSdkInstance.ggPM('15', prerollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 for the first segment (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition);

// Midroll
nSdkInstance.ggPM('15', midrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from where it left off before mid-roll (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// Postroll
nSdkInstance.ggPM('15', postrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>
}}

'''Attention:''' for Italy there is no need to tag ads in video stream ... ignore "with ads" example!

'''Note''': Event <code>'49'</code> 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 event <code>'7'</code>, <code>'57'</code>, or <code>'15'</code>.

'''Note''': when buffering occurs you have to send a event 6 (pause) and after buffering finished a 5 (play).

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

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

'''Handling Pause'''
The event <code>6</code> is used for handling pause. To indicate pause, stop passing the playhead position to the SDK and send Event 6 with playhead once. When content resumes, begin sending the playhead again with the correct playhead value. Also if buffering occurs for more than 1 second you may use Event 6 (pause) to indicate that.
e.g. pause at 1m2s and resume after a couple of seconds:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // now send nothing to SDK until player resumes (automatically because of buffering ends or user unpauses/resumes play
nSdkInstance.ggPM('5', 62); // ONLY WHEN PLAYING CONTENT (not ads!) - play/5 when resume occurs (when user click play or buffering ends)
nSdkInstance.ggPM('49', 63);
nSdkInstance.ggPM('49', 64);
...
</syntaxhighlight>

'''Handling Seek'''
The event <code>8</code> is used for handling forward/backward seek. To indicate seek, send Event 8 with 'from' and 'to' playhead.
e.g. seek from 1m2s to 2m0s:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // use pause, because buffering will occur (to be on safe side)
nSdkInstance.ggPM('8', 62,120);
nSdkInstance.ggPM('5', 120); // ONLY WHEN PLAYING CONTENT (not ads!) - play/5 when resuming
nSdkInstance.ggPM('49', 120);
nSdkInstance.ggPM('49', 121);
...
</syntaxhighlight>

===Interruption Scenarios===
The following possible browser interruption scenarios must be handled:
* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button
There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. midroll vs. content).
<syntaxhighlight lang="javascript">
var stopped = false;
function closePlayer() {
if (stopped) {return;}
stopped = true;
if (inMidroll) { // Only inside a midroll indicate <stop> for the ad
nSdkInstance.ggPM(7, playheadPositionMidroll);
}
nSdkInstance.ggPM(57, playheadPositionContent); // Indicate <end> for the content
nSdkInstance.ggPM(7, playheadPositionContent); // Indicate <stop> for the content
};
window.addEventListener("beforeunload", function (e) {
closePlayer(); // call nielsensdk with end/stop
});
window.addEventListener("pagehide", function (e) { // for iOS mobile "pagehide" recommended by apple
closePlayer(); // call nielsensdk with end/stop
});
</syntaxhighlight>

<blockquote>'''Note''': User may need to add code to support specific browser versions (e.g. older versions of Internet Explorer or covering Safari on mobile browsers ... you may use "onpagehide" event as well).</blockquote>

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

The following paragraph is a template for an opt-out statement.

''The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at https://priv-policy.imrworldwide.com/priv/browser/it/it/optout.html.''

'''Opt Back In'''

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

== Going Live ==
Following Nielsen testing, users need to make a couple of updates 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:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01"});</syntaxhighlight>

DCR Italy Video Browser SDK (6.0.0)

2018-03-13T09:26:37Z

NielsSedat:

DCR Italy Video App SDK

2018-02-15T15:45:11Z

NielsSedat:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International}} {{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 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 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.
* '''sfcode:''' Unique identifier for the environment that the SDK should point to.
* '''Nielsen SDK:''' The Nielsen SDK package contains a variety of sample players for your reference.
If you do not have any of these prerequisites or if you have any questions, please contact our SDK sales support team.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

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

== Setting up your Development Environment ==
{{ExampleCode|
xCode|
<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
* 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 (Not applicable for International (Germany))
* 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 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
<br />
<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 <br />
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] <br />
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.
<br />
|Android =
<big>'''Configuring Android 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 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 Nielsen App SDK 1.2 library is composed of two parts:
* The Java AppSdk.jar library that 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 the Google Play support to work properly.
Ensure to 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_COARSE_LOCATION" android:required="false" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details to handle 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 there is a Google service available and updated.
* If not available or updated, App SDK will not use this service when executing its functions and will make reference to 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.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;
}}

== 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 prior to version 5.1.1. (Version 4.0 for Android)

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

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

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || Yes || 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.
'''Italian Clients'''
* "it"
|| Nielsen-specified || Yes || "it"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"
|}
<br />
==== Sample SDK Initialization Code ====
{{ExampleCode|
|Swift =
Swift 4.0 Example:
<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"appversion": "1.0",
"appname": "app name here",
"sfcode": "it",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
<br />
<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",
@"appversion": "1.0",
@"appname": "app name here",
@"sfcode": "it",
@"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 =

[[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("appversion", "1.0")
.put("appname", "Sample App Name")
.put("sfcode", "it")
.put("nol_devDebug", "DEBUG"); // only for debug builds

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

The integration of Nielsen App SDK will depend on type of client app.<br />
* 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 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 handles 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 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, 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.
{{ExampleCode|
|Swift =
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode":"n",
"adloadtype":"2",
"program":"Program Name",
"length":"3600",
"airdate":"20171020 10:05:00"
];
</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @
{@"type": @"content",
@"assetid": [NSString stringWithFormat:@"ProgramAssetId-%d", i],
@"length": @"3600",
@"program", "Program Name",
@"title": @"Program S3, EP1",
@"isfullepisode": @"y",
@"adloadtype": "2",
@"airdate": "20161013 20:00:00"
}
</syntaxhighlight>
|Android = <syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
//SDK Metadata
.put("type", "content")
.put("assetid", "vid345-67483")
.put("program", "Program Name")
.put("title", "Program S3, EP1")
.put("length", "3600")
.put("isfullepisode", "y")
.put("adloadtype", "2")
.put("airdate", "20161013 20:00:00")
</syntaxhighlight>
}}

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

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

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

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|}
<br />

=== Ad Metadata ===
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
<br/>
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}

== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
|On App Start||<code>[nielsenMeter loadMetadata: contentMetadata];</code> || // contentMetadata Object contains the JSON metadata for the impression
|-
| 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 is processing playing information. [[DCR_Video_APP_SDK#play|play]] and [[DCR_Video_APP_SDK#loadMetadata|loadMetadata]] calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## [[DCR_Video_APP_SDK#playheadPosition|playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[DCR_Video_APP_SDK#stop|stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[DCR_Video_APP_SDK#end|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>

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.

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

=== Sequence of Calls ===
=== play ===
Use [[DCR_Video_APP_SDK#play|play]] to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c"> [nielsenAppApi play:(JSONObject channelInfo)];</syntaxhighlight>
|Android = <syntaxhighlight lang="java"> public void play(JSONObject channelInfo);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenAppApi?.play(JSONObject channelInfo);</syntaxhighlight>
}}

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

==== Sending playheadposition for content ====
<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 ===
{{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 ===
When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
{{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>
}}

== Privacy and Opt-Out ==
{{ExampleCode|

iOS|
== iOS Opt-Out Implementation ==
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL for the Nielsen Privacy web page should be retrieved from the optOutURL property of the SDK object <code>optOutURL</code> and opened in 'WebView' / External browser.
*If the App SDK returns NULL in the optOutURL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the [[optOutStatus]] method.



The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy iOS.jpg|link=]]

*URL to this web page should be called from SDK and opened in 'WebView' / External browser.
*If the App SDK returns NULL as Opt-Out URL, handle this case and retry later.
*To retrieve the current Opt-Out status, use the [[optOutStatus]] property from Nielsen's SDK API.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

Users can opt out or opt back into Nielsen Measurement. Opt-Out feature relies on iOS' system setting – "Limit Ad Tracking". The setting can be accessed in the Settings application on any iOS device: '''Settings → Privacy → Advertising → Limit Ad Tracking'''.

User is opted out of Nielsen online measurement research when the "Limit Ad Tracking" setting is enabled.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

|Android =
== Android Opt-Out Implementation ==
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL to this web page should be called from SDK by invoking <code>userOptOutURLString()</code> and opened in 'WebView' / External browser.
<syntaxhighlight lang="java">
public String userOptOutURLString()
</syntaxhighlight>

*If the App SDK returns NULL as Opt-Out URL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the <code> getOptOutStatus() </code> method.
<syntaxhighlight lang="java">
public boolean getOptOutStatus()
</syntaxhighlight>

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
optOutUrl = mAppSdk.userOptOutURLString();
if(optOutUrl !=null)
{
mWebView = (WebView) findViewById(R.id.webView);
mWebView.getSettings().setJavaScriptEnabled(true);
mWebView.getSettings().setBuiltInZoomControls(true);
mWebView.getSettings().setDisplayZoomControls(false);
mWebView.getSettings().setLoadWithOverviewMode(true);
mWebView.getSettings().setUseWideViewPort(true);
mWebView.setWebViewClient(new MonitorWebView());
mWebView.setWebChromeClient(new WebChromeClient());
mWebView.loadUrl(optOutUrl);
}
else
{
//Handle it gracefully and Retry later
}
</syntaxhighlight>

The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''Note:''' When ‘WebView’ / External browser is closed, do not pass the status returned from ‘WebView’ / External browser to the SDK within the app, as the new Opt-Out page will not return any response.</blockquote>

<blockquote>'''Note:''' App SDK manages the user’s choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

Starting from SDK version 5.1.1.18:
*SDK will be sending the data pings to census even though SDK is opted out (In earlier releases all the traffic from SDK to census will be ceased). However, all the outgoing pings will have the parameter uoo=true using which backend can ignore this data.
*Current Opt-Out page is now updated to have no hyperlinks for Opt-Out / Opt-In operations. SDK Opt-Out has to be done via
'''Google Settings → Ads → Opt out of Ads Personalization'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''Note:''' The App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

== Opt-Out Implementation for Amazon Devices ==
Amazon device users can opt out or opt back into Nielsen Measurement, any time using the device’s setting – 'Limit Ad Tracking' (Interest-based ads).

User is opted out of Nielsen Online Measurement when ‘Limit Ad Tracking’ is enabled.

'''For devices running on Fire OS 5.1 and above, retrieve the Ad tracking value.'''
=== Retrieving Ad tracking Value ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

*Returns limit_ad_tracking value "0" if enabled
*Returns limit_ad_tracking value "1" if disabled
*Returns limit_ad_tracking value "2" if ad tracking is not supported (below Fire OS 5.1).

<blockquote>'''Note:''' Google Play Services are not needed to retrieve ad tracking state on Amazon devices. Limit Ad Tracking can be accessed through '''Settings → Apps & Games → Advertising ID'''.</blockquote>

}}

== 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": "it"
// 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", "it")
// 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>

DCR Italy Video App SDK

2018-02-15T15:44:04Z

NielsSedat:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International}} {{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 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 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.
* '''sfcode:''' Unique identifier for the environment that the SDK should point to.
* '''Nielsen SDK:''' The Nielsen SDK package contains a variety of sample players for your reference.
If you do not have any of these prerequisites or if you have any questions, please contact our SDK sales support team.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

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

== Setting up your Development Environment ==
{{ExampleCode|
xCode|
<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
* 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 (Not applicable for International (Germany))
* 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 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
<br />
<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 <br />
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] <br />
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.
<br />
|Android =
<big>'''Configuring Android 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 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 Nielsen App SDK 1.2 library is composed of two parts:
* The Java AppSdk.jar library that 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 the Google Play support to work properly.
Ensure to 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_COARSE_LOCATION" android:required="false" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details to handle 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 there is a Google service available and updated.
* If not available or updated, App SDK will not use this service when executing its functions and will make reference to 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.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;
}}

== 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 prior to version 5.1.1. (Version 4.0 for Android)

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

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

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || Yes || 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.
'''Italian Clients'''
* "it"
|| Nielsen-specified || Yes || "it"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"
|}
<br />
==== Sample SDK Initialization Code ====
{{ExampleCode|
|Swift =
Swift 4.0 Example:
<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"appversion": "1.0",
"appname": "app name here",
"sfcode": "it",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
<br />
<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",
@"appversion": "1.0",
@"appname": "app name here",
@"sfcode": "it",
@"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 =

[[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("appversion", "1.0")
.put("appname", "Sample App Name")
.put("sfcode", "it")
.put("nol_devDebug", "DEBUG"); // only for debug builds

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

The integration of Nielsen App SDK will depend on type of client app.<br />
* 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 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 handles 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 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, 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.
{{ExampleCode|
|Swift =
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode":"n",
"adloadtype":"2",
"program":"Program Name",
"length":"3600",
"airdate":"20171020 10:05:00"
];
</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @
{@"type": @"content",
@"assetid": [NSString stringWithFormat:@"ProgramAssetId-%d", i],
@"length": @"3600",
@"program", "Program Name",
@"title": @"Program S3, EP1",
@"isfullepisode": @"y",
@"adloadtype": "2",
@"airdate": "20161013 20:00:00"
}
</syntaxhighlight>
|Android = <syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
//SDK Metadata
.put("type", "content")
.put("assetid", "vid345-67483")
.put("program", "Program Name")
.put("title", "Program S3, EP1")
.put("length", "3600")
.put("isfullepisode", "y")
.put("adloadtype", "2")
.put("airdate", "20161013 20:00:00")
</syntaxhighlight>
}}

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

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

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

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|}
<br />

=== Ad Metadata ===
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
<br/>
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}

== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
|On App Start||<code>[nielsenMeter loadMetadata: contentMetadata];</code> || // contentMetadata Object contains the JSON metadata for the impression
|-
| 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 is processing playing information. [[DCR_Video_APP_SDK#play|play]] and [[DCR_Video_APP_SDK#loadMetadata|loadMetadata]] calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## [[DCR_Video_APP_SDK#playheadPosition|playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[DCR_Video_APP_SDK#stop|stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[DCR_Video_APP_SDK#end|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>

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.

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

=== Sequence of Calls ===
=== play ===
Use [[DCR_Video_APP_SDK#play|play]] to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c"> [nielsenAppApi play:(JSONObject channelInfo)];</syntaxhighlight>
|Android = <syntaxhighlight lang="java"> public void play(JSONObject channelInfo);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenAppApi?.play(JSONObject channelInfo);</syntaxhighlight>
}}

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

==== Sending playheadposition for content ====
<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 ===
{{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 ===
When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
{{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>
}}

== Privacy and Opt-Out ==
{{ExampleCode|

iOS|
== iOS Opt-Out Implementation ==
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL for the Nielsen Privacy web page should be retrieved from the optOutURL property of the SDK object <code>optOutURL</code> and opened in 'WebView' / External browser.
*If the App SDK returns NULL in the optOutURL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the [[optOutStatus]] method.



The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy iOS.jpg|link=]]

*URL to this web page should be called from SDK and opened in 'WebView' / External browser.
*If the App SDK returns NULL as Opt-Out URL, handle this case and retry later.
*To retrieve the current Opt-Out status, use the [[optOutStatus]] property from Nielsen's SDK API.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

Users can opt out or opt back into Nielsen Measurement. Opt-Out feature relies on iOS' system setting – "Limit Ad Tracking". The setting can be accessed in the Settings application on any iOS device: '''Settings → Privacy → Advertising → Limit Ad Tracking'''.

User is opted out of Nielsen online measurement research when the "Limit Ad Tracking" setting is enabled.

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

|Android =
== Android Opt-Out Implementation ==
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL to this web page should be called from SDK by invoking <code>userOptOutURLString()</code> and opened in 'WebView' / External browser.
<syntaxhighlight lang="java">
public String userOptOutURLString()
</syntaxhighlight>

*If the App SDK returns NULL as Opt-Out URL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the <code> getOptOutStatus() </code> method.
<syntaxhighlight lang="java">
public boolean getOptOutStatus()
</syntaxhighlight>

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
optOutUrl = mAppSdk.userOptOutURLString();
if(optOutUrl !=null)
{
mWebView = (WebView) findViewById(R.id.webView);
mWebView.getSettings().setJavaScriptEnabled(true);
mWebView.getSettings().setBuiltInZoomControls(true);
mWebView.getSettings().setDisplayZoomControls(false);
mWebView.getSettings().setLoadWithOverviewMode(true);
mWebView.getSettings().setUseWideViewPort(true);
mWebView.setWebViewClient(new MonitorWebView());
mWebView.setWebChromeClient(new WebChromeClient());
mWebView.loadUrl(optOutUrl);
}
else
{
//Handle it gracefully and Retry later
}
</syntaxhighlight>

The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''Note:''' When ‘WebView’ / External browser is closed, do not pass the status returned from ‘WebView’ / External browser to the SDK within the app, as the new Opt-Out page will not return any response.</blockquote>

<blockquote>'''Note:''' App SDK manages the user’s choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

Starting from SDK version 5.1.1.18:
*SDK will be sending the data pings to census even though SDK is opted out (In earlier releases all the traffic from SDK to census will be ceased). However, all the outgoing pings will have the parameter uoo=true using which backend can ignore this data.
*Current Opt-Out page is now updated to have no hyperlinks for Opt-Out / Opt-In operations. SDK Opt-Out has to be done via
'''Google Settings → Ads → Opt out of Ads Personalization'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''Note:''' The App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

== Opt-Out Implementation for Amazon Devices ==
Amazon device users can opt out or opt back into Nielsen Measurement, any time using the device’s setting – 'Limit Ad Tracking' (Interest-based ads).

User is opted out of Nielsen Online Measurement when ‘Limit Ad Tracking’ is enabled.

'''For devices running on Fire OS 5.1 and above, retrieve the Ad tracking value.'''
=== Retrieving Ad tracking Value ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

*Returns limit_ad_tracking value "0" if enabled
*Returns limit_ad_tracking value "1" if disabled
*Returns limit_ad_tracking value "2" if ad tracking is not supported (below Fire OS 5.1).

<blockquote>'''Note:''' Google Play Services are not needed to retrieve ad tracking state on Amazon devices. Limit Ad Tracking can be accessed through '''Settings → Apps & Games → Advertising ID'''.</blockquote>

}}

== 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": "it"
// 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", "it")
// 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>

DCR Italy Video App SDK

2018-02-15T15:39:44Z

NielsSedat: /* Privacy and Opt-Out */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International}} {{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 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 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.
* '''sfcode:''' Unique identifier for the environment that the SDK should point to.
* '''Nielsen SDK:''' The Nielsen SDK package contains a variety of sample players for your reference.
If you do not have any of these prerequisites or if you have any questions, please contact our SDK sales support team.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

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

== Setting up your Development Environment ==
{{ExampleCode|
xCode|
<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
* 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 (Not applicable for International (Germany))
* 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 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
<br />
<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 <br />
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] <br />
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.
<br />
|Android =
<big>'''Configuring Android 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 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 Nielsen App SDK 1.2 library is composed of two parts:
* The Java AppSdk.jar library that 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 the Google Play support to work properly.
Ensure to 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_COARSE_LOCATION" android:required="false" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details to handle 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 there is a Google service available and updated.
* If not available or updated, App SDK will not use this service when executing its functions and will make reference to 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.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;
}}

== 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 prior to version 5.1.1. (Version 4.0 for Android)

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

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

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || Yes || 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.
'''Italian Clients'''
* "it"
|| Nielsen-specified || Yes || "it"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"
|}
<br />
==== Sample SDK Initialization Code ====
{{ExampleCode|
|Swift =
Swift 4.0 Example:
<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"appversion": "1.0",
"appname": "app name here",
"sfcode": "it",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
<br />
<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",
@"appversion": "1.0",
@"appname": "app name here",
@"sfcode": "it",
@"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 =

[[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("appversion", "1.0")
.put("appname", "Sample App Name")
.put("sfcode", "it")
.put("nol_devDebug", "DEBUG"); // only for debug builds

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

The integration of Nielsen App SDK will depend on type of client app.<br />
* 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 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 handles 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 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, 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.
{{ExampleCode|
|Swift =
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode":"n",
"adloadtype":"2",
"program":"Program Name",
"length":"3600",
"airdate":"20171020 10:05:00"
];
</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @
{@"type": @"content",
@"assetid": [NSString stringWithFormat:@"ProgramAssetId-%d", i],
@"length": @"3600",
@"program", "Program Name",
@"title": @"Program S3, EP1",
@"isfullepisode": @"y",
@"adloadtype": "2",
@"airdate": "20161013 20:00:00"
}
</syntaxhighlight>
|Android = <syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
//SDK Metadata
.put("type", "content")
.put("assetid", "vid345-67483")
.put("program", "Program Name")
.put("title", "Program S3, EP1")
.put("length", "3600")
.put("isfullepisode", "y")
.put("adloadtype", "2")
.put("airdate", "20161013 20:00:00")
</syntaxhighlight>
}}

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

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

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

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|}
<br />

=== Ad Metadata ===
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
<br/>
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}

== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
|On App Start||<code>[nielsenMeter loadMetadata: contentMetadata];</code> || // contentMetadata Object contains the JSON metadata for the impression
|-
| 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 is processing playing information. [[DCR_Video_APP_SDK#play|play]] and [[DCR_Video_APP_SDK#loadMetadata|loadMetadata]] calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## [[DCR_Video_APP_SDK#playheadPosition|playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[DCR_Video_APP_SDK#stop|stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[DCR_Video_APP_SDK#end|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>

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.

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

=== Sequence of Calls ===
=== play ===
Use [[DCR_Video_APP_SDK#play|play]] to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c"> [nielsenAppApi play:(JSONObject channelInfo)];</syntaxhighlight>
|Android = <syntaxhighlight lang="java"> public void play(JSONObject channelInfo);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenAppApi?.play(JSONObject channelInfo);</syntaxhighlight>
}}

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

==== Sending playheadposition for content ====
<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 ===
{{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 ===
When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
{{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>
}}

== Privacy and Opt-Out ==
{{ExampleCode|

iOS|
== iOS Opt-Out Implementation ==
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL for the Nielsen Privacy web page should be retrieved from the optOutURL property of the SDK object <code>optOutURL</code> and opened in 'WebView' / External browser.
*If the App SDK returns NULL in the optOutURL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the [[optOutStatus]] method.



The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy iOS.jpg|link=]]

*URL to this web page should be called from SDK and opened in 'WebView' / External browser.
*If the App SDK returns NULL as Opt-Out URL, handle this case and retry later.
*To retrieve the current Opt-Out status, use the [[optOutStatus]] property from Nielsen's SDK API.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

Users can opt out or opt back into Nielsen Measurement. Opt-Out feature relies on iOS' system setting – "Limit Ad Tracking". The setting can be accessed in the Settings application on any iOS device: '''Settings → Privacy → Advertising → Limit Ad Tracking'''.

User is opted out of Nielsen online measurement research when the "Limit Ad Tracking" setting is enabled.

[[File:Privacy policy App.png|link=]]

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

|Android =
== Android Opt-Out Implementation ==
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL to this web page should be called from SDK by invoking <code>userOptOutURLString()</code> and opened in 'WebView' / External browser.
<syntaxhighlight lang="java">
public String userOptOutURLString()
</syntaxhighlight>

*If the App SDK returns NULL as Opt-Out URL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the <code> getOptOutStatus() </code> method.
<syntaxhighlight lang="java">
public boolean getOptOutStatus()
</syntaxhighlight>

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
optOutUrl = mAppSdk.userOptOutURLString();
if(optOutUrl !=null)
{
mWebView = (WebView) findViewById(R.id.webView);
mWebView.getSettings().setJavaScriptEnabled(true);
mWebView.getSettings().setBuiltInZoomControls(true);
mWebView.getSettings().setDisplayZoomControls(false);
mWebView.getSettings().setLoadWithOverviewMode(true);
mWebView.getSettings().setUseWideViewPort(true);
mWebView.setWebViewClient(new MonitorWebView());
mWebView.setWebChromeClient(new WebChromeClient());
mWebView.loadUrl(optOutUrl);
}
else
{
//Handle it gracefully and Retry later
}
</syntaxhighlight>

The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''Note:''' When ‘WebView’ / External browser is closed, do not pass the status returned from ‘WebView’ / External browser to the SDK within the app, as the new Opt-Out page will not return any response.</blockquote>

<blockquote>'''Note:''' App SDK manages the user’s choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

Starting from SDK version 5.1.1.18:
*SDK will be sending the data pings to census even though SDK is opted out (In earlier releases all the traffic from SDK to census will be ceased). However, all the outgoing pings will have the parameter uoo=true using which backend can ignore this data.
*Current Opt-Out page is now updated to have no hyperlinks for Opt-Out / Opt-In operations. SDK Opt-Out has to be done via
'''Google Settings → Ads → Opt out of Ads Personalization'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''Note:''' The App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

== Opt-Out Implementation for Amazon Devices ==
Amazon device users can opt out or opt back into Nielsen Measurement, any time using the device’s setting – 'Limit Ad Tracking' (Interest-based ads).

User is opted out of Nielsen Online Measurement when ‘Limit Ad Tracking’ is enabled.

'''For devices running on Fire OS 5.1 and above, retrieve the Ad tracking value.'''
=== Retrieving Ad tracking Value ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

*Returns limit_ad_tracking value "0" if enabled
*Returns limit_ad_tracking value "1" if disabled
*Returns limit_ad_tracking value "2" if ad tracking is not supported (below Fire OS 5.1).

<blockquote>'''Note:''' Google Play Services are not needed to retrieve ad tracking state on Amazon devices. Limit Ad Tracking can be accessed through '''Settings → Apps & Games → Advertising ID'''.</blockquote>

}}

== 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": "it"
// 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", "it")
// 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>

DCR Italy Video App SDK

2018-02-15T15:25:57Z

NielsSedat: /* Privacy and Opt-Out */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International}} {{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 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 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.
* '''sfcode:''' Unique identifier for the environment that the SDK should point to.
* '''Nielsen SDK:''' The Nielsen SDK package contains a variety of sample players for your reference.
If you do not have any of these prerequisites or if you have any questions, please contact our SDK sales support team.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

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

== Setting up your Development Environment ==
{{ExampleCode|
xCode|
<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
* 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 (Not applicable for International (Germany))
* 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 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
<br />
<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 <br />
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] <br />
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.
<br />
|Android =
<big>'''Configuring Android 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 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 Nielsen App SDK 1.2 library is composed of two parts:
* The Java AppSdk.jar library that 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 the Google Play support to work properly.
Ensure to 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_COARSE_LOCATION" android:required="false" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details to handle 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 there is a Google service available and updated.
* If not available or updated, App SDK will not use this service when executing its functions and will make reference to 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.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;
}}

== 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 prior to version 5.1.1. (Version 4.0 for Android)

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

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

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || Yes || 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.
'''Italian Clients'''
* "it"
|| Nielsen-specified || Yes || "it"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"
|}
<br />
==== Sample SDK Initialization Code ====
{{ExampleCode|
|Swift =
Swift 4.0 Example:
<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"appversion": "1.0",
"appname": "app name here",
"sfcode": "it",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
<br />
<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",
@"appversion": "1.0",
@"appname": "app name here",
@"sfcode": "it",
@"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 =

[[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("appversion", "1.0")
.put("appname", "Sample App Name")
.put("sfcode", "it")
.put("nol_devDebug", "DEBUG"); // only for debug builds

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

The integration of Nielsen App SDK will depend on type of client app.<br />
* 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 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 handles 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 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, 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.
{{ExampleCode|
|Swift =
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode":"n",
"adloadtype":"2",
"program":"Program Name",
"length":"3600",
"airdate":"20171020 10:05:00"
];
</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @
{@"type": @"content",
@"assetid": [NSString stringWithFormat:@"ProgramAssetId-%d", i],
@"length": @"3600",
@"program", "Program Name",
@"title": @"Program S3, EP1",
@"isfullepisode": @"y",
@"adloadtype": "2",
@"airdate": "20161013 20:00:00"
}
</syntaxhighlight>
|Android = <syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
//SDK Metadata
.put("type", "content")
.put("assetid", "vid345-67483")
.put("program", "Program Name")
.put("title", "Program S3, EP1")
.put("length", "3600")
.put("isfullepisode", "y")
.put("adloadtype", "2")
.put("airdate", "20161013 20:00:00")
</syntaxhighlight>
}}

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

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

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

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|}
<br />

=== Ad Metadata ===
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
<br/>
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}

== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
|On App Start||<code>[nielsenMeter loadMetadata: contentMetadata];</code> || // contentMetadata Object contains the JSON metadata for the impression
|-
| 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 is processing playing information. [[DCR_Video_APP_SDK#play|play]] and [[DCR_Video_APP_SDK#loadMetadata|loadMetadata]] calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## [[DCR_Video_APP_SDK#playheadPosition|playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[DCR_Video_APP_SDK#stop|stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[DCR_Video_APP_SDK#end|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>

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.

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

=== Sequence of Calls ===
=== play ===
Use [[DCR_Video_APP_SDK#play|play]] to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c"> [nielsenAppApi play:(JSONObject channelInfo)];</syntaxhighlight>
|Android = <syntaxhighlight lang="java"> public void play(JSONObject channelInfo);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenAppApi?.play(JSONObject channelInfo);</syntaxhighlight>
}}

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

==== Sending playheadposition for content ====
<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 ===
{{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 ===
When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
{{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>
}}

== Privacy and Opt-Out ==
{{ExampleCode|

iOS|
== iOS Opt-Out Implementation ==
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL for the Nielsen Privacy web page should be retrieved from the optOutURL property of the SDK object <code>optOutURL</code> and opened in 'WebView' / External browser.
*If the App SDK returns NULL in the optOutURL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the [[optOutStatus]] method.



The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy App.png|link=]]

*URL to this web page should be called from SDK and opened in 'WebView' / External browser.
*If the App SDK returns NULL as Opt-Out URL, handle this case and retry later.
*To retrieve the current Opt-Out status, use the [[optOutStatus]] property from Nielsen's SDK API.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

Users can opt out or opt back into Nielsen Measurement. Opt-Out feature relies on iOS' system setting – "Limit Ad Tracking". The setting can be accessed in the Settings application on any iOS device: '''Settings → Privacy → Advertising → Limit Ad Tracking'''.

User is opted out of Nielsen online measurement research when the "Limit Ad Tracking" setting is enabled.

[[File:Privacy policy App.png|link=]]

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

|Android =
== Android Opt-Out Implementation ==
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL to this web page should be called from SDK by invoking <code>userOptOutURLString()</code> and opened in 'WebView' / External browser.
<syntaxhighlight lang="java">
public String userOptOutURLString()
</syntaxhighlight>

*If the App SDK returns NULL as Opt-Out URL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the <code> getOptOutStatus() </code> method.
<syntaxhighlight lang="java">
public boolean getOptOutStatus()
</syntaxhighlight>

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
optOutUrl = mAppSdk.userOptOutURLString();
if(optOutUrl !=null)
{
mWebView = (WebView) findViewById(R.id.webView);
mWebView.getSettings().setJavaScriptEnabled(true);
mWebView.getSettings().setBuiltInZoomControls(true);
mWebView.getSettings().setDisplayZoomControls(false);
mWebView.getSettings().setLoadWithOverviewMode(true);
mWebView.getSettings().setUseWideViewPort(true);
mWebView.setWebViewClient(new MonitorWebView());
mWebView.setWebChromeClient(new WebChromeClient());
mWebView.loadUrl(optOutUrl);
}
else
{
//Handle it gracefully and Retry later
}
</syntaxhighlight>

The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''Note:''' When ‘WebView’ / External browser is closed, do not pass the status returned from ‘WebView’ / External browser to the SDK within the app, as the new Opt-Out page will not return any response.</blockquote>

<blockquote>'''Note:''' App SDK manages the user’s choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

Starting from SDK version 5.1.1.18:
*SDK will be sending the data pings to census even though SDK is opted out (In earlier releases all the traffic from SDK to census will be ceased). However, all the outgoing pings will have the parameter uoo=true using which backend can ignore this data.
*Current Opt-Out page is now updated to have no hyperlinks for Opt-Out / Opt-In operations. SDK Opt-Out has to be done via
'''Google Settings → Ads → Opt out of Ads Personalization'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''Note:''' The App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

== Opt-Out Implementation for Amazon Devices ==
Amazon device users can opt out or opt back into Nielsen Measurement, any time using the device’s setting – 'Limit Ad Tracking' (Interest-based ads).

User is opted out of Nielsen Online Measurement when ‘Limit Ad Tracking’ is enabled.

'''For devices running on Fire OS 5.1 and above, retrieve the Ad tracking value.'''
=== Retrieving Ad tracking Value ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

*Returns limit_ad_tracking value "0" if enabled
*Returns limit_ad_tracking value "1" if disabled
*Returns limit_ad_tracking value "2" if ad tracking is not supported (below Fire OS 5.1).

<blockquote>'''Note:''' Google Play Services are not needed to retrieve ad tracking state on Amazon devices. Limit Ad Tracking can be accessed through '''Settings → Apps & Games → Advertising ID'''.</blockquote>

}}

== 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": "it"
// 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", "it")
// 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>

DCR Italy Video App SDK

2018-02-15T15:04:59Z

NielsSedat: /* Privacy and Opt-Out */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International}} {{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 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 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.
* '''sfcode:''' Unique identifier for the environment that the SDK should point to.
* '''Nielsen SDK:''' The Nielsen SDK package contains a variety of sample players for your reference.
If you do not have any of these prerequisites or if you have any questions, please contact our SDK sales support team.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

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

== Setting up your Development Environment ==
{{ExampleCode|
xCode|
<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
* 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 (Not applicable for International (Germany))
* 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 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
<br />
<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 <br />
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] <br />
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.
<br />
|Android =
<big>'''Configuring Android 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 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 Nielsen App SDK 1.2 library is composed of two parts:
* The Java AppSdk.jar library that 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 the Google Play support to work properly.
Ensure to 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_COARSE_LOCATION" android:required="false" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details to handle 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 there is a Google service available and updated.
* If not available or updated, App SDK will not use this service when executing its functions and will make reference to 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.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;
}}

== 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 prior to version 5.1.1. (Version 4.0 for Android)

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

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

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || Yes || 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.
'''Italian Clients'''
* "it"
|| Nielsen-specified || Yes || "it"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"
|}
<br />
==== Sample SDK Initialization Code ====
{{ExampleCode|
|Swift =
Swift 4.0 Example:
<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"appversion": "1.0",
"appname": "app name here",
"sfcode": "it",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
<br />
<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",
@"appversion": "1.0",
@"appname": "app name here",
@"sfcode": "it",
@"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 =

[[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("appversion", "1.0")
.put("appname", "Sample App Name")
.put("sfcode", "it")
.put("nol_devDebug", "DEBUG"); // only for debug builds

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

The integration of Nielsen App SDK will depend on type of client app.<br />
* 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 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 handles 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 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, 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.
{{ExampleCode|
|Swift =
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode":"n",
"adloadtype":"2",
"program":"Program Name",
"length":"3600",
"airdate":"20171020 10:05:00"
];
</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @
{@"type": @"content",
@"assetid": [NSString stringWithFormat:@"ProgramAssetId-%d", i],
@"length": @"3600",
@"program", "Program Name",
@"title": @"Program S3, EP1",
@"isfullepisode": @"y",
@"adloadtype": "2",
@"airdate": "20161013 20:00:00"
}
</syntaxhighlight>
|Android = <syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
//SDK Metadata
.put("type", "content")
.put("assetid", "vid345-67483")
.put("program", "Program Name")
.put("title", "Program S3, EP1")
.put("length", "3600")
.put("isfullepisode", "y")
.put("adloadtype", "2")
.put("airdate", "20161013 20:00:00")
</syntaxhighlight>
}}

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

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

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

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|}
<br />

=== Ad Metadata ===
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
<br/>
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}

== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
|On App Start||<code>[nielsenMeter loadMetadata: contentMetadata];</code> || // contentMetadata Object contains the JSON metadata for the impression
|-
| 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 is processing playing information. [[DCR_Video_APP_SDK#play|play]] and [[DCR_Video_APP_SDK#loadMetadata|loadMetadata]] calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## [[DCR_Video_APP_SDK#playheadPosition|playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[DCR_Video_APP_SDK#stop|stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[DCR_Video_APP_SDK#end|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>

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.

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

=== Sequence of Calls ===
=== play ===
Use [[DCR_Video_APP_SDK#play|play]] to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c"> [nielsenAppApi play:(JSONObject channelInfo)];</syntaxhighlight>
|Android = <syntaxhighlight lang="java"> public void play(JSONObject channelInfo);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenAppApi?.play(JSONObject channelInfo);</syntaxhighlight>
}}

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

==== Sending playheadposition for content ====
<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 ===
{{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 ===
When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
{{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>
}}

== Privacy and Opt-Out ==
{{ExampleCode|

iOS|
== iOS Opt-Out Implementation ==
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL for the Nielsen Privacy web page should be retrieved from the optOutURL property of the SDK object <code>optOutURL</code> and opened in 'WebView' / External browser.
*If the App SDK returns NULL in the optOutURL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the [[optOutStatus]] method.



The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy App.png|link=]]

*URL to this web page should be called from SDK and opened in 'WebView' / External browser.
*If the App SDK returns NULL as Opt-Out URL, handle this case and retry later.
*To retrieve the current Opt-Out status, use the [[optOutStatus]] property from Nielsen's SDK API.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

Users can opt out or opt back into Nielsen Measurement. Opt-Out feature relies on iOS' system setting – "Limit Ad Tracking". The setting can be accessed in the Settings application on any iOS device: '''Settings → Privacy → Advertising → Limit Ad Tracking'''.

User is opted out of Nielsen online measurement research when the "Limit Ad Tracking" setting is enabled.

[[File:Opt-Out iOS.jpg|link=]]
[[File:Privacy policy App.png|link=]]

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

|Android =
== Android Opt-Out Implementation ==
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL to this web page should be called from SDK by invoking <code>userOptOutURLString()</code> and opened in 'WebView' / External browser.
<syntaxhighlight lang="java">
public String userOptOutURLString()
</syntaxhighlight>

*If the App SDK returns NULL as Opt-Out URL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the <code> getOptOutStatus() </code> method.
<syntaxhighlight lang="java">
public boolean getOptOutStatus()
</syntaxhighlight>

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
optOutUrl = mAppSdk.userOptOutURLString();
if(optOutUrl !=null)
{
mWebView = (WebView) findViewById(R.id.webView);
mWebView.getSettings().setJavaScriptEnabled(true);
mWebView.getSettings().setBuiltInZoomControls(true);
mWebView.getSettings().setDisplayZoomControls(false);
mWebView.getSettings().setLoadWithOverviewMode(true);
mWebView.getSettings().setUseWideViewPort(true);
mWebView.setWebViewClient(new MonitorWebView());
mWebView.setWebChromeClient(new WebChromeClient());
mWebView.loadUrl(optOutUrl);
}
else
{
//Handle it gracefully and Retry later
}
</syntaxhighlight>

The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''Note:''' When ‘WebView’ / External browser is closed, do not pass the status returned from ‘WebView’ / External browser to the SDK within the app, as the new Opt-Out page will not return any response.</blockquote>

<blockquote>'''Note:''' App SDK manages the user’s choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

Starting from SDK version 5.1.1.18:
*SDK will be sending the data pings to census even though SDK is opted out (In earlier releases all the traffic from SDK to census will be ceased). However, all the outgoing pings will have the parameter uoo=true using which backend can ignore this data.
*Current Opt-Out page is now updated to have no hyperlinks for Opt-Out / Opt-In operations. SDK Opt-Out has to be done via
'''Google Settings → Ads → Opt out of Ads Personalization'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''Note:''' The App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

== Opt-Out Implementation for Amazon Devices ==
Amazon device users can opt out or opt back into Nielsen Measurement, any time using the device’s setting – 'Limit Ad Tracking' (Interest-based ads).

User is opted out of Nielsen Online Measurement when ‘Limit Ad Tracking’ is enabled.

'''For devices running on Fire OS 5.1 and above, retrieve the Ad tracking value.'''
=== Retrieving Ad tracking Value ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

*Returns limit_ad_tracking value "0" if enabled
*Returns limit_ad_tracking value "1" if disabled
*Returns limit_ad_tracking value "2" if ad tracking is not supported (below Fire OS 5.1).

<blockquote>'''Note:''' Google Play Services are not needed to retrieve ad tracking state on Amazon devices. Limit Ad Tracking can be accessed through '''Settings → Apps & Games → Advertising ID'''.</blockquote>

}}

== 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": "it"
// 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", "it")
// 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>

File:Privacy policy App.png

2018-02-15T15:01:16Z

NielsSedat:

DCR Italy Video App SDK

2018-02-15T10:19:45Z

NielsSedat: removed play after resume

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International}} {{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 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 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.
* '''sfcode:''' Unique identifier for the environment that the SDK should point to.
* '''Nielsen SDK:''' The Nielsen SDK package contains a variety of sample players for your reference.
If you do not have any of these prerequisites or if you have any questions, please contact our SDK sales support team.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

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

== Setting up your Development Environment ==
{{ExampleCode|
xCode|
<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
* 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 (Not applicable for International (Germany))
* 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 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
<br />
<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 <br />
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] <br />
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.
<br />
|Android =
<big>'''Configuring Android 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 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 Nielsen App SDK 1.2 library is composed of two parts:
* The Java AppSdk.jar library that 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 the Google Play support to work properly.
Ensure to 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_COARSE_LOCATION" android:required="false" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details to handle 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 there is a Google service available and updated.
* If not available or updated, App SDK will not use this service when executing its functions and will make reference to 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.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;
}}

== 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 prior to version 5.1.1. (Version 4.0 for Android)

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

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

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || Yes || 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.
'''Italian Clients'''
* "it"
|| Nielsen-specified || Yes || "it"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"
|}
<br />
==== Sample SDK Initialization Code ====
{{ExampleCode|
|Swift =
Swift 4.0 Example:
<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"appversion": "1.0",
"appname": "app name here",
"sfcode": "it",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
<br />
<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",
@"appversion": "1.0",
@"appname": "app name here",
@"sfcode": "it",
@"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 =

[[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("appversion", "1.0")
.put("appname", "Sample App Name")
.put("sfcode", "it")
.put("nol_devDebug", "DEBUG"); // only for debug builds

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

The integration of Nielsen App SDK will depend on type of client app.<br />
* 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 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 handles 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 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, 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.
{{ExampleCode|
|Swift =
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode":"n",
"adloadtype":"2",
"program":"Program Name",
"length":"3600",
"airdate":"20171020 10:05:00"
];
</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @
{@"type": @"content",
@"assetid": [NSString stringWithFormat:@"ProgramAssetId-%d", i],
@"length": @"3600",
@"program", "Program Name",
@"title": @"Program S3, EP1",
@"isfullepisode": @"y",
@"adloadtype": "2",
@"airdate": "20161013 20:00:00"
}
</syntaxhighlight>
|Android = <syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
//SDK Metadata
.put("type", "content")
.put("assetid", "vid345-67483")
.put("program", "Program Name")
.put("title", "Program S3, EP1")
.put("length", "3600")
.put("isfullepisode", "y")
.put("adloadtype", "2")
.put("airdate", "20161013 20:00:00")
</syntaxhighlight>
}}

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

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

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

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|}
<br />

=== Ad Metadata ===
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
<br/>
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}

== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
|On App Start||<code>[nielsenMeter loadMetadata: contentMetadata];</code> || // contentMetadata Object contains the JSON metadata for the impression
|-
| 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 is processing playing information. [[DCR_Video_APP_SDK#play|play]] and [[DCR_Video_APP_SDK#loadMetadata|loadMetadata]] calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## [[DCR_Video_APP_SDK#playheadPosition|playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[DCR_Video_APP_SDK#stop|stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[DCR_Video_APP_SDK#end|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>

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.

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

=== Sequence of Calls ===
=== play ===
Use [[DCR_Video_APP_SDK#play|play]] to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c"> [nielsenAppApi play:(JSONObject channelInfo)];</syntaxhighlight>
|Android = <syntaxhighlight lang="java"> public void play(JSONObject channelInfo);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenAppApi?.play(JSONObject channelInfo);</syntaxhighlight>
}}

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

==== Sending playheadposition for content ====
<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 ===
{{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 ===
When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
{{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>
}}

== Privacy and Opt-Out ==
{{ExampleCode|

iOS|
== iOS Opt-Out Implementation ==
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL for the Nielsen Privacy web page should be retrieved from the optOutURL property of the SDK object <code>optOutURL</code> and opened in 'WebView' / External browser.
*If the App SDK returns NULL in the optOutURL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the [[optOutStatus]] method.



The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy iOS.jpg|link=]]

*URL to this web page should be called from SDK and opened in 'WebView' / External browser.
*If the App SDK returns NULL as Opt-Out URL, handle this case and retry later.
*To retrieve the current Opt-Out status, use the [[optOutStatus]] property from Nielsen's SDK API.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

Users can opt out or opt back into Nielsen Measurement. Opt-Out feature relies on iOS' system setting – "Limit Ad Tracking". The setting can be accessed in the Settings application on any iOS device: '''Settings → Privacy → Advertising → Limit Ad Tracking'''.

User is opted out of Nielsen online measurement research when the "Limit Ad Tracking" setting is enabled.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

|Android =
== Android Opt-Out Implementation ==
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL to this web page should be called from SDK by invoking <code>userOptOutURLString()</code> and opened in 'WebView' / External browser.
<syntaxhighlight lang="java">
public String userOptOutURLString()
</syntaxhighlight>

*If the App SDK returns NULL as Opt-Out URL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the <code> getOptOutStatus() </code> method.
<syntaxhighlight lang="java">
public boolean getOptOutStatus()
</syntaxhighlight>

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
optOutUrl = mAppSdk.userOptOutURLString();
if(optOutUrl !=null)
{
mWebView = (WebView) findViewById(R.id.webView);
mWebView.getSettings().setJavaScriptEnabled(true);
mWebView.getSettings().setBuiltInZoomControls(true);
mWebView.getSettings().setDisplayZoomControls(false);
mWebView.getSettings().setLoadWithOverviewMode(true);
mWebView.getSettings().setUseWideViewPort(true);
mWebView.setWebViewClient(new MonitorWebView());
mWebView.setWebChromeClient(new WebChromeClient());
mWebView.loadUrl(optOutUrl);
}
else
{
//Handle it gracefully and Retry later
}
</syntaxhighlight>

The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''Note:''' When ‘WebView’ / External browser is closed, do not pass the status returned from ‘WebView’ / External browser to the SDK within the app, as the new Opt-Out page will not return any response.</blockquote>

<blockquote>'''Note:''' App SDK manages the user’s choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

Starting from SDK version 5.1.1.18:
*SDK will be sending the data pings to census even though SDK is opted out (In earlier releases all the traffic from SDK to census will be ceased). However, all the outgoing pings will have the parameter uoo=true using which backend can ignore this data.
*Current Opt-Out page is now updated to have no hyperlinks for Opt-Out / Opt-In operations. SDK Opt-Out has to be done via
'''Google Settings → Ads → Opt out of Ads Personalization'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''Note:''' The App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

== Opt-Out Implementation for Amazon Devices ==
Amazon device users can opt out or opt back into Nielsen Measurement, any time using the device’s setting – 'Limit Ad Tracking' (Interest-based ads).

User is opted out of Nielsen Online Measurement when ‘Limit Ad Tracking’ is enabled.

'''For devices running on Fire OS 5.1 and above, retrieve the Ad tracking value.'''
=== Retrieving Ad tracking Value ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

*Returns limit_ad_tracking value "0" if enabled
*Returns limit_ad_tracking value "1" if disabled
*Returns limit_ad_tracking value "2" if ad tracking is not supported (below Fire OS 5.1).

<blockquote>'''Note:''' Google Play Services are not needed to retrieve ad tracking state on Amazon devices. Limit Ad Tracking can be accessed through '''Settings → Apps & Games → Advertising ID'''.</blockquote>

}}

== 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": "it"
// 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", "it")
// 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>

DCR Italy Static Google AMP Cloud API

2018-01-30T13:20:53Z

NielsSedat:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International}} {{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/guides/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>Entertainment</code> || ✓
|-
| segA || custom segment to be used to break out reporting || <code>Music</code> ||
|-
| segB || custom segment to be used to break out reporting || <code>News</code> ||
|-
| segC || Reserved custom segment for Google AMP || <code>Google AMP</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.

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

=== Aggregation Limits ===
There are limits on the number of unique values that can be aggregated on in reporting. The specific limitations by key are:
{| class="wikitable"
|-
! Key !! Aggregation Limit
|-
| section || maximum of 25 unique values (section <= 25)
|-
| segA || total sum of segA, segB, and segC must be a maximum of 24 unique values (segA + segB + segC <= 24)
|-
| segB || total sum of segA, segB, and segC must be a maximum of 24 unique values (segA + segB + segC <= 24)
|}

== 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": "Entertainment",
"segA": "Music",
"segB": "News",
"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>

== 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://priv-policy.imrworldwide.com/priv/browser/it/it/optout.html

DCR Italy Static Google AMP Cloud API

2018-01-30T13:19:52Z

NielsSedat:

International

2017-12-27T10:09:14Z

NielsSedat: renamed german browser page title

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
{{CategoryIcon|International.png|International}}

__NOTOC__

<blockquote>Please contact your Nielsen representative for documentation if the guides for your country aren't listed.</blockquote>

{| class="wikitable"
! colspan="3" | Downloads
|-
| style="width: 90px;" |{{SmallIcon|DownloadIcon.png|alt=Cloud API}}
|style="width: 90px;" | {{SmallIcon|SDKIcon.png}}
| '''[[Digital Downloads|SDK Downloads]]'''
|}

{| class="wikitable"
|-
! style="width: 90px;" | Germany
! style="width: 90px;" |
! style="width: 45px;" |
! style="width: 45px;" | OS
!| Guide
|-
| rowspan="6" | {{SmallIcon|DEFlagIcon.png}}
| rowspan="6" | {{SmallIcon|SDKIcon.png}}
| rowspan="3" | {{OSIcon|VideoIcon.png}}
| {{OSIcon|macOSIcon.png}}
<br><br>
{{OSIcon|AndroidIcon.png}}
| '''[[DCR Germany Video App SDK]]'''
|-
| {{OSIcon|BrowserIcon.png}}
| '''[[DCR Germany Video Browser SDK]]'''
|}

{| class="wikitable"
|-
! style="width: 90px;" | Italy
! style="width: 90px;" |
! style="width: 45px;" |
! style="width: 45px;" | OS
!| Guide
|-
| rowspan="6" | {{SmallIcon|ITFlagIcon.png}}
| rowspan="6" | {{SmallIcon|SDKIcon.png}}
| rowspan="3" | {{OSIcon|VideoIcon.png}}
| {{OSIcon|macOSIcon.png}}
<br><br>
{{OSIcon|AndroidIcon.png}}
| '''[[DCR Italy Video App SDK]]'''
|-
| rowspan="2" | {{OSIcon|BrowserIcon.png}}
| '''[[DCR Italy Video Browser SDK (6.0.0)]]'''
|-
| '''[[DCR Italy Video Browser SDK (6.0.1)]] Object Video only'''
|-
| rowspan="4" | {{OSIcon|StaticIcon.png}}
| {{OSIcon|macOSIcon.png}}
<br><br>
{{OSIcon|AndroidIcon.png}}
| '''[[DCR Italy Static App SDK]]'''
|-
| {{OSIcon|BrowserIcon.png}}
| '''[[DCR Italy Static Browser SDK]]'''
|-
| {{OSIcon|FacebookIcon.png|alt=Facebook Instant Articles}}
| '''[[DCR Italy Static Facebook Instant Articles Browser SDK]]'''
|}

DCR Italy Video Browser SDK (6.0.0)

2017-12-27T09:58:11Z

NielsSedat: /* SDK Event Lifecycle */

DCR Italy Video Browser SDK (6.0.1)

2017-11-30T15:03:43Z

NielsSedat:

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

This guide will show how to integrate the Nielsen Software Development Kit (SDK) to enable Digital Content Ratings (DCR) video measurement on browser players.

== 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 is the framework for browsers developers to integrate Nielsen Measurement into their media player pages. 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 pages like:
*Site launch events and how long page is viewed
*Time of viewing a sub section / page.

== Prerequisites ==
To get started, an App ID, clientid and vcid is needed. These values are provided by Nielsen.

The App ID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration.
AppID: <syntaxhighlight lang="console">PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

The clientid is your 'parent# or companyid'
clientid: <syntaxhighlight lang="console">XX-XXXXXX"</syntaxhighlight> // eg. "it-123456"

The vcid is your channel id
vcid: <syntaxhighlight lang="console">"xXX"</syntaxhighlight> // eg. "c01"

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

=== Add Static Queue Snippet ===

Add the following script tag to the website:
<syntaxhighlight lang="html"><script>
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script></syntaxhighlight>

The static queue snippet allows the SDK APIs to be called while the actual SDK and configuration file are still being downloaded. As the queue can capture all API calls before the download completes, there is no wait time. Once the SDK is available, the API calls will transition from directing to the queue to the SDK seamlessly.

=== Create SDK Instance ===

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("<apid>", "<instanceName>",
{
clientid: "XX-XXXXXX", // eg. "it-123456"
vcid: "cXX", // eg. "c01"
nol_sdkDebug: "debug" // should be deleted when going live
}
)</syntaxhighlight>

When creating an instance, pass the following five values:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site || <code>"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"</code>
|-
| instanceName || Name of SDK instance || <code>"any string value"</code>
|-
| clientid || Brand value has to be passed in 3rd parameter object || Nielsen provided ||
|-
| vcid || VCID value has to be passed 3rd parameter object || Nielsen provided ||
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing. in 3rd parameter object || <code>{nol_sdkDebug: "debug"}</code>
|}

When the initialization call is made, a unique static configuration file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and will be cached on the user’s browser.

Once the configuration is downloaded, the SDK itself will be downloaded and initialized. All SDK modules are included in one file: “nlsSDK601.bundle.min.js”.

=== Example SDK Configuration ===

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:
<syntaxhighlight lang="html"><script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01", nol_sdkDebug: "DEBUG"});
</script></syntaxhighlight>

== Create Metadata Objects ==
There are two types of asset metadata:
* content: identify video
* ad: identify each ad ('''for Italy there is no need to tag ads''')
The metadata received for each asset is used for classification and reporting.

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

=== Content Metadata ===

Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required?
|-
| type ||
Type of measurement:
*video – <code>"content"</code>
|| <code>"content"</code> || ✓
|-
| assetid || Unique ID assigned to content (max. 40 characters) || custom || ✓
|-
| program || Program name (max. 254 characters) || custom || ✓
|-
| title || Episode title (max. 254 characters) || custom || ✓
|-
| length || Length of content in seconds for VOD. The estimated content length has to be passed for live content. || <code>seconds</code> (86400 for live stream) || ✓
|-
| airdate || Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || <code>YYYYMMDD hh:mm:ss</code> || ✓
|-
| isfullepisode || Full episode flag ||
<code>"y"</code> - full episode
<code>"n"</code> - non-full episode
|| ✓
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load "1"
#Dynamic - Dynamic Ad Insertion (DAI) "2"
|| <code>"1"</code> - Linear
<code>"2"</code> - Dynamic
|| ✓ (has to be "2" for DCR/Italy)
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || Nielsen provided ||
|-
| subbrand || subbrand/VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || Nielsen provided ||
|}

'''Example Content Object'''
... with all mandatory parameters - you may ignore the optional ones.

<syntaxhighlight lang="javascript">
//create content object
var contentMetadataObject =
{
type: "content",
assetid: "VID123-123456",
program: "program name",
title: "episode title",
length: "1020",
airdate: "19700101 00:00:00",
isfullepisode: "y",
adloadtype: "2"
};
</syntaxhighlight>

'''Note''': all parameters should be provided as strings (also length)

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

'''Attention:''' for Audiweb there is no need to tag ads in video stream ... you may ignore this paragraph. If there are ads in your stream, but not tagged than simply do nothing while ad is playing.

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

'''Example Ad Object'''
<syntaxhighlight lang="javascript">//create ad object
var adMetadataObject =
{
assetid: "AD-1",
type: "preroll"
};</syntaxhighlight>

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

== Call Nielsen APIs ==
The method for calling events is <code>ggPM()</code>.
<syntaxhighlight lang="javascript">nSdkInstance.ggPM('event', parameter, ...);</syntaxhighlight>

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event Number !! Values to pass !! Event Name || Description
|-
| <code>'3'</code> || content/ad metadata object || load content metadata || Load metadata event for content. Has to be called at the very first beginning of each stream.
|-
| <code>'5'</code> || playhead position || content play || Call when content or ads start playing or resumes from pause.
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'6'</code> || playhead position || pause || Call when content or ads is pausing. Use Event 5 to resume ...
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'7'</code> || playhead position || stop || Call when ads complete playing and at the very end of the stream. The playhead position must be passed when calling stop
|-
| <code>'8'</code> || playhead position from, playhead position to || seek || Call when scrubbing forward or backward with playhead position 'from' and 'to'
|-
| <code>'15'</code> || content/ad metadata object || load ad metadata || Call at the beginning of each ad, don’t use ‘play’ (event 5) if event 15 is used
|-
| <code>'49'</code> || playhead position || playhead position || '''VOD''': current position in seconds.
'''Live''': current unix timestamp (seconds since January 1st 1970).
Note: has to be called on a secondly basis.
For each ad the playheads starts with 0 (no Live unix timestamp for ads)
|-
| <code>'57'</code> || playhead position || end || 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.
|}

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

{{Examples|
without Ads|

<big>example '''without''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>

'''Note''': if there are ads played in stream simply use a pause (event 6) when ads start playing and a play (event 5) when content start playing.

|with Ads=
<big> example '''with''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream (even if 1st asset is preroll)

// Preroll
nSdkInstance.ggPM('15', prerollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 for the first segment (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition);

// Midroll
nSdkInstance.ggPM('15', midrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from where it left off before mid-roll (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// Postroll
nSdkInstance.ggPM('15', postrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>
}}

'''Attention:''' for Italy there is no need to tag ads in video stream ... ignore "with ads" example!

'''Note''': Event <code>'49'</code> 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 event <code>'7'</code>, <code>'57'</code>, or <code>'15'</code>.

'''Note''': when buffering occurs you have to send a event 6 (pause) and after buffering finished a 5 (play).

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

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

'''Handling Pause'''
The event <code>6</code> is used for handling pause. To indicate pause, stop passing the playhead position to the SDK and send Event 6 with playhead once. When content resumes, begin sending the playhead again with the correct playhead value. Also if buffering occurs for more than 1 second you may use Event 6 (pause) to indicate that.
e.g. pause at 1m2s and resume after a couple of seconds:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // now send nothing to SDK until player resumes (automatically because of buffering ends or user unpauses/resumes play
nSdkInstance.ggPM('5', 62); // ONLY WHEN PLAYING CONTENT (not ads!) - play/5 when resume occurs (when user click play or buffering ends)
nSdkInstance.ggPM('49', 63);
nSdkInstance.ggPM('49', 64);
...
</syntaxhighlight>

'''Handling Seek'''
The event <code>8</code> is used for handling forward/backward seek. To indicate seek, send Event 8 with 'from' and 'to' playhead.
e.g. seek from 1m2s to 2m0s:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // use pause, because buffering will occur (to be on safe side)
nSdkInstance.ggPM('8', 62,120);
nSdkInstance.ggPM('5', 120); // ONLY WHEN PLAYING CONTENT (not ads!) - play/5 when resuming
nSdkInstance.ggPM('49', 120);
nSdkInstance.ggPM('49', 121);
...
</syntaxhighlight>

'''Interruption Scenarios'''
The following possible browser interruption scenarios must be handled:
* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button
There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. midroll vs. content).
<syntaxhighlight lang="javascript">
function closePlayer() {
if (insideMidroll) { // Only inside a midroll indicate 'stop' for the ad
nSdkInstance.ggPM('7', playheadPositionMidroll);
}

// Indicate 'end' for the content and 'stop' for the stream
nSdkInstance.ggPM('57', playheadPositionContent);
nSdkInstance.ggPM('7', playheadPositionContent);
};
if ('onpagehide' in window) {
window.addEventListener("pagehide", function (e) { // for iOS mobile recommended by apple
closePlayer(); // call nielsensdk with end/stop
});
} else {
window.addEventListener("beforeunload", function (e) {
closePlayer(); // call nielsensdk with end/stop
});
}
</syntaxhighlight>

<blockquote>'''Note''': User may need to add code to support specific browser versions (e.g. older versions of Internet Explorer or covering Safari on mobile browsers ... you may use "onpagehide" event as well).</blockquote>

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

The following paragraph is a template for an opt-out statement.

''The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at https://priv-policy.imrworldwide.com/priv/browser/it/it/optout.html.''

'''Opt Back In'''

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

== Going Live ==
Following Nielsen testing, users need to make a couple of updates 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:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01"});</syntaxhighlight>

DCR Italy Video App SDK

2017-11-21T13:56:00Z

NielsSedat:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International}} {{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 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 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.
* '''sfcode:''' Unique identifier for the environment that the SDK should point to.
* '''Nielsen SDK:''' The Nielsen SDK package contains a variety of sample players for your reference.
If you do not have any of these prerequisites or if you have any questions, please contact our SDK sales support team.
Refer to [[Digital Measurement Onboarding]] guide for information on how to get a Nielsen App SDK and appid.

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

== Setting up your Development Environment ==
{{ExampleCode|
xCode|
<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
* 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 (Not applicable for International (Germany))
* 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 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
<br />
<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 <br />
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] <br />
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.
<br />
|Android =
<big>'''Configuring Android 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 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 Nielsen App SDK 1.2 library is composed of two parts:
* The Java AppSdk.jar library that 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 the Google Play support to work properly.
Ensure to 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_COARSE_LOCATION" android:required="false" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
For more details to handle 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 there is a Google service available and updated.
* If not available or updated, App SDK will not use this service when executing its functions and will make reference to 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.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;
}}

== 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 prior to version 5.1.1. (Version 4.0 for Android)

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

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

* The appid is provided by the Nielsen Technical Account Manager (TAM). The appid is a GUID data type and is specific to the application.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || Yes || 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.
'''Italian Clients'''
* "it"
|| Nielsen-specified || Yes || "it"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || Optional || "DEBUG"
|}
<br />
==== Sample SDK Initialization Code ====
{{ExampleCode|
|Swift =
Swift 4.0 Example:
<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PDA7D5EE6-B1B8-XXXX-XXXX-2A788BCXXXCA",
"appversion": "1.0",
"appname": "app name here",
"sfcode": "it",
"nol_devDebug": "DEBUG"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
<br />
<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",
@"appversion": "1.0",
@"appname": "app name here",
@"sfcode": "it",
@"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 =

[[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("appversion", "1.0")
.put("appname", "Sample App Name")
.put("sfcode", "it")
.put("nol_devDebug", "DEBUG"); // only for debug builds

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

The integration of Nielsen App SDK will depend on type of client app.<br />
* 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 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 handles 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 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, 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.
{{ExampleCode|
|Swift =
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
];

let contentMetadata = [
"type": "content",
"assetid": "88675545",
"title": "Program S3, EP1",
"isfullepisode":"n",
"adloadtype":"2",
"program":"Program Name",
"length":"3600",
"airdate":"20171020 10:05:00"
];
</syntaxhighlight>
|Objective C = <syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @
{@"type": @"content",
@"assetid": [NSString stringWithFormat:@"ProgramAssetId-%d", i],
@"length": @"3600",
@"program", "Program Name",
@"title": @"Program S3, EP1",
@"isfullepisode": @"y",
@"adloadtype": "2",
@"airdate": "20161013 20:00:00"
}
</syntaxhighlight>
|Android = <syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
//SDK Metadata
.put("type", "content")
.put("assetid", "vid345-67483")
.put("program", "Program Name")
.put("title", "Program S3, EP1")
.put("length", "3600")
.put("isfullepisode", "y")
.put("adloadtype", "2")
.put("airdate", "20161013 20:00:00")
</syntaxhighlight>
}}

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

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

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

<code>"2"</code> Dynamic – Dynamic Ad Insertion (DAI)
|| <code>"2"</code> - DCR measures content with dynamic ads || Yes
|}
<br />

=== Ad Metadata ===
The ad metadata (if applicable) should be passed for each individual ad, if ads are available during or before the stream begins.
<br/>
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of ad || 'preroll', 'midroll', or 'postroll' || ✓
|-
| assetid || unique ID assigned to ad || custom || ✓
|}

== Configure API Calls ==
=== Sample API Sequence ===
A Sample API sequence could follow this flow:
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
|On App Start||<code>[nielsenMeter loadMetadata: contentMetadata];</code> || // contentMetadata Object contains the JSON metadata for the impression
|-
| 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 is processing playing information. [[DCR_Video_APP_SDK#play|play]] and [[DCR_Video_APP_SDK#loadMetadata|loadMetadata]] calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
## [[DCR_Video_APP_SDK#playheadPosition|playheadPosition]] – Call this API every one second when playhead position timer is fired.
## [[DCR_Video_APP_SDK#stop|stop]] – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
## [[DCR_Video_APP_SDK#end|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>

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.

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

=== Sequence of Calls ===
=== play ===
Use [[DCR_Video_APP_SDK#play|play]] to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player.
{{ExampleCode|
|Objective C = <syntaxhighlight lang="objective-c"> [nielsenAppApi play:(JSONObject channelInfo)];</syntaxhighlight>
|Android = <syntaxhighlight lang="java"> public void play(JSONObject channelInfo);</syntaxhighlight>
|Swift = <syntaxhighlight lang="swift">nielsenAppApi?.play(JSONObject channelInfo);</syntaxhighlight>
}}

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

==== Sending playheadposition for content ====
<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 ===
{{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 ===
When content stop is initiated and content cannot be resumed from the same position (it can only be restarted from the beginning of stream).
{{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>
}}

== Privacy and Opt-Out ==
{{ExampleCode|

iOS|
== iOS Opt-Out Implementation ==
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL for the Nielsen Privacy web page should be retrieved from the optOutURL property of the SDK object <code>optOutURL</code> and opened in 'WebView' / External browser.
*If the App SDK returns NULL in the optOutURL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the [[optOutStatus]] method.



The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy iOS.jpg|link=]]

*URL to this web page should be called from SDK and opened in 'WebView' / External browser.
*If the App SDK returns NULL as Opt-Out URL, handle this case and retry later.
*To retrieve the current Opt-Out status, use the [[optOutStatus]] property from Nielsen's SDK API.
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus;
</syntaxhighlight>
*App should provide a UI control like 'close' or 'back' button to close the 'WebView' / External browser.

Users can opt out or opt back into Nielsen Measurement. Opt-Out feature relies on iOS' system setting – "Limit Ad Tracking". The setting can be accessed in the Settings application on any iOS device: '''Settings → Privacy → Advertising → Limit Ad Tracking'''.

User is opted out of Nielsen online measurement research when the "Limit Ad Tracking" setting is enabled.

[[File:Opt-Out iOS.jpg|link=]]

<blockquote>'''Note:''' For API Version 5.1 and above, App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

|Android =
== Android Opt-Out Implementation ==
To opt out, users must have access to "[https://priv-policy.imrworldwide.com/priv/mobile/it/it/optout.html About Nielsen Measurement]" page. User can click this page from app settings screen.

Include '''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.
*URL to this web page should be called from SDK by invoking <code>userOptOutURLString()</code> and opened in 'WebView' / External browser.
<syntaxhighlight lang="java">
public String userOptOutURLString()
</syntaxhighlight>

*If the App SDK returns NULL as Opt-Out URL, handle the exception gracefully and retry later.
*To retrieve the current Opt-Out status of a device, use the <code> getOptOutStatus() </code> method.
<syntaxhighlight lang="java">
public boolean getOptOutStatus()
</syntaxhighlight>

=== Displaying Opt-Out in a WebView ===
<syntaxhighlight lang="java">
optOutUrl = mAppSdk.userOptOutURLString();
if(optOutUrl !=null)
{
mWebView = (WebView) findViewById(R.id.webView);
mWebView.getSettings().setJavaScriptEnabled(true);
mWebView.getSettings().setBuiltInZoomControls(true);
mWebView.getSettings().setDisplayZoomControls(false);
mWebView.getSettings().setLoadWithOverviewMode(true);
mWebView.getSettings().setUseWideViewPort(true);
mWebView.setWebViewClient(new MonitorWebView());
mWebView.setWebChromeClient(new WebChromeClient());
mWebView.loadUrl(optOutUrl);
}
else
{
//Handle it gracefully and Retry later
}
</syntaxhighlight>

The app must provide access to "About Nielsen Measurement" page for the users. Include "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.

[[File:Privacy policy iOS.jpg|link=]]

<blockquote>'''Note:''' When ‘WebView’ / External browser is closed, do not pass the status returned from ‘WebView’ / External browser to the SDK within the app, as the new Opt-Out page will not return any response.</blockquote>

<blockquote>'''Note:''' App SDK manages the user’s choice (Opt-Out / Opt-In), the app does not need to manage this status.</blockquote>

Starting from SDK version 5.1.1.18:
*SDK will be sending the data pings to census even though SDK is opted out (In earlier releases all the traffic from SDK to census will be ceased). However, all the outgoing pings will have the parameter uoo=true using which backend can ignore this data.
*Current Opt-Out page is now updated to have no hyperlinks for Opt-Out / Opt-In operations. SDK Opt-Out has to be done via
'''Google Settings → Ads → Opt out of Ads Personalization'''.
<blockquote>'''Note:''' For Amazon devices, see [[#Opt-Out Implementation for Amazon Devices|Opt-Out Implementation for Amazon Devices]] below.</blockquote>

[[File:andr-ads.jpg|link=]]

<blockquote>'''Note:''' The App SDK will fire data pings and continue measurement even after the user has opted out from Nielsen measurement on a device. The data ping will be marked as opted-out ping.</blockquote>

== Opt-Out Implementation for Amazon Devices ==
Amazon device users can opt out or opt back into Nielsen Measurement, any time using the device’s setting – 'Limit Ad Tracking' (Interest-based ads).

User is opted out of Nielsen Online Measurement when ‘Limit Ad Tracking’ is enabled.

'''For devices running on Fire OS 5.1 and above, retrieve the Ad tracking value.'''
=== Retrieving Ad tracking Value ===

<syntaxhighlight lang="java">
ContentResolver cr = getContentResolver();
int limitAdTracking = Secure.getInt(cr, "limit_ad_tracking", 2);
</syntaxhighlight>

*Returns limit_ad_tracking value "0" if enabled
*Returns limit_ad_tracking value "1" if disabled
*Returns limit_ad_tracking value "2" if ad tracking is not supported (below Fire OS 5.1).

<blockquote>'''Note:''' Google Play Services are not needed to retrieve ad tracking state on Amazon devices. Limit Ad Tracking can be accessed through '''Settings → Apps & Games → Advertising ID'''.</blockquote>

}}

== 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": "it"
// 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", "it")
// 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>

DCR Italy Video Browser SDK (6.0.0)

2017-11-16T09:12:44Z

NielsSedat:

DCR Italy Video Browser SDK (6.0.1)

2017-11-15T15:36:30Z

NielsSedat:

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

This guide will show how to integrate the Nielsen Software Development Kit (SDK) to enable Digital Content Ratings (DCR) video measurement on browser players.

== 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 is the framework for browsers developers to integrate Nielsen Measurement into their media player pages. 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 pages like:
*Site launch events and how long page is viewed
*Time of viewing a sub section / page.

== Prerequisites ==
To get started, an App ID, clientid and vcid is needed. These values are provided by Nielsen.

The App ID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration.
AppID: <syntaxhighlight lang="console">PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

The clientid is your 'parent# or companyid'
clientid: <syntaxhighlight lang="console">XX-XXXXXX"</syntaxhighlight> // eg. "it-123456"

The vcid is your channel id
vcid: <syntaxhighlight lang="console">"xXX"</syntaxhighlight> // eg. "c01"

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

=== Add Static Queue Snippet ===

Add the following script tag to the website:
<syntaxhighlight lang="html"><script>
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script></syntaxhighlight>

The static queue snippet allows the SDK APIs to be called while the actual SDK and configuration file are still being downloaded. As the queue can capture all API calls before the download completes, there is no wait time. Once the SDK is available, the API calls will transition from directing to the queue to the SDK seamlessly.

=== Create SDK Instance ===

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("<apid>", "<instanceName>",
{
clientid: "XX-XXXXXX", // eg. "it-123456"
vcid: "cXX", // eg. "c01"
nol_sdkDebug: "debug" // should be deleted when going live
}
)</syntaxhighlight>

When creating an instance, pass the following five values:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site || <code>"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"</code>
|-
| instanceName || Name of SDK instance || <code>"any string value"</code>
|-
| clientid || Brand value has to be passed in 3rd parameter object || Nielsen provided ||
|-
| vcid || VCID value has to be passed 3rd parameter object || Nielsen provided ||
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing. in 3rd parameter object || <code>{nol_sdkDebug: "debug"}</code>
|}

When the initialization call is made, a unique static configuration file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and will be cached on the user’s browser.

Once the configuration is downloaded, the SDK itself will be downloaded and initialized. All SDK modules are included in one file: “nlsSDK601.bundle.min.js”.

=== Example SDK Configuration ===

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:
<syntaxhighlight lang="html"><script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01", nol_sdkDebug: "DEBUG"});
</script></syntaxhighlight>

== Create Metadata Objects ==
There are two types of asset metadata:
* content: identify video
* ad: identify each ad ('''for Italy there is no need to tag ads''')
The metadata received for each asset is used for classification and reporting.

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

=== Content Metadata ===

Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required?
|-
| type ||
Type of measurement:
*video – <code>"content"</code>
|| <code>"content"</code> || ✓
|-
| assetid || Unique ID assigned to content (max. 40 characters) || custom || ✓
|-
| program || Program name (max. 254 characters) || custom || ✓
|-
| title || Episode title (max. 254 characters) || custom || ✓
|-
| length || Length of content in seconds for VOD. The estimated content length has to be passed for live content. || <code>seconds</code> (86400 for live stream) || ✓
|-
| airdate || Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || <code>YYYYMMDD hh:mm:ss</code> || ✓
|-
| isfullepisode || Full episode flag ||
<code>"y"</code> - full episode
<code>"n"</code> - non-full episode
|| ✓
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load "1"
#Dynamic - Dynamic Ad Insertion (DAI) "2"
|| <code>"1"</code> - Linear
<code>"2"</code> - Dynamic
|| ✓ (has to be "2" for DCR/Italy)
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || Nielsen provided ||
|-
| subbrand || subbrand/VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || Nielsen provided ||
|}

'''Example Content Object'''
... with all mandatory parameters - you may ignore the optional ones.

<syntaxhighlight lang="javascript">
//create content object
var contentMetadataObject =
{
type: "content",
assetid: "VID123-123456",
program: "program name",
title: "episode title",
length: "1020",
airdate: "19700101 00:00:00",
isfullepisode: "y",
adloadtype: "2"
};
</syntaxhighlight>

'''Note''': all parameters should be provided as strings (also length)

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

'''Attention:''' for Audiweb there is no need to tag ads in video stream ... you may ignore this paragraph. If there are ads in your stream, but not tagged than simply do nothing while ad is playing.

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

'''Example Ad Object'''
<syntaxhighlight lang="javascript">//create ad object
var adMetadataObject =
{
assetid: "AD-1",
type: "preroll"
};</syntaxhighlight>

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

== Call Nielsen APIs ==
The method for calling events is <code>ggPM()</code>.
<syntaxhighlight lang="javascript">nSdkInstance.ggPM('event', parameter, ...);</syntaxhighlight>

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event Number !! Values to pass !! Event Name || Description
|-
| <code>'3'</code> || content/ad metadata object || load content metadata || Load metadata event for content. Has to be called at the very first beginning of each stream.
|-
| <code>'5'</code> || playhead position || content play || Call when content or ads start playing or resumes from pause.
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'6'</code> || playhead position || pause || Call when content or ads is pausing. Use Event 5 to resume ...
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'7'</code> || playhead position || stop || Call when ads complete playing and at the very end of the stream. The playhead position must be passed when calling stop
|-
| <code>'8'</code> || playhead position from, playhead position to || seek || Call when scrubbing forward or backward with playhead position 'from' and 'to'
|-
| <code>'15'</code> || content/ad metadata object || load ad metadata || Call at the beginning of each ad, don’t use ‘play’ (event 5) if event 15 is used
|-
| <code>'49'</code> || playhead position || playhead position || '''VOD''': current position in seconds.
'''Live''': current unix timestamp (seconds since January 1st 1970).
Note: has to be called on a secondly basis.
For each ad the playheads starts with 0 (no Live unix timestamp for ads)
|-
| <code>'57'</code> || playhead position || end || 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.
|}

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

{{Examples|
without Ads|

<big>example '''without''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>

'''Note''': if there are ads played in stream simply use a pause (event 6) when ads start playing and a play (event 5) when content start playing.

|with Ads=
<big> example '''with''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream (even if 1st asset is preroll)

// Preroll
nSdkInstance.ggPM('15', prerollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 for the first segment (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition);

// Midroll
nSdkInstance.ggPM('15', midrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from where it left off before mid-roll (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// Postroll
nSdkInstance.ggPM('15', postrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>
}}

'''Attention:''' for Italy there is no need to tag ads in video stream ... ignore "with ads" example!

'''Note''': Event <code>'49'</code> 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 event <code>'7'</code>, <code>'57'</code>, or <code>'15'</code>.

'''Note''': when buffering occurs you have to send a event 6 (pause) and after buffering finished a 5 (play).

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

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

'''Handling Pause'''
The event <code>6</code> is used for handling pause. To indicate pause, stop passing the playhead position to the SDK and send Event 6 with playhead once. When content resumes, begin sending the playhead again with the correct playhead value. Also if buffering occurs for more than 1 second you may use Event 6 (pause) to indicate that.
e.g. pause at 1m2s and resume after a couple of seconds:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // now send nothing to SDK until player resumes (automatically because of buffering ends or user unpauses/resumes play
nSdkInstance.ggPM('5', 62); // play/5 when resume occurs (when user click play or buffering ends)
nSdkInstance.ggPM('49', 63);
nSdkInstance.ggPM('49', 64);
...
</syntaxhighlight>

'''Handling Seek'''
The event <code>8</code> is used for handling forward/backward seek. To indicate seek, send Event 8 with 'from' and 'to' playhead.
e.g. seek from 1m2s to 2m0s:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // use pause, because buffering will occur (to be on safe side)
nSdkInstance.ggPM('8', 62,120);
nSdkInstance.ggPM('5', 120); // play/5 when resuming
nSdkInstance.ggPM('49', 120);
nSdkInstance.ggPM('49', 121);
...
</syntaxhighlight>

'''Interruption Scenarios'''
The following possible browser interruption scenarios must be handled:
* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button
There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. midroll vs. content).
<syntaxhighlight lang="javascript">
function closePlayer() {
if (insideMidroll) { // Only inside a midroll indicate 'stop' for the ad
nSdkInstance.ggPM('7', playheadPositionMidroll);
}

// Indicate 'end' for the content and 'stop' for the stream
nSdkInstance.ggPM('57', playheadPositionContent);
nSdkInstance.ggPM('7', playheadPositionContent);
};
if ('onpagehide' in window) {
window.addEventListener("pagehide", function (e) { // for iOS mobile recommended by apple
closePlayer(); // call nielsensdk with end/stop
});
} else {
window.addEventListener("beforeunload", function (e) {
closePlayer(); // call nielsensdk with end/stop
});
}
</syntaxhighlight>

<blockquote>'''Note''': User may need to add code to support specific browser versions (e.g. older versions of Internet Explorer or covering Safari on mobile browsers ... you may use "onpagehide" event as well).</blockquote>

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

The following paragraph is a template for an opt-out statement.

''The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at https://priv-policy.imrworldwide.com/priv/browser/it/it/optout.html.''

'''Opt Back In'''

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

== Going Live ==
Following Nielsen testing, users need to make a couple of updates 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:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01"});</syntaxhighlight>

DCR Italy Video Browser SDK (6.0.0)

2017-11-15T15:33:29Z

NielsSedat:

DCR Italy Video Browser SDK (6.0.0)

2017-11-15T09:52:04Z

NielsSedat:

DCR Italy Video Browser SDK (6.0.0)

2017-11-14T12:44:20Z

NielsSedat: added missing interrupt scenarios

DCR Italy Video Browser SDK (6.0.1)

2017-11-14T12:39:13Z

NielsSedat:

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

This guide will show how to integrate the Nielsen Software Development Kit (SDK) to enable Digital Content Ratings (DCR) video measurement on browser players.

== 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 is the framework for browsers developers to integrate Nielsen Measurement into their media player pages. 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 pages like:
*Site launch events and how long page is viewed
*Time of viewing a sub section / page.

== Prerequisites ==
To get started, an App ID, clientid and vcid is needed. These values are provided by Nielsen.

The App ID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration.
AppID: <syntaxhighlight lang="console">PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

The clientid is your 'parent# or companyid'
clientid: <syntaxhighlight lang="console">XX-XXXXXX"</syntaxhighlight> // eg. "it-123456"

The vcid is your channel id
vcid: <syntaxhighlight lang="console">"xXX"</syntaxhighlight> // eg. "c01"

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

=== Add Static Queue Snippet ===

Add the following script tag to the website:
<syntaxhighlight lang="html"><script>
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script></syntaxhighlight>

The static queue snippet allows the SDK APIs to be called while the actual SDK and configuration file are still being downloaded. As the queue can capture all API calls before the download completes, there is no wait time. Once the SDK is available, the API calls will transition from directing to the queue to the SDK seamlessly.

=== Create SDK Instance ===

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("<apid>", "<instanceName>",
{
clientid: "XX-XXXXXX", // eg. "it-123456"
vcid: "cXX", // eg. "c01"
nol_sdkDebug: "debug" // should be deleted when going live
}
)</syntaxhighlight>

When creating an instance, pass the following five values:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site || <code>"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"</code>
|-
| instanceName || Name of SDK instance || <code>"any string value"</code>
|-
| clientid || Brand value has to be passed in 3rd parameter object || Nielsen provided ||
|-
| vcid || VCID value has to be passed 3rd parameter object || Nielsen provided ||
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing. in 3rd parameter object || <code>{nol_sdkDebug: "debug"}</code>
|}

When the initialization call is made, a unique static configuration file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and will be cached on the user’s browser.

Once the configuration is downloaded, the SDK itself will be downloaded and initialized. All SDK modules are included in one file: “nlsSDK601.bundle.min.js”.

=== Example SDK Configuration ===

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:
<syntaxhighlight lang="html"><script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01", nol_sdkDebug: "DEBUG"});
</script></syntaxhighlight>

== Create Metadata Objects ==
There are two types of asset metadata:
* content: identify video
* ad: identify each ad ('''for Italy there is no need to tag ads''')
The metadata received for each asset is used for classification and reporting.

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

=== Content Metadata ===

Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required?
|-
| type ||
Type of measurement:
*video – <code>"content"</code>
|| <code>"content"</code> || ✓
|-
| assetid || Unique ID assigned to content (max. 40 characters) || custom || ✓
|-
| program || Program name (max. 254 characters) || custom || ✓
|-
| title || Episode title (max. 254 characters) || custom || ✓
|-
| length || Length of content in seconds for VOD. The estimated content length has to be passed for live content. || <code>seconds</code> (86400 for live stream) || ✓
|-
| airdate || Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || <code>YYYYMMDD hh:mm:ss</code> || ✓
|-
| isfullepisode || Full episode flag ||
<code>"y"</code> - full episode
<code>"n"</code> - non-full episode
|| ✓
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load "1"
#Dynamic - Dynamic Ad Insertion (DAI) "2"
|| <code>"1"</code> - Linear
<code>"2"</code> - Dynamic
|| ✓ (has to be "2" for DCR/Italy)
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || Nielsen provided ||
|-
| subbrand || subbrand/VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || Nielsen provided ||
|}

'''Example Content Object'''
... with all mandatory parameters - you may ignore the optional ones.

<syntaxhighlight lang="javascript">
//create content object
var contentMetadataObject =
{
type: "content",
assetid: "VID123-123456",
program: "program name",
title: "episode title",
length: "1020",
airdate: "19700101 00:00:00",
isfullepisode: "y",
adloadtype: "2"
};
</syntaxhighlight>

'''Note''': all parameters should be provided as strings (also length)

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

'''Attention:''' for Audiweb there is no need to tag ads in video stream ... you may ignore this paragraph. If there are ads in your stream, but not tagged than simply do nothing while ad is playing.

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

'''Example Ad Object'''
<syntaxhighlight lang="javascript">//create ad object
var adMetadataObject =
{
assetid: "AD-1",
type: "preroll"
};</syntaxhighlight>

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

== Call Nielsen APIs ==
The method for calling events is <code>ggPM()</code>.
<syntaxhighlight lang="javascript">nSdkInstance.ggPM('event', parameter, ...);</syntaxhighlight>

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event Number !! Values to pass !! Event Name || Description
|-
| <code>'3'</code> || content/ad metadata object || load content metadata || Load metadata event for content. Has to be called at the very first beginning of each stream.
|-
| <code>'5'</code> || playhead position || content play || Call when content or ads start playing or resumes from pause.
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'6'</code> || playhead position || pause || Call when content or ads is pausing. Use Event 5 to resume ...
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'7'</code> || playhead position || stop || Call when ads complete playing and at the very end of the stream. The playhead position must be passed when calling stop
|-
| <code>'8'</code> || playhead position from, playhead position to || seek || Call when scrubbing forward or backward with playhead position 'from' and 'to'
|-
| <code>'15'</code> || content/ad metadata object || load ad metadata || Call at the beginning of each ad, don’t use ‘play’ (event 5) if event 15 is used
|-
| <code>'49'</code> || playhead position || playhead position || '''VOD''': current position in seconds.
'''Live''': current unix timestamp (seconds since January 1st 1970).
Note: has to be called on a secondly basis.
For each ad the playheads starts with 0 (no Live unix timestamp for ads)
|-
| <code>'57'</code> || playhead position || end || 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.
|}

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

{{Examples|
without Ads|

<big>example '''without''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>

'''Note''': if there are ads played in stream simply use a pause (event 6) when ads start playing and a play (event 5) when content start playing.

|with Ads=
<big> example '''with''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream (even if 1st asset is preroll)

// Preroll
nSdkInstance.ggPM('15', prerollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 for the first segment (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition);

// Midroll
nSdkInstance.ggPM('15', midrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from where it left off before mid-roll (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// Postroll
nSdkInstance.ggPM('15', postrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>
}}

'''Attention:''' for Italy there is no need to tag ads in video stream ... ignore "with ads" example!

'''Note''': Event <code>'49'</code> 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 event <code>'7'</code>, <code>'57'</code>, or <code>'15'</code>.

'''Note''': when buffering occurs you have to send a event 6 (pause) and after buffering finished a 5 (play).

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

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

'''Handling Pause'''
The event <code>6</code> is used for handling pause. To indicate pause, stop passing the playhead position to the SDK and send Event 6 with playhead once. When content resumes, begin sending the playhead again with the correct playhead value. Also if buffering occurs for more than 1 second you may use Event 6 (pause) to indicate that.
e.g. pause at 1m2s and resume after a couple of seconds:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // now send nothing to SDK until player resumes (automatically because of buffering ends or user unpauses/resumes play
nSdkInstance.ggPM('5', 62); // play/5 when resume occurs (when user click play or buffering ends)
nSdkInstance.ggPM('49', 63);
nSdkInstance.ggPM('49', 64);
...
</syntaxhighlight>

'''Handling Seek'''
The event <code>8</code> is used for handling forward/backward seek. To indicate seek, send Event 8 with 'from' and 'to' playhead.
e.g. seek from 1m2s to 2m0s:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // use pause, because buffering will occur (to be on safe side)
nSdkInstance.ggPM('8', 62,120);
nSdkInstance.ggPM('5', 120); // play/5 when resuming
nSdkInstance.ggPM('49', 120);
nSdkInstance.ggPM('49', 121);
...
</syntaxhighlight>

'''Interruption Scenarios'''
The following possible browser interruption scenarios must be handled:
* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button
There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. midroll vs. content).
<syntaxhighlight lang="javascript">window.addEventListener('beforeunload', function(event)
{
// Only inside a midroll indicate 'stop' for the ad
if (insideMidroll) {
nSdkInstance.ggPM('7', playheadPosition);
}

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

<blockquote>'''Note''': User may need to add code to support specific browser versions (e.g. older versions of Internet Explorer or covering Safari on mobile browsers ... you may use "onpagehide" event as well).</blockquote>

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

The following paragraph is a template for an opt-out statement.

''The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at https://priv-policy.imrworldwide.com/priv/browser/it/it/optout.html.''

'''Opt Back In'''

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

== Going Live ==
Following Nielsen testing, users need to make a couple of updates 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:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01"});</syntaxhighlight>

DCR Italy Static App SDK

2017-11-14T09:01:15Z

NielsSedat:

DCR Italy Video Browser SDK (6.0.1)

2017-11-09T17:04:58Z

NielsSedat:

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

This guide will show how to integrate the Nielsen Software Development Kit (SDK) to enable Digital Content Ratings (DCR) video measurement on browser players.

== 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 is the framework for browsers developers to integrate Nielsen Measurement into their media player pages. 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 pages like:
*Site launch events and how long page is viewed
*Time of viewing a sub section / page.

== Prerequisites ==
To get started, an App ID, clientid and vcid is needed. These values are provided by Nielsen.

The App ID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration.
AppID: <syntaxhighlight lang="console">PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

The clientid is your 'parent# or companyid'
clientid: <syntaxhighlight lang="console">XX-XXXXXX"</syntaxhighlight> // eg. "it-123456"

The vcid is your channel id
vcid: <syntaxhighlight lang="console">"xXX"</syntaxhighlight> // eg. "c01"

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

=== Add Static Queue Snippet ===

Add the following script tag to the website:
<syntaxhighlight lang="html"><script>
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script></syntaxhighlight>

The static queue snippet allows the SDK APIs to be called while the actual SDK and configuration file are still being downloaded. As the queue can capture all API calls before the download completes, there is no wait time. Once the SDK is available, the API calls will transition from directing to the queue to the SDK seamlessly.

=== Create SDK Instance ===

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("<apid>", "<instanceName>",
{
clientid: "XX-XXXXXX", // eg. "it-123456"
vcid: "cXX", // eg. "c01"
nol_sdkDebug: "debug" // should be deleted when going live
}
)</syntaxhighlight>

When creating an instance, pass the following five values:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site || <code>"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"</code>
|-
| instanceName || Name of SDK instance || <code>"any string value"</code>
|-
| clientid || Brand value has to be passed in 3rd parameter object || Nielsen provided ||
|-
| vcid || VCID value has to be passed 3rd parameter object || Nielsen provided ||
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing. in 3rd parameter object || <code>{nol_sdkDebug: "debug"}</code>
|}

When the initialization call is made, a unique static configuration file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and will be cached on the user’s browser.

Once the configuration is downloaded, the SDK itself will be downloaded and initialized. All SDK modules are included in one file: “nlsSDK601.bundle.min.js”.

=== Example SDK Configuration ===

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:
<syntaxhighlight lang="html"><script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01", nol_sdkDebug: "DEBUG"});
</script></syntaxhighlight>

== Create Metadata Objects ==
There are two types of asset metadata:
* content: identify video
* ad: identify each ad ('''for Italy there is no need to tag ads''')
The metadata received for each asset is used for classification and reporting.

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

=== Content Metadata ===

Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required?
|-
| type ||
Type of measurement:
*video – <code>"content"</code>
|| <code>"content"</code> || ✓
|-
| assetid || Unique ID assigned to content (max. 40 characters) || custom || ✓
|-
| program || Program name (max. 254 characters) || custom || ✓
|-
| title || Episode title (max. 254 characters) || custom || ✓
|-
| length || Length of content in seconds for VOD. The estimated content length has to be passed for live content. || <code>seconds</code> (86400 for live stream) || ✓
|-
| airdate || Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || <code>YYYYMMDD hh:mm:ss</code> || ✓
|-
| isfullepisode || Full episode flag ||
<code>"y"</code> - full episode
<code>"n"</code> - non-full episode
|| ✓
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load "1"
#Dynamic - Dynamic Ad Insertion (DAI) "2"
|| <code>"1"</code> - Linear
<code>"2"</code> - Dynamic
|| ✓ (has to be "2" for DCR/Italy)
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || Nielsen provided ||
|-
| subbrand || subbrand/VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || Nielsen provided ||
|}

'''Example Content Object'''
... with all mandatory parameters - you may ignore the optional ones.

<syntaxhighlight lang="javascript">
//create content object
var contentMetadataObject =
{
type: "content",
assetid: "VID123-123456",
program: "program name",
title: "episode title",
length: "1020",
airdate: "19700101 00:00:00",
isfullepisode: "y",
adloadtype: "2"
};
</syntaxhighlight>

'''Note''': all parameters should be provided as strings (also length)

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

'''Attention:''' for Audiweb there is no need to tag ads in video stream ... you may ignore this paragraph. If there are ads in your stream, but not tagged than simply do nothing while ad is playing.

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

'''Example Ad Object'''
<syntaxhighlight lang="javascript">//create ad object
var adMetadataObject =
{
assetid: "AD-1",
type: "preroll"
};</syntaxhighlight>

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

== Call Nielsen APIs ==
The method for calling events is <code>ggPM()</code>.
<syntaxhighlight lang="javascript">nSdkInstance.ggPM('event', parameter, ...);</syntaxhighlight>

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event Number !! Values to pass !! Event Name || Description
|-
| <code>'3'</code> || content/ad metadata object || load content metadata || Load metadata event for content. Has to be called at the very first beginning of each stream.
|-
| <code>'5'</code> || playhead position || content play || Call when content or ads start playing or resumes from pause.
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'6'</code> || playhead position || pause || Call when content or ads is pausing. Use Event 5 to resume ...
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'7'</code> || playhead position || stop || Call when ads complete playing and at the very end of the stream. The playhead position must be passed when calling stop
|-
| <code>'8'</code> || playhead position from, playhead position to || seek || Call when scrubbing forward or backward with playhead position 'from' and 'to'
|-
| <code>'15'</code> || content/ad metadata object || load ad metadata || Call at the beginning of each ad, don’t use ‘play’ (event 5) if event 15 is used
|-
| <code>'49'</code> || playhead position || playhead position || '''VOD''': current position in seconds.
'''Live''': current unix timestamp (seconds since January 1st 1970).
Note: has to be called on a secondly basis.
For each ad the playheads starts with 0 (no Live unix timestamp for ads)
|-
| <code>'57'</code> || playhead position || end || 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.
|}

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

{{Examples|
without Ads|

<big>example '''without''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>

'''Note''': if there are ads played in stream simply use a pause (event 6) when ads start playing and a play (event 5) when content start playing.

|with Ads=
<big> example '''with''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream (even if 1st asset is preroll)

// Preroll
nSdkInstance.ggPM('15', prerollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 for the first segment (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition);

// Midroll
nSdkInstance.ggPM('15', midrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from where it left off before mid-roll (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// Postroll
nSdkInstance.ggPM('15', postrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>
}}

'''Attention:''' for Italy there is no need to tag ads in video stream ... ignore "with ads" example!

'''Note''': Event <code>'49'</code> 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 event <code>'7'</code>, <code>'57'</code>, or <code>'15'</code>.

'''Note''': when buffering occurs you have to send a event 6 (pause) and after buffering finished a 5 (play).

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

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

'''Handling Pause'''
The event <code>6</code> is used for handling pause. To indicate pause, stop passing the playhead position to the SDK and send Event 6 with playhead once. When content resumes, begin sending the playhead again with the correct playhead value. Also if buffering occurs for more than 1 second you may use Event 6 (pause) to indicate that.
e.g. pause at 1m2s and resume after a couple of seconds:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // now send nothing to SDK until player resumes (automatically because of buffering ends or user unpauses/resumes play
nSdkInstance.ggPM('5', 62); // play/5 when resume occurs (when user click play or buffering ends)
nSdkInstance.ggPM('49', 63);
nSdkInstance.ggPM('49', 64);
...
</syntaxhighlight>

'''Handling Seek'''
The event <code>8</code> is used for handling forward/backward seek. To indicate seek, send Event 8 with 'from' and 'to' playhead.
e.g. seek from 1m2s to 2m0s:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // use pause, because buffering will occur (to be on safe side)
nSdkInstance.ggPM('8', 62,120);
nSdkInstance.ggPM('5', 120); // play/5 when resuming
nSdkInstance.ggPM('49', 120);
nSdkInstance.ggPM('49', 121);
...
</syntaxhighlight>

'''Interruption Scenarios'''
The following possible browser interruption scenarios must be handled:
* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button
There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. midroll vs. content).
<syntaxhighlight lang="javascript">window.addEventListener('beforeunload', function(event)
{
// Only inside a midroll indicate 'stop' for the ad
if (insideMidroll) {
nSdkInstance.ggPM('7', playheadPosition);
}

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

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

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

The following paragraph is a template for an opt-out statement.

''The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at https://priv-policy.imrworldwide.com/priv/browser/it/it/optout.html.''

'''Opt Back In'''

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

== Going Live ==
Following Nielsen testing, users need to make a couple of updates 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:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01"});</syntaxhighlight>

DCR Italy Video Browser SDK (6.0.1)

2017-11-09T17:03:48Z

NielsSedat:

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

This guide will show how to integrate the Nielsen Software Development Kit (SDK) to enable Digital Content Ratings (DCR) video measurement on browser players.

== Prerequisites ==
To get started, an App ID, clientid and vcid is needed. These values are provided by Nielsen.

The App ID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration.
AppID: <syntaxhighlight lang="console">PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

The clientid is your 'parent# or companyid'
clientid: <syntaxhighlight lang="console">XX-XXXXXX"</syntaxhighlight> // eg. "it-123456"

The vcid is your channel id
vcid: <syntaxhighlight lang="console">"xXX"</syntaxhighlight> // eg. "c01"

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

=== Add Static Queue Snippet ===

Add the following script tag to the website:
<syntaxhighlight lang="html"><script>
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script></syntaxhighlight>

The static queue snippet allows the SDK APIs to be called while the actual SDK and configuration file are still being downloaded. As the queue can capture all API calls before the download completes, there is no wait time. Once the SDK is available, the API calls will transition from directing to the queue to the SDK seamlessly.

=== Create SDK Instance ===

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("<apid>", "<instanceName>",
{
clientid: "XX-XXXXXX", // eg. "it-123456"
vcid: "cXX", // eg. "c01"
nol_sdkDebug: "debug" // should be deleted when going live
}
)</syntaxhighlight>

When creating an instance, pass the following five values:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site || <code>"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"</code>
|-
| instanceName || Name of SDK instance || <code>"any string value"</code>
|-
| clientid || Brand value has to be passed in 3rd parameter object || Nielsen provided ||
|-
| vcid || VCID value has to be passed 3rd parameter object || Nielsen provided ||
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing. in 3rd parameter object || <code>{nol_sdkDebug: "debug"}</code>
|}

When the initialization call is made, a unique static configuration file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and will be cached on the user’s browser.

Once the configuration is downloaded, the SDK itself will be downloaded and initialized. All SDK modules are included in one file: “nlsSDK601.bundle.min.js”.

=== Example SDK Configuration ===

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:
<syntaxhighlight lang="html"><script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01", nol_sdkDebug: "DEBUG"});
</script></syntaxhighlight>

== Create Metadata Objects ==
There are two types of asset metadata:
* content: identify video
* ad: identify each ad ('''for Italy there is no need to tag ads''')
The metadata received for each asset is used for classification and reporting.

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

=== Content Metadata ===

Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required?
|-
| type ||
Type of measurement:
*video – <code>"content"</code>
|| <code>"content"</code> || ✓
|-
| assetid || Unique ID assigned to content (max. 40 characters) || custom || ✓
|-
| program || Program name (max. 254 characters) || custom || ✓
|-
| title || Episode title (max. 254 characters) || custom || ✓
|-
| length || Length of content in seconds for VOD. The estimated content length has to be passed for live content. || <code>seconds</code> (86400 for live stream) || ✓
|-
| airdate || Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || <code>YYYYMMDD hh:mm:ss</code> || ✓
|-
| isfullepisode || Full episode flag ||
<code>"y"</code> - full episode
<code>"n"</code> - non-full episode
|| ✓
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load "1"
#Dynamic - Dynamic Ad Insertion (DAI) "2"
|| <code>"1"</code> - Linear
<code>"2"</code> - Dynamic
|| ✓ (has to be "2" for DCR/Italy)
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || Nielsen provided ||
|-
| subbrand || subbrand/VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || Nielsen provided ||
|}

'''Example Content Object'''
... with all mandatory parameters - you may ignore the optional ones.

<syntaxhighlight lang="javascript">
//create content object
var contentMetadataObject =
{
type: "content",
assetid: "VID123-123456",
program: "program name",
title: "episode title",
length: "1020",
airdate: "19700101 00:00:00",
isfullepisode: "y",
adloadtype: "2"
};
</syntaxhighlight>

'''Note''': all parameters should be provided as strings (also length)

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

'''Attention:''' for Audiweb there is no need to tag ads in video stream ... you may ignore this paragraph. If there are ads in your stream, but not tagged than simply do nothing while ad is playing.

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

'''Example Ad Object'''
<syntaxhighlight lang="javascript">//create ad object
var adMetadataObject =
{
assetid: "AD-1",
type: "preroll"
};</syntaxhighlight>

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

== Call Nielsen APIs ==
The method for calling events is <code>ggPM()</code>.
<syntaxhighlight lang="javascript">nSdkInstance.ggPM('event', parameter, ...);</syntaxhighlight>

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event Number !! Values to pass !! Event Name || Description
|-
| <code>'3'</code> || content/ad metadata object || load content metadata || Load metadata event for content. Has to be called at the very first beginning of each stream.
|-
| <code>'5'</code> || playhead position || content play || Call when content or ads start playing or resumes from pause.
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'6'</code> || playhead position || pause || Call when content or ads is pausing. Use Event 5 to resume ...
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'7'</code> || playhead position || stop || Call when ads complete playing and at the very end of the stream. The playhead position must be passed when calling stop
|-
| <code>'8'</code> || playhead position from, playhead position to || seek || Call when scrubbing forward or backward with playhead position 'from' and 'to'
|-
| <code>'15'</code> || content/ad metadata object || load ad metadata || Call at the beginning of each ad, don’t use ‘play’ (event 5) if event 15 is used
|-
| <code>'49'</code> || playhead position || playhead position || '''VOD''': current position in seconds.
'''Live''': current unix timestamp (seconds since January 1st 1970).
Note: has to be called on a secondly basis.
For each ad the playheads starts with 0 (no Live unix timestamp for ads)
|-
| <code>'57'</code> || playhead position || end || 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.
|}

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

{{Examples|
without Ads|

<big>example '''without''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>

'''Note''': if there are ads played in stream simply use a pause (event 6) when ads start playing and a play (event 5) when content start playing.

|with Ads=
<big> example '''with''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream (even if 1st asset is preroll)

// Preroll
nSdkInstance.ggPM('15', prerollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 for the first segment (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition);

// Midroll
nSdkInstance.ggPM('15', midrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from where it left off before mid-roll (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// Postroll
nSdkInstance.ggPM('15', postrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>
}}

'''Attention:''' for Italy there is no need to tag ads in video stream ... ignore "with ads" example!

'''Note''': Event <code>'49'</code> 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 event <code>'7'</code>, <code>'57'</code>, or <code>'15'</code>.

'''Note''': when buffering occurs you have to send a event 6 (pause) and after buffering finished a 5 (play).

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

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

'''Handling Pause'''
The event <code>6</code> is used for handling pause. To indicate pause, stop passing the playhead position to the SDK and send Event 6 with playhead once. When content resumes, begin sending the playhead again with the correct playhead value. Also if buffering occurs for more than 1 second you may use Event 6 (pause) to indicate that.
e.g. pause at 1m2s and resume after a couple of seconds:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // now send nothing to SDK until player resumes (automatically because of buffering ends or user unpauses/resumes play
nSdkInstance.ggPM('5', 62); // play/5 when resume occurs (when user click play or buffering ends)
nSdkInstance.ggPM('49', 63);
nSdkInstance.ggPM('49', 64);
...
</syntaxhighlight>

'''Handling Seek'''
The event <code>8</code> is used for handling forward/backward seek. To indicate seek, send Event 8 with 'from' and 'to' playhead.
e.g. seek from 1m2s to 2m0s:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // use pause, because buffering will occur (to be on safe side)
nSdkInstance.ggPM('8', 62,120);
nSdkInstance.ggPM('5', 120); // play/5 when resuming
nSdkInstance.ggPM('49', 120);
nSdkInstance.ggPM('49', 121);
...
</syntaxhighlight>

'''Interruption Scenarios'''
The following possible browser interruption scenarios must be handled:
* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button
There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. midroll vs. content).
<syntaxhighlight lang="javascript">window.addEventListener('beforeunload', function(event)
{
// Only inside a midroll indicate 'stop' for the ad
if (insideMidroll) {
nSdkInstance.ggPM('7', playheadPosition);
}

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

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

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

The following paragraph is a template for an opt-out statement.

''The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at https://priv-policy.imrworldwide.com/priv/browser/it/it/optout.html.''

'''Opt Back In'''

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

== Going Live ==
Following Nielsen testing, users need to make a couple of updates 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:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01"});</syntaxhighlight>

DCR Italy Static Browser SDK

2017-11-09T14:28:06Z

NielsSedat:

DCR Italy Video Browser SDK (6.0.0)

2017-11-09T14:26:31Z

NielsSedat:

DCR Italy Video Browser SDK (6.0.0)

2017-11-09T14:25:43Z

NielsSedat: added overview

International

2017-11-08T16:11:41Z

NielsSedat:

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{CurrentBreadcrumb}}
[[Category:Digital]]
{{CategoryIcon|International.png|International}}

__NOTOC__

<blockquote>This section is under maintenance. Please contact your Nielsen representative for documentation if the guides for your country aren't listed.</blockquote>

{| class="wikitable"
|-
! style="width: 90px;" | Italy
! style="width: 90px;" |
! style="width: 45px;" |
! style="width: 45px;" | OS
!| Guide
|-
| rowspan="5" | {{SmallIcon|ITFlagIcon.png}}
| rowspan="5" | {{SmallIcon|SDKIcon.png}}
| rowspan="2" | {{OSIcon|VideoIcon.png}}
| {{OSIcon|macOSIcon.png}}
<br><br>
{{OSIcon|AndroidIcon.png}}
| '''[[DCR Italy Video App SDK]]'''
|-
| {{OSIcon|BrowserIcon.png}}
| '''[[DCR Italy Video Browser SDK (6.0.1)]] for Object Video users'''
|-
| rowspan="3" | {{OSIcon|StaticIcon.png}}
| {{OSIcon|macOSIcon.png}}
<br><br>
{{OSIcon|AndroidIcon.png}}
| '''[[DCR Italy Static App SDK]]'''
|-
| rowspan="2" | {{OSIcon|BrowserIcon.png}}
| '''[[DCR Italy Static Browser SDK]]'''
|-
| '''[[DCR Italy Static Browser SDK (6.0.1)]]'''
|}

DCR Italy Video Browser SDK (6.0.1)

2017-11-08T15:20:08Z

NielsSedat:

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

This guide will show how to integrate the Nielsen Software Development Kit (SDK) to enable Digital Content Ratings (DCR) video measurement on browser players.

== Prerequisites ==
To get started, an App ID, clientid and vcid is needed. These values are provided by Nielsen.

The App ID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration.
AppID: <syntaxhighlight lang="console">PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

The clientid is your 'parent# or companyid'
clientid: <syntaxhighlight lang="console">XX-XXXXXX"</syntaxhighlight> // eg. "it-123456"

The vcid is your channel id
vcid: <syntaxhighlight lang="console">"xXX"</syntaxhighlight> // eg. "c01"

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

=== Add Static Queue Snippet ===

Add the following script tag to the website:
<syntaxhighlight lang="html"><script>
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script></syntaxhighlight>

The static queue snippet allows the SDK APIs to be called while the actual SDK and configuration file are still being downloaded. As the queue can capture all API calls before the download completes, there is no wait time. Once the SDK is available, the API calls will transition from directing to the queue to the SDK seamlessly.

=== Create SDK Instance ===

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("<apid>", "<instanceName>",
{
clientid: "XX-XXXXXX", // eg. "it-123456"
vcid: "cXX", // eg. "c01"
nol_sdkDebug: "debug" // should be deleted when going live
}
)</syntaxhighlight>

When creating an instance, pass the following five values:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site || <code>"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"</code>
|-
| instanceName || Name of SDK instance || <code>"any string value"</code>
|-
| clientid || Brand value has to be passed in 3rd parameter object || Nielsen provided ||
|-
| vcid || VCID value has to be passed 3rd parameter object || Nielsen provided ||
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing. in 3rd parameter object || <code>{nol_sdkDebug: "debug"}</code>
|}

When the initialization call is made, a unique static configuration file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and will be cached on the user’s browser.

Once the configuration is downloaded, the SDK itself will be downloaded and initialized. All SDK modules are included in one file: “nlsSDK601.bundle.min.js”.

=== Example SDK Configuration ===

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:
<syntaxhighlight lang="html"><script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01", nol_sdkDebug: "DEBUG"});
</script></syntaxhighlight>

== Create Metadata Objects ==
There are two types of asset metadata:
* content: identify video
* ad: identify each ad ('''for Italy there is no need to tag ads''')
The metadata received for each asset is used for classification and reporting.

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

=== Content Metadata ===

Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required?
|-
| type ||
Type of measurement:
*video – <code>"content"</code>
|| <code>"content"</code> || ✓
|-
| assetid || Unique ID assigned to content (max. 40 characters) || custom || ✓
|-
| program || Program name (max. 254 characters) || custom || ✓
|-
| title || Episode title (max. 254 characters) || custom || ✓
|-
| length || Length of content in seconds for VOD. The estimated content length has to be passed for live content. || <code>seconds</code> (86400 for live stream) || ✓
|-
| airdate || Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || <code>YYYYMMDD hh:mm:ss</code> || ✓
|-
| isfullepisode || Full episode flag ||
<code>"y"</code> - full episode
<code>"n"</code> - non-full episode
|| ✓
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load "1"
#Dynamic - Dynamic Ad Insertion (DAI) "2"
|| <code>"1"</code> - Linear
<code>"2"</code> - Dynamic
|| ✓ (has to be "2" for DCR/Italy)
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || Nielsen provided ||
|-
| subbrand || subbrand/VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || Nielsen provided ||
|}

'''Example Content Object'''
... with all mandatory parameters - you may ignore the optional ones.

<syntaxhighlight lang="javascript">
//create content object
var contentMetadataObject =
{
type: "content",
assetid: "VID123-123456",
program: "program name",
title: "episode title",
length: "1020",
airdate: "19700101 00:00:00",
isfullepisode: "y",
adloadtype: "2"
};
</syntaxhighlight>

'''Note''': all parameters should be provided as strings (also length)

'''Note''': for Audiweb clients there is no need to use "mediaURL", "segB", "segC", "crossId1", "crossId2" and "hasAds". These parameters can be left out completely from structure. They are optional and not mandatory (and out of current reporting too).

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

'''Attention:''' for Audiweb there is no need to tag ads in video stream ... you may ignore this paragraph. If there are ads in your stream, but not tagged than simply do nothing while ad is playing.

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

'''Example Ad Object'''
<syntaxhighlight lang="javascript">//create ad object
var adMetadataObject =
{
assetid: "AD-1",
type: "preroll"
};</syntaxhighlight>

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

== Call Nielsen APIs ==
The method for calling events is <code>ggPM()</code>.
<syntaxhighlight lang="javascript">nSdkInstance.ggPM('event', parameter, ...);</syntaxhighlight>

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event Number !! Values to pass !! Event Name || Description
|-
| <code>'3'</code> || content/ad metadata object || load content metadata || Load metadata event for content. Has to be called at the very first beginning of each stream.
|-
| <code>'5'</code> || playhead position || content play || Call when content or ads start playing or resumes from pause.
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'6'</code> || playhead position || pause || Call when content or ads is pausing. Use Event 5 to resume ...
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'7'</code> || playhead position || stop || Call when ads complete playing and at the very end of the stream. The playhead position must be passed when calling stop
|-
| <code>'8'</code> || playhead position from, playhead position to || seek || Call when scrubbing forward or backward with playhead position 'from' and 'to'
|-
| <code>'15'</code> || content/ad metadata object || load ad metadata || Call at the beginning of each ad, don’t use ‘play’ (event 5) if event 15 is used
|-
| <code>'49'</code> || playhead position || playhead position || '''VOD''': current position in seconds.
'''Live''': current unix timestamp (seconds since January 1st 1970).
Note: has to be called on a secondly basis.
For each ad the playheads starts with 0 (no Live unix timestamp for ads)
|-
| <code>'57'</code> || playhead position || end || 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.
|}

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

{{Examples|
without Ads|

<big>example '''without''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>

'''Note''': if there are ads played in stream simply use a pause (event 6) when ads start playing and a play (event 5) when content start playing.

|with Ads=
<big> example '''with''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream (even if 1st asset is preroll)

// Preroll
nSdkInstance.ggPM('15', prerollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 for the first segment (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition);

// Midroll
nSdkInstance.ggPM('15', midrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from where it left off before mid-roll (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// Postroll
nSdkInstance.ggPM('15', postrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>
}}

'''Attention:''' for Italy there is no need to tag ads in video stream ... ignore "with ads" example!

'''Note''': Event <code>'49'</code> 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 event <code>'7'</code>, <code>'57'</code>, or <code>'15'</code>.

'''Note''': when buffering occurs you have to send a event 6 (pause) and after buffering finished a 5 (play).

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

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

'''Handling Pause'''
The event <code>6</code> is used for handling pause. To indicate pause, stop passing the playhead position to the SDK and send Event 6 with playhead once. When content resumes, begin sending the playhead again with the correct playhead value. Also if buffering occurs for more than 1 second you may use Event 6 (pause) to indicate that.
e.g. pause at 1m2s and resume after a couple of seconds:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // now send nothing to SDK until player resumes (automatically because of buffering ends or user unpauses/resumes play
nSdkInstance.ggPM('5', 62); // play/5 when resume occurs (when user click play or buffering ends)
nSdkInstance.ggPM('49', 63);
nSdkInstance.ggPM('49', 64);
...
</syntaxhighlight>

'''Handling Seek'''
The event <code>8</code> is used for handling forward/backward seek. To indicate seek, send Event 8 with 'from' and 'to' playhead.
e.g. seek from 1m2s to 2m0s:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // use pause, because buffering will occur (to be on safe side)
nSdkInstance.ggPM('8', 62,120);
nSdkInstance.ggPM('5', 120); // play/5 when resuming
nSdkInstance.ggPM('49', 120);
nSdkInstance.ggPM('49', 121);
...
</syntaxhighlight>

'''Interruption Scenarios'''
The following possible browser interruption scenarios must be handled:
* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button
There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. midroll vs. content).
<syntaxhighlight lang="javascript">window.addEventListener('beforeunload', function(event)
{
// Only inside a midroll indicate 'stop' for the ad
if (insideMidroll) {
nSdkInstance.ggPM('7', playheadPosition);
}

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

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

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

The following paragraph is a template for an opt-out statement.

''The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at https://priv-policy.imrworldwide.com/priv/browser/it/it/optout.html.''

'''Opt Back In'''

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

== Going Live ==
Once the DCR Tracking Code is added to Instant Articles, Nielsen will validate the implementation. Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01"});</syntaxhighlight>

DCR Italy Video Browser SDK (6.0.1)

2017-11-08T15:19:33Z

NielsSedat:

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

This guide will show how to integrate the Nielsen Software Development Kit (SDK) to enable Digital Content Ratings (DCR) video measurement on browser players.

== Prerequisites ==
To get started, an App ID, clientid and vcid is needed. These values are provided by Nielsen.

The App ID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration.
AppID: <syntaxhighlight lang="console">PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

The clientid is your 'parent# or companyid'
clientid: <syntaxhighlight lang="console">XX-XXXXXX"</syntaxhighlight> // eg. "it-123456"

The vcid is your channel id
vcid: <syntaxhighlight lang="console">"xXX"</syntaxhighlight> // eg. "c01"

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

=== Add Static Queue Snippet ===

Add the following script tag to the website:
<syntaxhighlight lang="html"><script>
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script></syntaxhighlight>

The static queue snippet allows the SDK APIs to be called while the actual SDK and configuration file are still being downloaded. As the queue can capture all API calls before the download completes, there is no wait time. Once the SDK is available, the API calls will transition from directing to the queue to the SDK seamlessly.

=== Create SDK Instance ===

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("<apid>", "<instanceName>",
{
clientid: "XX-XXXXXX", // eg. "it-123456"
vcid: "cXX", // eg. "c01"
nol_sdkDebug: "debug" // should be deleted when going live
}
)</syntaxhighlight>

When creating an instance, pass the following five values:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site || <code>"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"</code>
|-
| instanceName || Name of SDK instance || <code>"any string value"</code>
|-
| clientid || Brand value has to be passed in 3rd parameter object || Nielsen provided ||
|-
| vcid || VCID value has to be passed 3rd parameter object || Nielsen provided ||
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing. in 3rd parameter object || <code>{nol_sdkDebug: "debug"}</code>
|}

When the initialization call is made, a unique static configuration file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and will be cached on the user’s browser.

Once the configuration is downloaded, the SDK itself will be downloaded and initialized. All SDK modules are included in one file: “nlsSDK601.bundle.min.js”.

=== Example SDK Configuration ===

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:
<syntaxhighlight lang="html"><script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01", nol_sdkDebug: "DEBUG"});
</script></syntaxhighlight>

== Create Metadata Objects ==
There are two types of asset metadata:
* content: identify video
* ad: identify each ad ('''for Italy there is no need to tag ads''')
The metadata received for each asset is used for classification and reporting.

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

=== Content Metadata ===

Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required?
|-
| type ||
Type of measurement:
*video – <code>"content"</code>
|| <code>"content"</code> || ✓
|-
| assetid || Unique ID assigned to content (max. 40 characters) || custom || ✓
|-
| program || Program name (max. 254 characters) || custom || ✓
|-
| title || Episode title (max. 254 characters) || custom || ✓
|-
| length || Length of content in seconds for VOD. The estimated content length has to be passed for live content. || <code>seconds</code> (86400 for live stream) || ✓
|-
| airdate || Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || <code>YYYYMMDD hh:mm:ss</code> || ✓
|-
| isfullepisode || Full episode flag ||
<code>"y"</code> - full episode
<code>"n"</code> - non-full episode
|| ✓
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load "1"
#Dynamic - Dynamic Ad Insertion (DAI) "2"
|| <code>"1"</code> - Linear
<code>"2"</code> - Dynamic
|| ✓ (has to be "2" for DCR/Italy)
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || Nielsen provided ||
|-
| subbrand || subbrand/VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || Nielsen provided ||
|}

'''Example Content Object'''
... with all mandatory parameters - you may ignore the optional ones.

<syntaxhighlight lang="javascript">
//create content object
var contentMetadataObject =
{
type: "content",
assetid: "VID123-123456",
program: "program name",
title: "episode title",
length: "1020",
airdate: "19700101 00:00:00",
isfullepisode: "y",
adloadtype: "2"
};
</syntaxhighlight>

'''Note''': all parameters should be provided as strings (also length)

'''Note''': for Audiweb clients there is no need to use "mediaURL", "segB", "segC", "crossId1", "crossId2" and "hasAds". These parameters can be left out completely from structure. They are optional and not mandatory (and out of current reporting too).

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

'''Attention:''' for Audiweb there is no need to tag ads in video stream ... you may ignore this paragraph. If there are ads in your stream, but not tagged than simply do nothing while ad is playing.

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

'''Example Ad Object'''
<syntaxhighlight lang="javascript">//create ad object
var adMetadataObject =
{
assetid: "AD-1",
type: "preroll"
};</syntaxhighlight>

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

== Call Nielsen APIs ==
The method for calling events is <code>ggPM()</code>.
<syntaxhighlight lang="javascript">nSdkInstance.ggPM('event', parameter, ...);</syntaxhighlight>

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event Number !! Values to pass !! Event Name || Description
|-
| <code>'3'</code> || content/ad metadata object || load content metadata || Load metadata event for content. Has to be called at the very first beginning of each stream.
|-
| <code>'5'</code> || playhead position || content play || Call when content or ads start playing or resumes from pause.
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'6'</code> || playhead position || pause || Call when content or ads is pausing. Use Event 5 to resume ...
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'7'</code> || playhead position || stop || Call when ads complete playing and at the very end of the stream. The playhead position must be passed when calling stop
|-
| <code>'8'</code> || playhead position from, playhead position to || seek || Call when scrubbing forward or backward with playhead position 'from' and 'to'
|-
| <code>'15'</code> || content/ad metadata object || load ad metadata || Call at the beginning of each ad, don’t use ‘play’ (event 5) if event 15 is used
|-
| <code>'49'</code> || playhead position || playhead position || '''VOD''': current position in seconds.
'''Live''': current unix timestamp (seconds since January 1st 1970).
Note: has to be called on a secondly basis.
For each ad the playheads starts with 0 (no Live unix timestamp for ads)
|-
| <code>'57'</code> || playhead position || end || 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.
|}

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

{{Examples|
without Ads|

<big>example '''without''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>

'''Note''': if there are ads played in stream simply use a pause (event 6) when ads start playing and a play (event 5) when content start playing.

|with Ads=
<big> example '''with''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream (even if 1st asset is preroll)

// Preroll
nSdkInstance.ggPM('15', prerollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 for the first segment (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition);

// Midroll
nSdkInstance.ggPM('15', midrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from where it left off before mid-roll (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// Postroll
nSdkInstance.ggPM('15', postrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>
}}

'''Attention:''' for Italy there is no need to tag ads in video stream ... ignore "with ads" example!

'''Note''': Event <code>'49'</code> 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 event <code>'7'</code>, <code>'57'</code>, or <code>'15'</code>.

'''Note''': when buffering occurs you have to send a event 6 (pause) and after buffering finished a 5 (play).

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

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

'''Handling Pause'''
The event <code>6</code> is used for handling pause. To indicate pause, stop passing the playhead position to the SDK and send Event 6 with playhead once. When content resumes, begin sending the playhead again with the correct playhead value. Also if buffering occurs for more than 1 second you may use Event 6 (pause) to indicate that.
e.g. pause at 1m2s and resume after a couple of seconds:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // now send nothing to SDK until player resumes (automatically because of buffering ends or user unpauses/resumes play
nSdkInstance.ggPM('5', 62); // play/5 when resume occurs (when user click play or buffering ends)
nSdkInstance.ggPM('49', 63);
nSdkInstance.ggPM('49', 64);
...
</syntaxhighlight>

'''Handling Seek'''
The event <code>8</code> is used for handling forward/backward seek. To indicate seek, send Event 8 with 'from' and 'to' playhead.
e.g. seek from 1m2s to 2m0s:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // use pause, because buffering will occur (to be on safe side)
nSdkInstance.ggPM('8', 62,120);
nSdkInstance.ggPM('5', 120); // play/5 when resuming
nSdkInstance.ggPM('49', 120);
nSdkInstance.ggPM('49', 121);
...
</syntaxhighlight>

'''Interruption Scenarios'''
The following possible browser interruption scenarios must be handled:
* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button
There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. midroll vs. content).
<syntaxhighlight lang="javascript">window.addEventListener('beforeunload', function(event)
{
// Only inside a midroll indicate 'stop' for the ad
if (insideMidroll) {
nSdkInstance.ggPM('7', playheadPosition);
}

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

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

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

The following paragraph is a template for an opt-out statement.

''The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at https://priv-policy.imrworldwide.com/priv/browser/it/it/optout.html.''

'''Opt Back In'''

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

== Going Live ==
Once the DCR Tracking Code is added to Instant Articles, Nielsen will validate the implementation. Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01"});</syntaxhighlight>

DCR Italy Video Browser SDK (6.0.1)

2017-11-08T15:13:34Z

NielsSedat:

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

This guide will show how to integrate the Nielsen Software Development Kit (SDK) to enable Digital Content Ratings (DCR) video measurement on browser players.

== Prerequisites ==
To get started, an App ID, clientid and vcid is needed. These values are provided by Nielsen.

The App ID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration.
AppID: <syntaxhighlight lang="console">PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

The clientid is your 'parent# or companyid'
clientid: <syntaxhighlight lang="console">XX-XXXXXX"</syntaxhighlight> // eg. "it-123456"

The vcid is your channel id
vcid: <syntaxhighlight lang="console">"xXX"</syntaxhighlight> // eg. "c01"

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

=== Add Static Queue Snippet ===

Add the following script tag to the website:
<syntaxhighlight lang="html"><script>
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script></syntaxhighlight>

The static queue snippet allows the SDK APIs to be called while the actual SDK and configuration file are still being downloaded. As the queue can capture all API calls before the download completes, there is no wait time. Once the SDK is available, the API calls will transition from directing to the queue to the SDK seamlessly.

=== Create SDK Instance ===

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("<apid>", "<instanceName>",
{
clientid: "XX-XXXXXX", // eg. "it-123456"
vcid: "cXX", // eg. "c01"
nol_sdkDebug: "debug" // should be deleted when going live
}
)</syntaxhighlight>

When creating an instance, pass the following five values:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site || <code>"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"</code>
|-
| instanceName || Name of SDK instance || <code>"any string value"</code>
|-
| clientid || Brand value has to be passed in 3rd parameter object || Nielsen provided ||
|-
| vcid || VCID value has to be passed 3rd parameter object || Nielsen provided ||
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing. in 3rd parameter object || <code>{nol_sdkDebug: "debug"}</code>
|}

When the initialization call is made, a unique static configuration file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and will be cached on the user’s browser.

Once the configuration is downloaded, the SDK itself will be downloaded and initialized. All SDK modules are included in one file: “nlsSDK601.bundle.min.js”.

=== Example SDK Configuration ===

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:
<syntaxhighlight lang="html"><script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01", nol_sdkDebug: "DEBUG"});
</script></syntaxhighlight>

== Create Metadata Objects ==
There are two types of asset metadata:
* content: identify video
* ad: identify each ad ('''for Italy there is no need to tag ads''')
The metadata received for each asset is used for classification and reporting.

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

=== Content Metadata ===

Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required?
|-
| type ||
Type of measurement:
*video – <code>"content"</code>
|| <code>"content"</code> || ✓
|-
| assetid || Unique ID assigned to content (max. 40 characters) || custom || ✓
|-
| program || Program name (max. 254 characters) || custom || ✓
|-
| title || Episode title (max. 254 characters) || custom || ✓
|-
| length || Length of content in seconds for VOD. The estimated content length has to be passed for live content. || <code>seconds</code> (86400 for live stream) || ✓
|-
| airdate || Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || <code>YYYYMMDD hh:mm:ss</code> || ✓
|-
| isfullepisode || Full episode flag ||
<code>"y"</code> - full episode
<code>"n"</code> - non-full episode
|| ✓
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load "1"
#Dynamic - Dynamic Ad Insertion (DAI) "2"
|| <code>"1"</code> - Linear
<code>"2"</code> - Dynamic
|| ✓ (has to be "2" for DCR/Italy)
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || Nielsen provided ||
|-
| subbrand || subbrand/VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || Nielsen provided ||
|}

'''Example Content Object'''
... with all mandatory parameters - you may ignore the optional ones.

<syntaxhighlight lang="javascript">
//create content object
var contentMetadataObject =
{
type: "content",
assetid: "VID123-123456",
program: "program name",
title: "episode title",
length: "1020",
airdate: "19700101 00:00:00",
isfullepisode: "y"
};
</syntaxhighlight>

'''Note''': all parameters should be provided as strings (also length)

'''Note''': for Audiweb clients there is no need to use "mediaURL", "segB", "segC", "crossId1", "crossId2" and "hasAds". These parameters can be left out completely from structure. They are optional and not mandatory (and out of current reporting too).

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

'''Attention:''' for Audiweb there is no need to tag ads in video stream ... you may ignore this paragraph. If there are ads in your stream, but not tagged than simply do nothing while ad is playing.

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

'''Example Ad Object'''
<syntaxhighlight lang="javascript">//create ad object
var adMetadataObject =
{
assetid: "AD-1",
type: "preroll"
};</syntaxhighlight>

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

== Call Nielsen APIs ==
The method for calling events is <code>ggPM()</code>.
<syntaxhighlight lang="javascript">nSdkInstance.ggPM('event', parameter, ...);</syntaxhighlight>

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event Number !! Values to pass !! Event Name || Description
|-
| <code>'3'</code> || content/ad metadata object || load content metadata || Load metadata event for content. Has to be called at the very first beginning of each stream.
|-
| <code>'5'</code> || playhead position || content play || Call when content or ads start playing or resumes from pause.
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'6'</code> || playhead position || pause || Call when content or ads is pausing. Use Event 5 to resume ...
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'7'</code> || playhead position || stop || Call when ads complete playing and at the very end of the stream. The playhead position must be passed when calling stop
|-
| <code>'8'</code> || playhead position from, playhead position to || seek || Call when scrubbing forward or backward with playhead position 'from' and 'to'
|-
| <code>'15'</code> || content/ad metadata object || load ad metadata || Call at the beginning of each ad, don’t use ‘play’ (event 5) if event 15 is used
|-
| <code>'49'</code> || playhead position || playhead position || '''VOD''': current position in seconds.
'''Live''': current unix timestamp (seconds since January 1st 1970).
Note: has to be called on a secondly basis.
For each ad the playheads starts with 0 (no Live unix timestamp for ads)
|-
| <code>'57'</code> || playhead position || end || 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.
|}

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

{{Examples|
without Ads|

<big>example '''without''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>

'''Note''': if there are ads played in stream simply use a pause (event 6) when ads start playing and a play (event 5) when content start playing.

|with Ads=
<big> example '''with''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream (even if 1st asset is preroll)

// Preroll
nSdkInstance.ggPM('15', prerollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 for the first segment (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition);

// Midroll
nSdkInstance.ggPM('15', midrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from where it left off before mid-roll (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// Postroll
nSdkInstance.ggPM('15', postrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>
}}

'''Attention:''' for Italy there is no need to tag ads in video stream ... ignore "with ads" example!

'''Note''': Event <code>'49'</code> 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 event <code>'7'</code>, <code>'57'</code>, or <code>'15'</code>.

'''Note''': when buffering occurs you have to send a event 6 (pause) and after buffering finished a 5 (play).

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

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

'''Handling Pause'''
The event <code>6</code> is used for handling pause. To indicate pause, stop passing the playhead position to the SDK and send Event 6 with playhead once. When content resumes, begin sending the playhead again with the correct playhead value. Also if buffering occurs for more than 1 second you may use Event 6 (pause) to indicate that.
e.g. pause at 1m2s and resume after a couple of seconds:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // now send nothing to SDK until player resumes (automatically because of buffering ends or user unpauses/resumes play
nSdkInstance.ggPM('5', 62); // play/5 when resume occurs (when user click play or buffering ends)
nSdkInstance.ggPM('49', 63);
nSdkInstance.ggPM('49', 64);
...
</syntaxhighlight>

'''Handling Seek'''
The event <code>8</code> is used for handling forward/backward seek. To indicate seek, send Event 8 with 'from' and 'to' playhead.
e.g. seek from 1m2s to 2m0s:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // use pause, because buffering will occur (to be on safe side)
nSdkInstance.ggPM('8', 62,120);
nSdkInstance.ggPM('5', 120); // play/5 when resuming
nSdkInstance.ggPM('49', 120);
nSdkInstance.ggPM('49', 121);
...
</syntaxhighlight>

'''Interruption Scenarios'''
The following possible browser interruption scenarios must be handled:
* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button
There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. midroll vs. content).
<syntaxhighlight lang="javascript">window.addEventListener('beforeunload', function(event)
{
// Only inside a midroll indicate 'stop' for the ad
if (insideMidroll) {
nSdkInstance.ggPM('7', playheadPosition);
}

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

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

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

The following paragraph is a template for an opt-out statement.

''The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at https://priv-policy.imrworldwide.com/priv/browser/it/it/optout.html.''

'''Opt Back In'''

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

== Going Live ==
Once the DCR Tracking Code is added to Instant Articles, Nielsen will validate the implementation. Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01"});</syntaxhighlight>

DCR Italy Video Browser SDK (6.0.1)

2017-11-08T10:09:39Z

NielsSedat: /* Content Metadata */

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

This guide will show how to integrate the Nielsen Software Development Kit (SDK) to enable Digital Content Ratings (DCR) video measurement on browser players.

== Prerequisites ==
To get started, an App ID, clientid and vcid is needed. These values are provided by Nielsen.

The App ID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration.
AppID: <syntaxhighlight lang="console">PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

The clientid is your 'parent# or companyid'
clientid: <syntaxhighlight lang="console">XX-XXXXXX"</syntaxhighlight> // eg. "it-123456"

The vcid is your channel id
vcid: <syntaxhighlight lang="console">"xXX"</syntaxhighlight> // eg. "c01"

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

=== Add Static Queue Snippet ===

Add the following script tag to the website:
<syntaxhighlight lang="html"><script>
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script></syntaxhighlight>

The static queue snippet allows the SDK APIs to be called while the actual SDK and configuration file are still being downloaded. As the queue can capture all API calls before the download completes, there is no wait time. Once the SDK is available, the API calls will transition from directing to the queue to the SDK seamlessly.

=== Create SDK Instance ===

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("<apid>", "<instanceName>",
{
clientid: "XX-XXXXXX", // eg. "it-123456"
vcid: "cXX", // eg. "c01"
nol_sdkDebug: "debug" // should be deleted when going live
}
)</syntaxhighlight>

When creating an instance, pass the following five values:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site || <code>"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"</code>
|-
| instanceName || Name of SDK instance || <code>"any string value"</code>
|-
| clientid || Brand value has to be passed in 3rd parameter object || Nielsen provided ||
|-
| vcid || VCID value has to be passed 3rd parameter object || Nielsen provided ||
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing. in 3rd parameter object || <code>{nol_sdkDebug: "debug"}</code>
|}

When the initialization call is made, a unique static configuration file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and will be cached on the user’s browser.

Once the configuration is downloaded, the SDK itself will be downloaded and initialized. All SDK modules are included in one file: “nlsSDK601.bundle.min.js”.

=== Example SDK Configuration ===

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:
<syntaxhighlight lang="html"><script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01", nol_sdkDebug: "DEBUG"});
</script></syntaxhighlight>

== Create Metadata Objects ==
There are two types of asset metadata:
* content: identify video
* ad: identify each ad ('''for Italy there is no need to tag ads''')
The metadata received for each asset is used for classification and reporting.

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

=== Content Metadata ===

Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required?
|-
| type ||
Type of measurement:
*video – <code>"content"</code>
|| <code>"content"</code> || ✓
|-
| assetid || Unique ID assigned to content (max. 40 characters) || custom || ✓
|-
| program || Program name (max. 254 characters) || custom || ✓
|-
| title || Episode title (max. 254 characters) || custom || ✓
|-
| length || Length of content in seconds for VOD. The estimated content length has to be passed for live content. || <code>seconds</code> (86400 for live stream) || ✓
|-
| airdate || Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || <code>YYYYMMDD hh:mm:ss</code> || ✓
|-
| isfullepisode || Full episode flag ||
<code>"y"</code> - full episode
<code>"n"</code> - non-full episode
|| ✓
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load
#Dynamic - Dynamic Ad Insertion (DAI)
|| <code>"1"</code> - Linear
<code>"2"</code> - Dynamic
||
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || Nielsen provided ||
|-
| subbrand || subbrand/VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || Nielsen provided ||
|-
| mediaURL || URL location of the content being streamed (max. 254 characters) || custom ||
|-
|| hasAds || Whether the content is ad supported ||
<code>"0"</code> - No Ads
<code>"1"</code> - Ad Supported
<code>"2"</code> - Unknown (default)
||
|}

'''Example Content Object'''
... with all mandatory parameters - you may ignore the optional ones.

<syntaxhighlight lang="javascript">
//create content object
var contentMetadataObject =
{
type: "content",
assetid: "VID123-123456",
program: "program name",
title: "episode title",
length: "1020",
airdate: "19700101 00:00:00",
isfullepisode: "y"
};
</syntaxhighlight>

'''Note''': all parameters should be provided as strings (also length)

'''Note''': for Audiweb clients there is no need to use "mediaURL", "segB", "segC", "crossId1", "crossId2" and "hasAds". These parameters can be left out completely from structure. They are optional and not mandatory (and out of current reporting too).

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

'''Attention:''' for Audiweb there is no need to tag ads in video stream ... you may ignore this paragraph. If there are ads in your stream, but not tagged than simply do nothing while ad is playing.

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

'''Example Ad Object'''
<syntaxhighlight lang="javascript">//create ad object
var adMetadataObject =
{
assetid: "AD-1",
type: "preroll"
};</syntaxhighlight>

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

== Call Nielsen APIs ==
The method for calling events is <code>ggPM()</code>.
<syntaxhighlight lang="javascript">nSdkInstance.ggPM('event', parameter, ...);</syntaxhighlight>

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event Number !! Values to pass !! Event Name || Description
|-
| <code>'3'</code> || content/ad metadata object || load content metadata || Load metadata event for content. Has to be called at the very first beginning of each stream.
|-
| <code>'5'</code> || playhead position || content play || Call when content or ads start playing or resumes from pause.
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'6'</code> || playhead position || pause || Call when content or ads is pausing. Use Event 5 to resume ...
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'7'</code> || playhead position || stop || Call when ads complete playing and at the very end of the stream. The playhead position must be passed when calling stop
|-
| <code>'8'</code> || playhead position from, playhead position to || seek || Call when scrubbing forward or backward with playhead position 'from' and 'to'
|-
| <code>'15'</code> || content/ad metadata object || load ad metadata || Call at the beginning of each ad, don’t use ‘play’ (event 5) if event 15 is used
|-
| <code>'49'</code> || playhead position || playhead position || '''VOD''': current position in seconds.
'''Live''': current unix timestamp (seconds since January 1st 1970).
Note: has to be called on a secondly basis.
For each ad the playheads starts with 0 (no Live unix timestamp for ads)
|-
| <code>'57'</code> || playhead position || end || 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.
|}

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

{{Examples|
without Ads|

<big>example '''without''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>

'''Note''': if there are ads played in stream simply use a pause (event 6) when ads start playing and a play (event 5) when content start playing.

|with Ads=
<big> example '''with''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream (even if 1st asset is preroll)

// Preroll
nSdkInstance.ggPM('15', prerollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 for the first segment (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition);

// Midroll
nSdkInstance.ggPM('15', midrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from where it left off before mid-roll (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// Postroll
nSdkInstance.ggPM('15', postrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>
}}

'''Attention:''' for Italy there is no need to tag ads in video stream ... ignore "with ads" example!

'''Note''': Event <code>'49'</code> 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 event <code>'7'</code>, <code>'57'</code>, or <code>'15'</code>.

'''Note''': when buffering occurs you have to send a event 6 (pause) and after buffering finished a 5 (play).

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

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

'''Handling Pause'''
The event <code>6</code> is used for handling pause. To indicate pause, stop passing the playhead position to the SDK and send Event 6 with playhead once. When content resumes, begin sending the playhead again with the correct playhead value. Also if buffering occurs for more than 1 second you may use Event 6 (pause) to indicate that.
e.g. pause at 1m2s and resume after a couple of seconds:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // now send nothing to SDK until player resumes (automatically because of buffering ends or user unpauses/resumes play
nSdkInstance.ggPM('5', 62); // play/5 when resume occurs (when user click play or buffering ends)
nSdkInstance.ggPM('49', 63);
nSdkInstance.ggPM('49', 64);
...
</syntaxhighlight>

'''Handling Seek'''
The event <code>8</code> is used for handling forward/backward seek. To indicate seek, send Event 8 with 'from' and 'to' playhead.
e.g. seek from 1m2s to 2m0s:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // use pause, because buffering will occur (to be on safe side)
nSdkInstance.ggPM('8', 62,120);
nSdkInstance.ggPM('5', 120); // play/5 when resuming
nSdkInstance.ggPM('49', 120);
nSdkInstance.ggPM('49', 121);
...
</syntaxhighlight>

'''Interruption Scenarios'''
The following possible browser interruption scenarios must be handled:
* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button
There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. midroll vs. content).
<syntaxhighlight lang="javascript">window.addEventListener('beforeunload', function(event)
{
// Only inside a midroll indicate 'stop' for the ad
if (insideMidroll) {
nSdkInstance.ggPM('7', playheadPosition);
}

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

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

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

The following paragraph is a template for an opt-out statement.

''The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at https://priv-policy.imrworldwide.com/priv/browser/it/it/optout.html.''

'''Opt Back In'''

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

== Going Live ==
Once the DCR Tracking Code is added to Instant Articles, Nielsen will validate the implementation. Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01"});</syntaxhighlight>

DCR Italy Video Browser SDK (6.0.1)

2017-11-07T16:15:10Z

NielsSedat:

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

This guide will show how to integrate the Nielsen Software Development Kit (SDK) to enable Digital Content Ratings (DCR) video measurement on browser players.

== Prerequisites ==
To get started, an App ID, clientid and vcid is needed. These values are provided by Nielsen.

The App ID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration.
AppID: <syntaxhighlight lang="console">PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

The clientid is your 'parent# or companyid'
clientid: <syntaxhighlight lang="console">XX-XXXXXX"</syntaxhighlight> // eg. "it-123456"

The vcid is your channel id
vcid: <syntaxhighlight lang="console">"xXX"</syntaxhighlight> // eg. "c01"

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

=== Add Static Queue Snippet ===

Add the following script tag to the website:
<syntaxhighlight lang="html"><script>
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script></syntaxhighlight>

The static queue snippet allows the SDK APIs to be called while the actual SDK and configuration file are still being downloaded. As the queue can capture all API calls before the download completes, there is no wait time. Once the SDK is available, the API calls will transition from directing to the queue to the SDK seamlessly.

=== Create SDK Instance ===

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("<apid>", "<instanceName>",
{
clientid: "XX-XXXXXX", // eg. "it-123456"
vcid: "cXX", // eg. "c01"
nol_sdkDebug: "debug" // should be deleted when going live
}
)</syntaxhighlight>

When creating an instance, pass the following five values:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site || <code>"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"</code>
|-
| instanceName || Name of SDK instance || <code>"any string value"</code>
|-
| clientid || Brand value has to be passed in 3rd parameter object || Nielsen provided ||
|-
| vcid || VCID value has to be passed 3rd parameter object || Nielsen provided ||
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing. in 3rd parameter object || <code>{nol_sdkDebug: "debug"}</code>
|}

When the initialization call is made, a unique static configuration file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and will be cached on the user’s browser.

Once the configuration is downloaded, the SDK itself will be downloaded and initialized. All SDK modules are included in one file: “nlsSDK601.bundle.min.js”.

=== Example SDK Configuration ===

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:
<syntaxhighlight lang="html"><script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01", nol_sdkDebug: "DEBUG"});
</script></syntaxhighlight>

== Create Metadata Objects ==
There are two types of asset metadata:
* content: identify video
* ad: identify each ad ('''for Italy there is no need to tag ads''')
The metadata received for each asset is used for classification and reporting.

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

=== Content Metadata ===

Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required?
|-
| type ||
Type of measurement:
*video – <code>"content"</code>
|| <code>"content"</code> || ✓
|-
| assetid || Unique ID assigned to content (max. 40 characters) || custom || ✓
|-
| program || Program name (max. 254 characters) || custom || ✓
|-
| title || Episode title (max. 254 characters) || custom || ✓
|-
| length || Length of content in seconds for VOD. The estimated content length has to be passed for live content. || <code>seconds</code> (86400 for live stream) || ✓
|-
| airdate || Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || <code>YYYYMMDD hh:mm:ss</code> || ✓
|-
| isfullepisode || Full episode flag ||
<code>"y"</code> - full episode
<code>"n"</code> - non-full episode
|| ✓
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load
#Dynamic - Dynamic Ad Insertion (DAI)
|| <code>"1"</code> - Linear
<code>"2"</code> - Dynamic
|| ✓
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || Nielsen provided ||
|-
| subbrand || subbrand/VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || Nielsen provided ||
|-
| mediaURL || URL location of the content being streamed (max. 254 characters) || custom ||
|-
|| hasAds || Whether the content is ad supported ||
<code>"0"</code> - No Ads
<code>"1"</code> - Ad Supported
<code>"2"</code> - Unknown (default)
||
|}

'''Example Content Object'''
<syntaxhighlight lang="javascript">
//create content object
var contentMetadataObject =
{
type: "content",
assetid: "VID123-123456",
program: "program name",
title: "episode title",
length: "1020",
airdate: "19700101 00:00:00",
isfullepisode: "y",
adloadtype: "2"
};
</syntaxhighlight>

'''Note''': all parameters should be provided as strings (also length)

'''Note''': for Audiweb clients there is no need to use "mediaURL", "segB", "segC", "crossId1", "crossId2" and "hasAds". These parameters can be left out completely from structure. They are optional and not mandatory (and out of current reporting too).

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

'''Attention:''' for Audiweb there is no need to tag ads in video stream ... you may ignore this paragraph. If there are ads in your stream, but not tagged than simply do nothing while ad is playing.

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

'''Example Ad Object'''
<syntaxhighlight lang="javascript">//create ad object
var adMetadataObject =
{
assetid: "AD-1",
type: "preroll"
};</syntaxhighlight>

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

== Call Nielsen APIs ==
The method for calling events is <code>ggPM()</code>.
<syntaxhighlight lang="javascript">nSdkInstance.ggPM('event', parameter, ...);</syntaxhighlight>

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event Number !! Values to pass !! Event Name || Description
|-
| <code>'3'</code> || content/ad metadata object || load content metadata || Load metadata event for content. Has to be called at the very first beginning of each stream.
|-
| <code>'5'</code> || playhead position || content play || Call when content or ads start playing or resumes from pause.
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'6'</code> || playhead position || pause || Call when content or ads is pausing. Use Event 5 to resume ...
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'7'</code> || playhead position || stop || Call when ads complete playing and at the very end of the stream. The playhead position must be passed when calling stop
|-
| <code>'8'</code> || playhead position from, playhead position to || seek || Call when scrubbing forward or backward with playhead position 'from' and 'to'
|-
| <code>'15'</code> || content/ad metadata object || load ad metadata || Call at the beginning of each ad, don’t use ‘play’ (event 5) if event 15 is used
|-
| <code>'49'</code> || playhead position || playhead position || '''VOD''': current position in seconds.
'''Live''': current unix timestamp (seconds since January 1st 1970).
Note: has to be called on a secondly basis.
For each ad the playheads starts with 0 (no Live unix timestamp for ads)
|-
| <code>'57'</code> || playhead position || end || 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.
|}

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

{{Examples|
without Ads|

<big>example '''without''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>

'''Note''': if there are ads played in stream simply use a pause (event 6) when ads start playing and a play (event 5) when content start playing.

|with Ads=
<big> example '''with''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream (even if 1st asset is preroll)

// Preroll
nSdkInstance.ggPM('15', prerollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 for the first segment (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition);

// Midroll
nSdkInstance.ggPM('15', midrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from where it left off before mid-roll (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// Postroll
nSdkInstance.ggPM('15', postrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>
}}

'''Attention:''' for Italy there is no need to tag ads in video stream ... ignore "with ads" example!

'''Note''': Event <code>'49'</code> 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 event <code>'7'</code>, <code>'57'</code>, or <code>'15'</code>.

'''Note''': when buffering occurs you have to send a event 6 (pause) and after buffering finished a 5 (play).

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

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

'''Handling Pause'''
The event <code>6</code> is used for handling pause. To indicate pause, stop passing the playhead position to the SDK and send Event 6 with playhead once. When content resumes, begin sending the playhead again with the correct playhead value. Also if buffering occurs for more than 1 second you may use Event 6 (pause) to indicate that.
e.g. pause at 1m2s and resume after a couple of seconds:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // now send nothing to SDK until player resumes (automatically because of buffering ends or user unpauses/resumes play
nSdkInstance.ggPM('5', 62); // play/5 when resume occurs (when user click play or buffering ends)
nSdkInstance.ggPM('49', 63);
nSdkInstance.ggPM('49', 64);
...
</syntaxhighlight>

'''Handling Seek'''
The event <code>8</code> is used for handling forward/backward seek. To indicate seek, send Event 8 with 'from' and 'to' playhead.
e.g. seek from 1m2s to 2m0s:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // use pause, because buffering will occur (to be on safe side)
nSdkInstance.ggPM('8', 62,120);
nSdkInstance.ggPM('5', 120); // play/5 when resuming
nSdkInstance.ggPM('49', 120);
nSdkInstance.ggPM('49', 121);
...
</syntaxhighlight>

'''Interruption Scenarios'''
The following possible browser interruption scenarios must be handled:
* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button
There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. midroll vs. content).
<syntaxhighlight lang="javascript">window.addEventListener('beforeunload', function(event)
{
// Only inside a midroll indicate 'stop' for the ad
if (insideMidroll) {
nSdkInstance.ggPM('7', playheadPosition);
}

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

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

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

The following paragraph is a template for an opt-out statement.

''The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at https://priv-policy.imrworldwide.com/priv/browser/it/it/optout.html.''

'''Opt Back In'''

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

== Going Live ==
Once the DCR Tracking Code is added to Instant Articles, Nielsen will validate the implementation. Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01"});</syntaxhighlight>

DCR Italy Video Browser SDK (6.0.1)

2017-11-07T12:13:07Z

NielsSedat:

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

This guide will show how to integrate the Nielsen Software Development Kit (SDK) to enable Digital Content Ratings (DCR) video measurement on browser players.

== Prerequisites ==
To get started, an App ID, clientid and vcid is needed. These values are provided by Nielsen.

The App ID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration.
AppID: <syntaxhighlight lang="console">PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

The clientid is your 'parent# or companyid'
clientid: <syntaxhighlight lang="console">XX-XXXXXX"</syntaxhighlight> // eg. "it-123456"

The vcid is your channel id
vcid: <syntaxhighlight lang="console">"xXX"</syntaxhighlight> // eg. "c01"

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

=== Add Static Queue Snippet ===

Add the following script tag to the website:
<syntaxhighlight lang="html"><script>
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script></syntaxhighlight>

The static queue snippet allows the SDK APIs to be called while the actual SDK and configuration file are still being downloaded. As the queue can capture all API calls before the download completes, there is no wait time. Once the SDK is available, the API calls will transition from directing to the queue to the SDK seamlessly.

=== Create SDK Instance ===

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("<apid>", "<instanceName>",
{
clientid: "XX-XXXXXX", // eg. "it-123456"
vcid: "cXX", // eg. "c01"
nol_sdkDebug: "debug" // should be deleted when going live
}
)</syntaxhighlight>

When creating an instance, pass the following three values:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site || <code>"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"</code>
|-
| instanceName || Name of SDK instance || <code>"any string value"</code>
|-
| clientid || Brand value has to be passed in 3rd parameter object || Nielsen provided ||
|-
| vcid || VCID value has to be passed 3rd parameter object || Nielsen provided ||
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing. in 3rd parameter object || <code>{nol_sdkDebug: "debug"}</code>
|}

When the initialization call is made, a unique static configuration file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and will be cached on the user’s browser.

Once the configuration is downloaded, the SDK itself will be downloaded and initialized. All SDK modules are included in one file: “nlsSDK601.bundle.min.js”.

=== Example SDK Configuration ===

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:
<syntaxhighlight lang="html"><script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01", nol_sdkDebug: "DEBUG"});
</script></syntaxhighlight>

== Create Metadata Objects ==
There are two types of asset metadata:
* content: identify video
* ad: identify each ad ('''for Italy there is no need to tag ads''')
The metadata received for each asset is used for classification and reporting.

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

=== Content Metadata ===

Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required?
|-
| type ||
Type of measurement:
*video – <code>"content"</code>
|| <code>"content"</code> || ✓
|-
| assetid || Unique ID assigned to content (max. 40 characters) || custom || ✓
|-
| program || Program name (max. 254 characters) || custom || ✓
|-
| title || Episode title (max. 254 characters) || custom || ✓
|-
| length || Length of content in seconds for VOD. The estimated content length has to be passed for live content. || <code>seconds</code> (86400 for live stream) || ✓
|-
| airdate || Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || <code>YYYYMMDD hh:mm:ss</code> || ✓
|-
| isfullepisode || Full episode flag ||
<code>"y"</code> - full episode
<code>"n"</code> - non-full episode
|| ✓
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load
#Dynamic - Dynamic Ad Insertion (DAI)
|| <code>"1"</code> - Linear
<code>"2"</code> - Dynamic
|| ✓
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || Nielsen provided ||
|-
| subbrand || subbrand/VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || Nielsen provided ||
|-
| mediaURL || URL location of the content being streamed (max. 254 characters) || custom ||
|-
|| hasAds || Whether the content is ad supported ||
<code>"0"</code> - No Ads
<code>"1"</code> - Ad Supported
<code>"2"</code> - Unknown (default)
||
|}

'''Example Content Object'''
<syntaxhighlight lang="javascript">
//create content object
var contentMetadataObject =
{
type: "content",
assetid: "VID123-123456",
program: "program name",
title: "episode title",
length: "1020",
airdate: "19700101 00:00:00",
isfullepisode: "y",
adloadtype: "2"
};
</syntaxhighlight>

'''Note''': all parameters should be provided as strings (also length)

'''Note''': for Audiweb clients there is no need to use "mediaURL", "segB", "segC", "crossId1", "crossId2" and "hasAds". These parameters can be left out completely from structure. They are optional and not mandatory (and out of current reporting too).

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

'''Attention:''' for Audiweb there is no need to tag ads in video stream ... you may ignore this paragraph. If there are ads in your stream, but not tagged than simply do nothing while ad is playing.

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

'''Example Ad Object'''
<syntaxhighlight lang="javascript">//create ad object
var adMetadataObject =
{
assetid: "AD-1",
type: "preroll"
};</syntaxhighlight>

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

== Call Nielsen APIs ==
The method for calling events is <code>ggPM()</code>.
<syntaxhighlight lang="javascript">nSdkInstance.ggPM('event', parameter, ...);</syntaxhighlight>

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event Number !! Values to pass !! Event Name || Description
|-
| <code>'3'</code> || content/ad metadata object || load content metadata || Load metadata event for content. Has to be called at the very first beginning of each stream.
|-
| <code>'5'</code> || playhead position || content play || Call when content or ads start playing or resumes from pause.
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'6'</code> || playhead position || pause || Call when content or ads is pausing. Use Event 5 to resume ...
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'7'</code> || playhead position || stop || Call when ads complete playing and at the very end of the stream. The playhead position must be passed when calling stop
|-
| <code>'8'</code> || playhead position from, playhead position to || seek || Call when scrubbing forward or backward with playhead position 'from' and 'to'
|-
| <code>'15'</code> || content/ad metadata object || load ad metadata || Call at the beginning of each ad, don’t use ‘play’ (event 5) if event 15 is used
|-
| <code>'49'</code> || playhead position || playhead position || '''VOD''': current position in seconds.
'''Live''': current unix timestamp (seconds since January 1st 1970).
Note: has to be called on a secondly basis.
For each ad the playheads starts with 0 (no Live unix timestamp for ads)
|-
| <code>'57'</code> || playhead position || end || 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.
|}

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

{{Examples|
without Ads|

<big>example '''without''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>

'''Note''': if there are ads played in stream simply use a pause (event 6) when ads start playing and a play (event 5) when content start playing.

|with Ads=
<big> example '''with''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream (even if 1st asset is preroll)

// Preroll
nSdkInstance.ggPM('15', prerollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 for the first segment (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition);

// Midroll
nSdkInstance.ggPM('15', midrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from where it left off before mid-roll (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// Postroll
nSdkInstance.ggPM('15', postrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>
}}

'''Attention:''' for Italy there is no need to tag ads in video stream ... ignore "with ads" example!

'''Note''': Event <code>'49'</code> 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 event <code>'7'</code>, <code>'57'</code>, or <code>'15'</code>.

'''Note''': when buffering occurs you have to send a event 6 (pause) and after buffering finished a 5 (play).

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

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

'''Handling Pause'''
The event <code>6</code> is used for handling pause. To indicate pause, stop passing the playhead position to the SDK and send Event 6 with playhead once. When content resumes, begin sending the playhead again with the correct playhead value. Also if buffering occurs for more than 1 second you may use Event 6 (pause) to indicate that.
e.g. pause at 1m2s and resume after a couple of seconds:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // now send nothing to SDK until player resumes (automatically because of buffering ends or user unpauses/resumes play
nSdkInstance.ggPM('5', 62); // play/5 when resume occurs (when user click play or buffering ends)
nSdkInstance.ggPM('49', 63);
nSdkInstance.ggPM('49', 64);
...
</syntaxhighlight>

'''Handling Seek'''
The event <code>8</code> is used for handling forward/backward seek. To indicate seek, send Event 8 with 'from' and 'to' playhead.
e.g. seek from 1m2s to 2m0s:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // use pause, because buffering will occur (to be on safe side)
nSdkInstance.ggPM('8', 62,120);
nSdkInstance.ggPM('5', 120); // play/5 when resuming
nSdkInstance.ggPM('49', 120);
nSdkInstance.ggPM('49', 121);
...
</syntaxhighlight>

'''Interruption Scenarios'''
The following possible browser interruption scenarios must be handled:
* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button
There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. midroll vs. content).
<syntaxhighlight lang="javascript">window.addEventListener('beforeunload', function(event)
{
// Only inside a midroll indicate 'stop' for the ad
if (insideMidroll) {
nSdkInstance.ggPM('7', playheadPosition);
}

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

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

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

The following paragraph is a template for an opt-out statement.

''The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at https://priv-policy.imrworldwide.com/priv/browser/it/it/optout.html.''

'''Opt Back In'''

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

== Going Live ==
Once the DCR Tracking Code is added to Instant Articles, Nielsen will validate the implementation. Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01"});</syntaxhighlight>

DCR Italy Video Browser SDK (6.0.1)

2017-11-07T12:11:54Z

NielsSedat:

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

This guide will show how to integrate the Nielsen Software Development Kit (SDK) to enable Digital Content Ratings (DCR) video measurement on browser players.

== Prerequisites ==
To get started, an App ID, clientid and vcid is needed. These values are provided by Nielsen.

The App ID is a unique ID assigned to the player/site/app. This will be provided upon starting the integration.
AppID: <syntaxhighlight lang="console">PXXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX</syntaxhighlight>

The clientid is your 'parent# or companyid'
clientid: <syntaxhighlight lang="console">XX-XXXXXX"</syntaxhighlight> // eg. "it-123456"

The vcid is your channel id
vcid: <syntaxhighlight lang="console">"xXX"</syntaxhighlight> // eg. "c01"

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

=== Add Static Queue Snippet ===

Add the following script tag to the website:
<syntaxhighlight lang="html"><script>
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");
</script></syntaxhighlight>

The static queue snippet allows the SDK APIs to be called while the actual SDK and configuration file are still being downloaded. As the queue can capture all API calls before the download completes, there is no wait time. Once the SDK is available, the API calls will transition from directing to the queue to the SDK seamlessly.

=== Create SDK Instance ===

To initialize the SDK, create an SDK instance by making the initialization call:

'''Initialization API Call'''
<syntaxhighlight lang="javascript">NOLBUNDLE.nlsQ("<apid>", "<instanceName>",
{
clientid: "XX-XXXXXX", // eg. "it-123456"
vcid: "cXX", // eg. "c01"
nol_sdkDebug: "debug" // should be deleted when going live
}
)</syntaxhighlight>

When creating an instance, pass the following three values:
{| class="wikitable"
|-
! Parameter !! Description !! Values
|-
| apid || Unique ID assigned to player/site || <code>"PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"</code>
|-
| instanceName || Name of SDK instance || <code>"any string value"</code>
|-
| clientid || Brand value has to be passed in 3rd parameter object || Nielsen provided ||
|-
| vcid || VCID value has to be passed 3rd parameter object || Nielsen provided ||
|-
| nol_sdkDebug || Enables Nielsen console logging. Only required for testing. in 3rd parameter object || <code>{nol_sdkDebug: "debug"}</code>
|}

When the initialization call is made, a unique static configuration file, <code><apid>.js</code>, will be downloaded based on the <code>apid</code> and will be cached on the user’s browser.

Once the configuration is downloaded, the SDK itself will be downloaded and initialized. All SDK modules are included in one file: “nlsSDK601.bundle.min.js”.

=== Example SDK Configuration ===

The configuration should include the Static Queue Snippet and an SDK Instance for an unique App ID as shown in the example:
<syntaxhighlight lang="html"><script type="text/javascript">
// Add Static Queue Snippet
!function(t,n)
{
t[n]=t[n]||
{
nlsQ:function(e,o,c,r,s,i)
{
return s=t.document,
r=s.createElement("script"),
r.async=1,
r.src=("http:"===t.location.protocol?"http:":"https:")+"//cdn-gl.imrworldwide.com/conf/"+e+".js#name="+o+"&ns="+n,
i=s.getElementsByTagName("script")[0],
i.parentNode.insertBefore(r,i),
t[n][o]=t[n][o]||{g:c||{},
ggPM:function(e,c,r,s,i){(t[n][o].q=t[n][o].q||[]).push([e,c,r,s,i])}},t[n][o]
}
}
}
(window,"NOLBUNDLE");

// Created SDK Instance
var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01", nol_sdkDebug: "DEBUG"});
</script></syntaxhighlight>

== Create Metadata Objects ==
There are two types of asset metadata:
* content: identify video
* ad: identify each ad ('''for Italy there is no need to tag ads''')
The metadata received for each asset is used for classification and reporting.

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

=== Content Metadata ===

Content metadata should remain constant throughout the completion of an episode / clip including the ads play.
{| class="wikitable"
|-
! Key !! Description !! Values !! Required?
|-
| type ||
Type of measurement:
*video – <code>"content"</code>
|| <code>"content"</code> || ✓
|-
| assetid || Unique ID assigned to content (max. 40 characters) || custom || ✓
|-
| program || Program name (max. 254 characters) || custom || ✓
|-
| title || Episode title (max. 254 characters) || custom || ✓
|-
| length || Length of content in seconds for VOD. The estimated content length has to be passed for live content. || <code>seconds</code> (86400 for live stream) || ✓
|-
| airdate || Original (local) air date and time (hh:mm:ss as 24h time stamp); if not known set it to eg. "19700101 00:00:00" || <code>YYYYMMDD hh:mm:ss</code> || ✓
|-
| isfullepisode || Full episode flag ||
<code>"y"</code> - full episode
<code>"n"</code> - non-full episode
|| ✓
|-
| adloadtype ||
Type of ad load:
#Linear - matches TV ad load
#Dynamic - Dynamic Ad Insertion (DAI)
|| <code>"1"</code> - Linear
<code>"2"</code> - Dynamic
|| ✓
|-
| clientid || Brand value is automatically populated through the App ID provided. The value passed here will override the default value. (e.g. Multiple brands in App) || Nielsen provided ||
|-
| subbrand || subbrand/VCID value is automatically populated through the App ID provided. This value passed here will override the default value. (e.g. Multiple Sub-brands in App) || Nielsen provided ||
|-
| mediaURL || URL location of the content being streamed (max. 254 characters) || custom ||
|-
|| hasAds || Whether the content is ad supported ||
<code>"0"</code> - No Ads
<code>"1"</code> - Ad Supported
<code>"2"</code> - Unknown (default)
||
|}

'''Example Content Object'''
<syntaxhighlight lang="javascript">
//create content object
var contentMetadataObject =
{
type: "content",
assetid: "VID123-123456",
program: "program name",
title: "episode title",
length: "1020",
airdate: "19700101 00:00:00",
isfullepisode: "y",
adloadtype: "2"
};
</syntaxhighlight>

'''Note''': all parameters should be provided as strings (also length)

'''Note''': for Audiweb clients there is no need to use "mediaURL", "segB", "segC", "crossId1", "crossId2" and "hasAds". These parameters can be left out completely from structure. They are optional and not mandatory (and out of current reporting too).

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

'''Attention:''' for Audiweb there is no need to tag ads in video stream ... you may ignore this paragraph. If there are ads in your stream, but not tagged than simply do nothing while ad is playing.

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

'''Example Ad Object'''
<syntaxhighlight lang="javascript">//create ad object
var adMetadataObject =
{
assetid: "AD-1",
type: "preroll"
};</syntaxhighlight>

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

== Call Nielsen APIs ==
The method for calling events is <code>ggPM()</code>.
<syntaxhighlight lang="javascript">nSdkInstance.ggPM('event', parameter, ...);</syntaxhighlight>

=== Events ===
The events are included in the table below:
{| class="wikitable"
|-
! Event Number !! Values to pass !! Event Name || Description
|-
| <code>'3'</code> || content/ad metadata object || load content metadata || Load metadata event for content. Has to be called at the very first beginning of each stream.
|-
| <code>'5'</code> || playhead position || content play || Call when content or ads start playing or resumes from pause.
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'6'</code> || playhead position || pause || Call when content or ads is pausing. Use Event 5 to resume ...
'''VOD''' (or ad): The playhead position must be passed.
'''Live''': current unix timestamp (seconds since January 1st 1970).
|-
| <code>'7'</code> || playhead position || stop || Call when ads complete playing and at the very end of the stream. The playhead position must be passed when calling stop
|-
| <code>'8'</code> || playhead position from, playhead position to || seek || Call when scrubbing forward or backward with playhead position 'from' and 'to'
|-
| <code>'15'</code> || content/ad metadata object || load ad metadata || Call at the beginning of each ad, don’t use ‘play’ (event 5) if event 15 is used
|-
| <code>'49'</code> || playhead position || playhead position || '''VOD''': current position in seconds.
'''Live''': current unix timestamp (seconds since January 1st 1970).
Note: has to be called on a secondly basis.
For each ad the playheads starts with 0 (no Live unix timestamp for ads)
|-
| <code>'57'</code> || playhead position || end || 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.
|}

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

{{Examples|
without Ads|

<big>example '''without''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>

'''Note''': if there are ads played in stream simply use a pause (event 6) when ads start playing and a play (event 5) when content start playing.

|with Ads=
<big> example '''with''' ads:</big>

<syntaxhighlight lang="javascript">
// Start of stream
nSdkInstance.ggPM('3', contentMetadataObject); // must be called as start of stream (even if 1st asset is preroll)

// Preroll
nSdkInstance.ggPM('15', prerollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from 0 for the first segment (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition);

// Midroll
nSdkInstance.ggPM('15', midrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// Content
nSdkInstance.ggPM('5', contentPlayheadPosition);
nSdkInstance.ggPM('49', contentPlayheadPosition); // must be fired every second with playhead starting from where it left off before mid-roll (or with seconds since 1970-01-01 00:00:00 in case of livestream)
... /*** pass playheads every second ***/
nSdkInstance.ggPM('49', contentPlayheadPosition);
nSdkInstance.ggPM('6', contentPlayheadPosition); // pause is also needed for legacy reasons before event 57
nSdkInstance.ggPM('57', contentPlayheadPosition); // has to be called here at the end of the content only once

// Postroll
nSdkInstance.ggPM('15', postrollMetadataObject);
nSdkInstance.ggPM('49', individualAdPlayheadPosition); // must be fired every second with playhead starting from 0
... /*** pass playhead every second ***/
nSdkInstance.ggPM('49', individualAdPlayheadPosition);
nSdkInstance.ggPM('7', individualAdPlayheadPosition);

// End of Stream
nSdkInstance.ggPM('7', contentPlayheadPosition); // must be called as indicator for end-of-stream
</syntaxhighlight>
}}

'''Attention:''' for Italy there is no need to tag ads in video stream ... ignore 2nd example!

'''Note''': Event <code>'49'</code> 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 event <code>'7'</code>, <code>'57'</code>, or <code>'15'</code>.

'''Note''': when buffering occurs you have to send a event 6 (pause) and after buffering finished a 5 (play).

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

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

'''Handling Pause'''
The event <code>6</code> is used for handling pause. To indicate pause, stop passing the playhead position to the SDK and send Event 6 with playhead once. When content resumes, begin sending the playhead again with the correct playhead value. Also if buffering occurs for more than 1 second you may use Event 6 (pause) to indicate that.
e.g. pause at 1m2s and resume after a couple of seconds:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // now send nothing to SDK until player resumes (automatically because of buffering ends or user unpauses/resumes play
nSdkInstance.ggPM('5', 62); // play/5 when resume occurs (when user click play or buffering ends)
nSdkInstance.ggPM('49', 63);
nSdkInstance.ggPM('49', 64);
...
</syntaxhighlight>

'''Handling Seek'''
The event <code>8</code> is used for handling forward/backward seek. To indicate seek, send Event 8 with 'from' and 'to' playhead.
e.g. seek from 1m2s to 2m0s:
<syntaxhighlight lang="javascript">
...
nSdkInstance.ggPM('49', 61);
nSdkInstance.ggPM('49', 62);
nSdkInstance.ggPM('6', 62); // use pause, because buffering will occur (to be on safe side)
nSdkInstance.ggPM('8', 62,120);
nSdkInstance.ggPM('5', 120); // play/5 when resuming
nSdkInstance.ggPM('49', 120);
nSdkInstance.ggPM('49', 121);
...
</syntaxhighlight>

'''Interruption Scenarios'''
The following possible browser interruption scenarios must be handled:
* Browser/Tab close
* Leaving the page to another destination
* Pressing the stop button
There are many cases where the player itself has the ability to detect such situations. If not, these interruption scenarios can be handled through JavaScript. The events that are called will depend on the asset being played (e.g. midroll vs. content).
<syntaxhighlight lang="javascript">window.addEventListener('beforeunload', function(event)
{
// Only inside a midroll indicate 'stop' for the ad
if (insideMidroll) {
nSdkInstance.ggPM('7', playheadPosition);
}

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

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

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

The following paragraph is a template for an opt-out statement.

''The properties may feature Nielsen proprietary measurement software, which will allow users to contribute to market research, such as Nielsen TV Ratings. To learn more about the information that Nielsen software may collect and your choices with regard to it, please see the Nielsen Digital Measurement Privacy Policy at https://priv-policy.imrworldwide.com/priv/browser/it/it/optout.html.''

'''Opt Back In'''

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

== Going Live ==
Once the DCR Tracking Code is added to Instant Articles, Nielsen will validate the implementation. Following Nielsen testing, users need to make a couple of updates to the initialization call to ensure that the site is being measured properly.
# '''Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
#* '''Example Production Initialization Call''' - Refer to the production initialization call below:<syntaxhighlight lang="javascript">var nSdkInstance = NOLBUNDLE.nlsQ("P14273221-CF5C-46BF-A832-994AEFB73AA4","myPlayerName", {clientid: "it-123456", vcid: "c01"});</syntaxhighlight>

Template:Examples

2017-11-07T12:06:22Z

NielsSedat:

<div class="section-container auto" data-section>
{{#if: {{{1|}}} | <div class="section">
<p class="title" data-section-title>{{{1}}}</p>
<div class="content" data-section-content>
{{{2}}}
</div>
</div> | }}
{{#if: {{{without Ads|}}} | <div class="section">
<p class="title" data-section-title>without Ads</p>
<div class="content" data-section-content>
{{{without Ads}}}
</div>
</div> | }}
{{#if: {{{with Ads|}}} | <div class="section">
<p class="title" data-section-title>with Ads</p>
<div class="content" data-section-content>
{{{with Ads}}}
</div>
</div> | }}
</div>

Template:Examples

2017-11-07T11:42:38Z

NielsSedat:

<div class="section-container auto" data-section>
{{#if: {{{1|}}} | <div class="section">
<p class="title" data-section-title>{{{1}}}</p>
<div class="content" data-section-content>
{{{2}}}
</div>
</div> | }}
{{#if: {{{withoutAds|}}} | <div class="section">
<p class="title" data-section-title>without Ads</p>
<div class="content" data-section-content>
{{{withoutAds}}}
</div>
</div> | }}
{{#if: {{{withAds|}}} | <div class="section">
<p class="title" data-section-title>with Ads</p>
<div class="content" data-section-content>
{{{withAds}}}
</div>
</div> | }}
</div>

Template:Examples

2017-11-07T11:40:15Z

NielsSedat:

<div class="section-container auto" data-section>
{{#if: {{{1|}}} | <div class="section">
<p class="title" data-section-title>{{{1}}}</p>
<div class="content" data-section-content>
{{{2}}}
</div>
</div> | }}
{{#if: {{{withoutAds|}}} | <div class="section">
<p class="title" data-section-title>without Ads</p>
<div class="content" data-section-content>
{{{without Ads}}}
</div>
</div> | }}
{{#if: {{{withAds|}}} | <div class="section">
<p class="title" data-section-title>with Ads</p>
<div class="content" data-section-content>
{{{with Ads}}}
</div>
</div> | }}
</div>

Template:Examples

2017-11-07T11:38:18Z

NielsSedat:

<div class="section-container auto" data-section>
{{#if: {{{1|}}} | <div class="section">
<p class="title" data-section-title>{{{1}}}</p>
<div class="content" data-section-content>
{{{2}}}
</div>
</div> | }}
{{#if: {{{withoutAds|}}} | <div class="section">
<p class="title" data-section-title>without Ads</p>
<div class="content" data-section-content>
{{{withoutAds}}}
</div>
</div> | }}
{{#if: {{{withAds|}}} | <div class="section">
<p class="title" data-section-title>with Ads</p>
<div class="content" data-section-content>
{{{withAds}}}
</div>
</div> | }}
</div>

Template:Examples

2017-11-07T11:35:50Z

NielsSedat:

<div class="section-container auto" data-section>
{{#if: {{{1|}}} | <div class="section">
<p class="title" data-section-title>{{{1}}}</p>
<div class="content" data-section-content>
{{{2}}}
</div>
</div> | }}
{{#if: {{{withoutAds|}}} | <div class="section">
<p class="title" data-section-title>without Ads</p>
<div class="content" data-section-content>
{{{without Ads}}}
</div>
</div> | }}
{{#if: {{{withAds|}}} | <div class="section">
<p class="title" data-section-title>with Ads</p>
<div class="content" data-section-content>
{{{with Ads}}}
</div>
</div> | }}
</div>