Engineering Client Portal - User contributions [en]

DCR Denmark Video Android SDK

2021-10-28T11:53:53Z

ShangningWang: /* MetaData Example */

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

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

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

== Step 1: Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service CLasses and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

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

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

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("nol_devDebug", "DEBUG"); // only for debug builds

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("nol_devDebug", "DEBUG"); // only for debug builds

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

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

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

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

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

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

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

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

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

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

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

JSONObject contentMetadata = new JSONObject()
.put("assetid", "unique_content_id")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "length in seconds")
.put("airdate", "20200713 10:22:00")
.put("isfullepisode", "y")
.put("adloadtype", "2")
.put("subbrand", "c05")
.put("stationId", "TESTXXYYSSWWLL")
.put("islivestn", "y")
.put("pbstarttm", "1631098029");

JSONObject adMetadata = new JSONObject()
.put("assetid", "unique_postroll_ad_id")
.put("type", "postroll"
.put("subbrand", "c05")
.put("stationId", "TESTXXYYSSWWLL")
.put("islivestn", "y")
.put("pbstarttm", "1631098029");

</syntaxhighlight>

== Step 4: Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

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

<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

==== sendID3 ====
Needs to be called when ID3 Tags are included in the Video Stream.
<syntaxhighlight lang="Java">mAppSdk..sendID3(String id3);</syntaxhighlight>

<blockquote>
ID3 Tags are parsed from the Video Stream, refer to the DK Reference Implementation [http://nielsenonlinesupport.com/dk/index.htm sdkRefImplDK] on how to parse ID3 Tags included in a sample HLS Stream.
For further technical details, please contact your Technical Account Manager (TAM).
</blockquote>

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

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

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

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

== Step 5: Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

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

=== For Content Playback ===

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

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

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

In order to disclose Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://sites.nielsen.com/priv/browser/dk/da/DigitalMeasurement.html .

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

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

Download the Reference Implementation for Android [https://nielsenonlinesupport.com/dk/android/DKRefPLAYER.zip DKRefPLAYER].
Unzip and open the project in Android Studio, then run it i.e. in the simulator or on Android device and then filter the Logcat output with ">>>" in order to see only relevant Nielsen SDK API Calls, as below:

<syntaxhighlight lang="java">
2021-04-08 15:11:27.075 D/NielsenInit: ====>>> SDK CALL : class NielsenInit :: Create new AppSdk() Instance.
2021-04-08 15:11:27.568 D/NielsenInit: ====>>> SDK EVENT - onAppSdkEvent: Description = Nielsen App SDK is initiated. AppSdk.jar aa.8.0.0.0_gsxaon. App SDK was successfully initiatedCode l param : 1617887487Code i param 2000
2021-04-08 15:11:29.497 D/NielsenInit: ====>>> SDK EVENT - onAppSdkEvent: Description = Nielsen App SDK has started up. AppSdk.jar aa.8.0.0.0_gsxaon. Config file successfully loaded and parsed.Code l param : 1617887489Code i param 2001
2021-04-08 15:11:42.736 D/MainActivity: ====>>> SDK CALL : appSdk.play(sdkMethods.loadChannelInfo());
2021-04-08 15:11:42.738 D/MainActivity: ====>>> SDK CALL : onPrepared() : appSdk.loadMetadata(data)
2021-04-08 15:11:43.065 D/MainActivity: ====>>> Media Player Event : onInfo ();what = 3
2021-04-08 15:11:43.065 D/MainActivity: ====>>> Media Player Event : first video frame pushed for rendering.
2021-04-08 15:11:43.747 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 0 / 224
2021-04-08 15:11:44.752 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 1 / 224
2021-04-08 15:11:45.759 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 2 / 224
2021-04-08 15:11:46.764 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 3 / 224
2021-04-08 15:11:47.767 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 4 / 224
2021-04-08 15:11:48.772 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 5 / 224
2021-04-08 15:11:49.777 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 6 / 224
2021-04-08 15:11:50.781 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 7 / 224
2021-04-08 15:11:51.819 D/MainActivity: ====>>> SDK CALL : appSdk.setPlayheadPosition(mCurrentPosition): @ 8 / 224
2021-04-08 15:11:51.821 D/MainActivity: ====>>> Activity onPause()
2021-04-08 15:11:52.668 D/MainActivity: ====>>>: Activity onDestroy()
2021-04-08 15:11:52.668 D/MainActivity: ====>>> SDK CALL : terminateNielsenSDK () :appSdk.end();
</syntaxhighlight>

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

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

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

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

DCR Sweden Video Android SDK

2021-10-28T11:53:32Z

ShangningWang: /* MetaData Example */

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

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

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

== Implementation ==
The Nielsen Android SDK comes in three flavors.

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

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

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

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

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_unknown", "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8...");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_unknown", "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8...");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

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

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

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

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

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

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

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

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

<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

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

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");
//please see metadata link above for all content parameters

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");
//please see metadata link above for all ad parameters
</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

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

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

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

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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

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

== Handling Foreground and Background states ==
There are a few approaches to managing the Foreground and Background states of an app available to use for state measurement.

*Utilizing the Androidx LifeCycleObserver (The recommended approach starting sdk version 7.1.0.0+)
*Utilizing the SdkBgFgDetectionUtility class
*Adding a tag to the Manifest XML
*Manual Management
=== The LifeCycleObserver ===
AndroidX replaces the original support library APIs with packages in the androidx namespace, and Android Studio 3.2 and higher provides an automated migration tool. (Select '''Refactor> Migrate to AndroidX''' from the menu bar.)

Starting with version 7.1.0, with AndroidX support, an additional utility is provided in the AppSDK - application background/foreground state detection by the AppSdk leveraging the Android Architecture component "LifeCycleObserver".

The AppSdk is now capable of detecting the application UI visibility state transitions between background and foreground, without forcing the applications to register for AppSdk's AppSdkApplication class, which is responsible for handling the detection of application background/foreground state transitions at present.

<blockquote>Please note, that if you already have an app designed that utilizes the depreciated SdkBgFgDetectionUtility Class, the AppSDK will ignore any calls to these methods if it can utilize the LifeCycleObserver. LifeCycleObserver based auto detection will take precedence.</blockquote>

==== Adding the AndroidX dependency ====
In order to make use of the app background/foreground state transition auto detection feature of AndroidX AppSdk, the app gradle file needs the androidx dependency. The AppSdk API calls - <code>appInForeground()</code> and <code>appInBackground()</code> will still be respected by AppSdk by executing the old AppSdk flow of handling "app in foreground" and "app in background" states as is.

==== Using the LifeCycle Extension ====
The following androidx dependency is required in the app gradle file:

<syntaxhighlight lang="java">implementation "androidx.lifecycle:lifecycle-extensions:2.1.0"</syntaxhighlight>

<blockquote>If you would like to take advantage of this auto detection feature of AppSdk at the very initial stage (e.g. splash screen or at of app launch time), before the AppSdk is initialized, can do so by calling the following newly introduced AppSdk public api, passing the application context :

<syntaxhighlight lang="java">public static void registerLifeCycleObserver(Context applicationContext)</syntaxhighlight></blockquote>

==== Log messages for the new auto detection ====

*When the AppSdk app successfully registers for the LifeCycleObserver : <code>Registered LifeCycleObserver for App Background/Foreground auto-detection</code>
*When the app enters the foreground state :<code>App is in foreground, auto detected by AppSDK</code>
*When the app enters the background state :<code>App is in background, auto detected by AppSDK</code>
*If the client app doesn't have the "androidx" gradle dependency and AppSdk fails to register LifeCycleObserver :<code>AndroidX LifecycleObserver can not be observed. Please use androidx dependency to activate SDK auto-detection of app background/foreground state.</code>
*When the appInForeground() is explicitly called while LifeCycleObserver auto detection is active :<code>Ignoring the appInBackground() call, as the App Background/Foreground auto-detection is active. The current state is - foreground</code>
*When the appInBackground() is explicitly called while LifeCycleObserver auto detection is active :<code>Ignoring the appInBackground() call, as the App Background/Foreground auto-detection is active. The current state is - background</code>

=== The SdkBgFgDetectionUtility class ===
Foreground/Background state measurement is a requirement of Nielsen AppSDK implementation which is especially crucial for static measurement. It may be implemented in multiple ways for Android. This includes

*Enable the Nielsen SDK to measure background/foreground state by makingthe relevant update to the AndroidManifest.
*Integrate Nielsen’s SdkBgFgDetectionUtility class within your Custom Application Class.
*Custom implementation of the required methods within your application.

==== ForeGround/Background Measurement via AndroidManifest ====
The simplest way to measure the app background/foreground state is to add the following application tag to the Manifest XML. Integrating this into the Manifest XML will enable the SDK to measure app state directly. This approach is supported for Android 4.0 and up only; it requires that the application class is not in use for some other purpose.

<syntaxhighlight lang="java"> <application android:name="com.nielsen.app.sdk.AppSdkApplication"> </syntaxhighlight>

==== Using the Android SdkBgFbDetectionUtility Class ====
For developers who are already using the application class, it is recommended that background/foreground state is implemented using the [[Android Background Foreground|SdkBgFgDetectionUtility class.]] The [[Android Background Foreground|SdkBgFgDetectionUtility class.]] is compatible with Android 4+ and has been made available to Nielsen clients. (You will need to copy/paste the code provided into a file).

==== Manual Background/ForeGround State Management ====
In cases where the developer is not able to use the AndroidManifest.xml solution nor the Nielsen provided [[Android Background Foreground|SdkBgFgDetectionUtility class.]] the developer will need to manually identify the change of state through the application and call the respective API (appInForeground() or appInBackground()) to inform the SDK regarding the change of state from background to foreground or foreground to background.

The SDK is informed about app state using the below methods.

<syntaxhighlight lang="java">AppLaunchMeasurementManager.appInForeground(getApplicationContext());</syntaxhighlight>
<syntaxhighlight lang="java">AppLaunchMeasurementManager.appInBackground(getApplicationContext());</syntaxhighlight>
Within the lifecycle of individual activities, onResume() and onPause() are best suited to providing indication of the app state.

Correct measurement of the foreground/background state is crucial to Static App measurement within Nielsen Digital Content Ratings (DCR).

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

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

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

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device.
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the No Ad version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

==== Retrieve current Opt-Out preference ====
Whether the user is opted out via OS-level Opt-out or via App-level Opt-out, the current Opt-Out status as detected by the SDK is available via the [[getOptOutStatus()]] property in the Nielsen Android SDK API. <code>appSdk.getOptOutStatus()</code>

===Global OptOut Example ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the No Ad version or the No ID version.

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>
===No Ad Framework Optout Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the No ID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

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

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

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

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

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

Sweden SDK Metadata

2021-10-27T11:14:18Z

ShangningWang: /* Content Metadata */

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

= Digital Metadata =
Digital Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.
 
'''Section 1''' focuses on the content metadata
 
'''Section 2''' focuses on the Ad metadata.
 

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

== Content Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| userid || || the user login ID. Used by MMS reach model. ''The uploaded value needs to be hashed with SHA512''. This is the user login ID on player. We prefer a numeric value.|| "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa..." || required if login feature

|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. ||
For VoD use internal format. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters] 
For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 
A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler".
|| ✓ 
|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for VoD, video length
* for event-Live stream, the planned length. If planned length not available, then put default value 0
* for simulcast and 24/7 live stream, 86400
|| ✓
|-
| clientpassparam || MMS Values, mms_values || pass-through parameters || For clients that provide DAI (dynamic ad insertion) service, this has a standard format: origcode=channelnumber.
'''Example:''' origcode=29
See the complete list of channel reference library with the channel number on [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler". Please use string, JSON format is not accepted. 
Length limit: 250 characters. A longer string may be truncated due to URL length limitation.
|| required for clients that have DAI service (Telia, Telenor, Allente, Comhem, Boxer, Sappa, Discovery, Cmore)
|-
| program || Program Name, ns_st_pr || program name || '''custom''' '''example:''' leif-och-billy 
Leave blank for simulcast.
|| ✓
|-
| title || Episode Name, ns_st_ep || episode name || '''custom''' '''example:''' en-ny-tjej-i-byn 
Leave blank for simulcast.
|| ✓
|-
| playlisttitle || Title Playlist, ns_st_pl || playlist reference as a string || string value with playlist name for '''example:''' barn ||
|-
| ispremiumcontent || MMS Premium, mms_premium || identify premium level via yes or no || "yes" or "no" || ✓
|-
| isautoplay || Auto Start, mms_auto || identify if autoplay is enabled on the video || "yes" or "no" || ✓
|-
| plugv || Player Version, ns_st_mv || player version. increment by 1 for each new version. || alphanumeric '''example:''' 1.0.1 || ✓
|-
| playerv || Mediaplayer, ns_st_mp || player identifier || alphanumeric '''example:''' HTML5, JW Player, Sonic || ✓
|}

Example of metadata object for content:

<syntaxhighlight lang="javascript">
var contentMetadataObject = {
type: "content",
userid: "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa…",
assetid: "simulcast_29",
length: "3359",
clientpassparam: "origcode=29",
program: "leif-och-billy",
title: "en-ny-tjej-i-byn",
playlisttitle: "barn",
ispremiumcontent: "yes",
isautoplay: "yes",
plugv: "1.0.1",
playerv: "Sonic"
};
</syntaxhighlight>

== Ad Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || Ad Type, ns_st_ad || type of ad || "preroll", "midroll", "postroll", "ad" if specific ad type cannot be identified. || ✓
|-
| assetid || Film Code, mms_customadid || custom Ad ID || Film code/Copy code.
'''Custom examples''': S1MYME202B, 51TRER1001, H1KYLE3032, E1UMBR1001

In case of no Film Code is available, use the string "empty".

For programmatic ads that you are sending "programmatic" as Film Code today, use "programmatic_{current UTC time in epoch form}".
|| ✓
|-
| length || Clip Length, ns_st_cl || length of ad in seconds || Length of ad in seconds. || ✓
|-
| isprogrammatic || Programmatic, mms_programmatic || identify if the ad is bought prommatic. || "yes" or "no" ||
|-
| isthirdpartyad || MMS Thirdparty, mms_thirdparty || identify if the ad is from third party ad server || "yes" or "no" ||
|-
| adplatformorigin || MMS Origin, mms_origin || identify where an ad is originated. It is used when isprogrammatic=yes or isthirdpartyad=yes. || custom '''examples:''' Smartclip, YuMe
||
|-
| adidx || Position in Break, ns_st_an || placement in ad break. It is passed by ad servers. || Custom with the following format:
{ad placement}/{total number of ads in an ad break} 

'''Example:''' 2/5, the second ad in an ad break with 5 ads.
|| ✓
|}

Example of metadata object for Ad:

<syntaxhighlight lang="javascript">
var prerollMetadataObject = {
type: "preroll",
assetid: "E1UMBR1001",
length: "3359",
isprogrammatic: "yes",
isthirdpartyad: "yes",
adplatformorigin: "YuMe",
adidx: "1/5"
};
</syntaxhighlight>

DCR Sweden Video Cloud API

2021-10-19T15:13:18Z

ShangningWang: /* Configure Payload */

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

= DCR Integration Utilizing Cloud API =
This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.
__TOC__
==Prerequisites==
To get started, you will need a Nielsen App ID. The App ID is a unique ID assigned to your app. This will be provided to you by your assigned Technical Account Manager upon starting the integration.

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

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

====URL Structure====

The Cloud API Calls are HTTP GET Requests with the URL structure:

<syntaxhighlight lang="javascript">[endpoint]/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

The URL includes the following components:

*<code>[endpoint]</code>: location of data collection environment
*<code>[appid]</code>: provided App ID
*<code>[sessionID]</code>: unique value for each user session
*<code>[payload]</code>: metadata and events

====Endpoint====

There are endpoints for testing and production:

*Testing: <code>https://sc-eucert.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://capi-sw.imrworldwide.com/nmapi/v2/</code>

During testing, all calls should be pointed to the testing endpoint. We will review the update to the production endpoint during the Go Live section of this guide.

====URL Example====
As you move through the integration steps, you can reference the below URL structure with the expanded payload:

<syntaxhighlight lang="javascript">
https://sc-eucert.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms]
}
</syntaxhighlight>

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

====Create Session ID====

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

A Session ID needs to be completely unique so it is recommended to use a version 4 UUID or another method of your choosing to guarantee there are no repeats, also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference and use.

Upon exiting the app, the session will need to be terminated using the delete event. Sessions will automatically expire after 30 minutes of cloud inactivity.

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

===Create First Party ID===
* An First Party ID <code>[fpid]</code> must be created and stored on the device. It is re-used until the expiration date or if the user has deleted it from the device storage.
The default expiration date should be set to the equivalent of 180 days.
* Additionally the Creation Time <code>[fpcrtm]</code> of the First Party ID should be stored as well. The same value should be used as long as the First Party ID is available on the device.

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

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

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

===Configure Payload===

All Cloud API requests must contain the following payload data:

*''devInfo'': device and app info
*''metadata'': asset metadata
*''event metadata'': type of event

The payload can be passed through key-values using the Nielsen reserved keys. The specific keys and descriptions are highlighted in the tables included in this section.

'''Payload Example'''

The example below should be referenced when following the steps for configuring the request payload.

<syntaxhighlight lang="javascript">
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "First Party ID",
"fpcrtm": "Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)"
"hem_unknown" : "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..."
},

// 3.2 Configure Payload: metadata
"metadata": {
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "uniqueassetid_simulcast", // unique ID for video
"userid": "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa…", // SHA512 hashed userid
"clientpassparam": "origcode=29", // Custom parameters passed
"program": "Program Name leif-och-billy", // program name
"title": "Episode Title S3 - EP1 en-ny-tjej-i-byn", // episode name
"length": "3359", // content duration in seconds
"playlisttitle": "barn", //playlist title
"ispremiumcontent": "yes", //identify premium level content
"isautoplay": "yes", //identify if autoplay is enabled
"plugv": "1.0.1", //player version
"playerv": "Sonic" // player identifier
},
"ad": {
"type": "preroll", // type of ad
"assetid": "E1UMBR1001", // unique ID for ad
"length": "3359", // ad duration in seconds
"isprogrammatic": "yes",//identify if the ad is bought prommatic
"isthirdpartyad": "yes",//identify if the ad is from third party ad server
"adplatformorigin": "YuMe",//identity of ad origin
"adidx": "1/5" //placement in ad break
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}
</syntaxhighlight>

=====Configure Payload: devInfo=====
An object <code>"devInfo"</code> will need to be created to capture App and Device information.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| devId || unique ID to identify user (e.g. Advertising ID, Roku Device ID) || custom || ✓
|-
| apn || app name || custom || ✓
|-
| apv || app build version || custom || ✓
|-
|-
| uoo || device opt-out status || <code>"true"</code> or <code>"false"</code> || ✓
|-
|-
| hem_unknown || Hashed email using SHA512. Used by MMS reach model. (required if login feature) || custom || ✓
|-
|-style="background-color:#d0f6f8;"
| fpid || First Party ID || custom || ✓
|-style="background-color:#d0f6f8;"
| fpcrtm || Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds) || custom || ✓
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "First Party ID",
"fpcrtm": "Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)"
"hem_unknown" : "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..." //SHA512 hashed value
},
</syntaxhighlight>

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

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

===== Create Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.
 
'''Note:''' program and title metadata values should be passed to SDK as UTF-8 strings.

===== Example Content Object =====
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "uniqueassetid",
"length": "2600",
"program": "program name",
"title": "episode title"
}</syntaxhighlight>

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

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

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "unique_preroll_ad_id"
}
</syntaxhighlight>
 
<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== Configure Payload: Events ===

The last part of the payload is for enabling events so content is measured correctly when viewed. The events and required parameters are included below.

==== Event Types ====

The available events are:
{| class="wikitable"
|-
! Event !! Description
|-
| <code>"playhead"</code> ||

===== Handling Playhead =====

Calling <code>"playhead"</code> is critical for accurate duration crediting. You can reference the below guidance to determine the correct playhead position to pass depending on the playback scenario.

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

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

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

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

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

'''User Actions'''
* SCRUBBING: Upon user scrubbing, the current position must be sent before a user scrubs, and the new position should be sent where the user lands, and begin sending in the 10 second updates thereafter.
* PAUSE: When content is paused, send current playhead position and stop passing playhead position until content is resumed.
* EXIT Stream: If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

|-
| <code>"complete"</code> || The complete event must be sent when the content has completed full playback. Before calling the complete event, a final playhead update with the final position is required to be sent to receive full duration credit. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is optional and can be sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. All creditable duration will be summarized for all asset types when delete occurs (content and ads).
|}

===== Event Parameters =====

The following parameters need to be passed when calling events:

{| class="wikitable"
|-
! Parameter !! Description !! Value !! Required
|-
| <code>"event"</code> || event type || <code>"playhead"</code>, <code>"complete"</code>, or <code>"delete"</code> || ✓
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || ✓
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || ✓
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || ✓
|-style="background-color:#d0f6f8;"
| <code>"sessid"</code> || Unique View Session ID must be created upon start of each stream playback, sessid is unique per video play. || <code>"xxxjavd6wzirm93xb95uxjy1ac5wu1627638609"</code> || ✓
|}

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

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"metadata": {
"content": [content metadata],
"ad": [ad metadata]
},
// Event Parameters
"event": [event], // event name
"position": [playheadPosition], //position in seconds
"type": [asset type], // values are "content" or "ad"
"utc": "1472760000000" //unix timestamp in milliseconds
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}
</syntaxhighlight>

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

===== Sample Event Lifecycle for VoD Stream =====
The sample event lifecycle can be used as a reference for identifying the order for calling events and values to pass.

<syntaxhighlight lang="javascript">
// Start of Session: session ID created when App is opened

// Preroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472760000000"}

// Midroll
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content resumes at 15 minutes
Content Playhead {"event": "playhead", "position": "900", "type": "content", "utc": "1472760000000"}

// Content completes at 30 minutes
Complete {"event": "complete", "position": "1800", "type": "content", "utc": "1472760000000"}

// Postroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472760000000"}
</syntaxhighlight>

'''Sample Event Lifecycle for VoD Stream - Detailed Storyline'''
This detailed event sequence provides additional insight for the correct events to call when handling certain playback scenarios.
<syntaxhighlight lang='javascript'>// SESSION STARTS
// Start of Session: session ID created when App is opened

// PREROLL
// Preroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Preroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "15", "type": "ad", "utc": "1472761500000"}

// CONTENT
// Content Start - Start new content streams with a position of "0" incrementing the position every 10 seconds.
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472761500000"}

// Content Stop Before Ad Break - Send a playhead update including the current content positon before an Ad break.
Content Playhead {"event": "playhead", "position": "299", "type": "content", "utc": "1472787400000"}

// MIDROLL
// Midroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472787500000"}

// Midroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "60", "type": "ad", "utc": "1472793500000"}

// CONTENT
// Content resumes at 5 minutes - Send playhead update with the current resumed position, and begin incrimenting the positon every 10 seconds.
Content Playhead {"event": "playhead", "position": "300", "type": "content", "utc": "1472799500000"}

// Content completes at 10:12 - Make sure to send in the playhead event with the final content position before sending the complete event.
Final Content Playhead {"event": "playhead", "position": "612", "type": "content", "utc": "1472830700000"}

Complete {"event": "complete", "position": "612", "type": "content", "utc": "1472830800000"}

// POSTROLL
// Postroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472830900000"}

// Postroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "45", "type": "ad", "utc": "1472835300000"}

// SESSION ENDS

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472835400000"} </syntaxhighlight>

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

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

*Wi-Fi OFF / ON
*App going Background / Foreground (Video players only, not for Audio players)
*App Crash or Exit

When playback is interrupted, the app needs to send delete immediately.

Once playback resumes, a new session will need to be created with a unique session ID. All of the required metadata and events will need to be sent.

'''Note:''' The session will automatically timeout after 30 minutes of inactivity.

=== Example Request ===

Now that we walked through the Cloud API integration steps, your requests should have the following components: Session ID, App ID, and Payload. You can reference the example below when your reviewing your integration.

<syntaxhighlight lang="javascript">
// 1. Create Session ID
sessionID = dfc7dc6a-66a7-4705-9fba-adaaf7e3d5e0 // Example sessionID created using a UUID Generator

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

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000"
"hem_unknown" : "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..." //SHA512 hashed value
},

// 3.2 Configure Payload: metadata
"metadata": {
"type": "content", // "content" for video
"assetid": "uniqueassetid_simulcast", // unique ID for video
"userid": "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa…", // SHA512 hashed userid
"clientpassparam": "origcode=29", // Custom parameters passed
"program": "Program Name leif-och-billy", // program name
"title": "Episode Title S3 - EP1 en-ny-tjej-i-byn", // episode name
"length": "3359", // content duration in seconds
"playlisttitle": "barn", //playlist title
"ispremiumcontent": "yes", //identify premium level content
"isautoplay": "yes", //identify if autoplay is enabled
"plugv": "1.0.1", //player version
"playerv": "Sonic" // player identifier
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123", // unique ID for ad
"length": "3359", // ad duration in seconds
"isprogrammatic": "yes",//identify if the ad is bought prommatic
"isthirdpartyad": "yes",//identify if the ad is from third party ad server
"adplatformorigin": "YuMe",//identity of ad origin
"adidx": "1/5" //placement in ad break
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}

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

==== Enable Debug Logging ====

Now that you have set up the Cloud API requests, you can enable debug logging to validate your integration. Enabling debug logging is required for Nielsen certification.

==== GET Request ====

Display GET Request to console using a name to identify each event (e.g. playhead).

<syntaxhighlight lang="javascript">
console.log("Event", image);
</syntaxhighlight>

==== Payload ====

Output payload to identify required metadata and events.

<syntaxhighlight lang="javascript">
console.log("Event Payload", payload);
</syntaxhighlight>

==== HTTP Response Code ====

Confirm request was completed by viewing HTTP response code.

<syntaxhighlight lang="javascript">
code = msg.GetResponseCode();
console.log("Response Code", code);
</syntaxhighlight>

You can reference the HTTP Response Code table when reviewing your requests:

{| class="wikitable"
|-
! Status Code !! Status Text !! Description
|-
| <code>200</code> || OK || request received
|-
| <code>403</code> || Forbidden || invalid App ID
|-
| <code>404</code> || Not Found || JSON issue
|}

== Opt-Out ==
Your app must provide a means for the user to Opt-Out, or Opt-In to Nielsen Measurement. This requirement can be fulfilled by checking the device OS for the user's setting of "Limit Ad Tracking" or similar option. If the device offers "Limit Ad Tracking" settings, you should set <code>uoo=true</code> or <code>uoo=false</code> depending on the user's privacy setting. Also, ensure that the <code>devId</code> is set to a blank value if the user elects to opt-out.

If the device does not have OS-level "Do Not Track" settings, you can implement opt-out by creating an Opt-Out/Opt-In button, toggle switch, or slider within the app "Settings", or "About" section to allow the user selection.

[[File:Nielsen Opt-Out.png|link=]]

You will need to store the User Opt-Out (uoo) status, so that it can be retrieved and populated in the <code>"devInfo"</code> metadata which will be sent in every Cloud API event (playhead, complete, & delete).

{| class="wikitable"
|-
! uoo Key !! Description !! Values
|-
| uoo || Device is Opted-In to Nielsen Measurement (Recommended Default Setting) || <code>"false"</code>
|-
| uoo || Device is Opted-Out of Nielsen Measurement || <code>"true"</code>
|}

===== devInfo Opt-In JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "7be25cf9-8c40-5cc2-871e-19bf41940288",
"uoo": "false"
},
</syntaxhighlight>

===== devInfo Opt-Out JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "", //devId must be blank when a user elects to Opt-Out.
"uoo": "true"
},
</syntaxhighlight>

===== Privacy Information Template To Include In Opt-Out Screen =====

Additionally, all applications must display the Nielsen privacy policy within their application, typically in the Settings/About screen of your application. The Nielsen privacy policy text is listed below.

<blockquote>
'''''ABOUT NIELSEN MEASUREMENT'''''

Television and the way we watch it have come a long way since Nielsen began measuring TV audiences in 1950. Today, the ability to watch our favorite shows at any time and on multiple devices amplifies the need for exceptionally adept and flexible audience measurement capabilities.

Consumers are changing with the times, and the same goes for us. As technology continues to evolve and media companies try new ways to attract viewers, understanding what consumers are watching — and what they're watching on — is more important than ever. Today, viewing video is a personal and mobile experience — anytime and anywhere. Our capabilities provide relevant metrics that are necessary to inform successful marketing and programming and drive continued growth. As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process, and use. While our digital measurement products are not used to identify you in any way, they help us and our client's measure and analyze how consumers engage with media across online, mobile, and emerging technologies, and offer insights into consumer behavior.

'''''YOUR CHOICES'''''

Nielsen believes that you should have a choice about whether to contribute to our research and insights. To opt-out or opt into Nielsen measurement, please toggle your "Limit Ad Tracking" (or similar setting) on your device, or make the appropriate selection within the application's settings. If you have this app on more than one device, you will need to opt-out of this app on each device. To learn more about our digital measurement products and your choices in regard to them, please visit https://sites.nielsen.com/priv/browser/se/sv/optout.html

</blockquote>
'''''Disclosure Template'''''

Additionally, you must update the App description information from the App Distribution Store with the Nielsen Measurement disclosure below:

This app features Nielsen's proprietary measurement software which will allow you to contribute to market research, like Nielsen's TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information.

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

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

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

Start the Reference Implementation for Sweden [http://nielsenonlinesupport.com/michel/sdkRefImplCloudDK/index.htm RefImplCloudAPISE].
<blockquote>
Review the Nielsen CloudAPI Call Sequence below the Video Player.
</blockquote>

== Disclose Nielsen Privacy Statement ==

In order to disclose the Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third-party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://sites.nielsen.com/priv/browser/se/sv/optout.html .

== Testing ==
Before providing an app build to Nielsen for testing, it is important to run validation checks once you have enabled debug logging.

=== Payload Validation ===

Ensure that all of the required payload data is populating while testing several videos. The following areas are critical to measurement:
*devInfo
*Asset metadata for both content, and ads
*Events

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

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset for VoD stream and UTC Unix Time in seconds for Live stream.
*Final playhead position is sent on content, or ad before switching between assets.
*Content metadata remains constant throughout an episode or clip play.
*Ad metadata is populated appropriately for each individual ad.
*Playhead position update resumes for content after an ad break and resets to 0 for each individual ad.
*For scrubbing, last current position should be sent while scrubbing occurs, and the new position should also be sent where the user scrubs to.
*Exiting a stream early should execute the last current position in a playhead update to receive accurate duration.
*Upon pause, the current position should be sent, and playhead updates should stop incrementing until resume play occurs.

==== complete ====
*Check that the complete event executes upon content complete after the final playhead update is sent
*Do not execute the complete event for ads

==== delete ====
*Check to see that the delete event occurs upon app exit, if the platform has the necessary exit callback events.

==== GET Request Format ====
*Ensure that the event payloads are formatted in JSON
*Check to see that each of the Cloud API GET requests are properly encoded

==== HTTP Response ====
*Make sure that each of the Cloud API Get requests are received by the Nielsen Cloud API properly through use of the HTTP Response Code outputs enabled in console.

==== Opt-Out ====
*Test the "uoo" key gets populated accurately for both Opt-In and Opt-Out selections by validating the Cloud API events called after the user Opt-Out/Opt-In selection.
*Test that the devId field is populated with a blank value if a user has elected to Opt-Out. For example: "devId": "",
*If the device supports "Limit Ad Tracking" or has device "Opt-Out" settings, test that uoo=true, and that devId is set to a blank value if enabled in the device settings.

== Go Live ==
After your integration has been certified, you will need to: Change the Endpoint and Disable Logging.

'''Change Endpoint:''' You will need to update to the production endpoint:

*Testing: <code>https://sc-eucert.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://capi-sw.imrworldwide.com/nmapi/v2/</code>

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

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

DCR Sweden Video Cloud API

2021-10-19T15:12:49Z

ShangningWang: /* Example Request */

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

= DCR Integration Utilizing Cloud API =
This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.
__TOC__
==Prerequisites==
To get started, you will need a Nielsen App ID. The App ID is a unique ID assigned to your app. This will be provided to you by your assigned Technical Account Manager upon starting the integration.

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

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

====URL Structure====

The Cloud API Calls are HTTP GET Requests with the URL structure:

<syntaxhighlight lang="javascript">[endpoint]/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

The URL includes the following components:

*<code>[endpoint]</code>: location of data collection environment
*<code>[appid]</code>: provided App ID
*<code>[sessionID]</code>: unique value for each user session
*<code>[payload]</code>: metadata and events

====Endpoint====

There are endpoints for testing and production:

*Testing: <code>https://sc-eucert.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://capi-sw.imrworldwide.com/nmapi/v2/</code>

During testing, all calls should be pointed to the testing endpoint. We will review the update to the production endpoint during the Go Live section of this guide.

====URL Example====
As you move through the integration steps, you can reference the below URL structure with the expanded payload:

<syntaxhighlight lang="javascript">
https://sc-eucert.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms]
}
</syntaxhighlight>

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

====Create Session ID====

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

A Session ID needs to be completely unique so it is recommended to use a version 4 UUID or another method of your choosing to guarantee there are no repeats, also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference and use.

Upon exiting the app, the session will need to be terminated using the delete event. Sessions will automatically expire after 30 minutes of cloud inactivity.

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

===Create First Party ID===
* An First Party ID <code>[fpid]</code> must be created and stored on the device. It is re-used until the expiration date or if the user has deleted it from the device storage.
The default expiration date should be set to the equivalent of 180 days.
* Additionally the Creation Time <code>[fpcrtm]</code> of the First Party ID should be stored as well. The same value should be used as long as the First Party ID is available on the device.

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

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

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

===Configure Payload===

All Cloud API requests must contain the following payload data:

*''devInfo'': device and app info
*''metadata'': asset metadata
*''event metadata'': type of event

The payload can be passed through key-values using the Nielsen reserved keys. The specific keys and descriptions are highlighted in the tables included in this section.

'''Payload Example'''

The example below should be referenced when following the steps for configuring the request payload.

<syntaxhighlight lang="javascript">
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "First Party ID",
"fpcrtm": "Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)"
"hem_unknown" : "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..."
},

// 3.2 Configure Payload: metadata
"metadata": {
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "uniqueassetid_simulcast", // unique ID for video
"userid": "uniqueUserId_2b5a2541ec8241d2f535238104af3c85", // unique USER ID
"clientpassparam": "origcode=29", // Custom parameters passed
"program": "Program Name leif-och-billy", // program name
"title": "Episode Title S3 - EP1 en-ny-tjej-i-byn", // episode name
"length": "3359", // content duration in seconds
"playlisttitle": "barn", //playlist title
"ispremiumcontent": "yes", //identify premium level content
"isautoplay": "yes", //identify if autoplay is enabled
"plugv": "1.0.1", //player version
"playerv": "Sonic" // player identifier
},
"ad": {
"type": "preroll", // type of ad
"assetid": "E1UMBR1001", // unique ID for ad
"length": "3359", // ad duration in seconds
"isprogrammatic": "yes",//identify if the ad is bought prommatic
"isthirdpartyad": "yes",//identify if the ad is from third party ad server
"adplatformorigin": "YuMe",//identity of ad origin
"adidx": "1/5" //placement in ad break
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}
</syntaxhighlight>

=====Configure Payload: devInfo=====
An object <code>"devInfo"</code> will need to be created to capture App and Device information.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| devId || unique ID to identify user (e.g. Advertising ID, Roku Device ID) || custom || ✓
|-
| apn || app name || custom || ✓
|-
| apv || app build version || custom || ✓
|-
|-
| uoo || device opt-out status || <code>"true"</code> or <code>"false"</code> || ✓
|-
|-
| hem_unknown || Hashed email using SHA512. Used by MMS reach model. (required if login feature) || custom || ✓
|-
|-style="background-color:#d0f6f8;"
| fpid || First Party ID || custom || ✓
|-style="background-color:#d0f6f8;"
| fpcrtm || Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds) || custom || ✓
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "First Party ID",
"fpcrtm": "Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)"
"hem_unknown" : "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..." //SHA512 hashed value
},
</syntaxhighlight>

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

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

