Android Step By Step

From Engineering Client Portal

Engineering Portal breadcrumbArrow.png Digital breadcrumbArrow.png Android Step By Step


Provided below are step-by-step quick start guides for implementing Nielsen Android SDK for DCR Static, DCR Video, and DTVR products. Click each section to get started.

→ Android DCR Static

Show/hide DCR Static

Android DCR Static Introduction

Show/hide Intro

The Digital Content Ratings (DCR) Static product provides content consumption measurement on client webpages. This measurement includes insight into the total time a user spent on a webpage, how they navigated through the page via links, and many other data points. This tutorial provides the steps to implement the DCR Static product in a sample Android app. It includes:

  • SDK Initialization Call
  • DCR Static Metadata: information about the sections being tracked


By the end of this guide you will have the needed steps to integrate Nielsen's AppSDK in the background of your app.

Android DCR Static Step 1 - Obtain AppID

Show/hide step 1

To begin using the Android SDK (AppSDK) you will need to obtain an Application ID (AppId)

Item Description Source
✅ App ID (appid) Unique ID assigned to the player/site and configured by product Contact your Nielsen TAM

The appid is a 37 character unique ID assigned to the player/site and configured by product and is required when creating a new instance of the AppSDK in the app.
Example: PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX

Android DCR Static Step 2 - SDK Initialization

Show/hide step 2

How to obtain the NielsenAppApi

The Nielsen AppSDK can either be downloaded directly or can be integrated into 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.

SDK Initialization

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

Parameter / Argument Description Source Required? Example
appid Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you. Nielsen-specified Yes PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
nol_devDebug Enables Nielsen console logging. Only required for testing Nielsen-specified Optional "DEBUG"

Debug flag for development environment

Player application developers / integrators can use Debug flag to check whether an App SDK API call made is successful. To activate the Debug flag, Pass the argument @"nol_devDebug":@"INFO", in the JSON string . The permitted values are:

  • INFO: Displays the API calls and the input data from the application (validate player name, app ID, etc.). It can be used as certification Aid.
  • WARN: Indicates potential integration / configuration errors or SDK issues.
  • ERROR: Indicates important integration errors or non-recoverable SDK issues.
  • DEBUG: Debug logs, used by the developers to debug more complex issues.

Once the flag is active, it logs each API call made and the data passed. The log created by this flag is minimal.

Note: DO NOT activate the Debug flag in a production environment.

Sample SDK Initialization Code

Initialization of App SDK object through a JSON object 

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

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

Here, appContext is the App context object and appSdkConfig is JSON object for holding the parameters (appid) the App passes to the Nielsen App SDK via a JSON string. The appid is obtained from Nielsen operational support and is unique to the app.

  • Ensure that SDK files (AppSdk.jar and libAppSdk.so [App SDK 1.2 Only]) are included under the App’s project and the App SDK is linked to the App (the setting to link App SDK to the App can be found on property page of the App’s project).

Android DCR Static Step 3 - Create/Load DCR Static Metadata Object

Show/hide step 3

Configure Metadata

Map the Nielsen keys to variables so that the content metadata is dynamically updated.

The Nielsen reserved keys are:

Key Description Data Type Value Required?
type asset type fixed 'static' Yes
assetid Unique ID for each article dynamic custom
(no Special Characters)		 No
section section of each site (e.g. section value should be first level in page URL: website.com/section). Limit to 25 unique values dynamic custom Yes
segA custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) dynamic custom No
segB custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) dynamic custom No
segC custom segment for reporting: Limit to 25 unique values across custom segments (segA + segB + segC) dynamic custom No

The values passed through the Nielsen keys will determine the breakouts that are seen in reporting. The custom segments (A, B & C) will roll into the sub-brand. To not use custom segments A, B and C, do not pass any value in these keys.


Configure API calls - loadMetadata

Use loadMetadata to pass 'content' Digital Measurement Metadata. The CMS data must be passed as a JSON object. 

    loadMetadata(JSONObject jsonMetadata);