===== Create Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.
 
'''Note:''' program and title metadata values should be passed to SDK as UTF-8 strings.

===== Example Content Object =====
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "uniqueassetid",
"length": "2600",
"program": "program name",
"title": "episode title"
}</syntaxhighlight>

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

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

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "unique_preroll_ad_id"
}
</syntaxhighlight>
 
<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== Configure Payload: Events ===

The last part of the payload is for enabling events so content is measured correctly when viewed. The events and required parameters are included below.

==== Event Types ====

The available events are:
{| class="wikitable"
|-
! Event !! Description
|-
| <code>"playhead"</code> ||

===== Handling Playhead =====

Calling <code>"playhead"</code> is critical for accurate duration crediting. You can reference the below guidance to determine the correct playhead position to pass depending on the playback scenario.

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

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

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

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

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

'''User Actions'''
* SCRUBBING: Upon user scrubbing, the current position must be sent before a user scrubs, and the new position should be sent where the user lands, and begin sending in the 10 second updates thereafter.
* PAUSE: When content is paused, send current playhead position and stop passing playhead position until content is resumed.
* EXIT Stream: If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

|-
| <code>"complete"</code> || The complete event must be sent when the content has completed full playback. Before calling the complete event, a final playhead update with the final position is required to be sent to receive full duration credit. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is optional and can be sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. All creditable duration will be summarized for all asset types when delete occurs (content and ads).
|}

===== Event Parameters =====

The following parameters need to be passed when calling events:

{| class="wikitable"
|-
! Parameter !! Description !! Value !! Required
|-
| <code>"event"</code> || event type || <code>"playhead"</code>, <code>"complete"</code>, or <code>"delete"</code> || ✓
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || ✓
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || ✓
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || ✓
|-style="background-color:#d0f6f8;"
| <code>"sessid"</code> || Unique View Session ID must be created upon start of each stream playback, sessid is unique per video play. || <code>"xxxjavd6wzirm93xb95uxjy1ac5wu1627638609"</code> || ✓
|}

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

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"metadata": {
"content": [content metadata],
"ad": [ad metadata]
},
// Event Parameters
"event": [event], // event name
"position": [playheadPosition], //position in seconds
"type": [asset type], // values are "content" or "ad"
"utc": "1472760000000" //unix timestamp in milliseconds
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}
</syntaxhighlight>

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

===== Sample Event Lifecycle for VoD Stream =====
The sample event lifecycle can be used as a reference for identifying the order for calling events and values to pass.

<syntaxhighlight lang="javascript">
// Start of Session: session ID created when App is opened

// Preroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472760000000"}

// Midroll
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content resumes at 15 minutes
Content Playhead {"event": "playhead", "position": "900", "type": "content", "utc": "1472760000000"}

// Content completes at 30 minutes
Complete {"event": "complete", "position": "1800", "type": "content", "utc": "1472760000000"}

// Postroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472760000000"}
</syntaxhighlight>

'''Sample Event Lifecycle for VoD Stream - Detailed Storyline'''
This detailed event sequence provides additional insight for the correct events to call when handling certain playback scenarios.
<syntaxhighlight lang='javascript'>// SESSION STARTS
// Start of Session: session ID created when App is opened

// PREROLL
// Preroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Preroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "15", "type": "ad", "utc": "1472761500000"}

// CONTENT
// Content Start - Start new content streams with a position of "0" incrementing the position every 10 seconds.
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472761500000"}

// Content Stop Before Ad Break - Send a playhead update including the current content positon before an Ad break.
Content Playhead {"event": "playhead", "position": "299", "type": "content", "utc": "1472787400000"}

// MIDROLL
// Midroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472787500000"}

// Midroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "60", "type": "ad", "utc": "1472793500000"}

// CONTENT
// Content resumes at 5 minutes - Send playhead update with the current resumed position, and begin incrimenting the positon every 10 seconds.
Content Playhead {"event": "playhead", "position": "300", "type": "content", "utc": "1472799500000"}

// Content completes at 10:12 - Make sure to send in the playhead event with the final content position before sending the complete event.
Final Content Playhead {"event": "playhead", "position": "612", "type": "content", "utc": "1472830700000"}

Complete {"event": "complete", "position": "612", "type": "content", "utc": "1472830800000"}

// POSTROLL
// Postroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472830900000"}

// Postroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "45", "type": "ad", "utc": "1472835300000"}

// SESSION ENDS

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472835400000"} </syntaxhighlight>

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

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

*Wi-Fi OFF / ON
*App going Background / Foreground (Video players only, not for Audio players)
*App Crash or Exit

When playback is interrupted, the app needs to send delete immediately.

Once playback resumes, a new session will need to be created with a unique session ID. All of the required metadata and events will need to be sent.

'''Note:''' The session will automatically timeout after 30 minutes of inactivity.

=== Example Request ===

Now that we walked through the Cloud API integration steps, your requests should have the following components: Session ID, App ID, and Payload. You can reference the example below when your reviewing your integration.

<syntaxhighlight lang="javascript">
// 1. Create Session ID
sessionID = dfc7dc6a-66a7-4705-9fba-adaaf7e3d5e0 // Example sessionID created using a UUID Generator

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

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000"
"hem_unknown" : "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..." //SHA512 hashed value
},

// 3.2 Configure Payload: metadata
"metadata": {
"type": "content", // "content" for video
"assetid": "uniqueassetid_simulcast", // unique ID for video
"userid": "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa…", // SHA512 hashed userid
"clientpassparam": "origcode=29", // Custom parameters passed
"program": "Program Name leif-och-billy", // program name
"title": "Episode Title S3 - EP1 en-ny-tjej-i-byn", // episode name
"length": "3359", // content duration in seconds
"playlisttitle": "barn", //playlist title
"ispremiumcontent": "yes", //identify premium level content
"isautoplay": "yes", //identify if autoplay is enabled
"plugv": "1.0.1", //player version
"playerv": "Sonic" // player identifier
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123", // unique ID for ad
"length": "3359", // ad duration in seconds
"isprogrammatic": "yes",//identify if the ad is bought prommatic
"isthirdpartyad": "yes",//identify if the ad is from third party ad server
"adplatformorigin": "YuMe",//identity of ad origin
"adidx": "1/5" //placement in ad break
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}

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

==== Enable Debug Logging ====

Now that you have set up the Cloud API requests, you can enable debug logging to validate your integration. Enabling debug logging is required for Nielsen certification.

==== GET Request ====

Display GET Request to console using a name to identify each event (e.g. playhead).

<syntaxhighlight lang="javascript">
console.log("Event", image);
</syntaxhighlight>

==== Payload ====

Output payload to identify required metadata and events.

<syntaxhighlight lang="javascript">
console.log("Event Payload", payload);
</syntaxhighlight>

==== HTTP Response Code ====

Confirm request was completed by viewing HTTP response code.

<syntaxhighlight lang="javascript">
code = msg.GetResponseCode();
console.log("Response Code", code);
</syntaxhighlight>

You can reference the HTTP Response Code table when reviewing your requests:

{| class="wikitable"
|-
! Status Code !! Status Text !! Description
|-
| <code>200</code> || OK || request received
|-
| <code>403</code> || Forbidden || invalid App ID
|-
| <code>404</code> || Not Found || JSON issue
|}

== Opt-Out ==
Your app must provide a means for the user to Opt-Out, or Opt-In to Nielsen Measurement. This requirement can be fulfilled by checking the device OS for the user's setting of "Limit Ad Tracking" or similar option. If the device offers "Limit Ad Tracking" settings, you should set <code>uoo=true</code> or <code>uoo=false</code> depending on the user's privacy setting. Also, ensure that the <code>devId</code> is set to a blank value if the user elects to opt-out.

If the device does not have OS-level "Do Not Track" settings, you can implement opt-out by creating an Opt-Out/Opt-In button, toggle switch, or slider within the app "Settings", or "About" section to allow the user selection.

[[File:Nielsen Opt-Out.png|link=]]

You will need to store the User Opt-Out (uoo) status, so that it can be retrieved and populated in the <code>"devInfo"</code> metadata which will be sent in every Cloud API event (playhead, complete, & delete).

{| class="wikitable"
|-
! uoo Key !! Description !! Values
|-
| uoo || Device is Opted-In to Nielsen Measurement (Recommended Default Setting) || <code>"false"</code>
|-
| uoo || Device is Opted-Out of Nielsen Measurement || <code>"true"</code>
|}

===== devInfo Opt-In JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "7be25cf9-8c40-5cc2-871e-19bf41940288",
"uoo": "false"
},
</syntaxhighlight>

===== devInfo Opt-Out JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "", //devId must be blank when a user elects to Opt-Out.
"uoo": "true"
},
</syntaxhighlight>

===== Privacy Information Template To Include In Opt-Out Screen =====

Additionally, all applications must display the Nielsen privacy policy within their application, typically in the Settings/About screen of your application. The Nielsen privacy policy text is listed below.

<blockquote>
'''''ABOUT NIELSEN MEASUREMENT'''''

Television and the way we watch it have come a long way since Nielsen began measuring TV audiences in 1950. Today, the ability to watch our favorite shows at any time and on multiple devices amplifies the need for exceptionally adept and flexible audience measurement capabilities.

Consumers are changing with the times, and the same goes for us. As technology continues to evolve and media companies try new ways to attract viewers, understanding what consumers are watching — and what they're watching on — is more important than ever. Today, viewing video is a personal and mobile experience — anytime and anywhere. Our capabilities provide relevant metrics that are necessary to inform successful marketing and programming and drive continued growth. As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process, and use. While our digital measurement products are not used to identify you in any way, they help us and our client's measure and analyze how consumers engage with media across online, mobile, and emerging technologies, and offer insights into consumer behavior.

'''''YOUR CHOICES'''''

Nielsen believes that you should have a choice about whether to contribute to our research and insights. To opt-out or opt into Nielsen measurement, please toggle your "Limit Ad Tracking" (or similar setting) on your device, or make the appropriate selection within the application's settings. If you have this app on more than one device, you will need to opt-out of this app on each device. To learn more about our digital measurement products and your choices in regard to them, please visit https://sites.nielsen.com/priv/browser/se/sv/optout.html

</blockquote>
'''''Disclosure Template'''''

Additionally, you must update the App description information from the App Distribution Store with the Nielsen Measurement disclosure below:

This app features Nielsen's proprietary measurement software which will allow you to contribute to market research, like Nielsen's TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information.

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

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

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

Start the Reference Implementation for Sweden [http://nielsenonlinesupport.com/michel/sdkRefImplCloudDK/index.htm RefImplCloudAPISE].
<blockquote>
Review the Nielsen CloudAPI Call Sequence below the Video Player.
</blockquote>

== Disclose Nielsen Privacy Statement ==

In order to disclose the Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third-party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://sites.nielsen.com/priv/browser/se/sv/optout.html .

== Testing ==
Before providing an app build to Nielsen for testing, it is important to run validation checks once you have enabled debug logging.

=== Payload Validation ===

Ensure that all of the required payload data is populating while testing several videos. The following areas are critical to measurement:
*devInfo
*Asset metadata for both content, and ads
*Events

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

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset for VoD stream and UTC Unix Time in seconds for Live stream.
*Final playhead position is sent on content, or ad before switching between assets.
*Content metadata remains constant throughout an episode or clip play.
*Ad metadata is populated appropriately for each individual ad.
*Playhead position update resumes for content after an ad break and resets to 0 for each individual ad.
*For scrubbing, last current position should be sent while scrubbing occurs, and the new position should also be sent where the user scrubs to.
*Exiting a stream early should execute the last current position in a playhead update to receive accurate duration.
*Upon pause, the current position should be sent, and playhead updates should stop incrementing until resume play occurs.

==== complete ====
*Check that the complete event executes upon content complete after the final playhead update is sent
*Do not execute the complete event for ads

==== delete ====
*Check to see that the delete event occurs upon app exit, if the platform has the necessary exit callback events.

==== GET Request Format ====
*Ensure that the event payloads are formatted in JSON
*Check to see that each of the Cloud API GET requests are properly encoded

==== HTTP Response ====
*Make sure that each of the Cloud API Get requests are received by the Nielsen Cloud API properly through use of the HTTP Response Code outputs enabled in console.

==== Opt-Out ====
*Test the "uoo" key gets populated accurately for both Opt-In and Opt-Out selections by validating the Cloud API events called after the user Opt-Out/Opt-In selection.
*Test that the devId field is populated with a blank value if a user has elected to Opt-Out. For example: "devId": "",
*If the device supports "Limit Ad Tracking" or has device "Opt-Out" settings, test that uoo=true, and that devId is set to a blank value if enabled in the device settings.

== Go Live ==
After your integration has been certified, you will need to: Change the Endpoint and Disable Logging.

'''Change Endpoint:''' You will need to update to the production endpoint:

*Testing: <code>https://sc-eucert.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://capi-sw.imrworldwide.com/nmapi/v2/</code>

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

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

Sweden SDK Metadata

2021-10-19T15:11:45Z

ShangningWang: /* Content Metadata */

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

= Digital Metadata =
Digital Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.
 
'''Section 1''' focuses on the content metadata
 
'''Section 2''' focuses on the Ad metadata.
 

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

== Content Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| userid || || the user login ID. Used by MMS reach model. ''The uploaded value needs to be hashed with SHA512''. This is the user login ID on player. We prefer a numeric value but email will work just fine.|| "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa..." || required if login feature

|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. ||
For VoD use internal format. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters] 
For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 
A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler".
|| ✓ 
|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for VoD, video length
* for event-Live stream, the planned length. If planned length not available, then put default value 0
* for simulcast and 24/7 live stream, 86400
|| ✓
|-
| clientpassparam || MMS Values, mms_values || pass-through parameters || For clients that provide DAI (dynamic ad insertion) service, this has a standard format: origcode=channelnumber.
'''Example:''' origcode=29
See the complete list of channel reference library with the channel number on [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler". Please use string, JSON format is not accepted. 
Length limit: 250 characters. A longer string may be truncated due to URL length limitation.
|| required for clients that have DAI service (Telia, Telenor, Allente, Comhem, Boxer, Sappa, Discovery, Cmore)
|-
| program || Program Name, ns_st_pr || program name || '''custom''' '''example:''' leif-och-billy 
Leave blank for simulcast.
|| ✓
|-
| title || Episode Name, ns_st_ep || episode name || '''custom''' '''example:''' en-ny-tjej-i-byn 
Leave blank for simulcast.
|| ✓
|-
| playlisttitle || Title Playlist, ns_st_pl || playlist reference as a string || string value with playlist name for '''example:''' barn ||
|-
| ispremiumcontent || MMS Premium, mms_premium || identify premium level via yes or no || "yes" or "no" || ✓
|-
| isautoplay || Auto Start, mms_auto || identify if autoplay is enabled on the video || "yes" or "no" || ✓
|-
| plugv || Player Version, ns_st_mv || player version. increment by 1 for each new version. || alphanumeric '''example:''' 1.0.1 || ✓
|-
| playerv || Mediaplayer, ns_st_mp || player identifier || alphanumeric '''example:''' HTML5, JW Player, Sonic || ✓
|}

Example of metadata object for content:

<syntaxhighlight lang="javascript">
var contentMetadataObject = {
type: "content",
userid: "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa…",
assetid: "simulcast_29",
length: "3359",
clientpassparam: "origcode=29",
program: "leif-och-billy",
title: "en-ny-tjej-i-byn",
playlisttitle: "barn",
ispremiumcontent: "yes",
isautoplay: "yes",
plugv: "1.0.1",
playerv: "Sonic"
};
</syntaxhighlight>

== Ad Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || Ad Type, ns_st_ad || type of ad || "preroll", "midroll", "postroll", "ad" if specific ad type cannot be identified. || ✓
|-
| assetid || Film Code, mms_customadid || custom Ad ID || Film code/Copy code.
'''Custom examples''': S1MYME202B, 51TRER1001, H1KYLE3032, E1UMBR1001

In case of no Film Code is available, use the string "empty".

For programmatic ads that you are sending "programmatic" as Film Code today, use "programmatic_{current UTC time in epoch form}".
|| ✓
|-
| length || Clip Length, ns_st_cl || length of ad in seconds || Length of ad in seconds. || ✓
|-
| isprogrammatic || Programmatic, mms_programmatic || identify if the ad is bought prommatic. || "yes" or "no" ||
|-
| isthirdpartyad || MMS Thirdparty, mms_thirdparty || identify if the ad is from third party ad server || "yes" or "no" ||
|-
| adplatformorigin || MMS Origin, mms_origin || identify where an ad is originated. It is used when isprogrammatic=yes or isthirdpartyad=yes. || custom '''examples:''' Smartclip, YuMe
||
|-
| adidx || Position in Break, ns_st_an || placement in ad break. It is passed by ad servers. || Custom with the following format:
{ad placement}/{total number of ads in an ad break} 

'''Example:''' 2/5, the second ad in an ad break with 5 ads.
|| ✓
|}

Example of metadata object for Ad:

<syntaxhighlight lang="javascript">
var prerollMetadataObject = {
type: "preroll",
assetid: "E1UMBR1001",
length: "3359",
isprogrammatic: "yes",
isthirdpartyad: "yes",
adplatformorigin: "YuMe",
adidx: "1/5"
};
</syntaxhighlight>

Sweden SDK Metadata

2021-10-19T15:11:06Z

ShangningWang: /* Content Metadata */

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

= Digital Metadata =
Digital Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.
 
'''Section 1''' focuses on the content metadata
 
'''Section 2''' focuses on the Ad metadata.
 

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

== Content Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| userid || || the user login ID. Used by MMS reach model. ''The uploaded value needs to be hashed with SHA512''. This is the user login ID on player. We prefer a numeric value but email will work just fine.|| "fbd1a7a7d672a5fcf5cf5c55d8d9d0abbe3a4e0fa..." || required if login feature

|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. ||
For VoD use internal format. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters] 
For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 
A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler".
|| ✓ 
|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for VoD, video length
* for event-Live stream, the planned length. If planned length not available, then put default value 0
* for simulcast and 24/7 live stream, 86400
|| ✓
|-
| clientpassparam || MMS Values, mms_values || pass-through parameters || For clients that provide DAI (dynamic ad insertion) service, this has a standard format: origcode=channelnumber.
'''Example:''' origcode=29
See the complete list of channel reference library with the channel number on [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler". Please use string, JSON format is not accepted. 
Length limit: 250 characters. A longer string may be truncated due to URL length limitation.
|| required for clients that have DAI service (Telia, Telenor, Allente, Comhem, Boxer, Sappa, Discovery, Cmore)
|-
| program || Program Name, ns_st_pr || program name || '''custom''' '''example:''' leif-och-billy 
Leave blank for simulcast.
|| ✓
|-
| title || Episode Name, ns_st_ep || episode name || '''custom''' '''example:''' en-ny-tjej-i-byn 
Leave blank for simulcast.
|| ✓
|-
| playlisttitle || Title Playlist, ns_st_pl || playlist reference as a string || string value with playlist name for '''example:''' barn ||
|-
| ispremiumcontent || MMS Premium, mms_premium || identify premium level via yes or no || "yes" or "no" || ✓
|-
| isautoplay || Auto Start, mms_auto || identify if autoplay is enabled on the video || "yes" or "no" || ✓
|-
| plugv || Player Version, ns_st_mv || player version. increment by 1 for each new version. || alphanumeric '''example:''' 1.0.1 || ✓
|-
| playerv || Mediaplayer, ns_st_mp || player identifier || alphanumeric '''example:''' HTML5, JW Player, Sonic || ✓
|}

Example of metadata object for content:

<syntaxhighlight lang="javascript">
var contentMetadataObject = {
type: "content",
userid: "2b5a2541ec8241d2f535238104af3c85",
assetid: "simulcast_29",
length: "3359",
clientpassparam: "origcode=29",
program: "leif-och-billy",
title: "en-ny-tjej-i-byn",
playlisttitle: "barn",
ispremiumcontent: "yes",
isautoplay: "yes",
plugv: "1.0.1",
playerv: "Sonic"
};
</syntaxhighlight>

== Ad Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || Ad Type, ns_st_ad || type of ad || "preroll", "midroll", "postroll", "ad" if specific ad type cannot be identified. || ✓
|-
| assetid || Film Code, mms_customadid || custom Ad ID || Film code/Copy code.
'''Custom examples''': S1MYME202B, 51TRER1001, H1KYLE3032, E1UMBR1001

In case of no Film Code is available, use the string "empty".

For programmatic ads that you are sending "programmatic" as Film Code today, use "programmatic_{current UTC time in epoch form}".
|| ✓
|-
| length || Clip Length, ns_st_cl || length of ad in seconds || Length of ad in seconds. || ✓
|-
| isprogrammatic || Programmatic, mms_programmatic || identify if the ad is bought prommatic. || "yes" or "no" ||
|-
| isthirdpartyad || MMS Thirdparty, mms_thirdparty || identify if the ad is from third party ad server || "yes" or "no" ||
|-
| adplatformorigin || MMS Origin, mms_origin || identify where an ad is originated. It is used when isprogrammatic=yes or isthirdpartyad=yes. || custom '''examples:''' Smartclip, YuMe
||
|-
| adidx || Position in Break, ns_st_an || placement in ad break. It is passed by ad servers. || Custom with the following format:
{ad placement}/{total number of ads in an ad break} 

'''Example:''' 2/5, the second ad in an ad break with 5 ads.
|| ✓
|}

Example of metadata object for Ad:

<syntaxhighlight lang="javascript">
var prerollMetadataObject = {
type: "preroll",
assetid: "E1UMBR1001",
length: "3359",
isprogrammatic: "yes",
isthirdpartyad: "yes",
adplatformorigin: "YuMe",
adidx: "1/5"
};
</syntaxhighlight>

DCR Sweden Video Cloud API

2021-10-19T15:09:54Z

ShangningWang: /* Example Request */

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

= DCR Integration Utilizing Cloud API =
This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.
__TOC__
==Prerequisites==
To get started, you will need a Nielsen App ID. The App ID is a unique ID assigned to your app. This will be provided to you by your assigned Technical Account Manager upon starting the integration.

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

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

====URL Structure====

The Cloud API Calls are HTTP GET Requests with the URL structure:

<syntaxhighlight lang="javascript">[endpoint]/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

The URL includes the following components:

*<code>[endpoint]</code>: location of data collection environment
*<code>[appid]</code>: provided App ID
*<code>[sessionID]</code>: unique value for each user session
*<code>[payload]</code>: metadata and events

====Endpoint====

There are endpoints for testing and production:

*Testing: <code>https://sc-eucert.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://capi-sw.imrworldwide.com/nmapi/v2/</code>

During testing, all calls should be pointed to the testing endpoint. We will review the update to the production endpoint during the Go Live section of this guide.

====URL Example====
As you move through the integration steps, you can reference the below URL structure with the expanded payload:

<syntaxhighlight lang="javascript">
https://sc-eucert.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms]
}
</syntaxhighlight>

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

====Create Session ID====

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

A Session ID needs to be completely unique so it is recommended to use a version 4 UUID or another method of your choosing to guarantee there are no repeats, also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference and use.

Upon exiting the app, the session will need to be terminated using the delete event. Sessions will automatically expire after 30 minutes of cloud inactivity.

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

===Create First Party ID===
* An First Party ID <code>[fpid]</code> must be created and stored on the device. It is re-used until the expiration date or if the user has deleted it from the device storage.
The default expiration date should be set to the equivalent of 180 days.
* Additionally the Creation Time <code>[fpcrtm]</code> of the First Party ID should be stored as well. The same value should be used as long as the First Party ID is available on the device.

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

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

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

===Configure Payload===

All Cloud API requests must contain the following payload data:

*''devInfo'': device and app info
*''metadata'': asset metadata
*''event metadata'': type of event

The payload can be passed through key-values using the Nielsen reserved keys. The specific keys and descriptions are highlighted in the tables included in this section.

'''Payload Example'''

The example below should be referenced when following the steps for configuring the request payload.

<syntaxhighlight lang="javascript">
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "First Party ID",
"fpcrtm": "Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)"
"hem_unknown" : "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..."
},

// 3.2 Configure Payload: metadata
"metadata": {
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "uniqueassetid_simulcast", // unique ID for video
"userid": "uniqueUserId_2b5a2541ec8241d2f535238104af3c85", // unique USER ID
"clientpassparam": "origcode=29", // Custom parameters passed
"program": "Program Name leif-och-billy", // program name
"title": "Episode Title S3 - EP1 en-ny-tjej-i-byn", // episode name
"length": "3359", // content duration in seconds
"playlisttitle": "barn", //playlist title
"ispremiumcontent": "yes", //identify premium level content
"isautoplay": "yes", //identify if autoplay is enabled
"plugv": "1.0.1", //player version
"playerv": "Sonic" // player identifier
},
"ad": {
"type": "preroll", // type of ad
"assetid": "E1UMBR1001", // unique ID for ad
"length": "3359", // ad duration in seconds
"isprogrammatic": "yes",//identify if the ad is bought prommatic
"isthirdpartyad": "yes",//identify if the ad is from third party ad server
"adplatformorigin": "YuMe",//identity of ad origin
"adidx": "1/5" //placement in ad break
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}
</syntaxhighlight>

=====Configure Payload: devInfo=====
An object <code>"devInfo"</code> will need to be created to capture App and Device information.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| devId || unique ID to identify user (e.g. Advertising ID, Roku Device ID) || custom || ✓
|-
| apn || app name || custom || ✓
|-
| apv || app build version || custom || ✓
|-
|-
| uoo || device opt-out status || <code>"true"</code> or <code>"false"</code> || ✓
|-
|-
| hem_unknown || Hashed email using SHA512. Used by MMS reach model. (required if login feature) || custom || ✓
|-
|-style="background-color:#d0f6f8;"
| fpid || First Party ID || custom || ✓
|-style="background-color:#d0f6f8;"
| fpcrtm || Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds) || custom || ✓
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "First Party ID",
"fpcrtm": "Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)"
"hem_unknown" : "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..." //SHA512 hashed value
},
</syntaxhighlight>

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

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

===== Create Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.
 
'''Note:''' program and title metadata values should be passed to SDK as UTF-8 strings.

===== Example Content Object =====
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "uniqueassetid",
"length": "2600",
"program": "program name",
"title": "episode title"
}</syntaxhighlight>

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

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

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "unique_preroll_ad_id"
}
</syntaxhighlight>
 
<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== Configure Payload: Events ===

The last part of the payload is for enabling events so content is measured correctly when viewed. The events and required parameters are included below.

==== Event Types ====

The available events are:
{| class="wikitable"
|-
! Event !! Description
|-
| <code>"playhead"</code> ||

===== Handling Playhead =====

Calling <code>"playhead"</code> is critical for accurate duration crediting. You can reference the below guidance to determine the correct playhead position to pass depending on the playback scenario.

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

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

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

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

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

'''User Actions'''
* SCRUBBING: Upon user scrubbing, the current position must be sent before a user scrubs, and the new position should be sent where the user lands, and begin sending in the 10 second updates thereafter.
* PAUSE: When content is paused, send current playhead position and stop passing playhead position until content is resumed.
* EXIT Stream: If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

|-
| <code>"complete"</code> || The complete event must be sent when the content has completed full playback. Before calling the complete event, a final playhead update with the final position is required to be sent to receive full duration credit. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is optional and can be sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. All creditable duration will be summarized for all asset types when delete occurs (content and ads).
|}

===== Event Parameters =====

The following parameters need to be passed when calling events:

{| class="wikitable"
|-
! Parameter !! Description !! Value !! Required
|-
| <code>"event"</code> || event type || <code>"playhead"</code>, <code>"complete"</code>, or <code>"delete"</code> || ✓
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || ✓
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || ✓
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || ✓
|-style="background-color:#d0f6f8;"
| <code>"sessid"</code> || Unique View Session ID must be created upon start of each stream playback, sessid is unique per video play. || <code>"xxxjavd6wzirm93xb95uxjy1ac5wu1627638609"</code> || ✓
|}

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

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"metadata": {
"content": [content metadata],
"ad": [ad metadata]
},
// Event Parameters
"event": [event], // event name
"position": [playheadPosition], //position in seconds
"type": [asset type], // values are "content" or "ad"
"utc": "1472760000000" //unix timestamp in milliseconds
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}
</syntaxhighlight>

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

===== Sample Event Lifecycle for VoD Stream =====
The sample event lifecycle can be used as a reference for identifying the order for calling events and values to pass.

<syntaxhighlight lang="javascript">
// Start of Session: session ID created when App is opened

// Preroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472760000000"}

// Midroll
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content resumes at 15 minutes
Content Playhead {"event": "playhead", "position": "900", "type": "content", "utc": "1472760000000"}

// Content completes at 30 minutes
Complete {"event": "complete", "position": "1800", "type": "content", "utc": "1472760000000"}

// Postroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472760000000"}
</syntaxhighlight>

'''Sample Event Lifecycle for VoD Stream - Detailed Storyline'''
This detailed event sequence provides additional insight for the correct events to call when handling certain playback scenarios.
<syntaxhighlight lang='javascript'>// SESSION STARTS
// Start of Session: session ID created when App is opened

// PREROLL
// Preroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Preroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "15", "type": "ad", "utc": "1472761500000"}

// CONTENT
// Content Start - Start new content streams with a position of "0" incrementing the position every 10 seconds.
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472761500000"}

// Content Stop Before Ad Break - Send a playhead update including the current content positon before an Ad break.
Content Playhead {"event": "playhead", "position": "299", "type": "content", "utc": "1472787400000"}

// MIDROLL
// Midroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472787500000"}

// Midroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "60", "type": "ad", "utc": "1472793500000"}

// CONTENT
// Content resumes at 5 minutes - Send playhead update with the current resumed position, and begin incrimenting the positon every 10 seconds.
Content Playhead {"event": "playhead", "position": "300", "type": "content", "utc": "1472799500000"}

// Content completes at 10:12 - Make sure to send in the playhead event with the final content position before sending the complete event.
Final Content Playhead {"event": "playhead", "position": "612", "type": "content", "utc": "1472830700000"}

Complete {"event": "complete", "position": "612", "type": "content", "utc": "1472830800000"}

// POSTROLL
// Postroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472830900000"}

// Postroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "45", "type": "ad", "utc": "1472835300000"}

// SESSION ENDS

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472835400000"} </syntaxhighlight>

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

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

*Wi-Fi OFF / ON
*App going Background / Foreground (Video players only, not for Audio players)
*App Crash or Exit

When playback is interrupted, the app needs to send delete immediately.

Once playback resumes, a new session will need to be created with a unique session ID. All of the required metadata and events will need to be sent.

'''Note:''' The session will automatically timeout after 30 minutes of inactivity.

=== Example Request ===

Now that we walked through the Cloud API integration steps, your requests should have the following components: Session ID, App ID, and Payload. You can reference the example below when your reviewing your integration.

<syntaxhighlight lang="javascript">
// 1. Create Session ID
sessionID = dfc7dc6a-66a7-4705-9fba-adaaf7e3d5e0 // Example sessionID created using a UUID Generator

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

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000"
"hem_unknown" : "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..." //SHA512 hashed value
},

// 3.2 Configure Payload: metadata
"metadata": {
"type": "content", // "content" for video
"assetid": "uniqueassetid_simulcast", // unique ID for video
"userid": "uniqueUserId_2b5a2541ec8241d2f535238104af3c85", // SHA512 hashed userid
"clientpassparam": "origcode=29", // Custom parameters passed
"program": "Program Name leif-och-billy", // program name
"title": "Episode Title S3 - EP1 en-ny-tjej-i-byn", // episode name
"length": "3359", // content duration in seconds
"playlisttitle": "barn", //playlist title
"ispremiumcontent": "yes", //identify premium level content
"isautoplay": "yes", //identify if autoplay is enabled
"plugv": "1.0.1", //player version
"playerv": "Sonic" // player identifier
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123", // unique ID for ad
"length": "3359", // ad duration in seconds
"isprogrammatic": "yes",//identify if the ad is bought prommatic
"isthirdpartyad": "yes",//identify if the ad is from third party ad server
"adplatformorigin": "YuMe",//identity of ad origin
"adidx": "1/5" //placement in ad break
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}

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

==== Enable Debug Logging ====

Now that you have set up the Cloud API requests, you can enable debug logging to validate your integration. Enabling debug logging is required for Nielsen certification.

==== GET Request ====

Display GET Request to console using a name to identify each event (e.g. playhead).

<syntaxhighlight lang="javascript">
console.log("Event", image);
</syntaxhighlight>

==== Payload ====

Output payload to identify required metadata and events.

<syntaxhighlight lang="javascript">
console.log("Event Payload", payload);
</syntaxhighlight>

==== HTTP Response Code ====

Confirm request was completed by viewing HTTP response code.

<syntaxhighlight lang="javascript">
code = msg.GetResponseCode();
console.log("Response Code", code);
</syntaxhighlight>

You can reference the HTTP Response Code table when reviewing your requests:

{| class="wikitable"
|-
! Status Code !! Status Text !! Description
|-
| <code>200</code> || OK || request received
|-
| <code>403</code> || Forbidden || invalid App ID
|-
| <code>404</code> || Not Found || JSON issue
|}

== Opt-Out ==
Your app must provide a means for the user to Opt-Out, or Opt-In to Nielsen Measurement. This requirement can be fulfilled by checking the device OS for the user's setting of "Limit Ad Tracking" or similar option. If the device offers "Limit Ad Tracking" settings, you should set <code>uoo=true</code> or <code>uoo=false</code> depending on the user's privacy setting. Also, ensure that the <code>devId</code> is set to a blank value if the user elects to opt-out.

If the device does not have OS-level "Do Not Track" settings, you can implement opt-out by creating an Opt-Out/Opt-In button, toggle switch, or slider within the app "Settings", or "About" section to allow the user selection.

[[File:Nielsen Opt-Out.png|link=]]

You will need to store the User Opt-Out (uoo) status, so that it can be retrieved and populated in the <code>"devInfo"</code> metadata which will be sent in every Cloud API event (playhead, complete, & delete).

{| class="wikitable"
|-
! uoo Key !! Description !! Values
|-
| uoo || Device is Opted-In to Nielsen Measurement (Recommended Default Setting) || <code>"false"</code>
|-
| uoo || Device is Opted-Out of Nielsen Measurement || <code>"true"</code>
|}

===== devInfo Opt-In JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "7be25cf9-8c40-5cc2-871e-19bf41940288",
"uoo": "false"
},
</syntaxhighlight>

===== devInfo Opt-Out JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "", //devId must be blank when a user elects to Opt-Out.
"uoo": "true"
},
</syntaxhighlight>

===== Privacy Information Template To Include In Opt-Out Screen =====

Additionally, all applications must display the Nielsen privacy policy within their application, typically in the Settings/About screen of your application. The Nielsen privacy policy text is listed below.

<blockquote>
'''''ABOUT NIELSEN MEASUREMENT'''''

Television and the way we watch it have come a long way since Nielsen began measuring TV audiences in 1950. Today, the ability to watch our favorite shows at any time and on multiple devices amplifies the need for exceptionally adept and flexible audience measurement capabilities.

Consumers are changing with the times, and the same goes for us. As technology continues to evolve and media companies try new ways to attract viewers, understanding what consumers are watching — and what they're watching on — is more important than ever. Today, viewing video is a personal and mobile experience — anytime and anywhere. Our capabilities provide relevant metrics that are necessary to inform successful marketing and programming and drive continued growth. As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process, and use. While our digital measurement products are not used to identify you in any way, they help us and our client's measure and analyze how consumers engage with media across online, mobile, and emerging technologies, and offer insights into consumer behavior.

'''''YOUR CHOICES'''''

Nielsen believes that you should have a choice about whether to contribute to our research and insights. To opt-out or opt into Nielsen measurement, please toggle your "Limit Ad Tracking" (or similar setting) on your device, or make the appropriate selection within the application's settings. If you have this app on more than one device, you will need to opt-out of this app on each device. To learn more about our digital measurement products and your choices in regard to them, please visit https://sites.nielsen.com/priv/browser/se/sv/optout.html

</blockquote>
'''''Disclosure Template'''''

Additionally, you must update the App description information from the App Distribution Store with the Nielsen Measurement disclosure below:

This app features Nielsen's proprietary measurement software which will allow you to contribute to market research, like Nielsen's TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information.

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

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

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

Start the Reference Implementation for Sweden [http://nielsenonlinesupport.com/michel/sdkRefImplCloudDK/index.htm RefImplCloudAPISE].
<blockquote>
Review the Nielsen CloudAPI Call Sequence below the Video Player.
</blockquote>

== Disclose Nielsen Privacy Statement ==

In order to disclose the Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third-party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://sites.nielsen.com/priv/browser/se/sv/optout.html .

== Testing ==
Before providing an app build to Nielsen for testing, it is important to run validation checks once you have enabled debug logging.

=== Payload Validation ===

Ensure that all of the required payload data is populating while testing several videos. The following areas are critical to measurement:
*devInfo
*Asset metadata for both content, and ads
*Events

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

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset for VoD stream and UTC Unix Time in seconds for Live stream.
*Final playhead position is sent on content, or ad before switching between assets.
*Content metadata remains constant throughout an episode or clip play.
*Ad metadata is populated appropriately for each individual ad.
*Playhead position update resumes for content after an ad break and resets to 0 for each individual ad.
*For scrubbing, last current position should be sent while scrubbing occurs, and the new position should also be sent where the user scrubs to.
*Exiting a stream early should execute the last current position in a playhead update to receive accurate duration.
*Upon pause, the current position should be sent, and playhead updates should stop incrementing until resume play occurs.

==== complete ====
*Check that the complete event executes upon content complete after the final playhead update is sent
*Do not execute the complete event for ads

==== delete ====
*Check to see that the delete event occurs upon app exit, if the platform has the necessary exit callback events.

==== GET Request Format ====
*Ensure that the event payloads are formatted in JSON
*Check to see that each of the Cloud API GET requests are properly encoded

==== HTTP Response ====
*Make sure that each of the Cloud API Get requests are received by the Nielsen Cloud API properly through use of the HTTP Response Code outputs enabled in console.

==== Opt-Out ====
*Test the "uoo" key gets populated accurately for both Opt-In and Opt-Out selections by validating the Cloud API events called after the user Opt-Out/Opt-In selection.
*Test that the devId field is populated with a blank value if a user has elected to Opt-Out. For example: "devId": "",
*If the device supports "Limit Ad Tracking" or has device "Opt-Out" settings, test that uoo=true, and that devId is set to a blank value if enabled in the device settings.

== Go Live ==
After your integration has been certified, you will need to: Change the Endpoint and Disable Logging.

'''Change Endpoint:''' You will need to update to the production endpoint:

*Testing: <code>https://sc-eucert.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://capi-sw.imrworldwide.com/nmapi/v2/</code>

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

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

DCR Sweden Video Cloud API

2021-10-19T15:09:32Z

ShangningWang: /* Configure Payload */

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

= DCR Integration Utilizing Cloud API =
This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.
__TOC__
==Prerequisites==
To get started, you will need a Nielsen App ID. The App ID is a unique ID assigned to your app. This will be provided to you by your assigned Technical Account Manager upon starting the integration.

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

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

====URL Structure====

The Cloud API Calls are HTTP GET Requests with the URL structure:

<syntaxhighlight lang="javascript">[endpoint]/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

The URL includes the following components:

*<code>[endpoint]</code>: location of data collection environment
*<code>[appid]</code>: provided App ID
*<code>[sessionID]</code>: unique value for each user session
*<code>[payload]</code>: metadata and events

====Endpoint====

There are endpoints for testing and production:

*Testing: <code>https://sc-eucert.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://capi-sw.imrworldwide.com/nmapi/v2/</code>

During testing, all calls should be pointed to the testing endpoint. We will review the update to the production endpoint during the Go Live section of this guide.

====URL Example====
As you move through the integration steps, you can reference the below URL structure with the expanded payload:

<syntaxhighlight lang="javascript">
https://sc-eucert.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms]
}
</syntaxhighlight>

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

====Create Session ID====

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

A Session ID needs to be completely unique so it is recommended to use a version 4 UUID or another method of your choosing to guarantee there are no repeats, also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference and use.

Upon exiting the app, the session will need to be terminated using the delete event. Sessions will automatically expire after 30 minutes of cloud inactivity.

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

===Create First Party ID===
* An First Party ID <code>[fpid]</code> must be created and stored on the device. It is re-used until the expiration date or if the user has deleted it from the device storage.
The default expiration date should be set to the equivalent of 180 days.
* Additionally the Creation Time <code>[fpcrtm]</code> of the First Party ID should be stored as well. The same value should be used as long as the First Party ID is available on the device.

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

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

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

===Configure Payload===

All Cloud API requests must contain the following payload data:

*''devInfo'': device and app info
*''metadata'': asset metadata
*''event metadata'': type of event

The payload can be passed through key-values using the Nielsen reserved keys. The specific keys and descriptions are highlighted in the tables included in this section.

'''Payload Example'''

The example below should be referenced when following the steps for configuring the request payload.

<syntaxhighlight lang="javascript">
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "First Party ID",
"fpcrtm": "Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)"
"hem_unknown" : "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..."
},

// 3.2 Configure Payload: metadata
"metadata": {
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "uniqueassetid_simulcast", // unique ID for video
"userid": "uniqueUserId_2b5a2541ec8241d2f535238104af3c85", // unique USER ID
"clientpassparam": "origcode=29", // Custom parameters passed
"program": "Program Name leif-och-billy", // program name
"title": "Episode Title S3 - EP1 en-ny-tjej-i-byn", // episode name
"length": "3359", // content duration in seconds
"playlisttitle": "barn", //playlist title
"ispremiumcontent": "yes", //identify premium level content
"isautoplay": "yes", //identify if autoplay is enabled
"plugv": "1.0.1", //player version
"playerv": "Sonic" // player identifier
},
"ad": {
"type": "preroll", // type of ad
"assetid": "E1UMBR1001", // unique ID for ad
"length": "3359", // ad duration in seconds
"isprogrammatic": "yes",//identify if the ad is bought prommatic
"isthirdpartyad": "yes",//identify if the ad is from third party ad server
"adplatformorigin": "YuMe",//identity of ad origin
"adidx": "1/5" //placement in ad break
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}
</syntaxhighlight>

=====Configure Payload: devInfo=====
An object <code>"devInfo"</code> will need to be created to capture App and Device information.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| devId || unique ID to identify user (e.g. Advertising ID, Roku Device ID) || custom || ✓
|-
| apn || app name || custom || ✓
|-
| apv || app build version || custom || ✓
|-
|-
| uoo || device opt-out status || <code>"true"</code> or <code>"false"</code> || ✓
|-
|-
| hem_unknown || Hashed email using SHA512. Used by MMS reach model. (required if login feature) || custom || ✓
|-
|-style="background-color:#d0f6f8;"
| fpid || First Party ID || custom || ✓
|-style="background-color:#d0f6f8;"
| fpcrtm || Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds) || custom || ✓
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "First Party ID",
"fpcrtm": "Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)"
"hem_unknown" : "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8..." //SHA512 hashed value
},
</syntaxhighlight>

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

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

===== Create Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.
 
'''Note:''' program and title metadata values should be passed to SDK as UTF-8 strings.

===== Example Content Object =====
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "uniqueassetid",
"length": "2600",
"program": "program name",
"title": "episode title"
}</syntaxhighlight>

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

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

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "unique_preroll_ad_id"
}
</syntaxhighlight>
 
<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== Configure Payload: Events ===

The last part of the payload is for enabling events so content is measured correctly when viewed. The events and required parameters are included below.

==== Event Types ====

The available events are:
{| class="wikitable"
|-
! Event !! Description
|-
| <code>"playhead"</code> ||

===== Handling Playhead =====

Calling <code>"playhead"</code> is critical for accurate duration crediting. You can reference the below guidance to determine the correct playhead position to pass depending on the playback scenario.

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

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

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

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

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

'''User Actions'''
* SCRUBBING: Upon user scrubbing, the current position must be sent before a user scrubs, and the new position should be sent where the user lands, and begin sending in the 10 second updates thereafter.
* PAUSE: When content is paused, send current playhead position and stop passing playhead position until content is resumed.
* EXIT Stream: If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

|-
| <code>"complete"</code> || The complete event must be sent when the content has completed full playback. Before calling the complete event, a final playhead update with the final position is required to be sent to receive full duration credit. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is optional and can be sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. All creditable duration will be summarized for all asset types when delete occurs (content and ads).
|}

===== Event Parameters =====

The following parameters need to be passed when calling events:

{| class="wikitable"
|-
! Parameter !! Description !! Value !! Required
|-
| <code>"event"</code> || event type || <code>"playhead"</code>, <code>"complete"</code>, or <code>"delete"</code> || ✓
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || ✓
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || ✓
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || ✓
|-style="background-color:#d0f6f8;"
| <code>"sessid"</code> || Unique View Session ID must be created upon start of each stream playback, sessid is unique per video play. || <code>"xxxjavd6wzirm93xb95uxjy1ac5wu1627638609"</code> || ✓
|}

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

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"metadata": {
"content": [content metadata],
"ad": [ad metadata]
},
// Event Parameters
"event": [event], // event name
"position": [playheadPosition], //position in seconds
"type": [asset type], // values are "content" or "ad"
"utc": "1472760000000" //unix timestamp in milliseconds
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}
</syntaxhighlight>

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

===== Sample Event Lifecycle for VoD Stream =====
The sample event lifecycle can be used as a reference for identifying the order for calling events and values to pass.

<syntaxhighlight lang="javascript">
// Start of Session: session ID created when App is opened

// Preroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472760000000"}

// Midroll
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content resumes at 15 minutes
Content Playhead {"event": "playhead", "position": "900", "type": "content", "utc": "1472760000000"}

// Content completes at 30 minutes
Complete {"event": "complete", "position": "1800", "type": "content", "utc": "1472760000000"}

// Postroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472760000000"}
</syntaxhighlight>

'''Sample Event Lifecycle for VoD Stream - Detailed Storyline'''
This detailed event sequence provides additional insight for the correct events to call when handling certain playback scenarios.
<syntaxhighlight lang='javascript'>// SESSION STARTS
// Start of Session: session ID created when App is opened

// PREROLL
// Preroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Preroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "15", "type": "ad", "utc": "1472761500000"}

// CONTENT
// Content Start - Start new content streams with a position of "0" incrementing the position every 10 seconds.
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472761500000"}

// Content Stop Before Ad Break - Send a playhead update including the current content positon before an Ad break.
Content Playhead {"event": "playhead", "position": "299", "type": "content", "utc": "1472787400000"}

// MIDROLL
// Midroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472787500000"}

// Midroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "60", "type": "ad", "utc": "1472793500000"}

// CONTENT
// Content resumes at 5 minutes - Send playhead update with the current resumed position, and begin incrimenting the positon every 10 seconds.
Content Playhead {"event": "playhead", "position": "300", "type": "content", "utc": "1472799500000"}

// Content completes at 10:12 - Make sure to send in the playhead event with the final content position before sending the complete event.
Final Content Playhead {"event": "playhead", "position": "612", "type": "content", "utc": "1472830700000"}

Complete {"event": "complete", "position": "612", "type": "content", "utc": "1472830800000"}

// POSTROLL
// Postroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472830900000"}

// Postroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "45", "type": "ad", "utc": "1472835300000"}

// SESSION ENDS

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472835400000"} </syntaxhighlight>

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

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

*Wi-Fi OFF / ON
*App going Background / Foreground (Video players only, not for Audio players)
*App Crash or Exit

When playback is interrupted, the app needs to send delete immediately.

Once playback resumes, a new session will need to be created with a unique session ID. All of the required metadata and events will need to be sent.

'''Note:''' The session will automatically timeout after 30 minutes of inactivity.

=== Example Request ===

Now that we walked through the Cloud API integration steps, your requests should have the following components: Session ID, App ID, and Payload. You can reference the example below when your reviewing your integration.

<syntaxhighlight lang="javascript">
// 1. Create Session ID
sessionID = dfc7dc6a-66a7-4705-9fba-adaaf7e3d5e0 // Example sessionID created using a UUID Generator

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

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000"
"hem_unknown" : "61f1121944dfb76f09540c59a99b4000" //SHA512 hashed value
},

// 3.2 Configure Payload: metadata
"metadata": {
"type": "content", // "content" for video
"assetid": "uniqueassetid_simulcast", // unique ID for video
"userid": "uniqueUserId_2b5a2541ec8241d2f535238104af3c85", // SHA512 hashed userid
"clientpassparam": "origcode=29", // Custom parameters passed
"program": "Program Name leif-och-billy", // program name
"title": "Episode Title S3 - EP1 en-ny-tjej-i-byn", // episode name
"length": "3359", // content duration in seconds
"playlisttitle": "barn", //playlist title
"ispremiumcontent": "yes", //identify premium level content
"isautoplay": "yes", //identify if autoplay is enabled
"plugv": "1.0.1", //player version
"playerv": "Sonic" // player identifier
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123", // unique ID for ad
"length": "3359", // ad duration in seconds
"isprogrammatic": "yes",//identify if the ad is bought prommatic
"isthirdpartyad": "yes",//identify if the ad is from third party ad server
"adplatformorigin": "YuMe",//identity of ad origin
"adidx": "1/5" //placement in ad break
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}

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

==== Enable Debug Logging ====

Now that you have set up the Cloud API requests, you can enable debug logging to validate your integration. Enabling debug logging is required for Nielsen certification.

==== GET Request ====

Display GET Request to console using a name to identify each event (e.g. playhead).

<syntaxhighlight lang="javascript">
console.log("Event", image);
</syntaxhighlight>

==== Payload ====

Output payload to identify required metadata and events.

<syntaxhighlight lang="javascript">
console.log("Event Payload", payload);
</syntaxhighlight>

==== HTTP Response Code ====

Confirm request was completed by viewing HTTP response code.

<syntaxhighlight lang="javascript">
code = msg.GetResponseCode();
console.log("Response Code", code);
</syntaxhighlight>

You can reference the HTTP Response Code table when reviewing your requests:

{| class="wikitable"
|-
! Status Code !! Status Text !! Description
|-
| <code>200</code> || OK || request received
|-
| <code>403</code> || Forbidden || invalid App ID
|-
| <code>404</code> || Not Found || JSON issue
|}

== Opt-Out ==
Your app must provide a means for the user to Opt-Out, or Opt-In to Nielsen Measurement. This requirement can be fulfilled by checking the device OS for the user's setting of "Limit Ad Tracking" or similar option. If the device offers "Limit Ad Tracking" settings, you should set <code>uoo=true</code> or <code>uoo=false</code> depending on the user's privacy setting. Also, ensure that the <code>devId</code> is set to a blank value if the user elects to opt-out.

If the device does not have OS-level "Do Not Track" settings, you can implement opt-out by creating an Opt-Out/Opt-In button, toggle switch, or slider within the app "Settings", or "About" section to allow the user selection.

[[File:Nielsen Opt-Out.png|link=]]

You will need to store the User Opt-Out (uoo) status, so that it can be retrieved and populated in the <code>"devInfo"</code> metadata which will be sent in every Cloud API event (playhead, complete, & delete).

{| class="wikitable"
|-
! uoo Key !! Description !! Values
|-
| uoo || Device is Opted-In to Nielsen Measurement (Recommended Default Setting) || <code>"false"</code>
|-
| uoo || Device is Opted-Out of Nielsen Measurement || <code>"true"</code>
|}

===== devInfo Opt-In JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "7be25cf9-8c40-5cc2-871e-19bf41940288",
"uoo": "false"
},
</syntaxhighlight>

===== devInfo Opt-Out JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "", //devId must be blank when a user elects to Opt-Out.
"uoo": "true"
},
</syntaxhighlight>

===== Privacy Information Template To Include In Opt-Out Screen =====

Additionally, all applications must display the Nielsen privacy policy within their application, typically in the Settings/About screen of your application. The Nielsen privacy policy text is listed below.

<blockquote>
'''''ABOUT NIELSEN MEASUREMENT'''''

Television and the way we watch it have come a long way since Nielsen began measuring TV audiences in 1950. Today, the ability to watch our favorite shows at any time and on multiple devices amplifies the need for exceptionally adept and flexible audience measurement capabilities.

Consumers are changing with the times, and the same goes for us. As technology continues to evolve and media companies try new ways to attract viewers, understanding what consumers are watching — and what they're watching on — is more important than ever. Today, viewing video is a personal and mobile experience — anytime and anywhere. Our capabilities provide relevant metrics that are necessary to inform successful marketing and programming and drive continued growth. As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process, and use. While our digital measurement products are not used to identify you in any way, they help us and our client's measure and analyze how consumers engage with media across online, mobile, and emerging technologies, and offer insights into consumer behavior.

'''''YOUR CHOICES'''''

Nielsen believes that you should have a choice about whether to contribute to our research and insights. To opt-out or opt into Nielsen measurement, please toggle your "Limit Ad Tracking" (or similar setting) on your device, or make the appropriate selection within the application's settings. If you have this app on more than one device, you will need to opt-out of this app on each device. To learn more about our digital measurement products and your choices in regard to them, please visit https://sites.nielsen.com/priv/browser/se/sv/optout.html

</blockquote>
'''''Disclosure Template'''''

Additionally, you must update the App description information from the App Distribution Store with the Nielsen Measurement disclosure below:

This app features Nielsen's proprietary measurement software which will allow you to contribute to market research, like Nielsen's TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information.

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

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

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

Start the Reference Implementation for Sweden [http://nielsenonlinesupport.com/michel/sdkRefImplCloudDK/index.htm RefImplCloudAPISE].
<blockquote>
Review the Nielsen CloudAPI Call Sequence below the Video Player.
</blockquote>

== Disclose Nielsen Privacy Statement ==

In order to disclose the Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third-party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://sites.nielsen.com/priv/browser/se/sv/optout.html .

== Testing ==
Before providing an app build to Nielsen for testing, it is important to run validation checks once you have enabled debug logging.

=== Payload Validation ===

Ensure that all of the required payload data is populating while testing several videos. The following areas are critical to measurement:
*devInfo
*Asset metadata for both content, and ads
*Events

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

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset for VoD stream and UTC Unix Time in seconds for Live stream.
*Final playhead position is sent on content, or ad before switching between assets.
*Content metadata remains constant throughout an episode or clip play.
*Ad metadata is populated appropriately for each individual ad.
*Playhead position update resumes for content after an ad break and resets to 0 for each individual ad.
*For scrubbing, last current position should be sent while scrubbing occurs, and the new position should also be sent where the user scrubs to.
*Exiting a stream early should execute the last current position in a playhead update to receive accurate duration.
*Upon pause, the current position should be sent, and playhead updates should stop incrementing until resume play occurs.

==== complete ====
*Check that the complete event executes upon content complete after the final playhead update is sent
*Do not execute the complete event for ads

==== delete ====
*Check to see that the delete event occurs upon app exit, if the platform has the necessary exit callback events.

==== GET Request Format ====
*Ensure that the event payloads are formatted in JSON
*Check to see that each of the Cloud API GET requests are properly encoded

==== HTTP Response ====
*Make sure that each of the Cloud API Get requests are received by the Nielsen Cloud API properly through use of the HTTP Response Code outputs enabled in console.

==== Opt-Out ====
*Test the "uoo" key gets populated accurately for both Opt-In and Opt-Out selections by validating the Cloud API events called after the user Opt-Out/Opt-In selection.
*Test that the devId field is populated with a blank value if a user has elected to Opt-Out. For example: "devId": "",
*If the device supports "Limit Ad Tracking" or has device "Opt-Out" settings, test that uoo=true, and that devId is set to a blank value if enabled in the device settings.

== Go Live ==
After your integration has been certified, you will need to: Change the Endpoint and Disable Logging.

'''Change Endpoint:''' You will need to update to the production endpoint:

*Testing: <code>https://sc-eucert.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://capi-sw.imrworldwide.com/nmapi/v2/</code>

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

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

DCR Sweden Video Android SDK

2021-10-19T15:09:05Z

ShangningWang: /* Create SDK Instance */

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

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

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

== Implementation ==
The Nielsen Android SDK comes in three flavors.

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

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

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

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

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_unknown", "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8...");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_unknown", "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8...");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

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

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

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

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

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

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

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

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

<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");
//please see metadata link above for all content parameters

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");
//please see metadata link above for all ad parameters
</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

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

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

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

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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

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

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

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

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

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device.
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the No Ad version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

==== Retrieve current Opt-Out preference ====
Whether the user is opted out via OS-level Opt-out or via App-level Opt-out, the current Opt-Out status as detected by the SDK is available via the [[getOptOutStatus()]] property in the Nielsen Android SDK API. <code>appSdk.getOptOutStatus()</code>

===Global OptOut Example ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the No Ad version or the No ID version.

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>
===No Ad Framework Optout Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the No ID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

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

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

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

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

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

DCR Sweden Video Android SDK

2021-10-19T15:08:37Z

ShangningWang: /* Create SDK Instance */

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

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

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

== Implementation ==
The Nielsen Android SDK comes in three flavors.

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

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

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

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

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_unknown", "924899b875ea6767ab790bd2f4852345fcfec5d203c49be8e8...");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_unknown", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

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

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

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

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

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

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

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

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

<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");
//please see metadata link above for all content parameters

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");
//please see metadata link above for all ad parameters
</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

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

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

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

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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

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

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

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

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

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device.
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the No Ad version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

==== Retrieve current Opt-Out preference ====
Whether the user is opted out via OS-level Opt-out or via App-level Opt-out, the current Opt-Out status as detected by the SDK is available via the [[getOptOutStatus()]] property in the Nielsen Android SDK API. <code>appSdk.getOptOutStatus()</code>

===Global OptOut Example ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the No Ad version or the No ID version.

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>
===No Ad Framework Optout Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the No ID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

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

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

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

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

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

DCR Sweden Video iOS SDK

2021-10-19T15:07:58Z

ShangningWang: /* Create SDK Instance */

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

__TOC__

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

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

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

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

== Setting up your iOS Development Environment ==

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

=== Importing Frameworks ===

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

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

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

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

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

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

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

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

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

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

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

@implementation NlsAppApiFactory

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

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

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

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

@end
</syntaxhighlight>

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

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

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

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

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

override func viewDidLoad() {
super.viewDidLoad()

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

}
}
</syntaxhighlight>

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

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

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

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

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

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

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

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

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

<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== MetaData Example ===

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

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

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

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

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

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

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

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

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

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

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

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

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[playheadPosition|playheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelName); </code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad_123",
...
}</syntaxhighlight>
<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[playheadPosition|playheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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

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

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third-party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

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

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

== Privacy and Opt-Out ==

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

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

In addition, the following text must be included in your app store description.
<blockquote>"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information"</blockquote>

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

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

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

override func viewDidLoad() {
super.viewDidLoad()

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

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

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

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

@interface OptOutVC ()

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

@implementation OptOutVC

- (void)viewDidLoad {
[super viewDidLoad];

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

</syntaxhighlight>

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

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

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

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

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

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

override func viewDidLoad() {
super.viewDidLoad()

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

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

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

}

</syntaxhighlight>

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

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

@interface OptOutVC ()

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

@implementation OptOutVC

- (void)viewDidLoad {
[super viewDidLoad];

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

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

</syntaxhighlight>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

DCR Sweden Video Browser SDK

2021-10-19T15:07:27Z

ShangningWang: /* Sample SDK Initialization Call */

DCR Sweden Video Browser SDK

2021-10-19T15:07:14Z

ShangningWang: /* Initialization API Call */

DCR Sweden Video Cloud API

2021-10-19T15:05:22Z

ShangningWang: /* Example Request */

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

= DCR Integration Utilizing Cloud API =
This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.
__TOC__
==Prerequisites==
To get started, you will need a Nielsen App ID. The App ID is a unique ID assigned to your app. This will be provided to you by your assigned Technical Account Manager upon starting the integration.

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

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

====URL Structure====

The Cloud API Calls are HTTP GET Requests with the URL structure:

<syntaxhighlight lang="javascript">[endpoint]/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

The URL includes the following components:

*<code>[endpoint]</code>: location of data collection environment
*<code>[appid]</code>: provided App ID
*<code>[sessionID]</code>: unique value for each user session
*<code>[payload]</code>: metadata and events

====Endpoint====

There are endpoints for testing and production:

*Testing: <code>https://sc-eucert.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://capi-sw.imrworldwide.com/nmapi/v2/</code>

During testing, all calls should be pointed to the testing endpoint. We will review the update to the production endpoint during the Go Live section of this guide.

====URL Example====
As you move through the integration steps, you can reference the below URL structure with the expanded payload:

<syntaxhighlight lang="javascript">
https://sc-eucert.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms]
}
</syntaxhighlight>

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

====Create Session ID====

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

A Session ID needs to be completely unique so it is recommended to use a version 4 UUID or another method of your choosing to guarantee there are no repeats, also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference and use.

Upon exiting the app, the session will need to be terminated using the delete event. Sessions will automatically expire after 30 minutes of cloud inactivity.

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

===Create First Party ID===
* An First Party ID <code>[fpid]</code> must be created and stored on the device. It is re-used until the expiration date or if the user has deleted it from the device storage.
The default expiration date should be set to the equivalent of 180 days.
* Additionally the Creation Time <code>[fpcrtm]</code> of the First Party ID should be stored as well. The same value should be used as long as the First Party ID is available on the device.

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

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

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

===Configure Payload===

All Cloud API requests must contain the following payload data:

*''devInfo'': device and app info
*''metadata'': asset metadata
*''event metadata'': type of event

The payload can be passed through key-values using the Nielsen reserved keys. The specific keys and descriptions are highlighted in the tables included in this section.

'''Payload Example'''

The example below should be referenced when following the steps for configuring the request payload.

<syntaxhighlight lang="javascript">
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "First Party ID",
"fpcrtm": "Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)"
"hem_unknown" : "61f1121944dfb76f09540c59a99b4000"
},

// 3.2 Configure Payload: metadata
"metadata": {
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "uniqueassetid_simulcast", // unique ID for video
"userid": "uniqueUserId_2b5a2541ec8241d2f535238104af3c85", // unique USER ID
"clientpassparam": "origcode=29", // Custom parameters passed
"program": "Program Name leif-och-billy", // program name
"title": "Episode Title S3 - EP1 en-ny-tjej-i-byn", // episode name
"length": "3359", // content duration in seconds
"playlisttitle": "barn", //playlist title
"ispremiumcontent": "yes", //identify premium level content
"isautoplay": "yes", //identify if autoplay is enabled
"plugv": "1.0.1", //player version
"playerv": "Sonic" // player identifier
},
"ad": {
"type": "preroll", // type of ad
"assetid": "E1UMBR1001", // unique ID for ad
"length": "3359", // ad duration in seconds
"isprogrammatic": "yes",//identify if the ad is bought prommatic
"isthirdpartyad": "yes",//identify if the ad is from third party ad server
"adplatformorigin": "YuMe",//identity of ad origin
"adidx": "1/5" //placement in ad break
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}
</syntaxhighlight>

=====Configure Payload: devInfo=====
An object <code>"devInfo"</code> will need to be created to capture App and Device information.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| devId || unique ID to identify user (e.g. Advertising ID, Roku Device ID) || custom || ✓
|-
| apn || app name || custom || ✓
|-
| apv || app build version || custom || ✓
|-
|-
| uoo || device opt-out status || <code>"true"</code> or <code>"false"</code> || ✓
|-
|-
| hem_unknown || Hashed email using SHA512. Used by MMS reach model. (required if login feature) || custom || ✓
|-
|-style="background-color:#d0f6f8;"
| fpid || First Party ID || custom || ✓
|-style="background-color:#d0f6f8;"
| fpcrtm || Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds) || custom || ✓
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "First Party ID",
"fpcrtm": "Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)"
"hem_unknown" : "61f1121944dfb76f09540c59a99b4000" //SHA512 hashed value
},
</syntaxhighlight>

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

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

===== Create Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.
 
'''Note:''' program and title metadata values should be passed to SDK as UTF-8 strings.

===== Example Content Object =====
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "uniqueassetid",
"length": "2600",
"program": "program name",
"title": "episode title"
}</syntaxhighlight>

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

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

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "unique_preroll_ad_id"
}
</syntaxhighlight>
 
<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== Configure Payload: Events ===

The last part of the payload is for enabling events so content is measured correctly when viewed. The events and required parameters are included below.

==== Event Types ====

The available events are:
{| class="wikitable"
|-
! Event !! Description
|-
| <code>"playhead"</code> ||

===== Handling Playhead =====

Calling <code>"playhead"</code> is critical for accurate duration crediting. You can reference the below guidance to determine the correct playhead position to pass depending on the playback scenario.

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

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

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

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

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

'''User Actions'''
* SCRUBBING: Upon user scrubbing, the current position must be sent before a user scrubs, and the new position should be sent where the user lands, and begin sending in the 10 second updates thereafter.
* PAUSE: When content is paused, send current playhead position and stop passing playhead position until content is resumed.
* EXIT Stream: If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

|-
| <code>"complete"</code> || The complete event must be sent when the content has completed full playback. Before calling the complete event, a final playhead update with the final position is required to be sent to receive full duration credit. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is optional and can be sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. All creditable duration will be summarized for all asset types when delete occurs (content and ads).
|}

===== Event Parameters =====

The following parameters need to be passed when calling events:

{| class="wikitable"
|-
! Parameter !! Description !! Value !! Required
|-
| <code>"event"</code> || event type || <code>"playhead"</code>, <code>"complete"</code>, or <code>"delete"</code> || ✓
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || ✓
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || ✓
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || ✓
|-style="background-color:#d0f6f8;"
| <code>"sessid"</code> || Unique View Session ID must be created upon start of each stream playback, sessid is unique per video play. || <code>"xxxjavd6wzirm93xb95uxjy1ac5wu1627638609"</code> || ✓
|}

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

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"metadata": {
"content": [content metadata],
"ad": [ad metadata]
},
// Event Parameters
"event": [event], // event name
"position": [playheadPosition], //position in seconds
"type": [asset type], // values are "content" or "ad"
"utc": "1472760000000" //unix timestamp in milliseconds
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}
</syntaxhighlight>

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

===== Sample Event Lifecycle for VoD Stream =====
The sample event lifecycle can be used as a reference for identifying the order for calling events and values to pass.

<syntaxhighlight lang="javascript">
// Start of Session: session ID created when App is opened

// Preroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472760000000"}

// Midroll
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content resumes at 15 minutes
Content Playhead {"event": "playhead", "position": "900", "type": "content", "utc": "1472760000000"}

// Content completes at 30 minutes
Complete {"event": "complete", "position": "1800", "type": "content", "utc": "1472760000000"}

// Postroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472760000000"}
</syntaxhighlight>

'''Sample Event Lifecycle for VoD Stream - Detailed Storyline'''
This detailed event sequence provides additional insight for the correct events to call when handling certain playback scenarios.
<syntaxhighlight lang='javascript'>// SESSION STARTS
// Start of Session: session ID created when App is opened

// PREROLL
// Preroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Preroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "15", "type": "ad", "utc": "1472761500000"}

// CONTENT
// Content Start - Start new content streams with a position of "0" incrementing the position every 10 seconds.
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472761500000"}

// Content Stop Before Ad Break - Send a playhead update including the current content positon before an Ad break.
Content Playhead {"event": "playhead", "position": "299", "type": "content", "utc": "1472787400000"}

// MIDROLL
// Midroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472787500000"}

// Midroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "60", "type": "ad", "utc": "1472793500000"}

// CONTENT
// Content resumes at 5 minutes - Send playhead update with the current resumed position, and begin incrimenting the positon every 10 seconds.
Content Playhead {"event": "playhead", "position": "300", "type": "content", "utc": "1472799500000"}

// Content completes at 10:12 - Make sure to send in the playhead event with the final content position before sending the complete event.
Final Content Playhead {"event": "playhead", "position": "612", "type": "content", "utc": "1472830700000"}

Complete {"event": "complete", "position": "612", "type": "content", "utc": "1472830800000"}

// POSTROLL
// Postroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472830900000"}

// Postroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "45", "type": "ad", "utc": "1472835300000"}

// SESSION ENDS

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472835400000"} </syntaxhighlight>

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

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

*Wi-Fi OFF / ON
*App going Background / Foreground (Video players only, not for Audio players)
*App Crash or Exit

When playback is interrupted, the app needs to send delete immediately.

Once playback resumes, a new session will need to be created with a unique session ID. All of the required metadata and events will need to be sent.

'''Note:''' The session will automatically timeout after 30 minutes of inactivity.

=== Example Request ===

Now that we walked through the Cloud API integration steps, your requests should have the following components: Session ID, App ID, and Payload. You can reference the example below when your reviewing your integration.

<syntaxhighlight lang="javascript">
// 1. Create Session ID
sessionID = dfc7dc6a-66a7-4705-9fba-adaaf7e3d5e0 // Example sessionID created using a UUID Generator

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

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000"
"hem_unknown" : "61f1121944dfb76f09540c59a99b4000" //SHA512 hashed value
},

// 3.2 Configure Payload: metadata
"metadata": {
"type": "content", // "content" for video
"assetid": "uniqueassetid_simulcast", // unique ID for video
"userid": "uniqueUserId_2b5a2541ec8241d2f535238104af3c85", // SHA512 hashed userid
"clientpassparam": "origcode=29", // Custom parameters passed
"program": "Program Name leif-och-billy", // program name
"title": "Episode Title S3 - EP1 en-ny-tjej-i-byn", // episode name
"length": "3359", // content duration in seconds
"playlisttitle": "barn", //playlist title
"ispremiumcontent": "yes", //identify premium level content
"isautoplay": "yes", //identify if autoplay is enabled
"plugv": "1.0.1", //player version
"playerv": "Sonic" // player identifier
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123", // unique ID for ad
"length": "3359", // ad duration in seconds
"isprogrammatic": "yes",//identify if the ad is bought prommatic
"isthirdpartyad": "yes",//identify if the ad is from third party ad server
"adplatformorigin": "YuMe",//identity of ad origin
"adidx": "1/5" //placement in ad break
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}

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

==== Enable Debug Logging ====

Now that you have set up the Cloud API requests, you can enable debug logging to validate your integration. Enabling debug logging is required for Nielsen certification.

==== GET Request ====

Display GET Request to console using a name to identify each event (e.g. playhead).

<syntaxhighlight lang="javascript">
console.log("Event", image);
</syntaxhighlight>

==== Payload ====

Output payload to identify required metadata and events.

<syntaxhighlight lang="javascript">
console.log("Event Payload", payload);
</syntaxhighlight>

==== HTTP Response Code ====

Confirm request was completed by viewing HTTP response code.

<syntaxhighlight lang="javascript">
code = msg.GetResponseCode();
console.log("Response Code", code);
</syntaxhighlight>

You can reference the HTTP Response Code table when reviewing your requests:

{| class="wikitable"
|-
! Status Code !! Status Text !! Description
|-
| <code>200</code> || OK || request received
|-
| <code>403</code> || Forbidden || invalid App ID
|-
| <code>404</code> || Not Found || JSON issue
|}

== Opt-Out ==
Your app must provide a means for the user to Opt-Out, or Opt-In to Nielsen Measurement. This requirement can be fulfilled by checking the device OS for the user's setting of "Limit Ad Tracking" or similar option. If the device offers "Limit Ad Tracking" settings, you should set <code>uoo=true</code> or <code>uoo=false</code> depending on the user's privacy setting. Also, ensure that the <code>devId</code> is set to a blank value if the user elects to opt-out.

If the device does not have OS-level "Do Not Track" settings, you can implement opt-out by creating an Opt-Out/Opt-In button, toggle switch, or slider within the app "Settings", or "About" section to allow the user selection.

[[File:Nielsen Opt-Out.png|link=]]

You will need to store the User Opt-Out (uoo) status, so that it can be retrieved and populated in the <code>"devInfo"</code> metadata which will be sent in every Cloud API event (playhead, complete, & delete).

{| class="wikitable"
|-
! uoo Key !! Description !! Values
|-
| uoo || Device is Opted-In to Nielsen Measurement (Recommended Default Setting) || <code>"false"</code>
|-
| uoo || Device is Opted-Out of Nielsen Measurement || <code>"true"</code>
|}