Refer to Digital Measurement Metadata for the list of parameters to be passed in the JSON object.

Note: The loadMetadata call must have ("type": "static").


Call loadMetadata with JSON metadata as below. 

    new JSONObject()
        .put("type", "static")
        .put("section", "siteSection")
        .put("assetid", "vid345-67483")
        .put("segA", "segmentA")
        .put("segB", "segmentB")
        .put("segC","segmentC")
    }

As soon as this loadMetadata call is made, AppSDK will record a view event and start tracking the section/page time spent (AppSDK 9.1 and above).

DCR Static Duration Measurement per Section/Page/Asset

If your Nielsen AppID is enabled for DCR Static duration measurement, a view event will be recorded and a timer will be started for each screen/page. Duration will be measured until a new page is loaded or the app is moved to the background. The event which triggers recognition of page view and timer start is the loadMetadata API call with a metadata object of type 'static'. Once a page is viewed and the timer has started, duration will be measured until a new page has loaded with associated loadMetadata call having a different section name from the previous page. If a new loadMetadata call is made with the same section name, it will be ignored - no new view will be recorded. If it is desired to have a new view event even though the metadata contains the same section name (example: single-page apps having several assedIDs but common section name), staticEnd API can be called between page views. For the purposes of this overview, staticend will not be used. See this page for more information.


Keep Going

Show/hide

Congratulations, you've successfully integrated the Android SDK in your app!

You can add static loadMetadata calls for more sections/pages in your app to see what happens when transitioning between sections.

View your application's debug logs and search for the term (AppSDK) to see messages emitted by Nielsen AppSDK.

Next Steps

Show/hide

Now that you've integrated DCR Static for the AppSDK, what's next?

Going Live

In addition to the basic steps above, before going live developers need to handle app background/foreground events, make certain privacy disclosures, and allow users to opt out of Nielsen measurement. More details can be found here, along with a more comprehensive reference for implementing DCR Static measurement with AppSDK.

Once the DCR Tracking Code is added, Nielsen will validate the implementation. Following Nielsen testing, developers need to make a few updates to the initialization call to ensure that the app is being measured properly.

  1. App ID: Ensure that correct is used during initialization PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  2. Debug Logging: Disable logging by changing initialization call to use @"nol_devDebug":@"INFO".




→ Android DCR Video

Show/hide DCR Video

Android DCR Video Introduction

Show/hide Intro

The Digital Content Ratings (DCR) Video product provides content consumption measurement on client webpages. This measurement includes insight into the total time a user spent watching the tracked content, video player events, and much more. This example provides the steps to implement the DCR Video product in a sample Android app. It includes:

  • SDK Initialization
  • DCR Video Metadata: information about the content being tracked
  • DCR Video Events/API calls

By the end of this guide you will have the needed steps to integrate Nielsen's AppSDK in the background of your app.

Android DCR Video Step 1 - Obtain AppID

Show/hide step 1

To begin using the Android AppSDK, you will need to obtain an Application ID (AppId)

Item Description Source
✅ App ID (appid) Unique ID assigned to the player/site and configured by product Contact your Nielsen Representative

The appid is a 37 character unique ID assigned to the player/site and configured by product and is required when creating a new instance of the AppSDK in the app.
Example: PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX

Android DCR Video Step 2 - SDK Initialization

Show/hide step 2

Setting up your Development Environment
Configuring Android Development Environment
  • The Nielsen App SDK (located in the Downloads section of the website) 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.
  • The Nielsen App SDK can also be added via Artifact Repository.

The requirement for the Java AppSdk.jar library and the libAppSdk.so native library will depend on the type of host application that will make use of them.

  • For Video player applications
    • The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 3.0 and later will support it natively).
    • If the player application uses a 3rd party media player implementing its own HLS, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