===== devInfo Opt-In JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "7be25cf9-8c40-5cc2-871e-19bf41940288",
"uoo": "false"
},
</syntaxhighlight>

===== devInfo Opt-Out JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "", //devId must be blank when a user elects to Opt-Out.
"uoo": "true"
},
</syntaxhighlight>

===== Privacy Information Template To Include In Opt-Out Screen =====

Additionally, all applications must display the Nielsen privacy policy within their application, typically in the Settings/About screen of your application. The Nielsen privacy policy text is listed below.

<blockquote>
'''''ABOUT NIELSEN MEASUREMENT'''''

Television and the way we watch it have come a long way since Nielsen began measuring TV audiences in 1950. Today, the ability to watch our favorite shows at any time and on multiple devices amplifies the need for exceptionally adept and flexible audience measurement capabilities.

Consumers are changing with the times, and the same goes for us. As technology continues to evolve and media companies try new ways to attract viewers, understanding what consumers are watching — and what they're watching on — is more important than ever. Today, viewing video is a personal and mobile experience — anytime and anywhere. Our capabilities provide relevant metrics that are necessary to inform successful marketing and programming and drive continued growth. As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process, and use. While our digital measurement products are not used to identify you in any way, they help us and our client's measure and analyze how consumers engage with media across online, mobile, and emerging technologies, and offer insights into consumer behavior.

'''''YOUR CHOICES'''''

Nielsen believes that you should have a choice about whether to contribute to our research and insights. To opt-out or opt into Nielsen measurement, please toggle your "Limit Ad Tracking" (or similar setting) on your device, or make the appropriate selection within the application's settings. If you have this app on more than one device, you will need to opt-out of this app on each device. To learn more about our digital measurement products and your choices in regard to them, please visit https://sites.nielsen.com/priv/browser/se/sv/optout.html

</blockquote>
'''''Disclosure Template'''''

Additionally, you must update the App description information from the App Distribution Store with the Nielsen Measurement disclosure below:

This app features Nielsen's proprietary measurement software which will allow you to contribute to market research, like Nielsen's TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information.

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

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

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

Start the Reference Implementation for Sweden [http://nielsenonlinesupport.com/michel/sdkRefImplCloudDK/index.htm RefImplCloudAPISE].
<blockquote>
Review the Nielsen CloudAPI Call Sequence below the Video Player.
</blockquote>

== Disclose Nielsen Privacy Statement ==

In order to disclose the Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third-party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://sites.nielsen.com/priv/browser/se/sv/optout.html .

== Testing ==
Before providing an app build to Nielsen for testing, it is important to run validation checks once you have enabled debug logging.

=== Payload Validation ===

Ensure that all of the required payload data is populating while testing several videos. The following areas are critical to measurement:
*devInfo
*Asset metadata for both content, and ads
*Events

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

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset for VoD stream and UTC Unix Time in seconds for Live stream.
*Final playhead position is sent on content, or ad before switching between assets.
*Content metadata remains constant throughout an episode or clip play.
*Ad metadata is populated appropriately for each individual ad.
*Playhead position update resumes for content after an ad break and resets to 0 for each individual ad.
*For scrubbing, last current position should be sent while scrubbing occurs, and the new position should also be sent where the user scrubs to.
*Exiting a stream early should execute the last current position in a playhead update to receive accurate duration.
*Upon pause, the current position should be sent, and playhead updates should stop incrementing until resume play occurs.

==== complete ====
*Check that the complete event executes upon content complete after the final playhead update is sent
*Do not execute the complete event for ads

==== delete ====
*Check to see that the delete event occurs upon app exit, if the platform has the necessary exit callback events.

==== GET Request Format ====
*Ensure that the event payloads are formatted in JSON
*Check to see that each of the Cloud API GET requests are properly encoded

==== HTTP Response ====
*Make sure that each of the Cloud API Get requests are received by the Nielsen Cloud API properly through use of the HTTP Response Code outputs enabled in console.

==== Opt-Out ====
*Test the "uoo" key gets populated accurately for both Opt-In and Opt-Out selections by validating the Cloud API events called after the user Opt-Out/Opt-In selection.
*Test that the devId field is populated with a blank value if a user has elected to Opt-Out. For example: "devId": "",
*If the device supports "Limit Ad Tracking" or has device "Opt-Out" settings, test that uoo=true, and that devId is set to a blank value if enabled in the device settings.

== Go Live ==
After your integration has been certified, you will need to: Change the Endpoint and Disable Logging.

'''Change Endpoint:''' You will need to update to the production endpoint:

*Testing: <code>https://sc-eucert.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://capi-sw.imrworldwide.com/nmapi/v2/</code>

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

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

DCR Sweden Video Cloud API

2021-10-19T15:04:28Z

ShangningWang: /* Configure Payload */

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

= DCR Integration Utilizing Cloud API =
This guide shows you how to integrate the Nielsen Cloud API to enable Digital Content Ratings (DCR), and fuel other measurement products on your over-the-top (OTT) Apps.
__TOC__
==Prerequisites==
To get started, you will need a Nielsen App ID. The App ID is a unique ID assigned to your app. This will be provided to you by your assigned Technical Account Manager upon starting the integration.

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

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

====URL Structure====

The Cloud API Calls are HTTP GET Requests with the URL structure:

<syntaxhighlight lang="javascript">[endpoint]/[appid]/[sessionID]/a?b=[payload]</syntaxhighlight>

The URL includes the following components:

*<code>[endpoint]</code>: location of data collection environment
*<code>[appid]</code>: provided App ID
*<code>[sessionID]</code>: unique value for each user session
*<code>[payload]</code>: metadata and events

====Endpoint====

There are endpoints for testing and production:

*Testing: <code>https://sc-eucert.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://capi-sw.imrworldwide.com/nmapi/v2/</code>

During testing, all calls should be pointed to the testing endpoint. We will review the update to the production endpoint during the Go Live section of this guide.

====URL Example====
As you move through the integration steps, you can reference the below URL structure with the expanded payload:

<syntaxhighlight lang="javascript">
https://sc-eucert.imrworldwide.com/nmapi/v2/[appid]/[sessionID]/a?b=
{
"devInfo": [deviceInfo],
"metadata": {
"content": [content_metadata],
"ad": [ad metadata]
},
"event": [event],
"position": [playhead_position],
"type": [asset type],
"utc": [Unix time in ms]
}
</syntaxhighlight>

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

====Create Session ID====

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

A Session ID needs to be completely unique so it is recommended to use a version 4 UUID or another method of your choosing to guarantee there are no repeats, also see [[#Review the Reference Implementation for VoD and Live Streams|Reference Implementation for VoD and Live Streams]] for your reference and use.

Upon exiting the app, the session will need to be terminated using the delete event. Sessions will automatically expire after 30 minutes of cloud inactivity.

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

===Create First Party ID===
* An First Party ID <code>[fpid]</code> must be created and stored on the device. It is re-used until the expiration date or if the user has deleted it from the device storage.
The default expiration date should be set to the equivalent of 180 days.
* Additionally the Creation Time <code>[fpcrtm]</code> of the First Party ID should be stored as well. The same value should be used as long as the First Party ID is available on the device.

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

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

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

===Configure Payload===

All Cloud API requests must contain the following payload data:

*''devInfo'': device and app info
*''metadata'': asset metadata
*''event metadata'': type of event

The payload can be passed through key-values using the Nielsen reserved keys. The specific keys and descriptions are highlighted in the tables included in this section.

'''Payload Example'''

The example below should be referenced when following the steps for configuring the request payload.

<syntaxhighlight lang="javascript">
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "First Party ID",
"fpcrtm": "Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)"
"hem_unknown" : "61f1121944dfb76f09540c59a99b4000"
},

// 3.2 Configure Payload: metadata
"metadata": {
"content": { // object for measuring video content
"type": "content", // "content" for video
"assetid": "uniqueassetid_simulcast", // unique ID for video
"userid": "uniqueUserId_2b5a2541ec8241d2f535238104af3c85", // unique USER ID
"clientpassparam": "origcode=29", // Custom parameters passed
"program": "Program Name leif-och-billy", // program name
"title": "Episode Title S3 - EP1 en-ny-tjej-i-byn", // episode name
"length": "3359", // content duration in seconds
"playlisttitle": "barn", //playlist title
"ispremiumcontent": "yes", //identify premium level content
"isautoplay": "yes", //identify if autoplay is enabled
"plugv": "1.0.1", //player version
"playerv": "Sonic" // player identifier
},
"ad": {
"type": "preroll", // type of ad
"assetid": "E1UMBR1001", // unique ID for ad
"length": "3359", // ad duration in seconds
"isprogrammatic": "yes",//identify if the ad is bought prommatic
"isthirdpartyad": "yes",//identify if the ad is from third party ad server
"adplatformorigin": "YuMe",//identity of ad origin
"adidx": "1/5" //placement in ad break
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
}
</syntaxhighlight>

=====Configure Payload: devInfo=====
An object <code>"devInfo"</code> will need to be created to capture App and Device information.

{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| devId || unique ID to identify user (e.g. Advertising ID, Roku Device ID) || custom || ✓
|-
| apn || app name || custom || ✓
|-
| apv || app build version || custom || ✓
|-
|-
| uoo || device opt-out status || <code>"true"</code> or <code>"false"</code> || ✓
|-
|-
| hem_unknown || Hashed email using SHA512. Used by MMS reach model. (required if login feature) || custom || ✓
|-
|-style="background-color:#d0f6f8;"
| fpid || First Party ID || custom || ✓
|-style="background-color:#d0f6f8;"
| fpcrtm || Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds) || custom || ✓
|-
|}

'''Example devInfo Object'''
<syntaxhighlight lang="javascript">
// create devInfo object
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "First Party ID",
"fpcrtm": "Creation Time (UTC) of the First Party ID (Unix Timestamp in milliseconds)"
"hem_unknown" : "61f1121944dfb76f09540c59a99b4000" //SHA512 hashed value
},
</syntaxhighlight>

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

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

===== Create Content Metadata =====
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.
 
'''Note:''' program and title metadata values should be passed to SDK as UTF-8 strings.

===== Example Content Object =====
<syntaxhighlight lang='json'>// create content object
"content": {
"type": "content",
"assetid": "uniqueassetid",
"length": "2600",
"program": "program name",
"title": "episode title"
}</syntaxhighlight>

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

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

===== Example Ad Object =====
<syntaxhighlight lang="javascript">
// create ad object
"ad": {
"type": "preroll",
"assetid": "unique_preroll_ad_id"
}
</syntaxhighlight>
 
<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== Configure Payload: Events ===

The last part of the payload is for enabling events so content is measured correctly when viewed. The events and required parameters are included below.

==== Event Types ====

The available events are:
{| class="wikitable"
|-
! Event !! Description
|-
| <code>"playhead"</code> ||

===== Handling Playhead =====

Calling <code>"playhead"</code> is critical for accurate duration crediting. You can reference the below guidance to determine the correct playhead position to pass depending on the playback scenario.

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

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

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

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

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

'''User Actions'''
* SCRUBBING: Upon user scrubbing, the current position must be sent before a user scrubs, and the new position should be sent where the user lands, and begin sending in the 10 second updates thereafter.
* PAUSE: When content is paused, send current playhead position and stop passing playhead position until content is resumed.
* EXIT Stream: If a user exits a stream early, the last current position must be sent in a playhead update to receive accurate duration.

|-
| <code>"complete"</code> || The complete event must be sent when the content has completed full playback. Before calling the complete event, a final playhead update with the final position is required to be sent to receive full duration credit. For Live streams, a complete event must be sent at program boundaries.
|-
| <code>"delete"</code> || The delete event is optional and can be sent when the viewing session is terminated (typically on App close). A new session ID must be generated after sending a delete event. Delete should not be sent on app interruptions or foreground/background events. All creditable duration will be summarized for all asset types when delete occurs (content and ads).
|}

===== Event Parameters =====

The following parameters need to be passed when calling events:

{| class="wikitable"
|-
! Parameter !! Description !! Value !! Required
|-
| <code>"event"</code> || event type || <code>"playhead"</code>, <code>"complete"</code>, or <code>"delete"</code> || ✓
|-
| <code>"position"</code> || playhead position in seconds or Unix time in seconds || <code>"300"</code> || ✓
|-
| <code>"type"</code> || asset type || <code>"content"</code>, <code>"ad"</code> || ✓
|-
| <code>"utc"</code> || Unix timestamp in milliseconds. Must be passed every 10 seconds. || <code>"1472760000000"</code> || ✓
|-style="background-color:#d0f6f8;"
| <code>"sessid"</code> || Unique View Session ID must be created upon start of each stream playback, sessid is unique per video play. || <code>"xxxjavd6wzirm93xb95uxjy1ac5wu1627638609"</code> || ✓
|}

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

<syntaxhighlight lang="javascript">
"devInfo": [deviceInfo],
"metadata": {
"content": [content metadata],
"ad": [ad metadata]
},
// Event Parameters
"event": [event], // event name
"position": [playheadPosition], //position in seconds
"type": [asset type], // values are "content" or "ad"
"utc": "1472760000000" //unix timestamp in milliseconds
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}
</syntaxhighlight>

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

===== Sample Event Lifecycle for VoD Stream =====
The sample event lifecycle can be used as a reference for identifying the order for calling events and values to pass.

<syntaxhighlight lang="javascript">
// Start of Session: session ID created when App is opened

// Preroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472760000000"}

// Midroll
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Content resumes at 15 minutes
Content Playhead {"event": "playhead", "position": "900", "type": "content", "utc": "1472760000000"}

// Content completes at 30 minutes
Complete {"event": "complete", "position": "1800", "type": "content", "utc": "1472760000000"}

// Postroll
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472760000000"}
</syntaxhighlight>

'''Sample Event Lifecycle for VoD Stream - Detailed Storyline'''
This detailed event sequence provides additional insight for the correct events to call when handling certain playback scenarios.
<syntaxhighlight lang='javascript'>// SESSION STARTS
// Start of Session: session ID created when App is opened

// PREROLL
// Preroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472760000000"}

// Preroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "15", "type": "ad", "utc": "1472761500000"}

// CONTENT
// Content Start - Start new content streams with a position of "0" incrementing the position every 10 seconds.
Content Playhead {"event": "playhead", "position": "0", "type": "content", "utc": "1472761500000"}

// Content Stop Before Ad Break - Send a playhead update including the current content positon before an Ad break.
Content Playhead {"event": "playhead", "position": "299", "type": "content", "utc": "1472787400000"}

// MIDROLL
// Midroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Midroll Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472787500000"}

// Midroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "60", "type": "ad", "utc": "1472793500000"}

// CONTENT
// Content resumes at 5 minutes - Send playhead update with the current resumed position, and begin incrimenting the positon every 10 seconds.
Content Playhead {"event": "playhead", "position": "300", "type": "content", "utc": "1472799500000"}

// Content completes at 10:12 - Make sure to send in the playhead event with the final content position before sending the complete event.
Final Content Playhead {"event": "playhead", "position": "612", "type": "content", "utc": "1472830700000"}

Complete {"event": "complete", "position": "612", "type": "content", "utc": "1472830800000"}

// POSTROLL
// Postroll Start - Start each Ad with a position of "0", resetting to '0' for each Ad, and Ad break.
Ad Playhead {"event": "playhead", "position": "0", "type": "ad", "utc": "1472830900000"}

// Postroll Stop - End each Ad with the final position of the Ad.
Ad Playhead {"event": "playhead", "position": "45", "type": "ad", "utc": "1472835300000"}

// SESSION ENDS

//End of Session: The delete event should be called when the App is exited. The values for position and type not required to be passed.
Delete { "event": "delete", "position": "", "type": "", "utc": "1472835400000"} </syntaxhighlight>

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

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

*Wi-Fi OFF / ON
*App going Background / Foreground (Video players only, not for Audio players)
*App Crash or Exit

When playback is interrupted, the app needs to send delete immediately.

Once playback resumes, a new session will need to be created with a unique session ID. All of the required metadata and events will need to be sent.

'''Note:''' The session will automatically timeout after 30 minutes of inactivity.

=== Example Request ===

Now that we walked through the Cloud API integration steps, your requests should have the following components: Session ID, App ID, and Payload. You can reference the example below when your reviewing your integration.

<syntaxhighlight lang="javascript">
// 1. Create Session ID
sessionID = dfc7dc6a-66a7-4705-9fba-adaaf7e3d5e0 // Example sessionID created using a UUID Generator

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

// 3. Configure Payload
// 3.1 Configure Payload: devInfo
payload = {
"devInfo": {
"devId": "AD-ID",
"apn": "AppName",
"apv": "1.0",
"uoo": "false",
"fpid": "U4EDwDcpvWIbguYVyjlhzS1v0eaov1631180980",
"fpcrtm": "1631098029000"
"hem_md5" : "61f1121944dfb76f09540c59a99b4000" //hashed_md5_value
},

// 3.2 Configure Payload: metadata
"metadata": {
"type": "content", // "content" for video
"assetid": "uniqueassetid_simulcast", // unique ID for video
"userid": "uniqueUserId_2b5a2541ec8241d2f535238104af3c85", // unique USER ID hashed_md5_value
"clientpassparam": "origcode=29", // Custom parameters passed
"program": "Program Name leif-och-billy", // program name
"title": "Episode Title S3 - EP1 en-ny-tjej-i-byn", // episode name
"length": "3359", // content duration in seconds
"playlisttitle": "barn", //playlist title
"ispremiumcontent": "yes", //identify premium level content
"isautoplay": "yes", //identify if autoplay is enabled
"plugv": "1.0.1", //player version
"playerv": "Sonic" // player identifier
},
"ad": {
"type": "preroll", // type of ad
"assetid": "AD-ID123", // unique ID for ad
"length": "3359", // ad duration in seconds
"isprogrammatic": "yes",//identify if the ad is bought prommatic
"isthirdpartyad": "yes",//identify if the ad is from third party ad server
"adplatformorigin": "YuMe",//identity of ad origin
"adidx": "1/5" //placement in ad break
}
},

// 3.3 Configure Payload: events
"event": "playhead", //event name
"position": "300", // position in seconds
"type": "content", //"content" or "ad"
"utc": "1456448742000" //unix timestamp in milliseconds
"sessid": "xxxjavd6wzirm93xb95uxjy1ac5wu1627638609", // unique for each video play
}

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

==== Enable Debug Logging ====

Now that you have set up the Cloud API requests, you can enable debug logging to validate your integration. Enabling debug logging is required for Nielsen certification.

==== GET Request ====

Display GET Request to console using a name to identify each event (e.g. playhead).

<syntaxhighlight lang="javascript">
console.log("Event", image);
</syntaxhighlight>

==== Payload ====

Output payload to identify required metadata and events.

<syntaxhighlight lang="javascript">
console.log("Event Payload", payload);
</syntaxhighlight>

==== HTTP Response Code ====

Confirm request was completed by viewing HTTP response code.

<syntaxhighlight lang="javascript">
code = msg.GetResponseCode();
console.log("Response Code", code);
</syntaxhighlight>

You can reference the HTTP Response Code table when reviewing your requests:

{| class="wikitable"
|-
! Status Code !! Status Text !! Description
|-
| <code>200</code> || OK || request received
|-
| <code>403</code> || Forbidden || invalid App ID
|-
| <code>404</code> || Not Found || JSON issue
|}

== Opt-Out ==
Your app must provide a means for the user to Opt-Out, or Opt-In to Nielsen Measurement. This requirement can be fulfilled by checking the device OS for the user's setting of "Limit Ad Tracking" or similar option. If the device offers "Limit Ad Tracking" settings, you should set <code>uoo=true</code> or <code>uoo=false</code> depending on the user's privacy setting. Also, ensure that the <code>devId</code> is set to a blank value if the user elects to opt-out.

If the device does not have OS-level "Do Not Track" settings, you can implement opt-out by creating an Opt-Out/Opt-In button, toggle switch, or slider within the app "Settings", or "About" section to allow the user selection.

[[File:Nielsen Opt-Out.png|link=]]

You will need to store the User Opt-Out (uoo) status, so that it can be retrieved and populated in the <code>"devInfo"</code> metadata which will be sent in every Cloud API event (playhead, complete, & delete).

{| class="wikitable"
|-
! uoo Key !! Description !! Values
|-
| uoo || Device is Opted-In to Nielsen Measurement (Recommended Default Setting) || <code>"false"</code>
|-
| uoo || Device is Opted-Out of Nielsen Measurement || <code>"true"</code>
|}

===== devInfo Opt-In JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "7be25cf9-8c40-5cc2-871e-19bf41940288",
"uoo": "false"
},
</syntaxhighlight>

===== devInfo Opt-Out JSON Payload Example =====

<syntaxhighlight lang="javascript">
"devInfo": {
"apn": "Cloud API Sample App",
"apv": "1",
"devId": "", //devId must be blank when a user elects to Opt-Out.
"uoo": "true"
},
</syntaxhighlight>

===== Privacy Information Template To Include In Opt-Out Screen =====

Additionally, all applications must display the Nielsen privacy policy within their application, typically in the Settings/About screen of your application. The Nielsen privacy policy text is listed below.

<blockquote>
'''''ABOUT NIELSEN MEASUREMENT'''''

Television and the way we watch it have come a long way since Nielsen began measuring TV audiences in 1950. Today, the ability to watch our favorite shows at any time and on multiple devices amplifies the need for exceptionally adept and flexible audience measurement capabilities.

Consumers are changing with the times, and the same goes for us. As technology continues to evolve and media companies try new ways to attract viewers, understanding what consumers are watching — and what they're watching on — is more important than ever. Today, viewing video is a personal and mobile experience — anytime and anywhere. Our capabilities provide relevant metrics that are necessary to inform successful marketing and programming and drive continued growth. As a global information and measurement leader, we are committed to protecting the privacy and security of the data we collect, process, and use. While our digital measurement products are not used to identify you in any way, they help us and our client's measure and analyze how consumers engage with media across online, mobile, and emerging technologies, and offer insights into consumer behavior.

'''''YOUR CHOICES'''''

Nielsen believes that you should have a choice about whether to contribute to our research and insights. To opt-out or opt into Nielsen measurement, please toggle your "Limit Ad Tracking" (or similar setting) on your device, or make the appropriate selection within the application's settings. If you have this app on more than one device, you will need to opt-out of this app on each device. To learn more about our digital measurement products and your choices in regard to them, please visit https://sites.nielsen.com/priv/browser/se/sv/optout.html

</blockquote>
'''''Disclosure Template'''''

Additionally, you must update the App description information from the App Distribution Store with the Nielsen Measurement disclosure below:

This app features Nielsen's proprietary measurement software which will allow you to contribute to market research, like Nielsen's TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information.

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

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

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

Start the Reference Implementation for Sweden [http://nielsenonlinesupport.com/michel/sdkRefImplCloudDK/index.htm RefImplCloudAPISE].
<blockquote>
Review the Nielsen CloudAPI Call Sequence below the Video Player.
</blockquote>

== Disclose Nielsen Privacy Statement ==

In order to disclose the Nielsen measurement privacy statement, please include the following items in your privacy policy:
* A notice that the player includes third-party measurement software that allows users to contribute to market research with anonymous data.
* A link to the Nielsen Digital Measurement Privacy Policy located at https://sites.nielsen.com/priv/browser/se/sv/optout.html .

== Testing ==
Before providing an app build to Nielsen for testing, it is important to run validation checks once you have enabled debug logging.

=== Payload Validation ===

Ensure that all of the required payload data is populating while testing several videos. The following areas are critical to measurement:
*devInfo
*Asset metadata for both content, and ads
*Events

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

==== playhead ====
*Playhead position updates every 10 seconds starting at position '0' for each new asset for VoD stream and UTC Unix Time in seconds for Live stream.
*Final playhead position is sent on content, or ad before switching between assets.
*Content metadata remains constant throughout an episode or clip play.
*Ad metadata is populated appropriately for each individual ad.
*Playhead position update resumes for content after an ad break and resets to 0 for each individual ad.
*For scrubbing, last current position should be sent while scrubbing occurs, and the new position should also be sent where the user scrubs to.
*Exiting a stream early should execute the last current position in a playhead update to receive accurate duration.
*Upon pause, the current position should be sent, and playhead updates should stop incrementing until resume play occurs.

==== complete ====
*Check that the complete event executes upon content complete after the final playhead update is sent
*Do not execute the complete event for ads

==== delete ====
*Check to see that the delete event occurs upon app exit, if the platform has the necessary exit callback events.

==== GET Request Format ====
*Ensure that the event payloads are formatted in JSON
*Check to see that each of the Cloud API GET requests are properly encoded

==== HTTP Response ====
*Make sure that each of the Cloud API Get requests are received by the Nielsen Cloud API properly through use of the HTTP Response Code outputs enabled in console.

==== Opt-Out ====
*Test the "uoo" key gets populated accurately for both Opt-In and Opt-Out selections by validating the Cloud API events called after the user Opt-Out/Opt-In selection.
*Test that the devId field is populated with a blank value if a user has elected to Opt-Out. For example: "devId": "",
*If the device supports "Limit Ad Tracking" or has device "Opt-Out" settings, test that uoo=true, and that devId is set to a blank value if enabled in the device settings.

== Go Live ==
After your integration has been certified, you will need to: Change the Endpoint and Disable Logging.

'''Change Endpoint:''' You will need to update to the production endpoint:

*Testing: <code>https://sc-eucert.imrworldwide.com/nmapi/v2/</code>
*Production: <code>https://capi-sw.imrworldwide.com/nmapi/v2/</code>

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

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

DCR Sweden Video Android SDK

2021-10-19T15:03:33Z

ShangningWang: /* Create SDK Instance */

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

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

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

== Implementation ==
The Nielsen Android SDK comes in three flavors.

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

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

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

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_unknown || Hashed email using SHA512. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_unknown", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_unknown", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

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

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

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

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

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

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

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

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

<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");
//please see metadata link above for all content parameters

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");
//please see metadata link above for all ad parameters
</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

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

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

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

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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

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

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

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

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

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device.
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the No Ad version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

==== Retrieve current Opt-Out preference ====
Whether the user is opted out via OS-level Opt-out or via App-level Opt-out, the current Opt-Out status as detected by the SDK is available via the [[getOptOutStatus()]] property in the Nielsen Android SDK API. <code>appSdk.getOptOutStatus()</code>

===Global OptOut Example ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the No Ad version or the No ID version.

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>
===No Ad Framework Optout Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the No ID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

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

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

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

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

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

DCR Sweden Video iOS SDK

2021-10-19T15:02:40Z

ShangningWang: /* Create SDK Instance */

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

__TOC__

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

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

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

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

== Setting up your iOS Development Environment ==

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

=== Importing Frameworks ===

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

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

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

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

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

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

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

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_unknown || Hashed email using SHA512. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

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

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

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

@implementation NlsAppApiFactory

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

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

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

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

@end
</syntaxhighlight>

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

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

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

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

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

override func viewDidLoad() {
super.viewDidLoad()

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

}
}
</syntaxhighlight>

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

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

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

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

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

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

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

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

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

<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== MetaData Example ===

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

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

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

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

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

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

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

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

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

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

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

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

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[playheadPosition|playheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelName); </code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad_123",
...
}</syntaxhighlight>
<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[playheadPosition|playheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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

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

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third-party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

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

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

== Privacy and Opt-Out ==

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

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

In addition, the following text must be included in your app store description.
<blockquote>"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information"</blockquote>

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

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

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

override func viewDidLoad() {
super.viewDidLoad()

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

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

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

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

@interface OptOutVC ()

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

@implementation OptOutVC

- (void)viewDidLoad {
[super viewDidLoad];

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

</syntaxhighlight>

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

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

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

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

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

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

override func viewDidLoad() {
super.viewDidLoad()

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

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

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

}

</syntaxhighlight>

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

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

@interface OptOutVC ()

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

@implementation OptOutVC

- (void)viewDidLoad {
[super viewDidLoad];

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

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

</syntaxhighlight>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

DCR Sweden Video Browser SDK

2021-10-19T15:01:53Z

ShangningWang: /* Sample SDK Initialization Call */

DCR Sweden Video Browser SDK

2021-10-19T15:01:11Z

ShangningWang: /* Initialization API Call */

Sweden SDK Metadata

2021-10-19T15:00:16Z

ShangningWang: /* Content Metadata */

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

= Digital Metadata =
Digital Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.
 
'''Section 1''' focuses on the content metadata
 
'''Section 2''' focuses on the Ad metadata.
 

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

== Content Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| userid || || the user login ID. Used by MMS reach model. ''The uploaded value needs to be hashed with SHA512''. This is the user login ID on player. We prefer a numeric value but email will work just fine.|| "2b5a2541ec8241d2f535238104af3c85" || required if login feature

|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. ||
For VoD use internal format. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters] 
For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 
A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler".
|| ✓ 
|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for VoD, video length
* for event-Live stream, the planned length. If planned length not available, then put default value 0
* for simulcast and 24/7 live stream, 86400
|| ✓
|-
| clientpassparam || MMS Values, mms_values || pass-through parameters || For clients that provide DAI (dynamic ad insertion) service, this has a standard format: origcode=channelnumber.
'''Example:''' origcode=29
See the complete list of channel reference library with the channel number on [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler". Please use string, JSON format is not accepted. 
Length limit: 250 characters. A longer string may be truncated due to URL length limitation.
|| required for clients that have DAI service (Telia, Telenor, Allente, Comhem, Boxer, Sappa, Discovery, Cmore)
|-
| program || Program Name, ns_st_pr || program name || '''custom''' '''example:''' leif-och-billy 
Leave blank for simulcast.
|| ✓
|-
| title || Episode Name, ns_st_ep || episode name || '''custom''' '''example:''' en-ny-tjej-i-byn 
Leave blank for simulcast.
|| ✓
|-
| playlisttitle || Title Playlist, ns_st_pl || playlist reference as a string || string value with playlist name for '''example:''' barn ||
|-
| ispremiumcontent || MMS Premium, mms_premium || identify premium level via yes or no || "yes" or "no" || ✓
|-
| isautoplay || Auto Start, mms_auto || identify if autoplay is enabled on the video || "yes" or "no" || ✓
|-
| plugv || Player Version, ns_st_mv || player version. increment by 1 for each new version. || alphanumeric '''example:''' 1.0.1 || ✓
|-
| playerv || Mediaplayer, ns_st_mp || player identifier || alphanumeric '''example:''' HTML5, JW Player, Sonic || ✓
|}

Example of metadata object for content:

<syntaxhighlight lang="javascript">
var contentMetadataObject = {
type: "content",
userid: "2b5a2541ec8241d2f535238104af3c85",
assetid: "simulcast_29",
length: "3359",
clientpassparam: "origcode=29",
program: "leif-och-billy",
title: "en-ny-tjej-i-byn",
playlisttitle: "barn",
ispremiumcontent: "yes",
isautoplay: "yes",
plugv: "1.0.1",
playerv: "Sonic"
};
</syntaxhighlight>

== Ad Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || Ad Type, ns_st_ad || type of ad || "preroll", "midroll", "postroll", "ad" if specific ad type cannot be identified. || ✓
|-
| assetid || Film Code, mms_customadid || custom Ad ID || Film code/Copy code.
'''Custom examples''': S1MYME202B, 51TRER1001, H1KYLE3032, E1UMBR1001

In case of no Film Code is available, use the string "empty".

For programmatic ads that you are sending "programmatic" as Film Code today, use "programmatic_{current UTC time in epoch form}".
|| ✓
|-
| length || Clip Length, ns_st_cl || length of ad in seconds || Length of ad in seconds. || ✓
|-
| isprogrammatic || Programmatic, mms_programmatic || identify if the ad is bought prommatic. || "yes" or "no" ||
|-
| isthirdpartyad || MMS Thirdparty, mms_thirdparty || identify if the ad is from third party ad server || "yes" or "no" ||
|-
| adplatformorigin || MMS Origin, mms_origin || identify where an ad is originated. It is used when isprogrammatic=yes or isthirdpartyad=yes. || custom '''examples:''' Smartclip, YuMe
||
|-
| adidx || Position in Break, ns_st_an || placement in ad break. It is passed by ad servers. || Custom with the following format:
{ad placement}/{total number of ads in an ad break} 

'''Example:''' 2/5, the second ad in an ad break with 5 ads.
|| ✓
|}

Example of metadata object for Ad:

<syntaxhighlight lang="javascript">
var prerollMetadataObject = {
type: "preroll",
assetid: "E1UMBR1001",
length: "3359",
isprogrammatic: "yes",
isthirdpartyad: "yes",
adplatformorigin: "YuMe",
adidx: "1/5"
};
</syntaxhighlight>

DCR Sweden Video Android SDK

2021-10-11T13:25:52Z

ShangningWang: /* Webview Element */

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

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

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

== Implementation ==
The Nielsen Android SDK comes in three flavors.

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

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

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

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

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

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

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

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

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

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

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

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

<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");
//please see metadata link above for all content parameters

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");
//please see metadata link above for all ad parameters
</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

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

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

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

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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

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

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

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

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

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device.
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the No Ad version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

==== Retrieve current Opt-Out preference ====
Whether the user is opted out via OS-level Opt-out or via App-level Opt-out, the current Opt-Out status as detected by the SDK is available via the [[getOptOutStatus()]] property in the Nielsen Android SDK API. <code>appSdk.getOptOutStatus()</code>

===Global OptOut Example ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the No Ad version or the No ID version.

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>
===No Ad Framework Optout Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the No ID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

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

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

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

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

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

DCR Sweden Video Android SDK

2021-10-11T13:23:31Z

ShangningWang: /* Privacy and Opt-Out */

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

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

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

== Implementation ==
The Nielsen Android SDK comes in three flavors.

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

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

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

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

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

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

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

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

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

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

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

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

<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");
//please see metadata link above for all content parameters

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");
//please see metadata link above for all ad parameters
</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

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

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

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

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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

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

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

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

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

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device.
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the No Ad version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

In addition, the following text must be included in your app store description.
<blockquote>"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information"</blockquote>

==== Retrieve current Opt-Out preference ====
Whether the user is opted out via OS-level Opt-out or via App-level Opt-out, the current Opt-Out status as detected by the SDK is available via the [[getOptOutStatus()]] property in the Nielsen Android SDK API. <code>appSdk.getOptOutStatus()</code>

===Global OptOut Example ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the No Ad version or the No ID version.

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>
===No Ad Framework Optout Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the No ID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

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

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

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

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

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

DCR Sweden Video Browser SDK

2021-10-07T18:28:45Z

ShangningWang: /* Add Static Queue Snippet */

Sweden SDK Metadata

2021-10-01T13:43:50Z

ShangningWang: /* Content Metadata */

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

= Digital Metadata =
Digital Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.
 
'''Section 1''' focuses on the content metadata
 
'''Section 2''' focuses on the Ad metadata.
 

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

== Content Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| userid || || the user login ID. Used by MMS reach model. ''The uploaded value needs to be hashed with MD5''. This is the user login ID on player. We prefer a numeric value but email will work just fine.|| "2b5a2541ec8241d2f535238104af3c85" || required if login feature

|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. ||
For VoD use internal format. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters] 
For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 
A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler".
|| ✓ 
|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for VoD, video length
* for event-Live stream, the planned length. If planned length not available, then put default value 0
* for simulcast and 24/7 live stream, 86400
|| ✓
|-
| clientpassparam || MMS Values, mms_values || pass-through parameters || For clients that provide DAI (dynamic ad insertion) service, this has a standard format: origcode=channelnumber.
'''Example:''' origcode=29
See the complete list of channel reference library with the channel number on [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler". Please use string, JSON format is not accepted. 
Length limit: 250 characters. A longer string may be truncated due to URL length limitation.
|| required for clients that have DAI service (Telia, Telenor, Allente, Comhem, Boxer, Sappa, Discovery, Cmore)
|-
| program || Program Name, ns_st_pr || program name || '''custom''' '''example:''' leif-och-billy 
Leave blank for simulcast.
|| ✓
|-
| title || Episode Name, ns_st_ep || episode name || '''custom''' '''example:''' en-ny-tjej-i-byn 
Leave blank for simulcast.
|| ✓
|-
| playlisttitle || Title Playlist, ns_st_pl || playlist reference as a string || string value with playlist name for '''example:''' barn ||
|-
| ispremiumcontent || MMS Premium, mms_premium || identify premium level via yes or no || "yes" or "no" || ✓
|-
| isautoplay || Auto Start, mms_auto || identify if autoplay is enabled on the video || "yes" or "no" || ✓
|-
| plugv || Player Version, ns_st_mv || player version. increment by 1 for each new version. || alphanumeric '''example:''' 1.0.1 || ✓
|-
| playerv || Mediaplayer, ns_st_mp || player identifier || alphanumeric '''example:''' HTML5, JW Player, Sonic || ✓
|}

Example of metadata object for content:

<syntaxhighlight lang="javascript">
var contentMetadataObject = {
type: "content",
userid: "2b5a2541ec8241d2f535238104af3c85",
assetid: "simulcast_29",
length: "3359",
clientpassparam: "origcode=29",
program: "leif-och-billy",
title: "en-ny-tjej-i-byn",
playlisttitle: "barn",
ispremiumcontent: "yes",
isautoplay: "yes",
plugv: "1.0.1",
playerv: "Sonic"
};
</syntaxhighlight>

== Ad Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || Ad Type, ns_st_ad || type of ad || "preroll", "midroll", "postroll", "ad" if specific ad type cannot be identified. || ✓
|-
| assetid || Film Code, mms_customadid || custom Ad ID || Film code/Copy code.
'''Custom examples''': S1MYME202B, 51TRER1001, H1KYLE3032, E1UMBR1001

In case of no Film Code is available, use the string "empty".

For programmatic ads that you are sending "programmatic" as Film Code today, use "programmatic_{current UTC time in epoch form}".
|| ✓
|-
| length || Clip Length, ns_st_cl || length of ad in seconds || Length of ad in seconds. || ✓
|-
| isprogrammatic || Programmatic, mms_programmatic || identify if the ad is bought prommatic. || "yes" or "no" ||
|-
| isthirdpartyad || MMS Thirdparty, mms_thirdparty || identify if the ad is from third party ad server || "yes" or "no" ||
|-
| adplatformorigin || MMS Origin, mms_origin || identify where an ad is originated. It is used when isprogrammatic=yes or isthirdpartyad=yes. || custom '''examples:''' Smartclip, YuMe
||
|-
| adidx || Position in Break, ns_st_an || placement in ad break. It is passed by ad servers. || Custom with the following format:
{ad placement}/{total number of ads in an ad break} 

'''Example:''' 2/5, the second ad in an ad break with 5 ads.
|| ✓
|}

Example of metadata object for Ad:

<syntaxhighlight lang="javascript">
var prerollMetadataObject = {
type: "preroll",
assetid: "E1UMBR1001",
length: "3359",
isprogrammatic: "yes",
isthirdpartyad: "yes",
adplatformorigin: "YuMe",
adidx: "1/5"
};
</syntaxhighlight>

Sweden SDK Metadata

2021-10-01T09:22:37Z

ShangningWang: /* Ad Metadata */

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

= Digital Metadata =
Digital Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.
 
'''Section 1''' focuses on the content metadata
 
'''Section 2''' focuses on the Ad metadata.
 

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

== Content Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| userid || || the user login ID. Used by MMS reach model. ''The uploaded value needs to be hashed with MD5''. This is the user login ID on player. We prefer a numeric value but email will work just fine.|| "2b5a2541ec8241d2f535238104af3c85" || required if login feature

|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. ||
For VoD use internal format. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters] 
For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 
A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler".
|| ✓ 
|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for VoD, video length
* for event-Live stream, the planned length
* for simulcast and 24/7 live stream, 86400
|| ✓
|-
| clientpassparam || MMS Values, mms_values || pass-through parameters || For clients that provide DAI (dynamic ad insertion) service, this has a standard format: origcode=channelnumber.
'''Example:''' origcode=29
See the complete list of channel reference library with the channel number on [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler". Please use string, JSON format is not accepted. 
Length limit: 250 characters. A longer string may be truncated due to URL length limitation.
|| required for clients that have DAI service (Telia, Telenor, Allente, Comhem, Boxer, Sappa, Discovery, Cmore)
|-
| program || Program Name, ns_st_pr || program name || '''custom''' '''example:''' leif-och-billy 
Leave blank for simulcast.
|| ✓
|-
| title || Episode Name, ns_st_ep || episode name || '''custom''' '''example:''' en-ny-tjej-i-byn 
Leave blank for simulcast.
|| ✓
|-
| playlisttitle || Title Playlist, ns_st_pl || playlist reference as a string || string value with playlist name for '''example:''' barn ||
|-
| ispremiumcontent || MMS Premium, mms_premium || identify premium level via yes or no || "yes" or "no" || ✓
|-
| isautoplay || Auto Start, mms_auto || identify if autoplay is enabled on the video || "yes" or "no" || ✓
|-
| plugv || Player Version, ns_st_mv || player version. increment by 1 for each new version. || alphanumeric '''example:''' 1.0.1 || ✓
|-
| playerv || Mediaplayer, ns_st_mp || player identifier || alphanumeric '''example:''' HTML5, JW Player, Sonic || ✓
|}

Example of metadata object for content:

<syntaxhighlight lang="javascript">
var contentMetadataObject = {
type: "content",
userid: "2b5a2541ec8241d2f535238104af3c85",
assetid: "simulcast_29",
length: "3359",
clientpassparam: "origcode=29",
program: "leif-och-billy",
title: "en-ny-tjej-i-byn",
playlisttitle: "barn",
ispremiumcontent: "yes",
isautoplay: "yes",
plugv: "1.0.1",
playerv: "Sonic"
};
</syntaxhighlight>

== Ad Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || Ad Type, ns_st_ad || type of ad || "preroll", "midroll", "postroll", "ad" if specific ad type cannot be identified. || ✓
|-
| assetid || Film Code, mms_customadid || custom Ad ID || Film code/Copy code.
'''Custom examples''': S1MYME202B, 51TRER1001, H1KYLE3032, E1UMBR1001

In case of no Film Code is available, use the string "empty".

For programmatic ads that you are sending "programmatic" as Film Code today, use "programmatic_{current UTC time in epoch form}".
|| ✓
|-
| length || Clip Length, ns_st_cl || length of ad in seconds || Length of ad in seconds. || ✓
|-
| isprogrammatic || Programmatic, mms_programmatic || identify if the ad is bought prommatic. || "yes" or "no" ||
|-
| isthirdpartyad || MMS Thirdparty, mms_thirdparty || identify if the ad is from third party ad server || "yes" or "no" ||
|-
| adplatformorigin || MMS Origin, mms_origin || identify where an ad is originated. It is used when isprogrammatic=yes or isthirdpartyad=yes. || custom '''examples:''' Smartclip, YuMe
||
|-
| adidx || Position in Break, ns_st_an || placement in ad break. It is passed by ad servers. || Custom with the following format:
{ad placement}/{total number of ads in an ad break} 

'''Example:''' 2/5, the second ad in an ad break with 5 ads.
|| ✓
|}

Example of metadata object for Ad:

<syntaxhighlight lang="javascript">
var prerollMetadataObject = {
type: "preroll",
assetid: "E1UMBR1001",
length: "3359",
isprogrammatic: "yes",
isthirdpartyad: "yes",
adplatformorigin: "YuMe",
adidx: "1/5"
};
</syntaxhighlight>

Sweden SDK Metadata

2021-10-01T09:22:22Z

ShangningWang: /* Ad Metadata */

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

= Digital Metadata =
Digital Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.
 
'''Section 1''' focuses on the content metadata
 
'''Section 2''' focuses on the Ad metadata.
 

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

== Content Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| userid || || the user login ID. Used by MMS reach model. ''The uploaded value needs to be hashed with MD5''. This is the user login ID on player. We prefer a numeric value but email will work just fine.|| "2b5a2541ec8241d2f535238104af3c85" || required if login feature

|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. ||
For VoD use internal format. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters] 
For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 
A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler".
|| ✓ 
|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for VoD, video length
* for event-Live stream, the planned length
* for simulcast and 24/7 live stream, 86400
|| ✓
|-
| clientpassparam || MMS Values, mms_values || pass-through parameters || For clients that provide DAI (dynamic ad insertion) service, this has a standard format: origcode=channelnumber.
'''Example:''' origcode=29
See the complete list of channel reference library with the channel number on [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler". Please use string, JSON format is not accepted. 
Length limit: 250 characters. A longer string may be truncated due to URL length limitation.
|| required for clients that have DAI service (Telia, Telenor, Allente, Comhem, Boxer, Sappa, Discovery, Cmore)
|-
| program || Program Name, ns_st_pr || program name || '''custom''' '''example:''' leif-och-billy 
Leave blank for simulcast.
|| ✓
|-
| title || Episode Name, ns_st_ep || episode name || '''custom''' '''example:''' en-ny-tjej-i-byn 
Leave blank for simulcast.
|| ✓
|-
| playlisttitle || Title Playlist, ns_st_pl || playlist reference as a string || string value with playlist name for '''example:''' barn ||
|-
| ispremiumcontent || MMS Premium, mms_premium || identify premium level via yes or no || "yes" or "no" || ✓
|-
| isautoplay || Auto Start, mms_auto || identify if autoplay is enabled on the video || "yes" or "no" || ✓
|-
| plugv || Player Version, ns_st_mv || player version. increment by 1 for each new version. || alphanumeric '''example:''' 1.0.1 || ✓
|-
| playerv || Mediaplayer, ns_st_mp || player identifier || alphanumeric '''example:''' HTML5, JW Player, Sonic || ✓
|}

Example of metadata object for content:

<syntaxhighlight lang="javascript">
var contentMetadataObject = {
type: "content",
userid: "2b5a2541ec8241d2f535238104af3c85",
assetid: "simulcast_29",
length: "3359",
clientpassparam: "origcode=29",
program: "leif-och-billy",
title: "en-ny-tjej-i-byn",
playlisttitle: "barn",
ispremiumcontent: "yes",
isautoplay: "yes",
plugv: "1.0.1",
playerv: "Sonic"
};
</syntaxhighlight>

== Ad Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || Ad Type, ns_st_ad || type of ad || "preroll", "midroll", "postroll", "ad" if specific ad type cannot be identified. || ✓
|-
| assetid || Film Code, mms_customadid || custom Ad ID || Film code/Copy code.
'''Custom examples''': S1MYME202B, 51TRER1001, H1KYLE3032, E1UMBR1001

In case of no Film Code is available, use the string "empty".

For programmatic ads that you are sending "programmatic" as Film Code today, use the "programmatic_{current UTC time in epoch form}".
|| ✓
|-
| length || Clip Length, ns_st_cl || length of ad in seconds || Length of ad in seconds. || ✓
|-
| isprogrammatic || Programmatic, mms_programmatic || identify if the ad is bought prommatic. || "yes" or "no" ||
|-
| isthirdpartyad || MMS Thirdparty, mms_thirdparty || identify if the ad is from third party ad server || "yes" or "no" ||
|-
| adplatformorigin || MMS Origin, mms_origin || identify where an ad is originated. It is used when isprogrammatic=yes or isthirdpartyad=yes. || custom '''examples:''' Smartclip, YuMe
||
|-
| adidx || Position in Break, ns_st_an || placement in ad break. It is passed by ad servers. || Custom with the following format:
{ad placement}/{total number of ads in an ad break} 

'''Example:''' 2/5, the second ad in an ad break with 5 ads.
|| ✓
|}

Example of metadata object for Ad:

<syntaxhighlight lang="javascript">
var prerollMetadataObject = {
type: "preroll",
assetid: "E1UMBR1001",
length: "3359",
isprogrammatic: "yes",
isthirdpartyad: "yes",
adplatformorigin: "YuMe",
adidx: "1/5"
};
</syntaxhighlight>

Sweden SDK Metadata

2021-09-28T14:56:51Z

ShangningWang: /* Ad Metadata */

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

= Digital Metadata =
Digital Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.
 
'''Section 1''' focuses on the content metadata
 
'''Section 2''' focuses on the Ad metadata.
 

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

== Content Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| userid || || the user login ID. Used by MMS reach model. ''The uploaded value needs to be hashed with MD5''. This is the user login ID on player. We prefer a numeric value but email will work just fine.|| "2b5a2541ec8241d2f535238104af3c85" || required if login feature

|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. ||
For VoD use internal format. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters] 
For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 
A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler".
|| ✓ 
|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for VoD, video length
* for event-Live stream, the planned length
* for simulcast and 24/7 live stream, 86400
|| ✓
|-
| clientpassparam || MMS Values, mms_values || pass-through parameters || For clients that provide DAI (dynamic ad insertion) service, this has a standard format: origcode=channelnumber.
'''Example:''' origcode=29
See the complete list of channel reference library with the channel number on [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler". Please use string, JSON format is not accepted. 
Length limit: 250 characters. A longer string may be truncated due to URL length limitation.
|| required for clients that have DAI service (Telia, Telenor, Allente, Comhem, Boxer, Sappa, Discovery, Cmore)
|-
| program || Program Name, ns_st_pr || program name || '''custom''' '''example:''' leif-och-billy 
Leave blank for simulcast.
|| ✓
|-
| title || Episode Name, ns_st_ep || episode name || '''custom''' '''example:''' en-ny-tjej-i-byn 
Leave blank for simulcast.
|| ✓
|-
| playlisttitle || Title Playlist, ns_st_pl || playlist reference as a string || string value with playlist name for '''example:''' barn ||
|-
| ispremiumcontent || MMS Premium, mms_premium || identify premium level via yes or no || "yes" or "no" || ✓
|-
| isautoplay || Auto Start, mms_auto || identify if autoplay is enabled on the video || "yes" or "no" || ✓
|-
| plugv || Player Version, ns_st_mv || player version. increment by 1 for each new version. || alphanumeric '''example:''' 1.0.1 || ✓
|-
| playerv || Mediaplayer, ns_st_mp || player identifier || alphanumeric '''example:''' HTML5, JW Player, Sonic || ✓
|}

Example of metadata object for content:

<syntaxhighlight lang="javascript">
var contentMetadataObject = {
type: "content",
userid: "2b5a2541ec8241d2f535238104af3c85",
assetid: "simulcast_29",
length: "3359",
clientpassparam: "origcode=29",
program: "leif-och-billy",
title: "en-ny-tjej-i-byn",
playlisttitle: "barn",
ispremiumcontent: "yes",
isautoplay: "yes",
plugv: "1.0.1",
playerv: "Sonic"
};
</syntaxhighlight>

== Ad Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || Ad Type, ns_st_ad || type of ad || "preroll", "midroll", "postroll", "ad" if specific ad type cannot be identified. || ✓
|-
| assetid || Film Code, mms_customadid || custom Ad ID || Film code/Copy code.
'''Custom examples''': S1MYME202B, 51TRER1001, H1KYLE3032, E1UMBR1001

In case of no Film code is available, use the string "empty".
|| ✓
|-
| length || Clip Length, ns_st_cl || length of ad in seconds || Length of ad in seconds. || ✓
|-
| isprogrammatic || Programmatic, mms_programmatic || identify if the ad is bought prommatic. || "yes" or "no" ||
|-
| isthirdpartyad || MMS Thirdparty, mms_thirdparty || identify if the ad is from third party ad server || "yes" or "no" ||
|-
| adplatformorigin || MMS Origin, mms_origin || identify where an ad is originated. It is used when isprogrammatic=yes or isthirdpartyad=yes. || custom '''examples:''' Smartclip, YuMe
||
|-
| adidx || Position in Break, ns_st_an || placement in ad break. It is passed by ad servers. || Custom with the following format:
{ad placement}/{total number of ads in an ad break} 

'''Example:''' 2/5, the second ad in an ad break with 5 ads.
|| ✓
|}

Example of metadata object for Ad:

<syntaxhighlight lang="javascript">
var prerollMetadataObject = {
type: "preroll",
assetid: "E1UMBR1001",
length: "3359",
isprogrammatic: "yes",
isthirdpartyad: "yes",
adplatformorigin: "YuMe",
adidx: "1/5"
};
</syntaxhighlight>

DCR Sweden Video Browser SDK

2021-09-20T12:03:40Z

ShangningWang: /* Privacy and Opt-Out */

DCR Sweden Video Android SDK

2021-09-16T11:21:49Z

ShangningWang: /* Create Ad Metadata */

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

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

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

== Implementation ==
The Nielsen Android SDK comes in three flavors.

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

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

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

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

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

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

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

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

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

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

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

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

<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");
//please see metadata link above for all content parameters

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");
//please see metadata link above for all ad parameters
</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

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

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

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

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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

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

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

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

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

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device.
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the No Ad version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

In addition, The following text must be included in your app store description.
<blockquote>"'''Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://nielsen.com/digitalprivacy/ for more information'''"</blockquote>

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the No Ad version or the No ID version.

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the No ID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Opt-out Sample Code ==
=== Global Android SDK Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

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

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

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

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

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

DCR Sweden Video Android SDK

2021-09-16T11:21:29Z

ShangningWang: /* Create Content Metadata */

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

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

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

== Implementation ==
The Nielsen Android SDK comes in three flavors.

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

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

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

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

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

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

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

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

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

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

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

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

<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");
//please see metadata link above for all content parameters

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");
//please see metadata link above for all ad parameters
</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

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

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

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

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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

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

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

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

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

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device.
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the No Ad version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

In addition, The following text must be included in your app store description.
<blockquote>"'''Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://nielsen.com/digitalprivacy/ for more information'''"</blockquote>

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the No Ad version or the No ID version.

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the No ID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Opt-out Sample Code ==
=== Global Android SDK Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

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

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

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

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

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

DCR Sweden Video Browser SDK

2021-09-16T11:21:02Z

ShangningWang: /* Create Ad Metadata */

DCR Sweden Video Browser SDK

2021-09-16T11:20:44Z

ShangningWang: /* Create Content Metadata */

DCR Sweden Video iOS SDK

2021-09-16T11:19:48Z

ShangningWang: /* Create Ad Metadata */

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

__TOC__

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

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

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

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

== Setting up your iOS Development Environment ==

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

=== Importing Frameworks ===

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

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

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

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

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

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

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

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

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

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

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

@implementation NlsAppApiFactory

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

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

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

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

@end
</syntaxhighlight>

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

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

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

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

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

override func viewDidLoad() {
super.viewDidLoad()

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

}
}
</syntaxhighlight>

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

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

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

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

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

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

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

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

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

<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== MetaData Example ===

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

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

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

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

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

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

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

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

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

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

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

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

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[playheadPosition|playheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelName); </code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad_123",
...
}</syntaxhighlight>
<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[playheadPosition|playheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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

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

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third-party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

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

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

== Privacy and Opt-Out ==

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

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

In addition, the following text must be included in your app store description.
<blockquote>"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information"</blockquote>

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

Similar to the Global iOS SDK Flavor, it is a requirement to display a WebView element whose loadUrl is set to the
value obtained from optOutURL. This is a special URL that indicates Opt-in, or Opt-out and close the WebView.

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

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

== Opt-out example code ==
===== Swift =====
<syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

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

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

override func viewDidLoad() {
super.viewDidLoad()

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

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

// Uncomment below code if you are using the Global iOS SDK No Ad Framework Flavor. This will receive the user's selection
// from the custom User_Choice Optout page. Only required for the Global iOS SDK No Ad Framework Flavor
/*
func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler:
@escaping (WKNavigationActionPolicy) -> Void) {
print(navigationAction.request.url?.absoluteString as Any) //For debugging to check what is being passed from webpage.
if navigationAction.request.url?.absoluteString == "nielsen://close" {
closeOptOutView()
decisionHandler(.cancel)
} else {
if let url = navigationAction.request.url?.absoluteString, url.hasPrefix("nielsen") {
nielsenApi?.userOptOut(url). //either nielsenappsdk://1 or nielsenappsdk://0
decisionHandler(.cancel)
} else {
if navigationAction.navigationType == .linkActivated {
if let url = navigationAction.request.url?.absoluteString, url.hasSuffix("#") {
decisionHandler(.allow)
} else {
decisionHandler(.cancel)
webView.load(navigationAction.request)
}
} else {
decisionHandler(.allow)
}}}}
*/
}

</syntaxhighlight>

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

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

@interface OptOutVC ()

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

@implementation OptOutVC

- (void)viewDidLoad {
[super viewDidLoad];

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

// Uncomment below code if you are using the Global iOS SDK No Ad Framework Flavor. This will receive the user's selection
// from the custom User_Choice Optout page. Only required for the Global iOS SDK No Ad Framework Flavor
/*
- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction
decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler
{
if ([navigationAction.request.URL.absoluteString isEqualToString:kNielsenWebClose])
{ [self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
decisionHandler(WKNavigationActionPolicyCancel);
} else {
if ([navigationAction.request.URL.absoluteString hasPrefix:@"nielsen"])
{[self.nielsenAppApi userOptOut:navigationAction.request.URL.absoluteString];
decisionHandler(WKNavigationActionPolicyCancel);
} else {
if (navigationAction.navigationType == WKNavigationTypeLinkActivated)
{ if ([navigationAction.request.URL.absoluteString hasSuffix:@"#"])
{decisionHandler(WKNavigationActionPolicyAllow);
} else {
decisionHandler(WKNavigationActionPolicyCancel);
[webView loadRequest:[NSURLRequest requestWithURL:navigationAction.request.URL]];
}} else {
decisionHandler(WKNavigationActionPolicyAllow);
}}}
*/
}

</syntaxhighlight>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

DCR Sweden Video iOS SDK

2021-09-16T11:19:25Z

ShangningWang: /* Create Content Metadata */

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

__TOC__

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

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

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

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

== Setting up your iOS Development Environment ==

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

=== Importing Frameworks ===

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

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

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

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

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

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

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

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

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

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

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

@implementation NlsAppApiFactory

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

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

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

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

@end
</syntaxhighlight>

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

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

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

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

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

override func viewDidLoad() {
super.viewDidLoad()

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

}
}
</syntaxhighlight>

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

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

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

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

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

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

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

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

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

<blockquote> URL Character Limit: There is a URL character limit of 2K characters due to browser limitations. Exceeding this value could impair data delivery on particular browsers. </blockquote>

=== MetaData Example ===

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

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

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

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

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

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

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

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

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

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

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

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

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[playheadPosition|playheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelName); </code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad_123",
...
}</syntaxhighlight>
<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[playheadPosition|playheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

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

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

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third-party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

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

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

== Privacy and Opt-Out ==

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

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

In addition, the following text must be included in your app store description.
<blockquote>"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information"</blockquote>

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

Similar to the Global iOS SDK Flavor, it is a requirement to display a WebView element whose loadUrl is set to the
value obtained from optOutURL. This is a special URL that indicates Opt-in, or Opt-out and close the WebView.

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

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

== Opt-out example code ==
===== Swift =====
<syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

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

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

override func viewDidLoad() {
super.viewDidLoad()

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

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

// Uncomment below code if you are using the Global iOS SDK No Ad Framework Flavor. This will receive the user's selection
// from the custom User_Choice Optout page. Only required for the Global iOS SDK No Ad Framework Flavor
/*
func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler:
@escaping (WKNavigationActionPolicy) -> Void) {
print(navigationAction.request.url?.absoluteString as Any) //For debugging to check what is being passed from webpage.
if navigationAction.request.url?.absoluteString == "nielsen://close" {
closeOptOutView()
decisionHandler(.cancel)
} else {
if let url = navigationAction.request.url?.absoluteString, url.hasPrefix("nielsen") {
nielsenApi?.userOptOut(url). //either nielsenappsdk://1 or nielsenappsdk://0
decisionHandler(.cancel)
} else {
if navigationAction.navigationType == .linkActivated {
if let url = navigationAction.request.url?.absoluteString, url.hasSuffix("#") {
decisionHandler(.allow)
} else {
decisionHandler(.cancel)
webView.load(navigationAction.request)
}
} else {
decisionHandler(.allow)
}}}}
*/
}

</syntaxhighlight>

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

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

@interface OptOutVC ()

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

@implementation OptOutVC

- (void)viewDidLoad {
[super viewDidLoad];

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

// Uncomment below code if you are using the Global iOS SDK No Ad Framework Flavor. This will receive the user's selection
// from the custom User_Choice Optout page. Only required for the Global iOS SDK No Ad Framework Flavor
/*
- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction
decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler
{
if ([navigationAction.request.URL.absoluteString isEqualToString:kNielsenWebClose])
{ [self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
decisionHandler(WKNavigationActionPolicyCancel);
} else {
if ([navigationAction.request.URL.absoluteString hasPrefix:@"nielsen"])
{[self.nielsenAppApi userOptOut:navigationAction.request.URL.absoluteString];
decisionHandler(WKNavigationActionPolicyCancel);
} else {
if (navigationAction.navigationType == WKNavigationTypeLinkActivated)
{ if ([navigationAction.request.URL.absoluteString hasSuffix:@"#"])
{decisionHandler(WKNavigationActionPolicyAllow);
} else {
decisionHandler(WKNavigationActionPolicyCancel);
[webView loadRequest:[NSURLRequest requestWithURL:navigationAction.request.URL]];
}} else {
decisionHandler(WKNavigationActionPolicyAllow);
}}}
*/
}

</syntaxhighlight>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

DCR Sweden Video Browser SDK

2021-09-09T11:55:29Z

ShangningWang: /* Start the Measurement */

Sweden SDK Metadata

2021-09-08T14:35:51Z

ShangningWang: /* Content Metadata */

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

= Digital Metadata =
Digital Metadata can pass through key values using the Nielsen reserved keys. The keys and values are listed by the product below.
 
'''Section 1''' focuses on the content metadata
 
'''Section 2''' focuses on the Ad metadata.

== Content Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| userid || || the user login ID. Used by MMS reach model. ''The uploaded value needs to be hashed with MD5''. This is the user login ID on player. We prefer a numeric value but email will work just fine.|| "2b5a2541ec8241d2f535238104af3c85" || required if login feature

|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. ||
For VoD use internal format. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters] 
For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 
A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler".
|| ✓ 
|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for VoD, video length
* for event-Live stream, the planned length
* for simulcast and 24/7 live stream, 86400
|| ✓
|-
| clientpassparam || MMS Values, mms_values || pass-through parameters || For clients that provide DAI (dynamic ad insertion) service, this has a standard format: origcode=channelnumber.
'''Example:''' origcode=29
See the complete list of channel reference library with the channel number on [https://mms.se/?page_id=108 MMS homepage] tab "referensbandade kanaler". Please use string, JSON format is not accepted. 
Length limit: 250 characters. A longer string may be truncated due to URL length limitation.
|| required for clients that have DAI service (Telia, Telenor, Allente, Comhem, Boxer, Sappa, Discovery, Cmore)
|-
| program || Program Name, ns_st_pr || program name || '''custom''' '''example:''' leif-och-billy 
Leave blank for simulcast.
|| ✓
|-
| title || Episode Name, ns_st_ep || episode name || '''custom''' '''example:''' en-ny-tjej-i-byn 
Leave blank for simulcast.
|| ✓
|-
| playlisttitle || Title Playlist, ns_st_pl || playlist reference as a string || string value with playlist name for '''example:''' barn ||
|-
| ispremiumcontent || MMS Premium, mms_premium || identify premium level via yes or no || "yes" or "no" || ✓
|-
| isautoplay || Auto Start, mms_auto || identify if autoplay is enabled on the video || "yes" or "no" || ✓
|-
| plugv || Player Version, ns_st_mv || player version. increment by 1 for each new version. || alphanumeric '''example:''' 1.0.1 || ✓
|-
| playerv || Mediaplayer, ns_st_mp || player identifier || alphanumeric '''example:''' HTML5, JW Player, Sonic || ✓
|}

Example of metadata object for content:

<syntaxhighlight lang="javascript">
var contentMetadataObject = {
type: "content",
userid: "2b5a2541ec8241d2f535238104af3c85",
assetid: "simulcast_29",
length: "3359",
clientpassparam: "origcode=29",
program: "leif-och-billy",
title: "en-ny-tjej-i-byn",
playlisttitle: "barn",
ispremiumcontent: "yes",
isautoplay: "yes",
plugv: "1.0.1",
playerv: "Sonic"
};
</syntaxhighlight>

== Ad Metadata==

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || Ad Type, ns_st_ad || type of ad || "preroll", "midroll", "postroll", "ad" if specific ad type cannot be identified. || ✓
|-
| assetid || Film Code, mms_customadid || custom Ad ID || Film code/Copy code.
'''Custom examples''': S1MYME202B, 51TRER1001, H1KYLE3032, E1UMBR1001
|| ✓
|-
| length || Clip Length, ns_st_cl || length of ad in seconds || Length of ad in seconds. || ✓
|-
| isprogrammatic || Programmatic, mms_programmatic || identify if the ad is bought prommatic. || "yes" or "no" ||
|-
| isthirdpartyad || MMS Thirdparty, mms_thirdparty || identify if the ad is from third party ad server || "yes" or "no" ||
|-
| adplatformorigin || MMS Origin, mms_origin || identify where an ad is originated. It is used when isprogrammatic=yes or isthirdpartyad=yes. || custom '''examples:''' Smartclip, YuMe
||
|-
| adidx || Position in Break, ns_st_an || placement in ad break. It is passed by ad servers. || Custom with the following format:
{ad placement}/{total number of ads in an ad break} 

'''Example:''' 2/5, the second ad in an ad break with 5 ads.
|| ✓
|}

Example of metadata object for Ad:

<syntaxhighlight lang="javascript">
var prerollMetadataObject = {
type: "preroll",
assetid: "E1UMBR1001",
length: "3359",
isprogrammatic: "yes",
isthirdpartyad: "yes",
adplatformorigin: "YuMe",
adidx: "1/5"
};
</syntaxhighlight>

DCR Sweden Video iOS SDK

2021-09-06T15:10:06Z

ShangningWang: /* Webview Element */

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

__TOC__

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

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

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

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

== Setting up your iOS Development Environment ==

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

=== Importing Frameworks ===

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

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

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

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

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

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

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

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

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

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

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

@implementation NlsAppApiFactory

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

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

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

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

@end
</syntaxhighlight>

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

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

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

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

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# '''Processing state''' – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called

<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted NSString or a NSDictionary object. The JSON passed in the SDK must be well-formed.
* NSDictionary object
** If an object of unexpected type is passed to the method, the error message will be logged.
** If string has invalid JSON format, the error message will be logged.
* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

=== Create Content Metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play. 

Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

 
<blockquote> program and title metadata values should be passed to SDK as UTF-8 strings. </blockquote>

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. || For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 

A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage]

For VoD, it does not need to follow the simulcast_channelnumber format.

Length limit: 20 characters. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters]
|| ✓ 

|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for 24/7 live stream, 86400
* for event-Live streams, the planned length
* for VoD, video length
|| ✓
|-
| program || Program Name, ns_st_pr || program name || custom '''example:''' leif-och-billy || ✓
|-
| title || Episode Name, ns_st_ep || episode name || custom '''example:''' en-ny-tjej-i-byn || ✓
|}

=== Create Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad. 

Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

Note: All metadata values should be passed as UTF-8 strings.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> <code>"ad"</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to an asset within the same media house. || custom (no [[Special Characters]]) || ✓
|}

=== MetaData Example ===

==== Using Objective-C ====
<syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @
{
@"assetid" : "uniqueassetid",
@"type" : "content",
@"program" : "program name",
@"title" : "episode title",
@"length" : "2600"
}

NSDictionary *adMetadata = @
{
@"assetid" : "uniquepostrolladid",
@"type" : "postroll"
}
</syntaxhighlight>

==== Using Swift ====
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
]

let contentMetadata = [
"assetid" : "uniqueassetid",
"type" : "content",
"program" : "program name",
"title" : "episode title",
"length" : "2600"
]

let adMetadata = [
"assetid" : "uniquepostrolladid",
"type" : "postroll"
]

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player. Call play only when initially starting the video.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi play:channelInfo];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.play(channelInfo);</syntaxhighlight>
 

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi loadMetadata:metadataDict];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(metadataDict)</syntaxhighlight>
 

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">
[self.nielsenAppApi playheadPosition:pos];
</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">
self.nielsenAppApi?.playheadPosition(pos);
</syntaxhighlight>
 

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi stop];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.stop;</syntaxhighlight>
 

==== end ====
Call when the content asset completes playback. Stops measurement progress.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi end];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.end</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[playheadPosition|playheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelName); </code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad_123",
...
}</syntaxhighlight>
<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[playheadPosition|playheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelName); </code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third-party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Privacy and Opt-Out ==

There are currently 3 flavors of the Nielsen SDK. Please check the "Implementation" section for a comparison of the three flavors. Implementing opt-out for the three flavors are different:
# '''[[#Global_iOS_SDK_Opt-out|Global iOS SDK Opt-out]]''' - managed by ''AppTracking'' or ''Limit Ad Tracking'' setting on device.
# '''[[#Global_iOS_SDK_No_Ad_Framework_Opt-out|Global iOS SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without the Ad Framework.
# '''[[#Global_iOS_SDK_No_ID_Opt-out|Global iOS SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.
__NOTOC__
=== Global iOS SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen iOS