Once SDK is downloaded ensure to unzip the Nielsen SDK and copy the AppSdk.jar in your app (Android Studio) libs folder, then right click the AppSdk.jar and select Add As Library. Ensure the AppSdk.jar file is added in 'build.gradle (App Level) file.

  • App SDK 1.2 provides support for x86, mips, and armeabi-7a architecture.
Google Play Services

Add the Google Play Services in the project, Steps: Android Studio -> File -> Project Structure ->(In module selection) select App -> Dependencies (tab) -> Click "+" button and search for "*play-services*". Then select the most recent version of the play-services Artifact. Ensure it is added in build.gradle (App level) file

The following is required if target API level is set to 31 (Android 12) with the Ad Version of the Nielsen SDK. 

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>


Manifest File
  • Add the following permissions on the project’s AndroidManifest.xml file.
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/>

For more details to handle runtime permissions in Android versions, please visit [1].

  • In AndroidManifest.xml under <application> add the following metadata
<meta-data 
android:name="com.google.android.gms.version" 
android:value="@integer/google_play_services_version"/>
  • App SDK checks to see if there is a Google service available and updated.
  • If not available or updated, App SDK will not use this service when executing its functions and will make reference to missing imports and the app will not be compiled.
Library

Nielsen App SDK uses the following packages/classes from the Google Play service.

  • google-play-services_lib
Classes/package
  • com.google.android.gms.ads.identifier.AdvertisingIdClient;
  • com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
  • com.google.android.gms.common.ConnectionResult;
  • com.google.android.gms.common.GooglePlayServicesUtil;
  • com.google.android.gms.common.GooglePlayServicesRepairableException;
  • com.google.android.gms.common.GooglePlayServicesNotAvailableException;
SDK Initialization

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

Parameter / Argument Description Source Required? Example
appid Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you. Nielsen-specified Yes PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
nol_devDebug Enables Nielsen console logging. Only required for testing Nielsen-specified Optional "DEBUG"

Debug flag for development environment

Player application developers / integrators can use Debug flag to check whether an App SDK API call made is successful. To activate the Debug flag, Pass the argument @"nol_devDebug":@"DEBUG", in the JSON string . The permitted values are:

  • INFO: Displays the API calls and the input data from the application (validate player name, app ID, etc.). It can be used as certification Aid.
  • WARN: Indicates potential integration / configuration errors or SDK issues.
  • ERROR: Indicates important integration errors or non-recoverable SDK issues.
  • DEBUG: Debug logs, used by the developers to debug more complex issues.

Once the flag is active, it logs each API call made and the data passed. The log created by this flag is minimal.

Note: DO NOT activate the Debug flag in a production environment.

Sample SDK Initialization Code

Initialization of App SDK object through a JSON object 

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

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

Here, appContext is the App context object and appSdkConfig is JSON object for holding the parameters (appid) the App passes to the Nielsen App SDK via a JSON string. The appid is obtained from Nielsen operational support and is unique to the app.


The integration of Nielsen App SDK will depend on type of client app.

  • Ensure that SDK files (AppSdk.jar and libAppSdk.so [App SDK 1.2 Only]) are included under the App’s project and the App SDK is linked to the App (the setting to link App SDK to the App can be found on property page of the App’s project).


Android DCR Video Step 3 - Create DCR Video Content Metadata Object

Show/hide step 3

Handling JSON Metadata

The SDK methods handle only two types of objects: NSString, NSDictionary. The parameters passed must be either a JSON formatted string or a NSDictionary object. The JSON passed in the SDK must be well-formed.

  • NSDictionary object
    • If an object of unexpected type is passed to the method, the error message will be logged.
    • If string has invalid JSON format, the error message will be logged.
  • JSON value must be string value.
    • This includes boolean and numeric values. For example, a value of true should be represented with "true", number value 123 should be "123".
    • All the Variable Names like appid, appname, sfcode, dataSrc, title, type etc. are case-sensitive. Use the correct variable name as specified in the documentation.
  • JSON string can be prepared using either raw NSString or serialized NSDictionary.