The Nielsen SDK automatically leverages the iOS's '''Limit Ad Tracking''' or '''AppTracking''' setting.
* If the User's device is running < iOS 13.x, the Nielsen SDK will check the status of '''Limit Ad Tracking'''.
* iOS14 modifies the way Apple manages the collection of a User's Opt-In status through '''AppTracking'''. Starting with Version 8.x+, the Nielsen App SDK will check the iOS version during initialization. If the device is running iOS12 or iOS13, the Limit Ad Tracking setting is requested. If iOS14.x +, then AppTracking is utilized.
==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global iOS SDK, this optOutURL informs the user how to deactivate/activate “App Tracking/Limit Ad Tracking”.

In addition, the following text must be included in your app store description.
<blockquote>"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information"</blockquote>

=== Global iOS SDK No Ad Framework Opt-out ===
The ''User Choice'' method can be used without the Ad Framework, or in situations where the publisher does not wish to use the [https://developer.apple.com/documentation/apptrackingtransparency App Tracking Transparency Framework]. As this flavor of the Nielsen SDK does not use the Ad Framework, so it is necessary to display an Optout Page to the user and capture their selection.

Similar to the Global iOS SDK Flavor, it is a requirement to display a WebView element whose loadUrl is set to the
value obtained from optOutURL. This is a special URL that indicates Opt-in, or Opt-out and close the WebView.

==== This opt-out method works as follows: ====
* Get the Nielsen opt-out URL via [[optOutURL]]
* Display a WebView element whose loadUrl is set to the value obtained from [[optOutURL]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut]] function
** Example: <syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Global iOS SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the [https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-iOS-App-SDK-GlobalNoId_latest.zip NoID version] of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt out selection:
<syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Opt-out example code ==
===== Swift =====
<syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

class OptOutVC: UIViewController, NielsenAppApiDelegate, WKNavigationDelegate {
var nielsenApi : NielsenAppApi!
var webView: WKWebView!

override func loadView() {
webView = WKWebView()
webView.navigationDelegate = self
view = webView
}

override func viewDidLoad() {
super.viewDidLoad()

if let appApi = self.nielsenApi {
//Getting the optPut URL from SDK
if let url = URL(string: appApi.optOutURL) {
webView.load(URLRequest(url: url))
webView.allowsBackForwardNavigationGestures = true
}}}

func closeOptOutView() {
self.dismiss(animated: true, completion: nil)
}

// Uncomment below code if you are using the Global iOS SDK No Ad Framework Flavor. This will receive the user's selection
// from the custom User_Choice Optout page. Only required for the Global iOS SDK No Ad Framework Flavor
/*
func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler:
@escaping (WKNavigationActionPolicy) -> Void) {
print(navigationAction.request.url?.absoluteString as Any) //For debugging to check what is being passed from webpage.
if navigationAction.request.url?.absoluteString == "nielsen://close" {
closeOptOutView()
decisionHandler(.cancel)
} else {
if let url = navigationAction.request.url?.absoluteString, url.hasPrefix("nielsen") {
nielsenApi?.userOptOut(url). //either nielsenappsdk://1 or nielsenappsdk://0
decisionHandler(.cancel)
} else {
if navigationAction.navigationType == .linkActivated {
if let url = navigationAction.request.url?.absoluteString, url.hasSuffix("#") {
decisionHandler(.allow)
} else {
decisionHandler(.cancel)
webView.load(navigationAction.request)
}
} else {
decisionHandler(.allow)
}}}}
*/
}

</syntaxhighlight>

===== Objective-C =====
<syntaxhighlight lang="objective-c">

#import "OptOutVC.h"
#import "NielsenInit.h"
#import <NielsenAppApi/NielsenAppApi.h>

@interface OptOutVC ()

@property (weak, nonatomic) IBOutlet UIWebView *webView;
@end

@implementation OptOutVC

- (void)viewDidLoad {
[super viewDidLoad];

- (void)viewDidLoad {
[super viewDidLoad];
//Getting the optPut URL from eventTracker
[self.webView loadRequest:[NSURLRequest requestWithURL:[NSURL
URLWithString:self.nielsenApi.optOutURL]]];
}

// Uncomment below code if you are using the Global iOS SDK No Ad Framework Flavor. This will receive the user's selection
// from the custom User_Choice Optout page. Only required for the Global iOS SDK No Ad Framework Flavor
/*
- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction
decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler
{
if ([navigationAction.request.URL.absoluteString isEqualToString:kNielsenWebClose])
{ [self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
decisionHandler(WKNavigationActionPolicyCancel);
} else {
if ([navigationAction.request.URL.absoluteString hasPrefix:@"nielsen"])
{[self.nielsenAppApi userOptOut:navigationAction.request.URL.absoluteString];
decisionHandler(WKNavigationActionPolicyCancel);
} else {
if (navigationAction.navigationType == WKNavigationTypeLinkActivated)
{ if ([navigationAction.request.URL.absoluteString hasSuffix:@"#"])
{decisionHandler(WKNavigationActionPolicyAllow);
} else {
decisionHandler(WKNavigationActionPolicyCancel);
[webView loadRequest:[NSURLRequest requestWithURL:navigationAction.request.URL]];
}} else {
decisionHandler(WKNavigationActionPolicyAllow);
}}}
*/
}

</syntaxhighlight>

== Retrieve current Opt-Out preference ==
Whether the user is opted out via OS-level Opt-out or via User Choice Opt-out, the current Opt-Out status as detected by the SDK is available via the [[optOutStatus]] property in the Nielsen SDK API
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus
</syntaxhighlight>

== Optional Step for AirPlay ==
To implement OTT measurement, report OTT changes to the SDK using public API interface: [[updateOTT]]

In order to detect AirPlay and mirroring changes we use AVAudioSessionPortDescription properties that are different on different iOS versions. We found that on iOS versions 8 - 10 <code>AVAudioSessionPortDescription</code> has the following values: 
<code>
AirPlay: type = AirPlay; name = Apple TV 4K; UID = DC:56:E7:53:72:85-airplay 
Mirroring: type = AirPlay; name = Apple TV 4K; UID = DC:56:E7:53:72:85-screen
</code> 

For iOS 11+ some parameters like name and UID have different values: 
<code>
AirPlay: type = AirPlay; name = AirPlay; UID = 0eb63aae-5915-45f1-b0f7-0102a0e50d53 
Mirroring: type = AirPlay; name = Apple TV 4K; UID = 4335E8A9-1C0A-4251-9000-28CA5FA2F3CF-192731714653291-screen 
</code>

The following code snipped is suggested for AirPlay / mirroring detection on iOS devices.

{{ExampleCode|
|Objective C =
<syntaxhighlight lang="objective-c">
– (void)updateOTT:(id)ottInfo;
</syntaxhighlight>
=== Subscribe to AVAudioSessionRouteChangeNotification ===
<syntaxhighlight lang="objective-c">
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handleRouteChanged:) name:AVAudioSessionRouteChangeNotification object:nil];
</syntaxhighlight>

=== Handle AVAudioSessionRouteChangeNotification and prepare OTT dictionary:===
<syntaxhighlight lang="objective-c">
- (void)handleRouteChanged:(NSNotification *)notification
{
NSMutableDictionary *ottDict = [NSMutableDictionary dictionaryWithDictionary: @{@"ottStatus": @"0"}];

AVAudioSession *audioSession = [AVAudioSession sharedInstance];
AVAudioSessionRouteDescription *currentRoute = audioSession.currentRoute;
for (AVAudioSessionPortDescription *outputPort in currentRoute.outputs) {
if ([outputPort.portType isEqualToString:AVAudioSessionPortAirPlay]) {
ottDict[@"ottStatus"] = @"1";
ottDict[@"ottDeviceModel"] = outputPort.portName;
ottDict[@"ottDeviceID"] = outputPort.UID;

if ([outputPort.portName isEqualToString:@"AirPlay"]) {
ottDict[@"ottDevice"] = @"airplay";
ottDict[@"ottType"] = @"airplay";
}
else {
if ([outputPort.portName containsString:@"Apple TV"]) {
ottDict[@"ottDevice"] = @"appleTV";
}
else {
ottDict[@"ottDevice"] = @"other";
}

if ([outputPort.UID hasSuffix:@"airplay"]) {
ottDict[@"ottType"] = @"airplay";
}
else if ([outputPort.UID hasSuffix:@"screen"]) {
ottDict[@"ottType"] = @"mirroring";
}
else {
ottDict[@"ottType"] = @"other";
}
}
}
}

// report OTT status update to Nielsen SDK
[self reportOTTWithDict:ottDict];
}
</syntaxhighlight>

=== Report OTT update to the Nielsen SDK ===
<syntaxhighlight lang="objective-c">
- (void)reportOTTWithDict:(NSDictionary *)ottDict
{
[self.nielsenSDK updateOTT:ottDict];
}
</syntaxhighlight>

|Swift =
<syntaxhighlight lang="swift">
nielsenSdk.updateOTT(currentStatus)
</syntaxhighlight>

=== Subscribe to AVAudioSessionRouteChangeNotification ===
<syntaxhighlight lang="swift">
NotificationCenter.default.addObserver(self, selector: #selector(handleRouteChanged(_:)), name: NSNotification.Name.AVAudioSessionRouteChange, object: nil)
</syntaxhighlight>

=== Handle AVAudioSessionRouteChangeNotification and prepare OTT dictionary:===

<syntaxhighlight lang ="Swift">
func handleRouteChanged(_ notification: Notification) {
var currentStatus: [String: String] = ["ottStatus": "0"]

let session = AVAudioSession.sharedInstance()
let currentRoute = session.currentRoute
for outputPort in currentRoute.outputs {
if outputPort.portType == AVAudioSessionPortAirPlay {
currentStatus["ottStatus"] = "1"
currentStatus["ottDeviceModel"] = outputPort.portName
currentStatus["ottDeviceID"] = outputPort.uid

if outputPort.portName == "AirPlay" {
currentStatus["ottDevice"] = "airplay"
currentStatus["ottType"] = "airplay"
}
else {
if outputPort.portName.contains("Apple TV") {
currentStatus["ottDevice"] = "appleTV"
}
else {
currentStatus["ottDevice"] = "other"
}

if outputPort.uid.hasSuffix("airplay") {
currentStatus["ottType"] = "airplay"
}
else if outputPort.uid.hasSuffix("screen") {
currentStatus["ottType"] = "mirroring"
}
else {
currentStatus["ottType"] = "other"
}
}
}
}

// report OTT status update to Nielsen SDK
self.reportOTTUpdate(currentStatus)
}
</syntaxhighlight>

=== Report OTT update to the Nielsen SDK===
<syntaxhighlight lang ="Swift">
func reportOTTUpdate(_ ottDict: [String: String]) {
if let nielsenSdk = self.nielsenAppApi {
nielsenSdk.updateOTT(currentStatus)
}
}
</syntaxhighlight>
}}

== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "imr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910685&ch=se-910685_c01_P&asn=defChnAsset&fp_id=a2nfmy17lyvkhlxqstvmgypqly90m1629966210&fp_cr_tm=1629966210&fp_acc_tm=1629966210&fp_emm_tm=1629966210&ve_id=20A7CFD5-9860-4256-A6CE-45C251F4C243&sessionId=yvx0rtsxydmaxueji8zgfzj0f2f1w1629966209&tl=&prv=1&c6=vc,c01&ca=se-910685_c01_51HERB1501&cg=Play%20%3E%20Webbtv%20%3E%20Nyheter&c13=asid,P3D8D326A-2DBC-486A-8FD8-9AF4452B2A41&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,Aftonbladet&plugv=&playerv=&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_00000&c9=devid,12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8&enc=true&c1=nuid,12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8&at=timer&rt=video&c16=sdkv,ai.8.1.0&c27=cln,15&crs=&lat=&lon=&c29=plid,16299662096458868&c30=bldv,ai.8.1.0.0_gsxaoni&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,iOS14.6&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,5.47.83.0.25245&c51=adl,15&c52=noad,1&sd=15&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=51HERB1501&c3=st,a&c64=starttm,1629966240&adid=51HERB1501&c58=isLive,false&c59=sesid,iqal6k21r0de8gm901kif5xznar7q1629966240&c61=createtm,1629966255&c63=pipMode,&ci_userid=&is_auto_play=&pl_title=&is_prem=&is_prog=&ad_origin=&adidx=1%2F1&is_tpad=&ci_passthr=&c62=sendTime,1629966255&c68=bndlid,se.aftonbladet.Aftonbladet&c69=cvw,&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&uoo=&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,iPhone9%2C4~~devtypid,iPhone9%2C4~~sysname,iOS~~sysversion,14.6~~manuf,Apple&cat_id=a6f7fb13-8801-484c-9692-6db6dfb470aa&vtoff=0&rnd=1629966255319</nowiki></code>

== Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Going Live ==
Following Nielsen testing, you will need to:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_devDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

DCR Sweden Video Android SDK

2021-09-06T15:09:41Z

ShangningWang: /* Required Privacy Links */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Overview ==
The Nielsen SDK is one of the multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like It supports a variety of Nielsen Measurement Products like Digital in TV Ratings ([[DCR & DTVR|DTVR]]), Digital Content Ratings ([[DCR & DTVR|DCR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a subsection/page in the application.
 
This ''SDK Android integration guide'' is applicable for '''Android TV''' as well.

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || "App ID (appid)" || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || "Nielsen SDK" || Includes SDK frameworks and "sample implementation"; "See [[Android SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Implementation ==
The Nielsen Android SDK comes in three flavors.

{| class="wikitable"
|-
! SDK Flavor
! Description
|-
| '''Android Ad Version'''
|* Opt-In and Opt-Out functionality managed by Opt out of Ads Personalization setting on device. * The Nielsen SDK will collect the [https://developer.android.com/training/articles/ad-id Google Advertising ID] unless the user Opts out. * If the Google Play Service is unavailable, (ie: Amazon and Huawei devices) the Nielsen SDK will secure the Android ID. * There are 3 versions available starting with the Nielsen SDK 8.1.0.0.
|-
| '''Android No Ad Framework'''
|* Without the Google Play Services SDK, the Nielsen SDK cannot read the Google Advertising ID, so will retrieve the Android ID. * The Android ID is a 64-bit number (expressed as a hexadecimal string), unique to each combination of app-signing key, user and device. * The developer is required to present the User Choice Opt-Out page which is described in the [[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]].
|-
| '''Android SDK noID'''
|* This version of the Nielsen SDK is perfect for Kid apps, or where no ID is required. * For the requirement, please review the [[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]].
|}

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# ""Initial state"" – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the ""Initial state"".
# ""Idle state"" – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# ""Processing state"" – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# ""Disabled state"" – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

=== Create Content Metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

 
<blockquote> program and title metadata values should be passed to SDK as UTF-8 strings. </blockquote>

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. || For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 

A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage]

For VoD, it does not need to follow the simulcast_channelnumber format.

Length limit: 20 characters. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters]
|| ✓ 

|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for 24/7 live stream, 86400
* for event-Live streams, the planned length
* for VoD, video length
|| ✓
|-
| program || Program Name, ns_st_pr || program name || custom '''example:''' leif-och-billy || ✓
|-
| title || Episode Name, ns_st_ep || episode name || custom '''example:''' en-ny-tjej-i-byn || ✓
|}

=== Create Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

Note: All metadata values should be passed as UTF-8 strings.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> <code>"ad"</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to an asset within the same media house. || custom (no [[Special Characters]]) || ✓
|}

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "My Channel Name 1"
}</syntaxhighlight>

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelInfo); </code> || // channelName contains JSON metadata of channel name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device.
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the No Ad version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

In addition, The following text must be included in your app store description.
<blockquote>"'''Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://nielsen.com/digitalprivacy/ for more information'''"</blockquote>

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the No Ad version or the No ID version.

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the No ID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Opt-out Sample Code ==
=== Global Android SDK Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://sites.nielsen.com/priv/browser/se/sv/optout.html for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "imr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

== Step 9 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

DCR Sweden Video Android SDK

2021-09-06T15:04:33Z

ShangningWang: /* Privacy and Opt-Out */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Overview ==
The Nielsen SDK is one of the multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like It supports a variety of Nielsen Measurement Products like Digital in TV Ratings ([[DCR & DTVR|DTVR]]), Digital Content Ratings ([[DCR & DTVR|DCR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a subsection/page in the application.
 
This ''SDK Android integration guide'' is applicable for '''Android TV''' as well.

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || "App ID (appid)" || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || "Nielsen SDK" || Includes SDK frameworks and "sample implementation"; "See [[Android SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Implementation ==
The Nielsen Android SDK comes in three flavors.

{| class="wikitable"
|-
! SDK Flavor
! Description
|-
| '''Android Ad Version'''
|* Opt-In and Opt-Out functionality managed by Opt out of Ads Personalization setting on device. * The Nielsen SDK will collect the [https://developer.android.com/training/articles/ad-id Google Advertising ID] unless the user Opts out. * If the Google Play Service is unavailable, (ie: Amazon and Huawei devices) the Nielsen SDK will secure the Android ID. * There are 3 versions available starting with the Nielsen SDK 8.1.0.0.
|-
| '''Android No Ad Framework'''
|* Without the Google Play Services SDK, the Nielsen SDK cannot read the Google Advertising ID, so will retrieve the Android ID. * The Android ID is a 64-bit number (expressed as a hexadecimal string), unique to each combination of app-signing key, user and device. * The developer is required to present the User Choice Opt-Out page which is described in the [[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]].
|-
| '''Android SDK noID'''
|* This version of the Nielsen SDK is perfect for Kid apps, or where no ID is required. * For the requirement, please review the [[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]].
|}

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# ""Initial state"" – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the ""Initial state"".
# ""Idle state"" – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# ""Processing state"" – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# ""Disabled state"" – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

=== Create Content Metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

 
<blockquote> program and title metadata values should be passed to SDK as UTF-8 strings. </blockquote>

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. || For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 

A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage]

For VoD, it does not need to follow the simulcast_channelnumber format.

Length limit: 20 characters. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters]
|| ✓ 

|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for 24/7 live stream, 86400
* for event-Live streams, the planned length
* for VoD, video length
|| ✓
|-
| program || Program Name, ns_st_pr || program name || custom '''example:''' leif-och-billy || ✓
|-
| title || Episode Name, ns_st_ep || episode name || custom '''example:''' en-ny-tjej-i-byn || ✓
|}

=== Create Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

Note: All metadata values should be passed as UTF-8 strings.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> <code>"ad"</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to an asset within the same media house. || custom (no [[Special Characters]]) || ✓
|}

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "My Channel Name 1"
}</syntaxhighlight>

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelInfo); </code> || // channelName contains JSON metadata of channel name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device.
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the No Ad version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

In addition, The following text must be included in your app store description.
<blockquote>"'''Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://nielsen.com/digitalprivacy/ for more information'''"</blockquote>

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the No Ad version or the No ID version.

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the No ID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Opt-out Sample Code ==
=== Global Android SDK Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://www.nielsen.com/us/en/legal/privacy-statement/digital-measurement/ for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "imr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

== Step 9 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

DCR Sweden Video Android SDK

2021-09-06T15:01:09Z

ShangningWang: /* Implementation */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Overview ==
The Nielsen SDK is one of the multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like It supports a variety of Nielsen Measurement Products like Digital in TV Ratings ([[DCR & DTVR|DTVR]]), Digital Content Ratings ([[DCR & DTVR|DCR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a subsection/page in the application.
 
This ''SDK Android integration guide'' is applicable for '''Android TV''' as well.

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || "App ID (appid)" || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || "Nielsen SDK" || Includes SDK frameworks and "sample implementation"; "See [[Android SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Implementation ==
The Nielsen Android SDK comes in three flavors.

{| class="wikitable"
|-
! SDK Flavor
! Description
|-
| '''Android Ad Version'''
|* Opt-In and Opt-Out functionality managed by Opt out of Ads Personalization setting on device. * The Nielsen SDK will collect the [https://developer.android.com/training/articles/ad-id Google Advertising ID] unless the user Opts out. * If the Google Play Service is unavailable, (ie: Amazon and Huawei devices) the Nielsen SDK will secure the Android ID. * There are 3 versions available starting with the Nielsen SDK 8.1.0.0.
|-
| '''Android No Ad Framework'''
|* Without the Google Play Services SDK, the Nielsen SDK cannot read the Google Advertising ID, so will retrieve the Android ID. * The Android ID is a 64-bit number (expressed as a hexadecimal string), unique to each combination of app-signing key, user and device. * The developer is required to present the User Choice Opt-Out page which is described in the [[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]].
|-
| '''Android SDK noID'''
|* This version of the Nielsen SDK is perfect for Kid apps, or where no ID is required. * For the requirement, please review the [[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]].
|}

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# ""Initial state"" – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the ""Initial state"".
# ""Idle state"" – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# ""Processing state"" – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# ""Disabled state"" – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

=== Create Content Metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

 
<blockquote> program and title metadata values should be passed to SDK as UTF-8 strings. </blockquote>

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. || For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 

A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage]

For VoD, it does not need to follow the simulcast_channelnumber format.

Length limit: 20 characters. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters]
|| ✓ 

|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for 24/7 live stream, 86400
* for event-Live streams, the planned length
* for VoD, video length
|| ✓
|-
| program || Program Name, ns_st_pr || program name || custom '''example:''' leif-och-billy || ✓
|-
| title || Episode Name, ns_st_ep || episode name || custom '''example:''' en-ny-tjej-i-byn || ✓
|}

=== Create Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

Note: All metadata values should be passed as UTF-8 strings.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> <code>"ad"</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to an asset within the same media house. || custom (no [[Special Characters]]) || ✓
|}

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "My Channel Name 1"
}</syntaxhighlight>

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelInfo); </code> || // channelName contains JSON metadata of channel name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device ('''preferred approach''').
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the noAd version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

In addition, The following text must be included in your app store description.
<blockquote>"'''Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://nielsen.com/digitalprivacy/ for more information'''"</blockquote>

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the noAd version or the NoID version.
<blockquote>
Nielsen Android SDK 5.1.1.18 and above will check for ''OS-level opt-out'' first, if available. The user will be opted out if indicated at the OS-level '''OR''' the App-level.</blockquote>

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the NoID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Opt-out Sample Code ==
=== Global Android SDK Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://www.nielsen.com/us/en/legal/privacy-statement/digital-measurement/ for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "imr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

== Step 9 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

DCR Sweden Video Android SDK

2021-09-06T14:59:54Z

ShangningWang: /* Implementation */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Overview ==
The Nielsen SDK is one of the multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like It supports a variety of Nielsen Measurement Products like Digital in TV Ratings ([[DCR & DTVR|DTVR]]), Digital Content Ratings ([[DCR & DTVR|DCR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a subsection/page in the application.
 
This ''SDK Android integration guide'' is applicable for '''Android TV''' as well.

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || "App ID (appid)" || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || "Nielsen SDK" || Includes SDK frameworks and "sample implementation"; "See [[Android SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Implementation ==
The Nielsen Android SDK comes in three flavors.

{| class="wikitable"
|-
! SDK Flavor
! Description
|-
| '''Android Ad Version'''
|* Opt-In and Opt-Out functionality managed by Opt out of Ads Personalization setting on device. * The Nielsen SDK will collect the [https://developer.android.com/training/articles/ad-id Google Advertising ID] unless the user Opts out. * If the Google Play Service is unavailable, (ie: Amazon and Huawei devices) the Nielsen SDK will secure the Android ID. * There are 3 versions available starting with the Nielsen SDK 8.1.0.0.
|-
| '''Android No Ad Framework'''
|* Without the Google Play Services SDK, the Nielsen SDK cannot read the Google Advertising ID, so will retrieve the Android ID. * The Android ID is a 64-bit number (expressed as a hexadecimal string), unique to each combination of app-signing key, user and device. * The developer is required to present the User Choice Opt-Out page which is described in the [[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]].
|-
| '''Android SDK noID'''
|* This version of the Nielsen SDK is perfect for Kid apps, or where no ID is required. * For the requirement, please review the [[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]].
|}

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# ""Initial state"" – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the ""Initial state"".
# ""Idle state"" – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# ""Processing state"" – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# ""Disabled state"" – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

=== Create Content Metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

 
<blockquote> program and title metadata values should be passed to SDK as UTF-8 strings. </blockquote>

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. || For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 

A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage]

For VoD, it does not need to follow the simulcast_channelnumber format.

Length limit: 20 characters. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters]
|| ✓ 

|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for 24/7 live stream, 86400
* for event-Live streams, the planned length
* for VoD, video length
|| ✓
|-
| program || Program Name, ns_st_pr || program name || custom '''example:''' leif-och-billy || ✓
|-
| title || Episode Name, ns_st_ep || episode name || custom '''example:''' en-ny-tjej-i-byn || ✓
|}

=== Create Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

Note: All metadata values should be passed as UTF-8 strings.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> <code>"ad"</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to an asset within the same media house. || custom (no [[Special Characters]]) || ✓
|}

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "My Channel Name 1"
}</syntaxhighlight>

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelInfo); </code> || // channelName contains JSON metadata of channel name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device ('''preferred approach''').
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the noAd version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

In addition, The following text must be included in your app store description.
<blockquote>"'''Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://nielsen.com/digitalprivacy/ for more information'''"</blockquote>

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the noAd version or the NoID version.
<blockquote>
Nielsen Android SDK 5.1.1.18 and above will check for ''OS-level opt-out'' first, if available. The user will be opted out if indicated at the OS-level '''OR''' the App-level.</blockquote>

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the NoID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Opt-out Sample Code ==
=== Global Android SDK Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://www.nielsen.com/us/en/legal/privacy-statement/digital-measurement/ for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "imr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

== Step 9 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

DCR Sweden Video Android SDK

2021-09-06T14:59:10Z

ShangningWang: /* Implementation */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Overview ==
The Nielsen SDK is one of the multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like It supports a variety of Nielsen Measurement Products like Digital in TV Ratings ([[DCR & DTVR|DTVR]]), Digital Content Ratings ([[DCR & DTVR|DCR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a subsection/page in the application.
 
This ''SDK Android integration guide'' is applicable for '''Android TV''' as well.

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || "App ID (appid)" || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || "Nielsen SDK" || Includes SDK frameworks and "sample implementation"; "See [[Android SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Implementation ==
The Nielsen Android SDK comes in three flavors.

{| class="wikitable"
|-
! SDK Flavor
! Description
|-
| '''Android Ad Version'''
|* Opt-In and Opt-Out functionality managed by Opt out of Ads Personalization setting on device. * The Nielsen SDK will collect the [https://developer.android.com/training/articles/ad-id Google Advertising ID] unless the user Opts out. * If the Google Play Service is unavailable, (ie: Amazon and Huawei devices) the Nielsen SDK will secure the Android ID. * There are 3 versions available starting with the Nielsen SDK 8.1.0.0.
|-
| '''Android No Ad Framework'''
|* Without the Google Play Services SDK, the Nielsen SDK cannot read the Google Advertising ID, so will retrieve the Android ID. * The Android ID is a 64-bit number (expressed as a hexadecimal string), unique to each combination of app-signing key, user and device. * The developer is required to present the User Choice Opt-Out page which is described in the [[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]].
|-
| '''Android SDK noID'''
|* This version of the Nielsen SDK is perfect for Kid apps, or where no ID is required. * For the requirement, please review the [https://engineeringportal.nielsen.com//docs/DCR_Sweden_Video_Android_SDK#Global_Android_SDK_No_ID_Optout Global Android SDK No ID Opt-out].
|}

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# ""Initial state"" – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the ""Initial state"".
# ""Idle state"" – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# ""Processing state"" – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# ""Disabled state"" – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

=== Create Content Metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

 
<blockquote> program and title metadata values should be passed to SDK as UTF-8 strings. </blockquote>

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. || For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 

A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage]

For VoD, it does not need to follow the simulcast_channelnumber format.

Length limit: 20 characters. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters]
|| ✓ 

|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for 24/7 live stream, 86400
* for event-Live streams, the planned length
* for VoD, video length
|| ✓
|-
| program || Program Name, ns_st_pr || program name || custom '''example:''' leif-och-billy || ✓
|-
| title || Episode Name, ns_st_ep || episode name || custom '''example:''' en-ny-tjej-i-byn || ✓
|}

=== Create Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

Note: All metadata values should be passed as UTF-8 strings.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> <code>"ad"</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to an asset within the same media house. || custom (no [[Special Characters]]) || ✓
|}

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "My Channel Name 1"
}</syntaxhighlight>

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelInfo); </code> || // channelName contains JSON metadata of channel name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device ('''preferred approach''').
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the noAd version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

In addition, The following text must be included in your app store description.
<blockquote>"'''Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://nielsen.com/digitalprivacy/ for more information'''"</blockquote>

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the noAd version or the NoID version.
<blockquote>
Nielsen Android SDK 5.1.1.18 and above will check for ''OS-level opt-out'' first, if available. The user will be opted out if indicated at the OS-level '''OR''' the App-level.</blockquote>

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the NoID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Opt-out Sample Code ==
=== Global Android SDK Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://www.nielsen.com/us/en/legal/privacy-statement/digital-measurement/ for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "imr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

== Step 9 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

DCR Sweden Video Android SDK

2021-09-06T14:53:31Z

ShangningWang: /* Implementation */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Overview ==
The Nielsen SDK is one of the multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like It supports a variety of Nielsen Measurement Products like Digital in TV Ratings ([[DCR & DTVR|DTVR]]), Digital Content Ratings ([[DCR & DTVR|DCR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a subsection/page in the application.
 
This ''SDK Android integration guide'' is applicable for '''Android TV''' as well.

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || "App ID (appid)" || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || "Nielsen SDK" || Includes SDK frameworks and "sample implementation"; "See [[Android SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Implementation ==
The Nielsen Android SDK comes in three flavors.

{| class="wikitable"
|-
! SDK Flavor
! Description
|-
| '''Android Ad Version'''
|* Opt-In and Opt-Out functionality managed by Opt out of Ads Personalization setting on device. * The Nielsen SDK will collect the [https://developer.android.com/training/articles/ad-id Google Advertising ID] unless the user Opts out. * If the Google Play Service is unavailable, (ie: Amazon and Huawei devices) the Nielsen SDK will secure the Android ID. * There are 3 versions available starting with the Nielsen SDK 8.1.0.0.
|-
| '''Android No Ad Framework'''
|* Without the Google Play Services SDK, the Nielsen SDK cannot read the Google Advertising ID, so will retrieve the Android ID. * The Android ID is a 64-bit number (expressed as a hexadecimal string), unique to each combination of app-signing key, user and device. * The developer is required to present the User Choice Opt-Out page which is described in the [https://engineeringportal.nielsen.com//docs/DCR_Sweden_Video_Android_SDK#Global_Android_SDK_No_Ad_Framework_Optout Global Android SDK No Ad Framework Opt-out].
|-
| '''Android SDK noID'''
|* This version of the Nielsen SDK is perfect for Kid apps, or where no ID is required. * For the requirement, please review the [https://engineeringportal.nielsen.com//docs/DCR_Sweden_Video_Android_SDK#Global_Android_SDK_No_ID_Optout Global Android SDK No ID Opt-out].
|}

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# ""Initial state"" – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the ""Initial state"".
# ""Idle state"" – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# ""Processing state"" – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# ""Disabled state"" – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

=== Create Content Metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

 
<blockquote> program and title metadata values should be passed to SDK as UTF-8 strings. </blockquote>

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. || For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 

A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage]

For VoD, it does not need to follow the simulcast_channelnumber format.

Length limit: 20 characters. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters]
|| ✓ 

|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for 24/7 live stream, 86400
* for event-Live streams, the planned length
* for VoD, video length
|| ✓
|-
| program || Program Name, ns_st_pr || program name || custom '''example:''' leif-och-billy || ✓
|-
| title || Episode Name, ns_st_ep || episode name || custom '''example:''' en-ny-tjej-i-byn || ✓
|}

=== Create Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

Note: All metadata values should be passed as UTF-8 strings.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> <code>"ad"</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to an asset within the same media house. || custom (no [[Special Characters]]) || ✓
|}

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "My Channel Name 1"
}</syntaxhighlight>

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelInfo); </code> || // channelName contains JSON metadata of channel name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device ('''preferred approach''').
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the noAd version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

In addition, The following text must be included in your app store description.
<blockquote>"'''Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://nielsen.com/digitalprivacy/ for more information'''"</blockquote>

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the noAd version or the NoID version.
<blockquote>
Nielsen Android SDK 5.1.1.18 and above will check for ''OS-level opt-out'' first, if available. The user will be opted out if indicated at the OS-level '''OR''' the App-level.</blockquote>

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the NoID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Opt-out Sample Code ==
=== Global Android SDK Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://www.nielsen.com/us/en/legal/privacy-statement/digital-measurement/ for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "imr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

== Step 9 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

DCR Sweden Video Android SDK

2021-09-06T14:51:24Z

ShangningWang: /* Implementation */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Overview ==
The Nielsen SDK is one of the multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like It supports a variety of Nielsen Measurement Products like Digital in TV Ratings ([[DCR & DTVR|DTVR]]), Digital Content Ratings ([[DCR & DTVR|DCR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a subsection/page in the application.
 
This ''SDK Android integration guide'' is applicable for '''Android TV''' as well.

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || "App ID (appid)" || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || "Nielsen SDK" || Includes SDK frameworks and "sample implementation"; "See [[Android SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Implementation ==
The Nielsen Android SDK comes in three flavors.

{| class="wikitable"
|-
! SDK Flavor
! Description
|-
| '''Android Ad Version'''
|* Opt-In and Opt-Out functionality managed by Opt out of Ads Personalization setting on device. * The Nielsen SDK will collect the [https://developer.android.com/training/articles/ad-id Google Advertising ID] unless the user Opts out. * If the Google Play Service is unavailable, (ie: Amazon and Huawei devices) the Nielsen SDK will secure the Android ID. * There are 3 versions available starting with the Nielsen SDK 8.1.0.0.
|-
| '''Android No Ad Framework'''
|* Without the Ad Framework, the Nielsen SDK cannot read the Google Advertising ID, so will retrieve the Android ID. * The Android ID is a 64-bit number (expressed as a hexadecimal string), unique to each combination of app-signing key, user and device. * The developer is required to present the User Choice Opt-Out page which is described in the [https://engineeringportal.nielsen.com//docs/DCR_Sweden_Video_Android_SDK#Global_Android_SDK_No_Ad_Framework_Optout Global Android SDK No Ad Framework Opt-out].
|-
| '''Android SDK noID'''
|* This version of the Nielsen SDK is perfect for Kid apps, or where no ID is required. * For the requirement, please review the [https://engineeringportal.nielsen.com//docs/DCR_Sweden_Video_Android_SDK#Global_Android_SDK_No_ID_Optout Global Android SDK No ID Opt-out].
|}

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# ""Initial state"" – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the ""Initial state"".
# ""Idle state"" – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# ""Processing state"" – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# ""Disabled state"" – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

=== Create Content Metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

 
<blockquote> program and title metadata values should be passed to SDK as UTF-8 strings. </blockquote>

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. || For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 

A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage]

For VoD, it does not need to follow the simulcast_channelnumber format.

Length limit: 20 characters. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters]
|| ✓ 

|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for 24/7 live stream, 86400
* for event-Live streams, the planned length
* for VoD, video length
|| ✓
|-
| program || Program Name, ns_st_pr || program name || custom '''example:''' leif-och-billy || ✓
|-
| title || Episode Name, ns_st_ep || episode name || custom '''example:''' en-ny-tjej-i-byn || ✓
|}

=== Create Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

Note: All metadata values should be passed as UTF-8 strings.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> <code>"ad"</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to an asset within the same media house. || custom (no [[Special Characters]]) || ✓
|}

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "My Channel Name 1"
}</syntaxhighlight>

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelInfo); </code> || // channelName contains JSON metadata of channel name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device ('''preferred approach''').
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the noAd version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

In addition, The following text must be included in your app store description.
<blockquote>"'''Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://nielsen.com/digitalprivacy/ for more information'''"</blockquote>

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the noAd version or the NoID version.
<blockquote>
Nielsen Android SDK 5.1.1.18 and above will check for ''OS-level opt-out'' first, if available. The user will be opted out if indicated at the OS-level '''OR''' the App-level.</blockquote>

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the NoID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Opt-out Sample Code ==
=== Global Android SDK Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://www.nielsen.com/us/en/legal/privacy-statement/digital-measurement/ for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "imr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

== Step 9 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

DCR Sweden Video Android SDK

2021-09-06T13:14:40Z

ShangningWang: /* Guide */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Overview ==
The Nielsen SDK is one of the multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like It supports a variety of Nielsen Measurement Products like Digital in TV Ratings ([[DCR & DTVR|DTVR]]), Digital Content Ratings ([[DCR & DTVR|DCR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a subsection/page in the application.
 
This ''SDK Android integration guide'' is applicable for '''Android TV''' as well.

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || "App ID (appid)" || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || "Nielsen SDK" || Includes SDK frameworks and "sample implementation"; "See [[Android SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Implementation ==
The Nielsen Android SDK comes in three versions.

{| class="wikitable"
|-
! SDK Flavor
! Description
|-
| '''Android Ad Version'''
|* Opt-In and Opt-Out functionality managed by Opt out of Ads Personalization setting on device. * The Nielsen SDK will collect the [https://developer.android.com/training/articles/ad-id Google Advertising ID] unless the user Opts out. * If the Google Play Service is unavailable, (ie: Amazon and Huawei devices) the Nielsen SDK will secure the Android ID. * There are 3 versions available starting with the Nielsen SDK 8.1.0.0.
|-
| '''Android No Ad Framework'''
|* Without the Ad Framework, the Nielsen SDK cannot read the Google Advertising ID, so will retrieve the Android ID. * The Android ID is a 64-bit number (expressed as a hexadecimal string), unique to each combination of app-signing key, user and device. * The developer is required to present the User Choice Opt-Out page which is described in the [https://engineeringportal.nielsen.com//docs/DCR_Sweden_Video_Android_SDK#Global_Android_SDK_No_Ad_Framework_Optout Global Android SDK No Ad Framework Opt-out].
|-
| '''Android SDK noID'''
|* This version of the Nielsen SDK is perfect for Kid apps, or where no ID is required. * For the requirement, please review the [https://engineeringportal.nielsen.com//docs/DCR_Sweden_Video_Android_SDK#Global_Android_SDK_No_ID_Optout Global Android SDK No ID Opt-out].
|}

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# ""Initial state"" – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the ""Initial state"".
# ""Idle state"" – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# ""Processing state"" – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# ""Disabled state"" – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

=== Create Content Metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

 
<blockquote> program and title metadata values should be passed to SDK as UTF-8 strings. </blockquote>

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. || For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 

A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage]

For VoD, it does not need to follow the simulcast_channelnumber format.

Length limit: 20 characters. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters]
|| ✓ 

|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for 24/7 live stream, 86400
* for event-Live streams, the planned length
* for VoD, video length
|| ✓
|-
| program || Program Name, ns_st_pr || program name || custom '''example:''' leif-och-billy || ✓
|-
| title || Episode Name, ns_st_ep || episode name || custom '''example:''' en-ny-tjej-i-byn || ✓
|}

=== Create Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

Note: All metadata values should be passed as UTF-8 strings.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> <code>"ad"</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to an asset within the same media house. || custom (no [[Special Characters]]) || ✓
|}

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "My Channel Name 1"
}</syntaxhighlight>

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelInfo); </code> || // channelName contains JSON metadata of channel name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device ('''preferred approach''').
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the noAd version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

In addition, The following text must be included in your app store description.
<blockquote>"'''Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://nielsen.com/digitalprivacy/ for more information'''"</blockquote>

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the noAd version or the NoID version.
<blockquote>
Nielsen Android SDK 5.1.1.18 and above will check for ''OS-level opt-out'' first, if available. The user will be opted out if indicated at the OS-level '''OR''' the App-level.</blockquote>

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the NoID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Opt-out Sample Code ==
=== Global Android SDK Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://www.nielsen.com/us/en/legal/privacy-statement/digital-measurement/ for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "imr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

== Step 9 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

DCR Sweden Video iOS SDK

2021-09-06T13:13:59Z

ShangningWang: /* Test your player by yourself */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

__TOC__

== Overview ==
The Nielsen SDK is one of the multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like Digital in TV Ratings ([[DCR & DTVR|DTVR]]), Digital Content Ratings ([[DCR & DTVR|DCR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || '''Nielsen SDK''' || Includes SDK frameworks and '''sample implementation'''; "See [[iOS SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Implementation ==
Version 8 of the Nielsen App SDK comes in three versions. One that is enabled to work with the App Tracking Transparency Framework, another version that does not use the Ad Framework, and a version for Kids Apps or where no ID is required.

{| class="wikitable"
|-
! SDK Flavor
! Description
|-
| '''iOS Ad Version'''
|* Opt-In and Opt-Out functionality managed by the [https://developer.apple.com/documentation/apptrackingtransparency AppTrackingTransparency framework]. * The Nielsen SDK will attempt to collect the IDFA (Id for Advertisers) on the device. * For iOS14+, if the value returned is <code>ATTrackingManager.AuthorizationStatus.authorized</code>. * If the device is running iOS12 or iOS13, the Limit Ad Tracking setting is requested.
|-
| '''iOS No Ad Framework'''
|* Without the Ad Framework, the Nielsen SDK cannot read the IDFA, so it will attempt to retrieve the [https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor ID for Vendors (IDFV)]. * The IDFV may be used for analytics across apps from the same content provider. * The developer is required to present the User Choice Optout page. The detailed requirement is described in the [https://engineeringportal.nielsen.com//docs/DCR_Sweden_Video_iOS_SDK#Global_iOS_SDK_No_Ad_Framework_Opt-out Global iOS SDK No Ad Framework Opt-out] Section.
|-
| '''iOS SDK No ID'''
|* This version of the Nielsen SDK is perfect for Kid apps, or where no ID is required. * Please review the [https://engineeringportal.nielsen.com/docs/DCR_Sweden_Video_iOS_SDK#Global_iOS_SDK_No_ID_Opt-out Global iOS SDK No ID Opt-out] Section.
|}
=== How to obtain the NielsenAppApi.Framework ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of CocoaPods. We recommend using the CocoaPods-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_iOS_Artifactory_Guide|Select to obtain CocoaPods implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
* [[DCR_Video_iOS_SDK_xcframework|Using the XCFramework bundle]]

== Setting up your iOS Development Environment ==

=== Configuring Xcode Development Environment ===
Starting with SDK version 6.0.0.0, the Nielsen App SDK is compatible with Apple iOS versions 8.0 and above. In addition, the SDK uses the WKWebView class instead of the deprecated UIWebView as per Apple guidelines.

=== Importing Frameworks ===

1) Extract “NielsenAppApi.Framework” from the Nielsen App SDK zip file and copy it to Frameworks folder of the Xcode project. 

2) Import following frameworks and libraries into the Frameworks of the Xcode project before creating an instance of the Nielsen App SDK object.
* UIKit.framework
* Foundation.framework
* AdSupport.framework
* SystemConfiguration.framework
* Security.framework
** Nielsen Analytics framework makes use of a number of functions in this library.
* AVFoundation.framework
** This framework is mandatory for the iOS SDK version 5.1.1 to work.
* CoreLocation.framework
* CoreMedia.framework
* NielsenAppApi.framework
* libc++.tbd (as SDK contains Objective-C++ source file)
** Alternatively, include -lstdc++ in Build Settings → Other Linker Flag of the Xcode project 

3) Include header file <code>NielsenAppApi/NielsenAppApi.h</code> to the View Controller's header file. 

Note:
* The SDK uses the NSURLSession instead of the deprecated NSURLConnection.
* All communications between the SDK and the Census (Collection Facility) use HTTPS
 
==== Using Swift ====
To import a set of Objective-C files in the same app target as your Swift code, you rely on an Objective-C bridging header to expose those files to Swift. Xcode offers to create this header file when you add a Swift file to an existing Objective-C app, or an Objective-C file to an existing Swift app.

Select File/New File/Objective-C File 
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] 
Once this file has been created, you need to add the following:
<syntaxhighlight lang="swift">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>

==== Using Objective-C ====
Add the code
<syntaxhighlight lang ="objective-c">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
to the View Controller’s header file.
 

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

==== Sample SDK Initialization Code ====

Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>If App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.</blockquote>

===== Using Objective-C=====
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appversion": "1.0",
@"appname": "app name here",
@"nol_devDebug": @"DEBUG",
@"hem_md5": @"61f1121944dfb76f09540c59a99b4000"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

===== Using Swift =====

<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"appversion": "1.0",
"appname": "app name here",
"nol_devDebug": "DEBUG",
"hem_md5": "61f1121944dfb76f09540c59a99b4000"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
 
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# '''Processing state''' – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called

<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted NSString or a NSDictionary object. The JSON passed in the SDK must be well-formed.
* NSDictionary object
** If an object of unexpected type is passed to the method, the error message will be logged.
** If string has invalid JSON format, the error message will be logged.
* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

=== Create Content Metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play. 

Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

 
<blockquote> program and title metadata values should be passed to SDK as UTF-8 strings. </blockquote>

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. || For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 

A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage]

For VoD, it does not need to follow the simulcast_channelnumber format.

Length limit: 20 characters. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters]
|| ✓ 

|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for 24/7 live stream, 86400
* for event-Live streams, the planned length
* for VoD, video length
|| ✓
|-
| program || Program Name, ns_st_pr || program name || custom '''example:''' leif-och-billy || ✓
|-
| title || Episode Name, ns_st_ep || episode name || custom '''example:''' en-ny-tjej-i-byn || ✓
|}

=== Create Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad. 

Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

Note: All metadata values should be passed as UTF-8 strings.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> <code>"ad"</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to an asset within the same media house. || custom (no [[Special Characters]]) || ✓
|}

=== MetaData Example ===

==== Using Objective-C ====
<syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @
{
@"assetid" : "uniqueassetid",
@"type" : "content",
@"program" : "program name",
@"title" : "episode title",
@"length" : "2600"
}

NSDictionary *adMetadata = @
{
@"assetid" : "uniquepostrolladid",
@"type" : "postroll"
}
</syntaxhighlight>

==== Using Swift ====
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
]

let contentMetadata = [
"assetid" : "uniqueassetid",
"type" : "content",
"program" : "program name",
"title" : "episode title",
"length" : "2600"
]

let adMetadata = [
"assetid" : "uniquepostrolladid",
"type" : "postroll"
]

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player. Call play only when initially starting the video.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi play:channelInfo];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.play(channelInfo);</syntaxhighlight>
 

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi loadMetadata:metadataDict];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(metadataDict)</syntaxhighlight>
 

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">
[self.nielsenAppApi playheadPosition:pos];
</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">
self.nielsenAppApi?.playheadPosition(pos);
</syntaxhighlight>
 

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi stop];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.stop;</syntaxhighlight>
 

==== end ====
Call when the content asset completes playback. Stops measurement progress.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi end];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.end</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[playheadPosition|playheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelName); </code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad_123",
...
}</syntaxhighlight>
<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[playheadPosition|playheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelName); </code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third-party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Privacy and Opt-Out ==

There are currently 3 flavors of the Nielsen SDK. Please check the "Implementation" section for a comparison of the three flavors. Implementing opt-out for the three flavors are different:
# '''[[#Global_iOS_SDK_Opt-out|Global iOS SDK Opt-out]]''' - managed by ''AppTracking'' or ''Limit Ad Tracking'' setting on device.
# '''[[#Global_iOS_SDK_No_Ad_Framework_Opt-out|Global iOS SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without the Ad Framework.
# '''[[#Global_iOS_SDK_No_ID_Opt-out|Global iOS SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.
__NOTOC__
=== Global iOS SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen iOS