JSONObject contentMetadata = new JSONObject()
//SDK Metadata
    .put("type", "content")
    .put("assetid", "vid345-67483")
    .put("program", "The Big Bang Theory")
    .put("title", "The Pants Alternative S03E18")
    .put("crossId1", "EP009311820061")  //optional  
    .put("crossId2", "Content Originator")  //optional  
    .put("length", "3600")
    .put("isfullepisode", "yes") 
    .put("airdate", "2022-03-21T10:05:00")
    .put("adloadtype", "2")
    .put("segB", "CustomSegmentValueB") //optional
    .put("segC", "CustomSegmentValueC") //optional

Content metadata

Content metadata should remain constant throughout the entirety of an episode/clip.

Keys Description Values Required Provider
type Type of asset For Video use: content
For Static or text static		 Yes Nielsen
assetid Unique ID assigned to asset
Note: Refrain from using the following special characters (Special Characters).		 Examples:
BBT345a234
CBSs5e234F2021		 Yes Client
program Complete program or movie title
(no abbreviations or shorthand)
Note: there is a 25 character limit.		 The Big Bang Theory
TheBigBangTheory
The Dark Knight
TheDarkKnight
Yes Client
title Episode title with season and episode number (40 character limit)
(Formats accepted: S01E03, S1E3, S1 E3).		 Examples:
The Pants Alternative S03E18
The Pants Alternative S3E18
The Pants Alternative S3 E18
Can also accept: S3E18
Not Valid: 318 or 0318 		Yes Client
crossId1 Gracenote TMS ID (If available) should be passed for all telecasted content for clients using the Gracenote solution for proper matching purposes.
Note: The TMS ID will be a 14 character string. Normally leading with 2 alpha characters ('EP', 'MV', 'SH' or 'SP'), followed by 12 numbers. 		The TMS ID will be a 14 character string.
Normally being with 'EV,' 'EP', 'SH', 'SP', or 'MV'
Followed by 12 numbers after the initial two letter prefix.

The Giant Morning Show: SH009311820022
The Pants Alternative Episode : EP009311820061		 Optional Nielsen
crossId2 Populated by content distributor to contribute viewing from that distributor to the given content originator. Custom
For a full list of acceptable values, please contact your Nielsen reprentative.		 Yes, for distributors Nielsen
length Length of content in seconds
Note: Integers and decimals are acceptable values are acceptable for the length parameter.		 Examples:

For standard VOD content - 300 to represent 5 minutes, 1320 to represent 22 minutes, etc.
If DAI live stream of a discrete program (Live Event/Sporting Event), pass length of content. See example for standard VOD content above.
If unknown DAI live steam, pass a value of 0.

Yes Client
airdate Original broadcast or release date for the program
For USA, date should be EST
Outside USA, date should be local time.
If not applicable or available, original broadcast or release date for the Program.		 Acceptable Formats:
YYYY-MM-DDTHH:MI:SS
YYYY-MM-DDHH:MI:SS
YYYY-MM-DDTHH:MI:SS+xx:xx
YYYY-MM-DDTHH:MI:SS-xx:xx
YYYYMMDDHH:MI:SS
YYYYMMDD HH:MI:SS
MM-DD-YYYY
MM/DD/YYYY
YYYYMMDD		 Yes Client
isfullepisode Full episode flag to identify differences between long form content. y- full episode, n- non full episode(clip,teaser,promo,etc.)

Also accept:
lf or yes- longform
sf or no- shortform

Yes Nielsen
adloadtype Type of ad load:

1 Linear – matches TV ad load
2 Dynamic – Dynamic Ad Insertion (DAI)

2 - DCR measures content with dynamic ads Yes Nielsen
segB One of two custom segment for the clients granular reporting within a brand. Examples:
Genre - horror, comedy, etc.
Timeslot - primetime, daytime, etc.
News type - breakingnews, weather, etc.		 Optional Client
segC One of two custom segment for the clients granular reporting within a brand. Examples:
Genre - horror, comedy, etc.
Timeslot - primetime, daytime, etc.
News type - breakingnews, weather, etc.		 Optional Client

Custom segments (segB and segC) can be used to aggregate video and/or static content within a single Brand to receive more granular reports within a brand.

Examples regarding usage of segments within SDK:

  • All comedy clips and stories for a Brand rolled into a "Comedy" segment
  • genre grouping content by Comedy vs. Drama
  • group related Text + Video content - i.e. for a show that has a lot of - static pages associated with it
  • packaging based on how clients sell inventory
  • grouping related types of content either by genre, category or platform.



Android DCR Video Step 4 - Basic Set of Events - Sample Playback

Show/hide step 4

Configure API Calls
SDK Events
Event Parameter Description
'play' Call at start of each new stream
'loadMetadata' content/ad metadata object Needs to be called at the beginning of each asset
'setPlayheadPosition' playhead position as integer

VOD: || current position in seconds
Live: current Unix timestamp (seconds since Jan-1-1970 UTC)
Note: 'setPlayheadPosition' has to be called every second

Pass playhead position every second during playback

'stop' playhead position Call during any interruption to content or Ad playback and at the end of each Ad.
'end' playhead position in seconds Call when the current video asset completes playback and pass the playhead position.

Example: At the end of the content stream, if the user switches to another piece of content, when the browser is refreshed or closed.

Note: For livestream, send the Unix timestamp; for VOD send the time in seconds as integer. The final playhead position must be sent for the current asset being played before calling stop, end or loadmetadata,.

Life cycle of SDK instance

Life cycle of SDK instance includes four general states:

  1. 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.
  2. 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.
  3. Processing state – The SDK instance is processing playing information. The play and loadMetadata calls move the SDK instance into this state. In this state, the SDK instance will be able to process the following calls.
    1. setplayheadPosition – Call this API every one second when playhead position timer is fired. If a LIVE event, use the current Unix timestamp (seconds since Jan-1-1970 UTC).
    2. stop – Call this API when the playback is paused, switches between content and ad (within the same content playback) or encounters interruptions.
    3. end – Call when content completes. When called, the SDK instance exits from Processing state.
  4. 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.
    1. Initialization fails
    2. appDisableApi is set to true


Note: In case of any interruptions during playback due to alarm, calendar, call, flight mode, Wi-Fi toggle, channel change, etc., call stop to stop the measurement.

  • As soon as the playback resumes, loadMetadata and playheadPosition

API Call Sequence

Sample Use Case: Content has no Advertisements

Call play() at start of stream

Call loadMetadata() with JSON metadata for content as below. 

{
  "type": "content",
  "assetid": "vid345-67483",
  "program": "ProgramName",
  "title": "Program S3, EP1",
  "length": "3600",
  ...
}

Call setPlayheadPosition() every one second until a pause / stop. Use the sample API sequence below as a reference to identify the specific events that need to be called during content playback without ads.

Type Sample code Description
Start of stream mAppSdk.play(); // Call at start of each new stream
mAppSdk.loadMetadata(contentMetaDataObject); // contentMetadataObject contains the JSON metadata for the content being played
Content mAppSdk.setPlayheadPosition(playheadPosition); // position is position of the playhead while the content is being played
Interruption mAppSdk.stop(); // call stop when content playback is interrupted
Resume Content mAppSdk.loadMetadata(contentMetaDataObject); // Call loadMetadata and pass content metadata object when content resumes
mAppSdk.setPlayheadPosition(playheadPosition); // continue pasing playhead position every second starting from position where content is resumed
End of Stream mAppSdk.end(); // Content playback is completed.




Keep Going

Show/hide

Congratulations, you've successfully integrated the Android SDK in your app for a basic content playback scenario!

You can add more content to see channel-change scenarios or continue to next steps below.

View your application's debug logs and search for the term (AppSDK) to see messages emitted by Nielsen AppSDK during video playback.