The Nielsen SDK automatically leverages the iOS's '''Limit Ad Tracking''' or '''AppTracking''' setting.
* If the User's device is running < iOS 13.x, the Nielsen SDK will check the status of '''Limit Ad Tracking'''.
* iOS14 modifies the way Apple manages the collection of a User's Opt-In status through '''AppTracking'''. Starting with Version 8.x+, the Nielsen App SDK will check the iOS version during initialization. If the device is running iOS12 or iOS13, the Limit Ad Tracking setting is requested. If iOS14.x +, then AppTracking is utilized.
==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global iOS SDK, this optOutURL informs the user how to deactivate/activate “App Tracking/Limit Ad Tracking”.

In addition, the following text must be included in your app store description.
<blockquote>"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://nielsen.com/digitalprivacy/ for more information"</blockquote>

=== Global iOS SDK No Ad Framework Opt-out ===
The ''User Choice'' method can be used without the Ad Framework, or in situations where the publisher does not wish to use the [https://developer.apple.com/documentation/apptrackingtransparency App Tracking Transparency Framework]. As this flavor of the Nielsen SDK does not use the Ad Framework, so it is necessary to display an Optout Page to the user and capture their selection.

Similar to the Global iOS SDK Flavor, it is a requirement to display a WebView element whose loadUrl is set to the
value obtained from optOutURL. This is a special URL that indicates Opt-in, or Opt-out and close the WebView.

==== This opt-out method works as follows: ====
* Get the Nielsen opt-out URL via [[optOutURL]]
* Display a WebView element whose loadUrl is set to the value obtained from [[optOutURL]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut]] function
** Example: <syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Global iOS SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the [https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-iOS-App-SDK-GlobalNoId_latest.zip NoID version] of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt out selection:
<syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Opt-out example code ==
===== Swift =====
<syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

class OptOutVC: UIViewController, NielsenAppApiDelegate, WKNavigationDelegate {
var nielsenApi : NielsenAppApi!
var webView: WKWebView!

override func loadView() {
webView = WKWebView()
webView.navigationDelegate = self
view = webView
}

override func viewDidLoad() {
super.viewDidLoad()

if let appApi = self.nielsenApi {
//Getting the optPut URL from SDK
if let url = URL(string: appApi.optOutURL) {
webView.load(URLRequest(url: url))
webView.allowsBackForwardNavigationGestures = true
}}}

func closeOptOutView() {
self.dismiss(animated: true, completion: nil)
}

// Uncomment below code if you are using the Global iOS SDK No Ad Framework Flavor. This will receive the user's selection
// from the custom User_Choice Optout page. Only required for the Global iOS SDK No Ad Framework Flavor
/*
func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler:
@escaping (WKNavigationActionPolicy) -> Void) {
print(navigationAction.request.url?.absoluteString as Any) //For debugging to check what is being passed from webpage.
if navigationAction.request.url?.absoluteString == "nielsen://close" {
closeOptOutView()
decisionHandler(.cancel)
} else {
if let url = navigationAction.request.url?.absoluteString, url.hasPrefix("nielsen") {
nielsenApi?.userOptOut(url). //either nielsenappsdk://1 or nielsenappsdk://0
decisionHandler(.cancel)
} else {
if navigationAction.navigationType == .linkActivated {
if let url = navigationAction.request.url?.absoluteString, url.hasSuffix("#") {
decisionHandler(.allow)
} else {
decisionHandler(.cancel)
webView.load(navigationAction.request)
}
} else {
decisionHandler(.allow)
}}}}
*/
}

</syntaxhighlight>

===== Objective-C =====
<syntaxhighlight lang="objective-c">

#import "OptOutVC.h"
#import "NielsenInit.h"
#import <NielsenAppApi/NielsenAppApi.h>

@interface OptOutVC ()

@property (weak, nonatomic) IBOutlet UIWebView *webView;
@end

@implementation OptOutVC

- (void)viewDidLoad {
[super viewDidLoad];

- (void)viewDidLoad {
[super viewDidLoad];
//Getting the optPut URL from eventTracker
[self.webView loadRequest:[NSURLRequest requestWithURL:[NSURL
URLWithString:self.nielsenApi.optOutURL]]];
}

// Uncomment below code if you are using the Global iOS SDK No Ad Framework Flavor. This will receive the user's selection
// from the custom User_Choice Optout page. Only required for the Global iOS SDK No Ad Framework Flavor
/*
- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction
decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler
{
if ([navigationAction.request.URL.absoluteString isEqualToString:kNielsenWebClose])
{ [self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
decisionHandler(WKNavigationActionPolicyCancel);
} else {
if ([navigationAction.request.URL.absoluteString hasPrefix:@"nielsen"])
{[self.nielsenAppApi userOptOut:navigationAction.request.URL.absoluteString];
decisionHandler(WKNavigationActionPolicyCancel);
} else {
if (navigationAction.navigationType == WKNavigationTypeLinkActivated)
{ if ([navigationAction.request.URL.absoluteString hasSuffix:@"#"])
{decisionHandler(WKNavigationActionPolicyAllow);
} else {
decisionHandler(WKNavigationActionPolicyCancel);
[webView loadRequest:[NSURLRequest requestWithURL:navigationAction.request.URL]];
}} else {
decisionHandler(WKNavigationActionPolicyAllow);
}}}
*/
}

</syntaxhighlight>

== Retrieve current Opt-Out preference ==
Whether the user is opted out via OS-level Opt-out or via User Choice Opt-out, the current Opt-Out status as detected by the SDK is available via the [[optOutStatus]] property in the Nielsen SDK API
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus
</syntaxhighlight>

== Optional Step for AirPlay ==
To implement OTT measurement, report OTT changes to the SDK using public API interface: [[updateOTT]]

In order to detect AirPlay and mirroring changes we use AVAudioSessionPortDescription properties that are different on different iOS versions. We found that on iOS versions 8 - 10 <code>AVAudioSessionPortDescription</code> has the following values: 
<code>
AirPlay: type = AirPlay; name = Apple TV 4K; UID = DC:56:E7:53:72:85-airplay 
Mirroring: type = AirPlay; name = Apple TV 4K; UID = DC:56:E7:53:72:85-screen
</code> 

For iOS 11+ some parameters like name and UID have different values: 
<code>
AirPlay: type = AirPlay; name = AirPlay; UID = 0eb63aae-5915-45f1-b0f7-0102a0e50d53 
Mirroring: type = AirPlay; name = Apple TV 4K; UID = 4335E8A9-1C0A-4251-9000-28CA5FA2F3CF-192731714653291-screen 
</code>

The following code snipped is suggested for AirPlay / mirroring detection on iOS devices.

{{ExampleCode|
|Objective C =
<syntaxhighlight lang="objective-c">
– (void)updateOTT:(id)ottInfo;
</syntaxhighlight>
=== Subscribe to AVAudioSessionRouteChangeNotification ===
<syntaxhighlight lang="objective-c">
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handleRouteChanged:) name:AVAudioSessionRouteChangeNotification object:nil];
</syntaxhighlight>

=== Handle AVAudioSessionRouteChangeNotification and prepare OTT dictionary:===
<syntaxhighlight lang="objective-c">
- (void)handleRouteChanged:(NSNotification *)notification
{
NSMutableDictionary *ottDict = [NSMutableDictionary dictionaryWithDictionary: @{@"ottStatus": @"0"}];

AVAudioSession *audioSession = [AVAudioSession sharedInstance];
AVAudioSessionRouteDescription *currentRoute = audioSession.currentRoute;
for (AVAudioSessionPortDescription *outputPort in currentRoute.outputs) {
if ([outputPort.portType isEqualToString:AVAudioSessionPortAirPlay]) {
ottDict[@"ottStatus"] = @"1";
ottDict[@"ottDeviceModel"] = outputPort.portName;
ottDict[@"ottDeviceID"] = outputPort.UID;

if ([outputPort.portName isEqualToString:@"AirPlay"]) {
ottDict[@"ottDevice"] = @"airplay";
ottDict[@"ottType"] = @"airplay";
}
else {
if ([outputPort.portName containsString:@"Apple TV"]) {
ottDict[@"ottDevice"] = @"appleTV";
}
else {
ottDict[@"ottDevice"] = @"other";
}

if ([outputPort.UID hasSuffix:@"airplay"]) {
ottDict[@"ottType"] = @"airplay";
}
else if ([outputPort.UID hasSuffix:@"screen"]) {
ottDict[@"ottType"] = @"mirroring";
}
else {
ottDict[@"ottType"] = @"other";
}
}
}
}

// report OTT status update to Nielsen SDK
[self reportOTTWithDict:ottDict];
}
</syntaxhighlight>

=== Report OTT update to the Nielsen SDK ===
<syntaxhighlight lang="objective-c">
- (void)reportOTTWithDict:(NSDictionary *)ottDict
{
[self.nielsenSDK updateOTT:ottDict];
}
</syntaxhighlight>

|Swift =
<syntaxhighlight lang="swift">
nielsenSdk.updateOTT(currentStatus)
</syntaxhighlight>

=== Subscribe to AVAudioSessionRouteChangeNotification ===
<syntaxhighlight lang="swift">
NotificationCenter.default.addObserver(self, selector: #selector(handleRouteChanged(_:)), name: NSNotification.Name.AVAudioSessionRouteChange, object: nil)
</syntaxhighlight>

=== Handle AVAudioSessionRouteChangeNotification and prepare OTT dictionary:===

<syntaxhighlight lang ="Swift">
func handleRouteChanged(_ notification: Notification) {
var currentStatus: [String: String] = ["ottStatus": "0"]

let session = AVAudioSession.sharedInstance()
let currentRoute = session.currentRoute
for outputPort in currentRoute.outputs {
if outputPort.portType == AVAudioSessionPortAirPlay {
currentStatus["ottStatus"] = "1"
currentStatus["ottDeviceModel"] = outputPort.portName
currentStatus["ottDeviceID"] = outputPort.uid

if outputPort.portName == "AirPlay" {
currentStatus["ottDevice"] = "airplay"
currentStatus["ottType"] = "airplay"
}
else {
if outputPort.portName.contains("Apple TV") {
currentStatus["ottDevice"] = "appleTV"
}
else {
currentStatus["ottDevice"] = "other"
}

if outputPort.uid.hasSuffix("airplay") {
currentStatus["ottType"] = "airplay"
}
else if outputPort.uid.hasSuffix("screen") {
currentStatus["ottType"] = "mirroring"
}
else {
currentStatus["ottType"] = "other"
}
}
}
}

// report OTT status update to Nielsen SDK
self.reportOTTUpdate(currentStatus)
}
</syntaxhighlight>

=== Report OTT update to the Nielsen SDK===
<syntaxhighlight lang ="Swift">
func reportOTTUpdate(_ ottDict: [String: String]) {
if let nielsenSdk = self.nielsenAppApi {
nielsenSdk.updateOTT(currentStatus)
}
}
</syntaxhighlight>
}}

== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "imr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910685&ch=se-910685_c01_P&asn=defChnAsset&fp_id=a2nfmy17lyvkhlxqstvmgypqly90m1629966210&fp_cr_tm=1629966210&fp_acc_tm=1629966210&fp_emm_tm=1629966210&ve_id=20A7CFD5-9860-4256-A6CE-45C251F4C243&sessionId=yvx0rtsxydmaxueji8zgfzj0f2f1w1629966209&tl=&prv=1&c6=vc,c01&ca=se-910685_c01_51HERB1501&cg=Play%20%3E%20Webbtv%20%3E%20Nyheter&c13=asid,P3D8D326A-2DBC-486A-8FD8-9AF4452B2A41&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,Aftonbladet&plugv=&playerv=&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_00000&c9=devid,12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8&enc=true&c1=nuid,12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8&at=timer&rt=video&c16=sdkv,ai.8.1.0&c27=cln,15&crs=&lat=&lon=&c29=plid,16299662096458868&c30=bldv,ai.8.1.0.0_gsxaoni&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,iOS14.6&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,5.47.83.0.25245&c51=adl,15&c52=noad,1&sd=15&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=51HERB1501&c3=st,a&c64=starttm,1629966240&adid=51HERB1501&c58=isLive,false&c59=sesid,iqal6k21r0de8gm901kif5xznar7q1629966240&c61=createtm,1629966255&c63=pipMode,&ci_userid=&is_auto_play=&pl_title=&is_prem=&is_prog=&ad_origin=&adidx=1%2F1&is_tpad=&ci_passthr=&c62=sendTime,1629966255&c68=bndlid,se.aftonbladet.Aftonbladet&c69=cvw,&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&uoo=&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,iPhone9%2C4~~devtypid,iPhone9%2C4~~sysname,iOS~~sysversion,14.6~~manuf,Apple&cat_id=a6f7fb13-8801-484c-9692-6db6dfb470aa&vtoff=0&rnd=1629966255319</nowiki></code>

== Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Going Live ==
Following Nielsen testing, you will need to:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_devDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

DCR Sweden Video Browser SDK

2021-09-06T13:13:09Z

ShangningWang: /* Test your player by yourself */

DCR Sweden Video iOS SDK

2021-09-03T11:29:04Z

ShangningWang: /* Use Case 2: Content has Ads */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

__TOC__

== Overview ==
The Nielsen SDK is one of the multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like Digital in TV Ratings ([[DCR & DTVR|DTVR]]), Digital Content Ratings ([[DCR & DTVR|DCR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || '''App ID (appid)''' || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || '''Nielsen SDK''' || Includes SDK frameworks and '''sample implementation'''; "See [[iOS SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Implementation ==
Version 8 of the Nielsen App SDK comes in three versions. One that is enabled to work with the App Tracking Transparency Framework, another version that does not use the Ad Framework, and a version for Kids Apps or where no ID is required.

{| class="wikitable"
|-
! SDK Flavor
! Description
|-
| '''iOS Ad Version'''
|* Opt-In and Opt-Out functionality managed by the [https://developer.apple.com/documentation/apptrackingtransparency AppTrackingTransparency framework]. * The Nielsen SDK will attempt to collect the IDFA (Id for Advertisers) on the device. * For iOS14+, if the value returned is <code>ATTrackingManager.AuthorizationStatus.authorized</code>. * If the device is running iOS12 or iOS13, the Limit Ad Tracking setting is requested.
|-
| '''iOS No Ad Framework'''
|* Without the Ad Framework, the Nielsen SDK cannot read the IDFA, so it will attempt to retrieve the [https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor ID for Vendors (IDFV)]. * The IDFV may be used for analytics across apps from the same content provider. * The developer is required to present the User Choice Optout page. The detailed requirement is described in the [https://engineeringportal.nielsen.com//docs/DCR_Sweden_Video_iOS_SDK#Global_iOS_SDK_No_Ad_Framework_Opt-out Global iOS SDK No Ad Framework Opt-out] Section.
|-
| '''iOS SDK No ID'''
|* This version of the Nielsen SDK is perfect for Kid apps, or where no ID is required. * Please review the [https://engineeringportal.nielsen.com/docs/DCR_Sweden_Video_iOS_SDK#Global_iOS_SDK_No_ID_Opt-out Global iOS SDK No ID Opt-out] Section.
|}
=== How to obtain the NielsenAppApi.Framework ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of CocoaPods. We recommend using the CocoaPods-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_iOS_Artifactory_Guide|Select to obtain CocoaPods implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
* [[DCR_Video_iOS_SDK_xcframework|Using the XCFramework bundle]]

== Setting up your iOS Development Environment ==

=== Configuring Xcode Development Environment ===
Starting with SDK version 6.0.0.0, the Nielsen App SDK is compatible with Apple iOS versions 8.0 and above. In addition, the SDK uses the WKWebView class instead of the deprecated UIWebView as per Apple guidelines.

=== Importing Frameworks ===

1) Extract “NielsenAppApi.Framework” from the Nielsen App SDK zip file and copy it to Frameworks folder of the Xcode project. 

2) Import following frameworks and libraries into the Frameworks of the Xcode project before creating an instance of the Nielsen App SDK object.
* UIKit.framework
* Foundation.framework
* AdSupport.framework
* SystemConfiguration.framework
* Security.framework
** Nielsen Analytics framework makes use of a number of functions in this library.
* AVFoundation.framework
** This framework is mandatory for the iOS SDK version 5.1.1 to work.
* CoreLocation.framework
* CoreMedia.framework
* NielsenAppApi.framework
* libc++.tbd (as SDK contains Objective-C++ source file)
** Alternatively, include -lstdc++ in Build Settings → Other Linker Flag of the Xcode project 

3) Include header file <code>NielsenAppApi/NielsenAppApi.h</code> to the View Controller's header file. 

Note:
* The SDK uses the NSURLSession instead of the deprecated NSURLConnection.
* All communications between the SDK and the Census (Collection Facility) use HTTPS
 
==== Using Swift ====
To import a set of Objective-C files in the same app target as your Swift code, you rely on an Objective-C bridging header to expose those files to Swift. Xcode offers to create this header file when you add a Swift file to an existing Objective-C app, or an Objective-C file to an existing Swift app.

Select File/New File/Objective-C File 
Xcode will prompt you to create a bridging header.
[[File:bridgingheader 2x.png|600px|center|link=]] 
Once this file has been created, you need to add the following:
<syntaxhighlight lang="swift">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>

==== Using Objective-C ====
Add the code
<syntaxhighlight lang ="objective-c">
#import <NielsenAppApi/NielsenAppApi.h>
</syntaxhighlight>
to the View Controller’s header file.
 

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

==== Sample SDK Initialization Code ====

Initialize the Nielsen App object within the viewDidLoad view controller delegate method using initWithAppInfo:delegate:
<blockquote>If App SDK is initialized using init or new methods, it will ignore the API calls resulting in no measurement. The SDK will not return any errors.</blockquote>

===== Using Objective-C=====
<syntaxhighlight lang="objective-c">
#import "NlsAppApiFactory.h"
#import <NielsenAppApi/NielsenAppApi.h>

@implementation NlsAppApiFactory

+ (NielsenAppApi *)createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;
{
NSDictionary *appInformation = @{
@"appid": "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
@"appversion": "1.0",
@"appname": "app name here",
@"nol_devDebug": @"DEBUG",
@"hem_md5": @"61f1121944dfb76f09540c59a99b4000"
};
return [[NielsenAppApi alloc] initWithAppInfo:appInformation delegate:delegate];
}
@end
</syntaxhighlight>

The following would be the <code>NlsAppApiFactory.h</code> file:
<syntaxhighlight lang="objective-c">
#import <Foundation/Foundation.h>

@class NielsenAppApi;
@protocol NielsenAppApiDeligate;

@interface NlsAppApiFactory : NSObject

+ (NielsenAppAPI *) createNielsenAppApiWithDelegate:(id<NielsenAppApiDelegate>)delegate;

@end
</syntaxhighlight>

===== Using Swift =====

<code>NielsenInit.swift</code>
<syntaxhighlight lang="swift">
class NielsenInit: NSObject {
class func createNielsenAppApi(delegate: NielsenAppApiDelegate) -> NielsenAppApi?{
let appInformation:[String: String] = [
"appid": "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
"appversion": "1.0",
"appname": "app name here",
"nol_devDebug": "DEBUG",
"hem_md5": "61f1121944dfb76f09540c59a99b4000"
]
return NielsenAppApi(appInfo:appInformation, delegate:delegate)
}
}
</syntaxhighlight>

Sample code using AVPlayer.
 
<code>ViewController.swift</code>

<syntaxhighlight lang="swift">
class ViewController: UIViewController, NielsenAppApiDelegate, AVPictureInPictureControllerDelegate, CLLocationManagerDelegate {

let avPlayerViewController = AVPlayerViewController()
var avPlayer:AVPlayer?
var nielsenAppApi: NielsenAppApi!

override func viewDidLoad() {
super.viewDidLoad()

self.nielsenAppApi = NielsenInit.createNielsenAppApi(delegate: self)
NSLog("Nielsen SDK initialized")

}
}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# '''Initial state''' – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the '''Initial state'''.
# '''Idle state''' – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# '''Processing state''' – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# '''Disabled state''' – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called

<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted NSString or a NSDictionary object. The JSON passed in the SDK must be well-formed.
* NSDictionary object
** If an object of unexpected type is passed to the method, the error message will be logged.
** If string has invalid JSON format, the error message will be logged.
* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

=== Create Content Metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play. 

Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

 
<blockquote> program and title metadata values should be passed to SDK as UTF-8 strings. </blockquote>

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. || For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 

A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage]

For VoD, it does not need to follow the simulcast_channelnumber format.

Length limit: 20 characters. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters]
|| ✓ 

|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for 24/7 live stream, 86400
* for event-Live streams, the planned length
* for VoD, video length
|| ✓
|-
| program || Program Name, ns_st_pr || program name || custom '''example:''' leif-och-billy || ✓
|-
| title || Episode Name, ns_st_ep || episode name || custom '''example:''' en-ny-tjej-i-byn || ✓
|}

=== Create Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad. 

Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

Note: All metadata values should be passed as UTF-8 strings.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> <code>"ad"</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to an asset within the same media house. || custom (no [[Special Characters]]) || ✓
|}

=== MetaData Example ===

==== Using Objective-C ====
<syntaxhighlight lang="objective-c">
NSDictionary *channelInfo = @
{
@"channelName":@"My Channel Name 1",
}

NSDictionary *contentMetadata = @
{
@"assetid" : "uniqueassetid",
@"type" : "content",
@"program" : "program name",
@"title" : "episode title",
@"length" : "2600"
}

NSDictionary *adMetadata = @
{
@"assetid" : "uniquepostrolladid",
@"type" : "postroll"
}
</syntaxhighlight>

==== Using Swift ====
<syntaxhighlight lang="swift">
let channelInfo = [
"channelName": "My Channel Name 1",
]

let contentMetadata = [
"assetid" : "uniqueassetid",
"type" : "content",
"program" : "program name",
"title" : "episode title",
"length" : "2600"
]

let adMetadata = [
"assetid" : "uniquepostrolladid",
"type" : "postroll"
]

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the '''Play''' button on the player. Call play only when initially starting the video.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi play:channelInfo];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.play(channelInfo);</syntaxhighlight>
 

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi loadMetadata:metadataDict];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.loadMetadata(metadataDict)</syntaxhighlight>
 

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">
[self.nielsenAppApi playheadPosition:pos];
</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">
self.nielsenAppApi?.playheadPosition(pos);
</syntaxhighlight>
 

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi stop];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.stop;</syntaxhighlight>
 

==== end ====
Call when the content asset completes playback. Stops measurement progress.
===== Using Objective-C =====
<syntaxhighlight lang="objective-c">[self.nielsenAppApi end];</syntaxhighlight>
===== Using Swift =====
<syntaxhighlight lang="swift">self.nielsenAppApi?.end</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[playheadPosition|playheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelName); </code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "TheMovieTitle"
}</syntaxhighlight>
Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad_123",
...
}</syntaxhighlight>
<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[playheadPosition|playheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelName); </code> || // channelName contains JSON metadata of channel/video name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.playheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third-party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Privacy and Opt-Out ==

There are currently 3 flavors of the Nielsen SDK. Please check the "Implementation" section for a comparison of the three flavors. Implementing opt-out for the three flavors are different:
# '''[[#Global_iOS_SDK_Opt-out|Global iOS SDK Opt-out]]''' - managed by ''AppTracking'' or ''Limit Ad Tracking'' setting on device.
# '''[[#Global_iOS_SDK_No_Ad_Framework_Opt-out|Global iOS SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without the Ad Framework.
# '''[[#Global_iOS_SDK_No_ID_Opt-out|Global iOS SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.
__NOTOC__
=== Global iOS SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen iOS

The Nielsen SDK automatically leverages the iOS's '''Limit Ad Tracking''' or '''AppTracking''' setting.
* If the User's device is running < iOS 13.x, the Nielsen SDK will check the status of '''Limit Ad Tracking'''.
* iOS14 modifies the way Apple manages the collection of a User's Opt-In status through '''AppTracking'''. Starting with Version 8.x+, the Nielsen App SDK will check the iOS version during initialization. If the device is running iOS12 or iOS13, the Limit Ad Tracking setting is requested. If iOS14.x +, then AppTracking is utilized.
==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global iOS SDK, this optOutURL informs the user how to deactivate/activate “App Tracking/Limit Ad Tracking”.

In addition, the following text must be included in your app store description.
<blockquote>"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://nielsen.com/digitalprivacy/ for more information"</blockquote>

=== Global iOS SDK No Ad Framework Opt-out ===
The ''User Choice'' method can be used without the Ad Framework, or in situations where the publisher does not wish to use the [https://developer.apple.com/documentation/apptrackingtransparency App Tracking Transparency Framework]. As this flavor of the Nielsen SDK does not use the Ad Framework, so it is necessary to display an Optout Page to the user and capture their selection.

Similar to the Global iOS SDK Flavor, it is a requirement to display a WebView element whose loadUrl is set to the
value obtained from optOutURL. This is a special URL that indicates Opt-in, or Opt-out and close the WebView.

==== This opt-out method works as follows: ====
* Get the Nielsen opt-out URL via [[optOutURL]]
* Display a WebView element whose loadUrl is set to the value obtained from [[optOutURL]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut]] function
** Example: <syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Global iOS SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the [https://nielsendownloads-green.digitalengsdk.com/digital/Nielsen-iOS-App-SDK-GlobalNoId_latest.zip NoID version] of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt out selection:
<syntaxhighlight lang=swift>NielsenAppApi?.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Opt-out example code ==
===== Swift =====
<syntaxhighlight lang="swift">
import UIKit
import WebKit
import NielsenAppApi

class OptOutVC: UIViewController, NielsenAppApiDelegate, WKNavigationDelegate {
var nielsenApi : NielsenAppApi!
var webView: WKWebView!

override func loadView() {
webView = WKWebView()
webView.navigationDelegate = self
view = webView
}

override func viewDidLoad() {
super.viewDidLoad()

if let appApi = self.nielsenApi {
//Getting the optPut URL from SDK
if let url = URL(string: appApi.optOutURL) {
webView.load(URLRequest(url: url))
webView.allowsBackForwardNavigationGestures = true
}}}

func closeOptOutView() {
self.dismiss(animated: true, completion: nil)
}

// Uncomment below code if you are using the Global iOS SDK No Ad Framework Flavor. This will receive the user's selection
// from the custom User_Choice Optout page. Only required for the Global iOS SDK No Ad Framework Flavor
/*
func webView(_ webView: WKWebView, decidePolicyFor navigationAction: WKNavigationAction, decisionHandler:
@escaping (WKNavigationActionPolicy) -> Void) {
print(navigationAction.request.url?.absoluteString as Any) //For debugging to check what is being passed from webpage.
if navigationAction.request.url?.absoluteString == "nielsen://close" {
closeOptOutView()
decisionHandler(.cancel)
} else {
if let url = navigationAction.request.url?.absoluteString, url.hasPrefix("nielsen") {
nielsenApi?.userOptOut(url). //either nielsenappsdk://1 or nielsenappsdk://0
decisionHandler(.cancel)
} else {
if navigationAction.navigationType == .linkActivated {
if let url = navigationAction.request.url?.absoluteString, url.hasSuffix("#") {
decisionHandler(.allow)
} else {
decisionHandler(.cancel)
webView.load(navigationAction.request)
}
} else {
decisionHandler(.allow)
}}}}
*/
}

</syntaxhighlight>

===== Objective-C =====
<syntaxhighlight lang="objective-c">

#import "OptOutVC.h"
#import "NielsenInit.h"
#import <NielsenAppApi/NielsenAppApi.h>

@interface OptOutVC ()

@property (weak, nonatomic) IBOutlet UIWebView *webView;
@end

@implementation OptOutVC

- (void)viewDidLoad {
[super viewDidLoad];

- (void)viewDidLoad {
[super viewDidLoad];
//Getting the optPut URL from eventTracker
[self.webView loadRequest:[NSURLRequest requestWithURL:[NSURL
URLWithString:self.nielsenApi.optOutURL]]];
}

// Uncomment below code if you are using the Global iOS SDK No Ad Framework Flavor. This will receive the user's selection
// from the custom User_Choice Optout page. Only required for the Global iOS SDK No Ad Framework Flavor
/*
- (void)webView:(WKWebView *)webView decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction
decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler
{
if ([navigationAction.request.URL.absoluteString isEqualToString:kNielsenWebClose])
{ [self performSelector:@selector(closeOptOutView) withObject:nil afterDelay:0];
decisionHandler(WKNavigationActionPolicyCancel);
} else {
if ([navigationAction.request.URL.absoluteString hasPrefix:@"nielsen"])
{[self.nielsenAppApi userOptOut:navigationAction.request.URL.absoluteString];
decisionHandler(WKNavigationActionPolicyCancel);
} else {
if (navigationAction.navigationType == WKNavigationTypeLinkActivated)
{ if ([navigationAction.request.URL.absoluteString hasSuffix:@"#"])
{decisionHandler(WKNavigationActionPolicyAllow);
} else {
decisionHandler(WKNavigationActionPolicyCancel);
[webView loadRequest:[NSURLRequest requestWithURL:navigationAction.request.URL]];
}} else {
decisionHandler(WKNavigationActionPolicyAllow);
}}}
*/
}

</syntaxhighlight>

== Retrieve current Opt-Out preference ==
Whether the user is opted out via OS-level Opt-out or via User Choice Opt-out, the current Opt-Out status as detected by the SDK is available via the [[optOutStatus]] property in the Nielsen SDK API
<syntaxhighlight lang="objective-c">
@property (readonly) BOOL optOutStatus
</syntaxhighlight>

== Optional Step for AirPlay ==
To implement OTT measurement, report OTT changes to the SDK using public API interface: [[updateOTT]]

In order to detect AirPlay and mirroring changes we use AVAudioSessionPortDescription properties that are different on different iOS versions. We found that on iOS versions 8 - 10 <code>AVAudioSessionPortDescription</code> has the following values: 
<code>
AirPlay: type = AirPlay; name = Apple TV 4K; UID = DC:56:E7:53:72:85-airplay 
Mirroring: type = AirPlay; name = Apple TV 4K; UID = DC:56:E7:53:72:85-screen
</code> 

For iOS 11+ some parameters like name and UID have different values: 
<code>
AirPlay: type = AirPlay; name = AirPlay; UID = 0eb63aae-5915-45f1-b0f7-0102a0e50d53 
Mirroring: type = AirPlay; name = Apple TV 4K; UID = 4335E8A9-1C0A-4251-9000-28CA5FA2F3CF-192731714653291-screen 
</code>

The following code snipped is suggested for AirPlay / mirroring detection on iOS devices.

{{ExampleCode|
|Objective C =
<syntaxhighlight lang="objective-c">
– (void)updateOTT:(id)ottInfo;
</syntaxhighlight>
=== Subscribe to AVAudioSessionRouteChangeNotification ===
<syntaxhighlight lang="objective-c">
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(handleRouteChanged:) name:AVAudioSessionRouteChangeNotification object:nil];
</syntaxhighlight>

=== Handle AVAudioSessionRouteChangeNotification and prepare OTT dictionary:===
<syntaxhighlight lang="objective-c">
- (void)handleRouteChanged:(NSNotification *)notification
{
NSMutableDictionary *ottDict = [NSMutableDictionary dictionaryWithDictionary: @{@"ottStatus": @"0"}];

AVAudioSession *audioSession = [AVAudioSession sharedInstance];
AVAudioSessionRouteDescription *currentRoute = audioSession.currentRoute;
for (AVAudioSessionPortDescription *outputPort in currentRoute.outputs) {
if ([outputPort.portType isEqualToString:AVAudioSessionPortAirPlay]) {
ottDict[@"ottStatus"] = @"1";
ottDict[@"ottDeviceModel"] = outputPort.portName;
ottDict[@"ottDeviceID"] = outputPort.UID;

if ([outputPort.portName isEqualToString:@"AirPlay"]) {
ottDict[@"ottDevice"] = @"airplay";
ottDict[@"ottType"] = @"airplay";
}
else {
if ([outputPort.portName containsString:@"Apple TV"]) {
ottDict[@"ottDevice"] = @"appleTV";
}
else {
ottDict[@"ottDevice"] = @"other";
}

if ([outputPort.UID hasSuffix:@"airplay"]) {
ottDict[@"ottType"] = @"airplay";
}
else if ([outputPort.UID hasSuffix:@"screen"]) {
ottDict[@"ottType"] = @"mirroring";
}
else {
ottDict[@"ottType"] = @"other";
}
}
}
}

// report OTT status update to Nielsen SDK
[self reportOTTWithDict:ottDict];
}
</syntaxhighlight>

=== Report OTT update to the Nielsen SDK ===
<syntaxhighlight lang="objective-c">
- (void)reportOTTWithDict:(NSDictionary *)ottDict
{
[self.nielsenSDK updateOTT:ottDict];
}
</syntaxhighlight>

|Swift =
<syntaxhighlight lang="swift">
nielsenSdk.updateOTT(currentStatus)
</syntaxhighlight>

=== Subscribe to AVAudioSessionRouteChangeNotification ===
<syntaxhighlight lang="swift">
NotificationCenter.default.addObserver(self, selector: #selector(handleRouteChanged(_:)), name: NSNotification.Name.AVAudioSessionRouteChange, object: nil)
</syntaxhighlight>

=== Handle AVAudioSessionRouteChangeNotification and prepare OTT dictionary:===

<syntaxhighlight lang ="Swift">
func handleRouteChanged(_ notification: Notification) {
var currentStatus: [String: String] = ["ottStatus": "0"]

let session = AVAudioSession.sharedInstance()
let currentRoute = session.currentRoute
for outputPort in currentRoute.outputs {
if outputPort.portType == AVAudioSessionPortAirPlay {
currentStatus["ottStatus"] = "1"
currentStatus["ottDeviceModel"] = outputPort.portName
currentStatus["ottDeviceID"] = outputPort.uid

if outputPort.portName == "AirPlay" {
currentStatus["ottDevice"] = "airplay"
currentStatus["ottType"] = "airplay"
}
else {
if outputPort.portName.contains("Apple TV") {
currentStatus["ottDevice"] = "appleTV"
}
else {
currentStatus["ottDevice"] = "other"
}

if outputPort.uid.hasSuffix("airplay") {
currentStatus["ottType"] = "airplay"
}
else if outputPort.uid.hasSuffix("screen") {
currentStatus["ottType"] = "mirroring"
}
else {
currentStatus["ottType"] = "other"
}
}
}
}

// report OTT status update to Nielsen SDK
self.reportOTTUpdate(currentStatus)
}
</syntaxhighlight>

=== Report OTT update to the Nielsen SDK===
<syntaxhighlight lang ="Swift">
func reportOTTUpdate(_ ottDict: [String: String]) {
if let nielsenSdk = self.nielsenAppApi {
nielsenSdk.updateOTT(currentStatus)
}
}
</syntaxhighlight>
}}

== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "nmr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910685&ch=se-910685_c01_P&asn=defChnAsset&fp_id=a2nfmy17lyvkhlxqstvmgypqly90m1629966210&fp_cr_tm=1629966210&fp_acc_tm=1629966210&fp_emm_tm=1629966210&ve_id=20A7CFD5-9860-4256-A6CE-45C251F4C243&sessionId=yvx0rtsxydmaxueji8zgfzj0f2f1w1629966209&tl=&prv=1&c6=vc,c01&ca=se-910685_c01_51HERB1501&cg=Play%20%3E%20Webbtv%20%3E%20Nyheter&c13=asid,P3D8D326A-2DBC-486A-8FD8-9AF4452B2A41&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,Aftonbladet&plugv=&playerv=&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_00000&c9=devid,12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8&enc=true&c1=nuid,12b9377cbe7e5c94e8a70d9d23929523d14afa954793130f8a3959c7b849aca8&at=timer&rt=video&c16=sdkv,ai.8.1.0&c27=cln,15&crs=&lat=&lon=&c29=plid,16299662096458868&c30=bldv,ai.8.1.0.0_gsxaoni&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,iOS14.6&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,5.47.83.0.25245&c51=adl,15&c52=noad,1&sd=15&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=51HERB1501&c3=st,a&c64=starttm,1629966240&adid=51HERB1501&c58=isLive,false&c59=sesid,iqal6k21r0de8gm901kif5xznar7q1629966240&c61=createtm,1629966255&c63=pipMode,&ci_userid=&is_auto_play=&pl_title=&is_prem=&is_prog=&ad_origin=&adidx=1%2F1&is_tpad=&ci_passthr=&c62=sendTime,1629966255&c68=bndlid,se.aftonbladet.Aftonbladet&c69=cvw,&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&uoo=&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,iPhone9%2C4~~devtypid,iPhone9%2C4~~sysname,iOS~~sysversion,14.6~~manuf,Apple&cat_id=a6f7fb13-8801-484c-9692-6db6dfb470aa&vtoff=0&rnd=1629966255319</nowiki></code>

== Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Going Live ==
Following Nielsen testing, you will need to:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_devDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.

DCR Sweden Video Android SDK

2021-09-02T19:20:11Z

ShangningWang: /* Global Android SDK No Ad Framework Opt-out Sample Code */

{{Breadcrumb|}} {{Breadcrumb|Digital}} {{Breadcrumb|International DCR}} {{CurrentBreadcrumb}}
[[Category:Digital]]

== Overview ==
The Nielsen SDK is one of the multiple framework SDKs that Nielsen provides to enable measuring linear (live) and on-demand TV viewing using TVs, mobile devices, etc.
The App SDK is the framework for mobile application developers to integrate Nielsen Measurement into their media player applications. It supports a variety of Nielsen Measurement Products like It supports a variety of Nielsen Measurement Products like Digital in TV Ratings ([[DCR & DTVR|DTVR]]), Digital Content Ratings ([[DCR & DTVR|DCR]]), and [[Digital Ad Ratings]] (DAR). Nielsen SDKs are also equipped to measure static content and can track key life cycle events of an application like:
*Application launch events and how long app was running
*Time of viewing a subsection/page in the application.
 
This ''SDK Android integration guide'' is applicable for '''Android TV''' as well.

== Prerequisites ==
Before you start the integration, you will need:
{| class="wikitable"
|-
! style="width: 30px;" |
! style="width: 15%;" | Item
! Description
! Source
|-style="background-color:#d0f6f8;"
|| ☑ || "App ID (appid)" || Unique ID assigned to the player/site and configured by product. || Contact Nielsen
|-style="background-color:#d0f6f8;"
|| ☑ || "Nielsen SDK" || Includes SDK frameworks and "sample implementation"; "See [[Android SDK Release Notes]]" || [[Special:Downloads|Download]]
|}

== Implementation ==
The Nielsen Android SDK comes in three versions.

{| class="wikitable"
|-
! SDK Flavor
! Description
|-
| '''Android Ad Version'''
|* Opt-In and Opt-Out functionality managed by Opt out of Ads Personalization setting on device. * The Nielsen SDK will collect the [https://developer.android.com/training/articles/ad-id Google Advertising ID] unless the user Opts out. * If the Google Play Service is unavailable, (ie: Amazon and Huawei devices) the Nielsen SDK will secure the Android ID. * There are 3 versions available starting with the Nielsen SDK 8.1.0.0.
|-
| '''Android No Ad Framework'''
|* Without the Ad Framework, the Nielsen SDK cannot read the Google Advertising ID, so will retrieve the Android ID. * The Android ID is a 64-bit number (expressed as a hexadecimal string), unique to each combination of app-signing key, user and device. * The developer is required to present the User Choice Opt-Out page which is described in the [https://engineeringportal.nielsen.com//docs/DCR_Sweden_Video_Android_SDK#Global_Android_SDK_No_Ad_Framework_Optout Global Android SDK No Ad Framework Opt-out].
|-
| '''Android SDK noID'''
|* This version of the Nielsen SDK is perfect for Kid apps, or where no ID is required. * For the requirement, please review the [https://engineeringportal.nielsen.com//docs/DCR_Sweden_Video_Android_SDK#Global_Android_SDK_No_ID_Optout Global Android SDK No ID Opt-out].
|}

=== How to obtain the NielsenAppApi ===
The Nielsen AppSDK can either be downloaded directly or can be integrated directly within an application through the use of Gradle. We recommend using the Gradle-based integration whenever possible to ensure you maintain the most recent changes and enhancements to the Nielsen libraries.
* [[Digital_Measurement_Android_Artifactory_Guide|Select to obtain Gradle implementation guide]]
* [[Special:Downloads|Select to Download Directly]]
__TOC__

== Setting up your Android Development Environment ==
 
1) Ensure to unzip the Nielsen App SDK zip file and copy the "AppSdk.jar" into the app/libs folder on the App’s project. Add it as dependency. 
2) Add the following permissions on the project’s "AndroidManifest.xml" file. 

<syntaxhighlight lang="java">
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/></syntaxhighlight>
3) Add Google Play Services lib into dependencies as Nielsen AppSDK uses the following packages/classes from the Google Play service.
Libraries:
* com.google.android.gms:play-services
Requiered Google Play Service Classes and Packages :
* com.google.android.gms.ads.identifier.AdvertisingIdClient;
* com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
* com.google.android.gms.common.ConnectionResult;
* com.google.android.gms.common.GooglePlayServicesUtil;
* com.google.android.gms.common.GooglePlayServicesRepairableException;
* com.google.android.gms.common.GooglePlayServicesNotAvailableException;

4) Once the files are in place, import com.nielsen.app.sdk to the java source code and start accessing the public interface. 
<syntaxhighlight lang="java">import com.nielsen.app.sdk.*;</syntaxhighlight> 
 

Notes:
*The Nielsen App SDK (located in the "com.nielsen.app.sdk" package) class is the primary application interface to the Nielsen App SDK on Android.
*The Nielsen App SDK class is defined as the only public class belonging to the com.nielsen.app.sdk package.
*Nielsen App SDK is compatible with Android OS versions 2.3+.
*Clients can control / configure the protocol to be used – HTTPS or HTTP to suit their needs.
*The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 4.0 and later will support it natively).
*If the player application uses a 3rd party media player implementing its own HLS/MPEG-DASH stack, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

== Create SDK Instance ==
The latest version of the Nielsen App SDK allows instantiating multiple instances of the SDK object when needed, which can then be used simultaneously. '''For the general use case where only one video is played at the same time in the App, a single instance of SDK object can then be used to play back and measure all watched streams one after another.'''

The following table contains the list of arguments that can be passed via the AppInfo JSON schema.
{| class="wikitable"
|-
! Parameter / Argument !! Description !! Source !! Required/Obligatory? !! Example
|-
| appid || Unique id for the application assigned by Nielsen. It is GUID data type.|| Nielsen-specified || YES || "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
|-
| appname || Name of the application || Client-defined || NO || "Nielsen Sample App"
|-
| appversion || Current version of the app used || Client-defined || NO || "1.0.2"
|-
| nol_devDebug || Enables Nielsen console logging. Only required for testing
|| Nielsen-specified || NO || "DEBUG"
|-
| hem_md5 || Hashed email using md5. Used by MMS reach model.
|| Client-defined || Required if login feature || "61f1121944dfb76f09540c59a99b4000"
|}
 

1) AppSDK() is no longer a singleton object and should be created as below.
<syntaxhighlight lang="java">
try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(appContext, appSdkConfig, this);
}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}
</syntaxhighlight>
2) implement IAppNotifier into your activity like
<syntaxhighlight lang="java">public class MainActivity extends AppCompatActivity implements IAppNotifier
</syntaxhighlight>
3) implement callback
<syntaxhighlight lang="java">@Override
public void onAppSdkEvent(long timestamp, int code, String description){
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}
</syntaxhighlight>

So whole Activity will look like
<syntaxhighlight lang="java">
package com.example.josefvancura.nlsdemotmp;

import android.content.Context;
import android.support.v7.app.AppCompatActivity;
import android.os.Bundle;
import android.util.Log;

import com.nielsen.app.sdk.*;

import org.json.JSONException;
import org.json.JSONObject;

public class MainActivity extends AppCompatActivity implements IAppNotifier {

private AppSdk mAppSdk = null;
private String TAG = "MainActivity";

@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);

Context context = getApplicationContext();

try{
// Prepare AppSdk configuration object (JSONObject)
JSONObject appSdkConfig = new JSONObject()
.put("appid", "PXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX")
.put("appversion", "1.0")
.put("appname", "Sample App Name")
.put("nol_devDebug", "DEBUG"); // only for debug builds
.put("hem_md5", "61f1121944dfb76f09540c59a99b4000");

// Pass appSdkConfig to the AppSdk constructor
mAppSdk = new AppSdk(context, appSdkConfig, this ); // Notifier - activity implements IAppNotifier, callback in onAppSdkEvent()

}
catch (JSONException e){
Log.e(TAG, "Couldn’t prepare JSONObject for appSdkConfig", e);
}

}

@Override
public void onAppSdkEvent(long timestamp, int code, String description) {
Log.d(TAG, "SDK callback onAppSdkEvent " + description);
}

}
</syntaxhighlight>

==== APP SDK Error & Event Codes ====
To view the Error and Event codes for iOS and Android, please review the [[APP SDK Event Codes|App SDK Event Code]] Reference page.

==== Life cycle of SDK instance ====
Life cycle of SDK instance includes four general states:
# ""Initial state"" – The SDK is not initialized and hence, not ready to process playing information. Once the SDK is moved out of this state, it needs instantiation of the new SDK instance in order to get the instance in the ""Initial state"".
# ""Idle state"" – The SDK is initialized and is ready to process playing information. Once Initialized, the SDK instance is not processing any data, but is listening for the play event to occur.
# ""Processing state"" – The SDK instance is processing playing information. API calls "play" and "loadMetadata" move the SDK instance into this state. In this state, the SDK instance will be able to process the API calls (see below)
# ""Disabled state"" – The SDK instance is disabled and is not processing playing information. SDK instance moves into this state in one of the following scenarios.
## Initialization fails
## <code>appDisableApi</code> is called
<syntaxhighlight lang="objective-c">
@property (assign) BOOL appDisableApi;
</syntaxhighlight>

== Create Metadata Objects ==
The parameters passed must be either a JSON formatted string. The JSON passed in the SDK must be well-formed.

* JSON value must be string value.
** This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
** All the Variable Names like appid, appname, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
* JSON string can be prepared using either raw NSString or serialized NSDictionary. 

=== Create channelName Metadata ===
channelName should remain constant throughout the completion of an episode or live stream.
 
{| class="wikitable"
|-
! Key !! Description !! Values !! Required
|-
| channelName || Any string representing the channel/stream || custom || ✓
|-
|}

=== Create Content Metadata ===
Content metadata should remain constant throughout the entirety of an episode/clip including when ads play.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

 
<blockquote> program and title metadata values should be passed to SDK as UTF-8 strings. </blockquote>

{| class="wikitable"
|-
! Nielsen Key !! MMS Attribute Name, MMS Field Name !! Description !! Values !! Required
|-
| type || || type of asset || "content" || ✓
|-
| assetid || Content ID, mms_tid || unique ID assigned to an asset within the same media house. || For content on simulcast channels, this has a standard format: simulcast_channelnumber ('''Example''' for Channel TV4, the expected value is: simulcast_29). 

A complete list of channel reference libraries with channel numbers is on the [https://mms.se/?page_id=108 MMS homepage]

For VoD, it does not need to follow the simulcast_channelnumber format.

Length limit: 20 characters. [https://engineeringportal.nielsen.com/docs/Special_Characters No special characters]
|| ✓ 

|-
| length || Clip Length, ns_st_cl || length of content in seconds || Length of content in seconds.
* for 24/7 live stream, 86400
* for event-Live streams, the planned length
* for VoD, video length
|| ✓
|-
| program || Program Name, ns_st_pr || program name || custom '''example:''' leif-och-billy || ✓
|-
| title || Episode Name, ns_st_ep || episode name || custom '''example:''' en-ny-tjej-i-byn || ✓
|}

=== Create Ad Metadata ===
The Ad Metadata (if applicable) should be passed for each individual ad.
 
Please see the [[Sweden_SDK_Metadata|Metadata link]] for the full list of content and ad metadata.

Note: All metadata values should be passed as UTF-8 strings.
{| class="wikitable"
|-
! Keys !! Description !! Values !! Required
|-
| type || type of Ad || <code>"preroll"</code>, <code>"midroll"</code>, <code>"postroll"</code> <code>"ad"</code> - If specific type can not be identified.|| ✓
|-
| assetid || unique ID assigned to an asset within the same media house. || custom (no [[Special Characters]]) || ✓
|}

=== MetaData Example ===
<syntaxhighlight lang="java">
JSONObject channelInfo = new JSONObject()
.put("channelname","My Channel Name 1")

JSONObject contentMetadata = new JSONObject()
.put("assetid", "uniqueassetid")
.put("type", "content")
.put("program", "program name")
.put("title", "episode title")
.put("length", "2600");

JSONObject adMetadata = new JSONObject()
.put("assetid", "uniquepostrolladid")
.put("type", "postroll");

</syntaxhighlight>

== Start the Measurement ==

=== Overview of SDK API Calls ===

==== play ====
The play method prepares the SDK for reporting once an asset has loaded and playback has begun. Use play to pass the channel descriptor information through channelName parameter when the user taps the ""Play"" button on the player. Call play only when initially starting the video.

<syntaxhighlight lang="java">mAppSdk.play(JSONObject channelInfo);</syntaxhighlight>

==== loadMetadata ====
Needs to be called at the beginning of each asset, pass JSON object for relevant content or ad. Make sure to pass as 1st loadMetadata for content at the begining of playlist - see below API call sequence examples.
<syntaxhighlight lang="java">mAppSdk.loadMetadata(JSONObject contentMetadata);</syntaxhighlight>

==== playheadPosition ====
Pass playhead position every second during playback. for VOD: pass current position in seconds. for Live: current Unix timestamp (seconds since Jan-1-1970 UTC) - if it is possible to seek back in Live content, then pass related Unix time (not current). Pass whole number that increments only by 1 like 1,2,3..
<syntaxhighlight lang="Java">mAppSdk.setPlayheadPosition(long videoPositon);</syntaxhighlight>

==== stop ====
Call when
* ads complete playing
* when a user pauses playback
* upon any user interruption scenario - see bellow chapter Interruption scenario

<syntaxhighlight lang="java">mAppSdk.stop();</syntaxhighlight>

==== end ====
Call when the content asset completes playback. Stops measurement progress.
<syntaxhighlight lang="java">mAppSdk.end();</syntaxhighlight>
 

=== API Call Sequence ===
==== Use Case 1: Content has no Ads ====
Call [[play()]] at start of stream

Call [[loadMetadata()]] with JSON metadata for content as below.
<syntaxhighlight lang="json">{
"type": "content",
"assetid": "vid345-67483",
"program": "ProgramName",
"title": "Program S3, EP1",
"length": "3600",
...
}</syntaxhighlight>
Call [[setPlayheadPosition()]] every one second until a pause.
Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(); </code> || // Call at start of each new stream
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| Content || <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| Interruption || <code>mAppSdk.stop();</code> || // call stop when content playback is interrupted
|-
| rowspan="2" | Resume Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // Call loadMetadata and pass content metadata object when content resumes
|-
|<code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // continue pasing playhead position every second starting from position where content is resumed
|-
| End of Stream || <code>mAppSdk.end();</code> || // Content playback is completed.
|}

==== Use Case 2: Content has Ads ====
Call [[play()]] with channelName JSON as below.
<syntaxhighlight lang="json">{
"channelName": "My Channel Name 1"
}</syntaxhighlight>

Call [[loadMetadata()]] with JSON metadata for ad as below.
<syntaxhighlight lang="json">{
"type": "preroll",
"assetid": "ad-123"
...
}</syntaxhighlight>

<blockquote>Note: In case the individual ad details are not available, send ad pod (presence) details through the [[loadMetadata]] and playhead position through [[playheadPosition]].</blockquote>

Call [[setPlayheadPosition()]] every one second until a pause / another [[loadMetadata()]] is called. Playhead should be passed for the entire duration of ad pod, if the ad pod details are passed as part of [[loadMetadata()]].

The sample API sequence can be used as a reference to identify the specific events that need to be called during content and ad playback.
{| class="wikitable"
|-
! Type !! Sample code !! Description
|-
| rowspan="2" | Start of stream || <code>mAppSdk.play(channelInfo); </code> || // channelName contains JSON metadata of channel name being played
|-
| <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| rowspan="3" | Preroll || <code>mAppSdk.loadMetadata(prerollMetadataObject);</code> || // prerollMetadataObject contains the JSON metadata for the preroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the preroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after preroll occurs
|-
| rowspan="2" | Content || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| rowspan="6" | Midroll || <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // midrollMetadataObject contains the JSON metadata for the midroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // App moves to background(midroll pauses)
|-
| <code>mAppSdk.loadMetadata(midrollMetaDataObject);</code> || // App moves to foreground (midroll resumes)
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // playheadPosition is position of the playhead while the midroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after midroll occurs
|-
| rowspan="2" | Content (End of stream) || <code>mAppSdk.loadMetadata(contentMetaDataObject);</code> || // contentMetadataObject contains the JSON metadata for the content being played
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the content is being played
|-
| End of Stream || <code>mAppSdk.end();</code> || // Call end() at the end of content
|-
| rowspan="3" | Postroll || <code>mAppSdk.loadMetadata(postrollMetaDataObject);</code> || // postrollMetadataObject contains the JSON metadata for the postroll ad
|-
| <code>mAppSdk.setPlayheadPosition(playheadPosition);</code> || // position is position of the playhead while the postroll ad is being played
|-
| <code>mAppSdk.stop();</code> || // Call stop after postroll occurs
|}

<blockquote>Note: Each Ad playhead should reset or begin from 0 at ad start. When content has resumed following an ad break, playhead position must continue from where previous content segment was left off.</blockquote>

== Stop/Resume the Measurement for video Playback Interruptions ==
As part of integrating Nielsen App SDK with the player application, the Audio / Video app developer needs to handle the following possible interruption scenarios:
* Pause / Play
* Network Loss (Wi-Fi / Airplane / Cellular)
* Call Interrupt (SIM or Third party Skype / Hangout call)
* Alarm Interrupt
* Content Buffering
* Device Lock / Unlock (Video players only, not for Audio players)
* App going in the Background/Foreground (Video players only, not for Audio players)
* Channel / Station Change Scenario
* Unplugging of headphone
In case of encountering one of the above interruptions, the player application needs to
* Call <code>stop</code> immediately (except when content is buffering) and withhold sending playhead position.
* Once the playback resumes, start sending pings <code>playheadPosition</code> for the new viewing session.
Please see the [[Digital Measurement FAQ]] for more details

== Review SDK Integration Architecture Diagram ==

=== For Content Playback ===

[[File:nlsn-sdk-achitecture-diagram-content-v1.png||SDK Integration Architecture Diagram - Content]]

=== For Ad Playback ===
[[File:nlsn-sdk-achitecture-diagram-ad-v1.png||SDK Integration Architecture Diagram - Ad]]

== Privacy and Opt-Out ==
There are currently 3 flavors of the Nielsen SDK:
# '''[[#Global_Android_SDK_Opt-out|Global Android SDK Opt-out]]''' - managed by ''Opt out of Ads Personalization'' setting on device ('''preferred approach''').
# '''[[#Global_Android_SDK_No_Ad_Framework_Opt-out|Global Android SDK No Ad Framework Opt-out]]''' - Direct call to SDK. Can be used without Google Play Services or when using the noAd version of the SDK.
# '''[[#Global_Android_SDK_No_ID_Opt-out|Global Android SDK No ID Opt-out]]''' - Direct call to SDK. Should be used for Kids Category.

=== Global Android SDK Opt-out ===
''OS-level Opt-out'' method available on Nielsen Android when the [https://developers.google.com/android/guides/setup Google Play services APIs] have been setup in your project.

The Nielsen SDK automatically leverages the Android's '''Opt out of Ads Personalization''' setting. The user is opted out of demographic measurement if the OS-level '''Opt out of Ads Personalization''' setting is ''enabled''. As a publisher, you cannot override this setting.

==== Webview Element ====
It is a requirement to display a WebView element whose loadUrl is set to the value obtained from optOutURL.
If using the Global Android SDK, this optOutURL informs the user how to deactivate/activate “Out of Ads Personalization”.

In addition, The following text must be included in your app store description.
<blockquote>"'''Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://nielsen.com/digitalprivacy/ for more information'''"</blockquote>

=== Global Android SDK No Ad Framework Opt-out ===
The ''No Ad Framework Opt-out'' can be used when the host application does not leverage Google Play Services such as when using the noAd version or the NoID version.
<blockquote>
Nielsen Android SDK 5.1.1.18 and above will check for ''OS-level opt-out'' first, if available. The user will be opted out if indicated at the OS-level '''OR''' the App-level.</blockquote>

==== The No Ad Framework Opt-out method works as follows: ====
* Get the current Nielsen opt-out URL via [[userOptOutURLString()]]
* Display a WebView element whose loadUrl is set to the value obtained from [[userOptOutURLString()]]
* Detect if the WebView URL changes to a special URL that indicates Opt-in, or Opt-out and close the WebView
** Opt-out if the WebView URL = <code>nielsenappsdk://1</code>
** Opt-in if the WebView URL = <code>nielsenappsdk://0</code>
* Pass the detected URL to the [[userOptOut()]] function
** Example: <syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

=== Global Android SDK No ID Opt-out ===
If you are building an app that will be listed in the Kids Category:
# Ensure that you are using the NoID version of the Nielsen SDK Framework.
# Immediately following the initialization of the Nielsen SDK ensure you call the userOptOut API with Opt-out selection:
<syntaxhighlight lang=java>appSdk.userOptOut("nielsenappsdk://1"); // User opt-out</syntaxhighlight>

== Opt-out Sample Code ==
=== Global Android SDK Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user. Please see the next section if using the No Ad Framework build
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>
 

=== Global Android SDK No Ad Framework Opt-out Sample Code ===
The below code is an AndroidX example of displaying the Nielsen Privacy page to the user with the No Ad Framework SDK Build.
<syntaxhighlight lang="java">
public class OptOutActivity extends AppCompatActivity implements IAppNotifier {

WebView webView;
AppSdk appSdk;

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_optout);
webView = (WebView) findViewById(R.id.webView);
webView.getSettings().setJavaScriptEnabled(true);

webView.setWebViewClient(new WebViewClient() {
@SuppressWarnings("deprecation")
@Override
public void onReceivedError(WebView view, int errorCode, String description, String failingUrl) {
Toast.makeText(OptOutActivity.this, description, Toast.LENGTH_SHORT).show();
}
@TargetApi(android.os.Build.VERSION_CODES.M)
@Override
public void onReceivedError(WebView view, WebResourceRequest req, WebResourceError rerr) {
// Redirect to deprecated method, so you can use it in all SDK versions
onReceivedError(view, rerr.getErrorCode(), rerr.getDescription().toString(), req.getUrl().toString());
}

@Override
public boolean shouldOverrideUrlLoading(WebView view, String url) {

if(url.contains("nielsen")){
// If url value = "nielsenappsdk://1" it means the user selected Opt-out
// If url value = "nielsenappsdk://0" it means the user selected Opt-in
appSdk.userOptOut(url);
}
return true;
}

});
String url = appSdk.userOptOutURLString(); // Request Optout URL from NielsenSDK
webView.loadUrl(url); //Display to the user in a Webview
}
@Override
public void onBackPressed() {
super.onBackPressed();
mSdkInterface.getSDK(appSdk);
}
@Override
protected void onDestroy() {
super.onDestroy();
if (appSdk != null)
{
appSdk.close();
appSdk = null;
}
}
}
</syntaxhighlight>

=== Required Privacy Links ===
Users must either have access to the "About Nielsen Measurement" page, or have similar text available within the native app. 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.

In addition, the following text must be included in your app store description.
<blockquote>
'''"Please note: This app features Nielsen’s proprietary measurement software which contributes to market research, like Nielsen’s TV Ratings. Please see https://www.nielsen.com/us/en/legal/privacy-statement/digital-measurement/ for more information"'''</blockquote>

== Optional Step for DCR Chromecast Android SDK ==
For the implementation of Chromecast SDK architecture. Please refer to this guide: [https://engineeringportal.nielsen.com/docs/DCR_Chromecast_Android_SDK DCR Chromecast Android SDK]

== Test your player by yourself ==
=== Guide ===
1. Connect your PC and test device (tablet or phone) via same router. 
2. PC side: run Proxy sw (like Charles) and get local IP 
3. Test device: modify Wifi setting to pass through Proxy IP from step 2. 
4. Test device: run your player, launch video 
5. PC side: filter traffic by "nmr" and confirm presence of GN pings 

=== Example of GN ping ===
<code><nowiki>https://secure-sw.imrworldwide.com/cgi-bin/gn?prd=dcr&ci=se-910684&ch=se-910684_c01_P&asn=defChnAsset&fp_id=096ohdsc0jqkmct81qpxhmn19qx041630053963&fp_cr_tm=1630053963&fp_acc_tm=1630053963&fp_emm_tm=1630053963&ve_id=afc5d61a88b62672&sessionId=zc6gh3uhka7d2mtobb2b2m7sixygy1630053963&tl=Djuren%20p%C3%A5%20Djuris&prv=1&c6=vc,c01&ca=se-910684_c01_218531&cg=Hemligheter&c13=asid,T1194003B-797F-4896-A5C0-05914236146E&c32=segA,NA&c33=segB,NA&c34=segC,NA&c15=apn,&plugv=4.4.1&playerv=ExoPlayer&sup=1&segment2=&segment1=&forward=0&ad=1&cr=4_00_99_D1_10000&c9=devid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&enc=true&c1=nuid,c041ec5e50722cdf8cc5b4826c24ae54c5747a6570e900006c826b37ca01ce17&at=timer&rt=video&c16=sdkv,aa.8.1.0&c27=cln,34&crs=0&lat=&lon=&c29=plid,16300539624283525&c30=bldv,aa.8.1.0.0_gaxnons&st=dcr&c7=osgrp,&c8=devgrp,&c10=plt,&c40=adbid,&c14=osver,ANDROID.11&c26=dmap,1&dd=&hrd=&wkd=&c35=adrsid,&c36=cref1,&c37=cref2,&c11=agg,1&c12=apv,4.4.1.4004001&c51=adl,0&c52=noad,0&sd=578&pc=NA&c53=fef,n&c54=oad,&c55=cref3,&c57=adldf,2&ai=218531&c3=st,c&c64=starttm,1630053962&adid=218531&c58=isLive,false&c59=sesid,257f8bz854wmqa31gk3icyi7cmj131630053964&c61=createtm,1630053997&c63=pipMode,&ci_userid=&is_auto_play=no&pl_title=&is_prem=no&is_prog=&ad_origin=&adidx=&is_tpad=&ci_passthr=&c62=sendTime,1630053997&c68=bndlid,air.se.urplay.android_player.debug&nodeTM=&logTM=&c73=phtype,&c74=dvcnm,&c76=adbsnid,&c77=adsuprt,2&uoo=&evdata=PL%3A1630053964727%3A0&c71=ottflg,0&c72=otttyp,&c44=progen,&davty=1&si=&c66=mediaurl,&sdd=retry,0~~retryreason,~~devmodel,SM-G981B~~devtypid,samsung-SM-G981B~~sysname,Android~~sysversion,11~~manuf,samsung&cat_id=3398d8e4-e613-42c1-92aa-1a6fc52dcf5c&vtoff=0&rnd=1630053997971</nowiki></code>

== Step 9 : Provide your app for certification ==
Once ready please send your application to Nielsen local staff for certification.

== Step 10 : Going Live ==
After the integration has been certified by Nielsen (but not prior to that), do the following:

# '''Disable Debug Logging''': Disable logging by deleting <code>{nol_sdkDebug: 'DEBUG'}</code> from initialization call.
# '''Notify Nielsen''': Once you are ready to go live, let us know so we can enable you for reporting. We will not be able to collect or report data prior to receiving notification from you.