Next Steps

Show/hide

Going Live

In addition to the basic steps above, before going live developers need to handle app background/foreground events, make certain privacy disclosures, handle interruption events (stop, fast-forward, rewind), and allow users to opt out of Nielsen measurement. More details can be found here, along with a more comprehensive reference for implementing DCR Video measurement with AppSDK.

Once the DCR Tracking Code is added, Nielsen will validate the implementation. Following Nielsen testing, developers need to make a few updates to the initialization call to ensure that the app is being measured properly.

  1. App ID: Ensure that correct is used during initialization PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  2. Debug Logging: Disable logging by changing initialization call to use @"nol_devDebug":@"INFO".



→ Android DTVR

Show/hide Android DTVR

Android DTVR Introduction

Show/hide Intro

The Nielsen DTVR (Digital TV Ratings) product provides content consumption measurement in client mobile apps and webpages. This measurement includes insight into the total time a user spent watching the tracked content, video player events, and much more. This example provides the steps to implement the DTVR product in a sample Android app using Nielsen AppSDK. It includes:

  • SDK Initialization
  • DTVR Video Metadata: information about the content being tracked
  • DTVR Video Events/API calls
  • Extracting ID3 tags from the video stream and passing to AppSDK for measurement

By the end of this guide you will have the needed steps to integrate Nielsen's AppSDK in the background of your app for DTVR measurement.

NOTE: video streams must have Nielsen ID3 tags embedded in order to be measured using the DTVR product. See the section in this guide "Extracting ID3 Tags" or contact your Nielsen representative for more information.

Android DTVR Step 1 - Obtain AppID

Show/hide step 1

To begin using the Android AppSDK, you will need to obtain an Application ID (AppId)

Item Description Source
✅ App ID (appid) Unique ID assigned to the player/site and configured by product Contact your Nielsen Representative

The appid is a 37 character unique ID assigned to the player/site and configured by product and is required when creating a new instance of the AppSDK in the app.
Example: PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX

Android DTVR Step 2 - SDK Initialization

Show/hide step 2

Configuring Android Development Environment
  • The Nielsen App SDK (located in the Downloads section of the website) 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.
  • The Nielsen App SDK can also be added via Artifact Repository.

The requirement for the Java AppSdk.jar library and the libAppSdk.so native library will depend on the type of host application that will make use of them.

  • For Video player applications
    • The Android OS hosting the App SDK should use a media player supporting HLS streaming (Android 3.0 and later will support it natively).
    • If the player application uses a 3rd party media player implementing its own HLS, then the minimum Android version will be limited to version 2.3, since the SDK depends on Google Play support to work properly.

Once SDK is downloaded ensure to unzip the Nielsen SDK and copy the AppSdk.jar in your app (Android Studio) libs folder, then right click the AppSdk.jar and select Add As Library. Ensure the AppSdk.jar file is added in 'build.gradle (App Level) file.

  • App SDK 1.2 provides support for x86, mips, and armeabi-7a architecture.
Google Play Services

Add the Google Play Services in the project, Steps: Android Studio -> File -> Project Structure ->(In module selection) select App -> Dependencies (tab) -> Click "+" button and search for "*play-services*". Then select the most recent version of the play-services Artifact. Ensure it is added in build.gradle (App level) file

The following is required if target API level is set to 31 (Android 12) with the Ad Version of the Nielsen SDK. 

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>


Manifest File
  • Add the following permissions on the project’s AndroidManifest.xml file.
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.INTERNET"/>

For more details to handle runtime permissions in Android versions, please visit [2].

  • In AndroidManifest.xml under <application> add the following metadata
<meta-data 
android:name="com.google.android.gms.version" 
android:value="@integer/google_play_services_version"/>
  • App SDK checks to see if there is a Google service available and updated.
  • If not available or updated, App SDK will not use this service when executing its functions and will make reference to missing imports and the app will not be compiled.
Library

Nielsen App SDK uses the following packages/classes from the Google Play service.

  • google-play-services_lib
Classes/package
  • com.google.android.gms.ads.identifier.AdvertisingIdClient;
  • com.google.android.gms.ads.identifier.AdvertisingIdClient.Info;
  • com.google.android.gms.common.ConnectionResult;
  • com.google.android.gms.common.GooglePlayServicesUtil;
  • com.google.android.gms.common.GooglePlayServicesRepairableException;
  • com.google.android.gms.common.GooglePlayServicesNotAvailableException;
SDK Initialization

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

Parameter / Argument Description Source Required? Example
appid Unique Nielsen ID for the application. The ID is a GUID data type. If you did not receive your App ID, let us know and we will provide you. Nielsen-specified Yes PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
nol_devDebug Enables Nielsen console logging. Only required for testing Nielsen-specified Optional "DEBUG"

Debug flag for development environment

Player application developers / integrators can use Debug flag to check whether an App SDK API call made is successful. To activate the Debug flag, Pass the argument @"nol_devDebug":@"DEBUG", in the JSON string . The permitted values are:

  • INFO: Displays the API calls and the input data from the application (validate player name, app ID, etc.). It can be used as certification Aid.
  • WARN: Indicates potential integration / configuration errors or SDK issues.
  • ERROR: Indicates important integration errors or non-recoverable SDK issues.
  • DEBUG: Debug logs, used by the developers to debug more complex issues.

Once the flag is active, it logs each API call made and the data passed. The log created by this flag is minimal.

Note: DO NOT activate the Debug flag in a production environment.

Sample SDK Initialization Code

Initialization of App SDK object through a JSON object 

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

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

Here, appContext is the App context object and appSdkConfig is JSON object for holding the parameters (appid) the App passes to the Nielsen App SDK via a JSON string. The appid is obtained from Nielsen operational support and is unique to the app.


The integration of Nielsen App SDK will depend on type of client app.

  • Ensure that SDK files (AppSdk.jar and libAppSdk.so [App SDK 1.2 Only]) are included under the App’s project and the App SDK is linked to the App (the setting to link App SDK to the App can be found on property page of the App’s project).


Android DTVR Step 3 - Create DTVR Content Metadata Object

Show/hide step 3

Configure Metadata

Content metadata should remain constant throughout the completion of an episode or live stream.

Key Description Values Required
type type of asset "content"
adModel linear vs dynamic ad model 1 = Linear matches TV ad load ✓ 
   
    public JSONObject loadDtvr() {
     try {
            dtvrdata = new JSONObject()
                    .put( "type","content")
                    .put("adModel", "1");
        }
        return dtvrdata;
    }

Android DTVR Step 4 - Basic Set of Events - Sample Playback

Show/hide step 4

SDK Events/APIs
Event Parameter Description
'loadMetadata' content/ad metadata object Needs to be called at the beginning of each asset to pass type and adModel.
'sendID3' Used to send the ID3 tag payload retrieved from the stream Needs to be called at the beginning of playback
Configure API calls - loadMetadata

Use loadMetadata to pass the metadata object created above. 

 appSdk.loadMetadata(dtvrdata);
Configure API calls - sendID3

sendID3 API is a receiver for timed metadata events (ID3 tags. This API filters out Nielsen-specific ID3 tags from the system and buffers the data for transfer to Nielsen’s collection facility. 

 //Sending ID3 tag to SDK.
appSdk.sendID3(id3String);

Sample ID3 tags

  • www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/X100zdCIGeIlgZnkYj6UvQ==/AAAB2Jz2_k74GXSzx4npHuI_JwJd3QSUpW30rDkGTcbHEzIMWleCzM-uvNOP9fzJcQMWQLJqzXMCAxParOb5sGijSV9dNM3QiBniJYGZ5GI-lL1fXTTN0IgZ4iWBmeRiPpS9AAAAAAAAAAAAAAAAAAAAAFJWFM5SVhTONNU=/00000/00000/00
  • www.nielsen.com/X100zdCIGeIlgZnkYj6UvQ==/R8WHe7pEBeqBhu8jTeXydg==/AAICoyitYqlxT7n6aZ0oMCGheFi4CXFp46AMUPZz1lMr_M9tr3_cjee1SHqxrOiVerMDLeyn9xzocZSKwi746Re8vNOtpNCAZjYABs_J0R25IHpvOc1HS8QHGgD5TgOJeS6gX100zdCIGeIlgZnkYj6UvVJWFNhSVhTiPE0=/00000/46016/00

Refer to Retrieving ID3 Tags section to know more details.

Retrieving ID3 Tags

ID3 tags have a payload of about 249 characters and start with "www.nielsen.com".

Examples of extracting ID3 tags fromAndroid Native Media Player

As the Android Media Player versions (prior to Android 6 / Android API 23) do not support ID3, Nielsen has created a library that becomes an extension to the media player, thus MPX. This library extracts the ID3 tags and sends them to the app. For more information on how to use the MPX component, refer to the Nielsen-supplied sample application.

Starting from Android 6 (Android API 23), Android Native Media Player allows apps to register a callback to be invoked, when a selected track has the timed metadata available. Currently, only HTTP Live Streaming (HLS) data URI’s embedded with timed ID3 tags generate TimedMetadata. Once the HLS video starts, call onTimedMetaDataAvailable() as and when the player observes a TimedMetadata (ID3 tag). 

@Override
    public void onTimedMetaDataAvailable(MediaPlayer mediaPlayer, TimedMetaData timedMetaData) {

        if(timedMetaData != null && timedMetaData.getMetaData() != null && mMediaPlayer.isPlaying()){

            //getting metadata.
            String iD3Payload = new String(timedMetaData.getMetaData(), StandardCharsets.UTF_8);

            //If tag metadata contains "www.nielsen.com", then only sending to SDK
            if (null != iD3Payload && iD3Payload.contains("www.nielsen.com"))
            {
                //getting index
                int index = iD3Payload.indexOf("www.nielsen.com");

                //getting substring as ID3 tag will be of 249 characters
                String id3String = iD3Payload.substring(index, (index + 249));
                Log.d(TAG, "TimedMetaData ID3 Tag:" + id3String);

                //Sending ID3 tag to SDK.
                appSdk.sendID3(id3String);
            }
        }
    }
}
Life cycle of SDK instance

Life cycle of SDK instance includes four general states:

  1. Initial state – The SDK is not initialized and hence, not ready to process playing information.
  2. 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 loadMetadata and sendID3 events to occur.
  3. Processing state – The SDK instance is processing playing information. The loadMetadata call moves the SDK instance into this state. In this state, the SDK instance will be able to process sendID3 calls and measure content.
  4. Disabled state – The SDK instance is disabled.


Keep Going

Show/hide

Congratulations, you've successfully integrated the Android SDK in your app for a basic content playback scenario!

You can add more content to see channel-change scenarios or continue to next steps below.

View your application's debug logs and search for the term (AppSDK) to see messages emitted by Nielsen AppSDK during video playback.


Next Steps

Show/hide

Going Live

In addition to the basic steps above, before going live developers need to handle app background/foreground events, make certain privacy disclosures, handle interruption events (stop, fast-forward, rewind), and allow users to opt out of Nielsen measurement. More details can be found here, along with a more comprehensive reference for implementing DTVR measurement with AppSDK.

Once the DTVR Tracking Code is added, Nielsen will validate the implementation. Following Nielsen testing, developers need to make a few updates to the initialization call to ensure that the app is being measured properly.

  1. App ID: Ensure that correct is used during initialization PXXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
  2. Debug Logging: Disable logging by changing initialization call to use @"nol_devDebug":@"INFO".



Retrieved from "https://engineeringportal.nielsen.com/w/index.php?title=Android_Step_By_Step&oldid=6587"