Engineering Client Portal - User contributions [en]

AndroidTV

2026-06-19T11:51:48Z

VenkataDodla: /* 1: Download the package here */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integration into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR/DTVR)''' ====

'''4.1:''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DCR Video]
.put("adModel", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DTVR]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A comprehensive list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2:''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content. This is needed for DCR Video measurement.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

'''4.3:''' The following example demonstrates the passing of Nielsen ID3 tags to AppSDK during the playback of content. This is needed for DTVR measurement.

The following example code demonstrates the extraction of ID3 metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== Step 5: '''Stopping the AppSDK Measurement (DCR/DTVR)''' ====

The following code snippet demonstrates the pausing of AppSDK measurement whenever the video playback is paused or when switching between ad to content or content to ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

The following code snipped demonstrates the completion of AppSDK measurement in case of DCR Video typically used when content playback is completed. This is triggered 1) at the end of the content stream 2) if the user switches to another piece of content

Note: In case of DTVR this acts as an interrupt similar to stop() api

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== Step 6: Measuring Non Video Content (DCR Static) ====

The following code snippet demonstrates the measurement of static screens/pages by sending the metadata of the static page/screen to AppSDK.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

The following code snippet demonstrates the completion of static screens/pages measurement by invoking staticEnd() on AppSDK which will finalise the screen/page viewed time.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== Step 7: Opting out of AppSDK measurement ====
The following example code is to provide users the ability to opt out of Nielsen measurement.

Below code snippet is used to fetch the Nielsen opt-out web page URL

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Below code snippet is used to supply the response message captured from opt-out webpage to the AppSDK

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

==== Step 8: Closing the AppSDK instance ====
Kindly call this API whenever the application is closing or before creating another AppSDK instance.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When need to check the current SDK version.
|-
|getOptOutStatus()
|Retrieve the Opt-Out or Opt-In state.
|When need to know the Opt-Out or Opt-In status.
|}

=== Sample App: Download, Build, Emulator Setup and Install the AndroidTV ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 1: Download the package here ====
Click [https://d280mermnrvzn0.cloudfront.net/NielsenAndroidTVSampleVideoPlayerApp.zip here] to download the project and open the project in Android Studio IDE.

==== 2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-19T09:52:24Z

VenkataDodla: /* Sample App: Download, Build, Emulator Setup, and Install the AndroidTV */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integration into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR/DTVR)''' ====

'''4.1:''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DCR Video]
.put("adModel", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DTVR]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A comprehensive list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2:''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content. This is needed for DCR Video measurement.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

'''4.3:''' The following example demonstrates the passing of Nielsen ID3 tags to AppSDK during the playback of content. This is needed for DTVR measurement.

The following example code demonstrates the extraction of ID3 metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== Step 5: '''Stopping the AppSDK Measurement (DCR/DTVR)''' ====

The following code snippet demonstrates the pausing of AppSDK measurement whenever the video playback is paused or when switching between ad to content or content to ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

The following code snipped demonstrates the completion of AppSDK measurement in case of DCR Video typically used when content playback is completed. This is triggered 1) at the end of the content stream 2) if the user switches to another piece of content

Note: In case of DTVR this acts as an interrupt similar to stop() api

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== Step 6: Measuring Non Video Content (DCR Static) ====

The following code snippet demonstrates the measurement of static screens/pages by sending the metadata of the static page/screen to AppSDK.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

The following code snippet demonstrates the completion of static screens/pages measurement by invoking staticEnd() on AppSDK which will finalise the screen/page viewed time.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== Step 7: Opting out of AppSDK measurement ====
The following example code is to provide users the ability to opt out of Nielsen measurement.

Below code snippet is used to fetch the Nielsen opt-out web page URL

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Below code snippet is used to supply the response message captured from opt-out webpage to the AppSDK

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

==== Step 8: Closing the AppSDK instance ====
Kindly call this API whenever the application is closing or before creating another AppSDK instance.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When need to check the current SDK version.
|-
|getOptOutStatus()
|Retrieve the Opt-Out or Opt-In state.
|When need to know the Opt-Out or Opt-In status.
|}

=== Sample App: Download, Build, Emulator Setup and Install the AndroidTV ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T12:55:50Z

VenkataDodla: /* Step 2: Configuring Android AppSDK Initialization Parameters */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integration into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR/DTVR)''' ====

'''4.1:''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DCR Video]
.put("adModel", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DTVR]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A comprehensive list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2:''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content. This is needed for DCR Video measurement.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

'''4.3:''' The following example demonstrates the passing of Nielsen ID3 tags to AppSDK during the playback of content. This is needed for DTVR measurement.

The following example code demonstrates the extraction of ID3 metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== Step 5: '''Stopping the AppSDK Measurement (DCR/DTVR)''' ====

The following code snippet demonstrates the pausing of AppSDK measurement whenever the video playback is paused or when switching between ad to content or content to ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

The following code snipped demonstrates the completion of AppSDK measurement in case of DCR Video typically used when content playback is completed. This is triggered 1) at the end of the content stream 2) if the user switches to another piece of content

Note: In case of DTVR this acts as an interrupt similar to stop() api

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== Step 6: Measuring Non Video Content (DCR Static) ====

The following code snippet demonstrates the measurement of static screens/pages by sending the metadata of the static page/screen to AppSDK.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

The following code snippet demonstrates the completion of static screens/pages measurement by invoking staticEnd() on AppSDK which will finalise the screen/page viewed time.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== Step 7: Opting out of AppSDK measurement ====
The following example code is to provide users the ability to opt out of Nielsen measurement.

Below code snippet is used to fetch the Nielsen opt-out web page URL

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Below code snippet is used to supply the response message captured from opt-out webpage to the AppSDK

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

==== Step 8: Closing the AppSDK instance ====
Kindly call this API whenever the application is closing or before creating another AppSDK instance.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When need to check the current SDK version.
|-
|getOptOutStatus()
|Retrieve the Opt-Out or Opt-In state.
|When need to know the Opt-Out or Opt-In status.
|}

=== Sample App: Download, Build, Emulator Setup, and Install the AndroidTV ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T12:47:16Z

VenkataDodla: /* Step 4: Starting the AppSDK Measurement (DCR/DTVR) */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integration into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring Android AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing Android AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR/DTVR)''' ====

'''4.1:''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DCR Video]
.put("adModel", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DTVR]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A comprehensive list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2:''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content. This is needed for DCR Video measurement.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

'''4.3:''' The following example demonstrates the passing of Nielsen ID3 tags to AppSDK during the playback of content. This is needed for DTVR measurement.

The following example code demonstrates the extraction of ID3 metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== Step 5: '''Stopping the AppSDK Measurement (DCR/DTVR)''' ====

The following code snippet demonstrates the pausing of AppSDK measurement whenever the video playback is paused or when switching between ad to content or content to ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

The following code snipped demonstrates the completion of AppSDK measurement in case of DCR Video typically used when content playback is completed. This is triggered 1) at the end of the content stream 2) if the user switches to another piece of content

Note: In case of DTVR this acts as an interrupt similar to stop() api

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== Step 6: Measuring Non Video Content (DCR Static) ====

The following code snippet demonstrates the measurement of static screens/pages by sending the metadata of the static page/screen to AppSDK.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

The following code snippet demonstrates the completion of static screens/pages measurement by invoking staticEnd() on AppSDK which will finalise the screen/page viewed time.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== Step 7: Opting out of AppSDK measurement ====
The following example code is to provide users the ability to opt out of Nielsen measurement.

Below code snippet is used to fetch the Nielsen opt-out web page URL

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Below code snippet is used to supply the response message captured from opt-out webpage to the AppSDK

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

==== Step 8: Closing the AppSDK instance ====
Kindly call this API whenever the application is closing or before creating another AppSDK instance.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When need to check the current SDK version.
|-
|getOptOutStatus()
|Retrieve the Opt-Out or Opt-In state.
|When need to know the Opt-Out or Opt-In status.
|}

=== Sample App: Download, Build, Emulator Setup, and Install the AndroidTV ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T12:45:47Z

VenkataDodla: /* Sample App: Download, Build, and Emulator Setup */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integration into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring Android AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing Android AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR/DTVR)''' ====

'''4.1''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DCR Video]
.put("adModel", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DTVR]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A comprehensive list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content. This is needed for DCR Video measurement.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

'''4.3''' The following example demonstrates the passing of Nielsen ID3 tags to AppSDK during the playback of content. This is needed for DTVR measurement.

The following example code demonstrates the extraction of ID3 metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== Step 5: '''Stopping the AppSDK Measurement (DCR/DTVR)''' ====

The following code snippet demonstrates the pausing of AppSDK measurement whenever the video playback is paused or when switching between ad to content or content to ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

The following code snipped demonstrates the completion of AppSDK measurement in case of DCR Video typically used when content playback is completed. This is triggered 1) at the end of the content stream 2) if the user switches to another piece of content

Note: In case of DTVR this acts as an interrupt similar to stop() api

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== Step 6: Measuring Non Video Content (DCR Static) ====

The following code snippet demonstrates the measurement of static screens/pages by sending the metadata of the static page/screen to AppSDK.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

The following code snippet demonstrates the completion of static screens/pages measurement by invoking staticEnd() on AppSDK which will finalise the screen/page viewed time.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== Step 7: Opting out of AppSDK measurement ====
The following example code is to provide users the ability to opt out of Nielsen measurement.

Below code snippet is used to fetch the Nielsen opt-out web page URL

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Below code snippet is used to supply the response message captured from opt-out webpage to the AppSDK

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

==== Step 8: Closing the AppSDK instance ====
Kindly call this API whenever the application is closing or before creating another AppSDK instance.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When need to check the current SDK version.
|-
|getOptOutStatus()
|Retrieve the Opt-Out or Opt-In state.
|When need to know the Opt-Out or Opt-In status.
|}

=== Sample App: Download, Build, Emulator Setup, and Install the AndroidTV ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T12:44:27Z

VenkataDodla: /* Open up Android TV Emulator */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integration into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring Android AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing Android AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR/DTVR)''' ====

'''4.1''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DCR Video]
.put("adModel", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DTVR]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A comprehensive list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content. This is needed for DCR Video measurement.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

'''4.3''' The following example demonstrates the passing of Nielsen ID3 tags to AppSDK during the playback of content. This is needed for DTVR measurement.

The following example code demonstrates the extraction of ID3 metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== Step 5: '''Stopping the AppSDK Measurement (DCR/DTVR)''' ====

The following code snippet demonstrates the pausing of AppSDK measurement whenever the video playback is paused or when switching between ad to content or content to ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

The following code snipped demonstrates the completion of AppSDK measurement in case of DCR Video typically used when content playback is completed. This is triggered 1) at the end of the content stream 2) if the user switches to another piece of content

Note: In case of DTVR this acts as an interrupt similar to stop() api

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== Step 6: Measuring Non Video Content (DCR Static) ====

The following code snippet demonstrates the measurement of static screens/pages by sending the metadata of the static page/screen to AppSDK.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

The following code snippet demonstrates the completion of static screens/pages measurement by invoking staticEnd() on AppSDK which will finalise the screen/page viewed time.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== Step 7: Opting out of AppSDK measurement ====
The following example code is to provide users the ability to opt out of Nielsen measurement.

Below code snippet is used to fetch the Nielsen opt-out web page URL

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Below code snippet is used to supply the response message captured from opt-out webpage to the AppSDK

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

==== Step 8: Closing the AppSDK instance ====
Kindly call this API whenever the application is closing or before creating another AppSDK instance.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When need to check the current SDK version.
|-
|getOptOutStatus()
|Retrieve the Opt-Out or Opt-In state.
|When need to know the Opt-Out or Opt-In status.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T12:41:28Z

VenkataDodla: /* Android AppSDK Integrations into Android TV App */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integration into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring Android AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing Android AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR/DTVR)''' ====

'''4.1''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DCR Video]
.put("adModel", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DTVR]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A comprehensive list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content. This is needed for DCR Video measurement.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

'''4.3''' The following example demonstrates the passing of Nielsen ID3 tags to AppSDK during the playback of content. This is needed for DTVR measurement.

The following example code demonstrates the extraction of ID3 metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== Step 5: '''Stopping the AppSDK Measurement (DCR/DTVR)''' ====

The following code snippet demonstrates the pausing of AppSDK measurement whenever the video playback is paused or when switching between ad to content or content to ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

The following code snipped demonstrates the completion of AppSDK measurement in case of DCR Video typically used when content playback is completed. This is triggered 1) at the end of the content stream 2) if the user switches to another piece of content

Note: In case of DTVR this acts as an interrupt similar to stop() api

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== Step 6: Measuring Non Video Content (DCR Static) ====

The following code snippet demonstrates the measurement of static screens/pages by sending the metadata of the static page/screen to AppSDK.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

The following code snippet demonstrates the completion of static screens/pages measurement by invoking staticEnd() on AppSDK which will finalise the screen/page viewed time.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== Step 7: Opting out of AppSDK measurement ====
The following example code is to provide users the ability to opt out of Nielsen measurement.

Below code snippet is used to fetch the Nielsen opt-out web page URL

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Below code snippet is used to supply the response message captured from opt-out webpage to the AppSDK

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

==== Step 8: Closing the AppSDK instance ====
Kindly call this API whenever the application is closing or before creating another AppSDK instance.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When need to check the current SDK version.
|-
|getOptOutStatus()
|Retrieve the Opt-Out or Opt-In state.
|When need to know the Opt-Out or Opt-In status.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T12:41:08Z

VenkataDodla: /* Step 4: Starting the AppSDK Measurement (DCR/DTVR) */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring Android AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing Android AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR/DTVR)''' ====

'''4.1''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DCR Video]
.put("adModel", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DTVR]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A comprehensive list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content. This is needed for DCR Video measurement.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

'''4.3''' The following example demonstrates the passing of Nielsen ID3 tags to AppSDK during the playback of content. This is needed for DTVR measurement.

The following example code demonstrates the extraction of ID3 metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== Step 5: '''Stopping the AppSDK Measurement (DCR/DTVR)''' ====

The following code snippet demonstrates the pausing of AppSDK measurement whenever the video playback is paused or when switching between ad to content or content to ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

The following code snipped demonstrates the completion of AppSDK measurement in case of DCR Video typically used when content playback is completed. This is triggered 1) at the end of the content stream 2) if the user switches to another piece of content

Note: In case of DTVR this acts as an interrupt similar to stop() api

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== Step 6: Measuring Non Video Content (DCR Static) ====

The following code snippet demonstrates the measurement of static screens/pages by sending the metadata of the static page/screen to AppSDK.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

The following code snippet demonstrates the completion of static screens/pages measurement by invoking staticEnd() on AppSDK which will finalise the screen/page viewed time.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== Step 7: Opting out of AppSDK measurement ====
The following example code is to provide users the ability to opt out of Nielsen measurement.

Below code snippet is used to fetch the Nielsen opt-out web page URL

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Below code snippet is used to supply the response message captured from opt-out webpage to the AppSDK

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

==== Step 8: Closing the AppSDK instance ====
Kindly call this API whenever the application is closing or before creating another AppSDK instance.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When need to check the current SDK version.
|-
|getOptOutStatus()
|Retrieve the Opt-Out or Opt-In state.
|When need to know the Opt-Out or Opt-In status.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T12:34:04Z

VenkataDodla:

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring Android AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing Android AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR/DTVR)''' ====

'''4.1''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DCR Video]
.put("adModel", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DTVR]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A comprehensive list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content. This is needed for DCR Video measurement.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

'''4.3''' The following example demonstrates the passing of Nielsen ID3 tags to AppSDK during the playback of content. This is needed for DTVR measurement.

The following example code demonstrates the extraction of ID3 metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight><syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== Step 5: '''Stopping the AppSDK Measurement (DCR/DTVR)''' ====

The following code snippet demonstrates the pausing of AppSDK measurement whenever the video playback is paused or when switching between ad to content or content to ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

The following code snipped demonstrates the completion of AppSDK measurement in case of DCR Video typically used when content playback is completed. This is triggered 1) at the end of the content stream 2) if the user switches to another piece of content

Note: In case of DTVR this acts as an interrupt similar to stop() api

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== Step 6: Measuring Non Video Content (DCR Static) ====

The following code snippet demonstrates the measurement of static screens/pages by sending the metadata of the static page/screen to AppSDK.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

The following code snippet demonstrates the completion of static screens/pages measurement by invoking staticEnd() on AppSDK which will finalise the screen/page viewed time.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== Step 7: Opting out of AppSDK measurement ====
The following example code is to provide users the ability to opt out of Nielsen measurement.

Below code snippet is used to fetch the Nielsen opt-out web page URL

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Below code snippet is used to supply the response message captured from opt-out webpage to the AppSDK

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

==== Step 8: Closing the AppSDK instance ====
Kindly call this API whenever the application is closing or before creating another AppSDK instance.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When need to check the current SDK version.
|-
|getOptOutStatus()
|Retrieve the Opt-Out or Opt-In state.
|When need to know the Opt-Out or Opt-In status.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T12:27:54Z

VenkataDodla: /* Step 7: Opting out of AppSDK measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring Android AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing Android AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR/DTVR)''' ====

'''4.1''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DCR Video]
.put("adModel", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DTVR]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A comprehensive list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content. This is needed for DCR Video measurement.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

'''4.3''' The following example demonstrates the passing of Nielsen ID3 tags to AppSDK during the playback of content. This is needed for DTVR measurement.

The following example code demonstrates the extraction of ID3 metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight><syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== Step 5: '''Stopping the AppSDK Measurement (DCR/DTVR)''' ====

The following code snippet demonstrates the pausing of AppSDK measurement whenever the video playback is paused or when switching between ad to content or content to ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

The following code snipped demonstrates the completion of AppSDK measurement in case of DCR Video typically used when content playback is completed. This is triggered 1) at the end of the content stream 2) if the user switches to another piece of content

Note: In case of DTVR this acts as an interrupt similar to stop() api

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== Step 6: Measuring Non Video Content (DCR Static) ====

The following code snippet demonstrates the measurement of static screens/pages by sending the metadata of the static page/screen to AppSDK.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

The following code snippet demonstrates the completion of static screens/pages measurement by invoking staticEnd() on AppSDK which will finalise the screen/page viewed time.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== Step 7: Opting out of AppSDK measurement ====
The following example code is to provide users the ability to opt out of Nielsen measurement.

Below code snippet is used to fetch the Nielsen opt-out web page URL

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Below code snippet is used to supply the response message captured from opt-out webpage to the AppSDK

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== Step 8: Closing the AppSDK instance ====
Kindly call this API whenever the application is closing or before creating another AppSDK instance.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T12:18:34Z

VenkataDodla: /* Step 4: Starting the AppSDK Measurement (DCR/DTVR) */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring Android AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing Android AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR/DTVR)''' ====

'''4.1''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DCR Video]
.put("adModel", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DTVR]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A comprehensive list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content. This is needed for DCR Video measurement.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

'''4.3''' The following example demonstrates the passing of Nielsen ID3 tags to AppSDK during the playback of content. This is needed for DTVR measurement.

The following example code demonstrates the extraction of ID3 metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight><syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== Step 5: '''Stopping the AppSDK Measurement (DCR/DTVR)''' ====

The following code snippet demonstrates the pausing of AppSDK measurement whenever the video playback is paused or when switching between ad to content or content to ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

The following code snipped demonstrates the completion of AppSDK measurement in case of DCR Video typically used when content playback is completed. This is triggered 1) at the end of the content stream 2) if the user switches to another piece of content

Note: In case of DTVR this acts as an interrupt similar to stop() api

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== Step 6: Measuring Non Video Content (DCR Static) ====

The following code snippet demonstrates the measurement of static screens/pages by sending the metadata of the static page/screen to AppSDK.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

The following code snippet demonstrates the completion of static screens/pages measurement by invoking staticEnd() on AppSDK which will finalise the screen/page viewed time.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== Step 7: Opting out of AppSDK measurement ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T12:16:32Z

VenkataDodla: /* Step 4: Starting the AppSDK Measurement (DCR Video) */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring Android AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing Android AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR/DTVR)''' ====

'''4.1''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DCR Video]
.put("adModel", "2") // type of ad load i.e 1=linear, 2=dynamic [required for DTVR]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A comprehensive list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content. This is needed for DCR Video measurement.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

'''4.3''' The following example demonstrates the passing of Nielsen ID3 tags to AppSDK during the playback of content. This is needed for DTVR measurement.

The following example code demonstrates the extraction of ID3 metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight><syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== Step 5: '''Stopping the AppSDK Measurement (DCR/DTVR)''' ====

The following code snippet demonstrates the pausing of AppSDK measurement whenever the video playback is paused or when switching between ad to content or content to ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

The following code snipped demonstrates the completion of AppSDK measurement in case of DCR Video typically used when content playback is completed. This is triggered 1) at the end of the content stream 2) if the user switches to another piece of content

Note: In case of DTVR this acts as an interrupt similar to stop() api

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== Step 6: Measuring Non Video Content (DCR Static) ====

The following code snippet demonstrates the measurement of static screens/pages by sending the metadata of the static page/screen to AppSDK.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

The following code snippet demonstrates the completion of static screens/pages measurement by invoking staticEnd() on AppSDK which will finalise the screen/page viewed time.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== Step 7: Opting out of AppSDK measurement ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T11:39:44Z

VenkataDodla: /* Step 4: Starting the AppSDK Measurement (DCR Video) */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring Android AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing Android AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR Video)''' ====

'''4.1''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A detailed list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T11:38:17Z

VenkataDodla: /* Step 4: Starting the AppSDK Measurement (DCR Video) */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring Android AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing Android AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR Video)''' ====

'''4.1''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A detailed list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T11:37:47Z

VenkataDodla: /* Step 4: Starting the AppSDK Measurement (DCR Video) */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring Android AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing Android AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR Video)''' ====

'''4.1''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A detailed list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T11:36:24Z

VenkataDodla: /* Step 4: Starting the AppSDK Measurement (DCR Video) */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring Android AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing Android AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR Video)''' ====

'''4.1''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A detailed list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T11:35:44Z

VenkataDodla: /* Step 4: Starting the AppSDK Measurement (DCR Video) */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring Android AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing Android AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR Video)''' ====
The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

'''4.1''' The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A detailed list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

'''4.2''' The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T11:31:15Z

VenkataDodla: /* Step1: Adding Nielsen AppSDK Dependency */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
The below steps cover the complete integration process including AppSDK initialization, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step 1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== Step 2: Configuring Android AppSDK Initialization Parameters ====
Build the JSON object by providing required values (App ID and Debug level).

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== Step 3: Initializing Android AppSDK ====
The following example code is for creating a singleton manager (Refer NielsenSdkManager.kt from the sample app source) and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''Step 4: Starting the AppSDK Measurement (DCR Video)''' ====
The following example code demonstrates the invocation of play() and loadMetadata() api calls whenever video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // name of the episode [required]
.put("length", "3600") // length of content [required]
.put("adloadtype", "2") // type of ad load i.e 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName") // pass descriptive stream information through this parameter
.put("mediaURL", "videoUrl") // Video URL value for the content that is being played

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

A detailed list of parameters which can be passed to AppSDK are listed here - [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()]

The following example demonstrates the passing of playhead positions to AppSDK every one second during the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T11:04:15Z

VenkataDodla: /* Android AppSDK Integrations into Android TV App */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
The below steps cover the complete integration process including AppSDK initialisation, metadata ingestion, playhead tracking, ID3 tag processing and user opt-out/opt-in implementation.

==== Step1: Adding Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the Application module within the build.gradle file.

In the app-level configuration file (build.gradle), add the below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

SDK should receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T10:49:21Z

VenkataDodla: /* Open up Android TV Emulator */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

SDK should receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T10:47:42Z

VenkataDodla: /* 1.8: User Opt-Out Implementation */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

SDK should receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.

<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T10:46:59Z

VenkataDodla: /* 1.7: DTVR - ID3 Tag Processing */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

SDK should receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.

<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T10:46:43Z

VenkataDodla: /* 1.6: DCR Static - Non Video Content Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

SDK should receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.

<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T10:46:14Z

VenkataDodla: /* 1.5: DCR Video - Stop/End Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

SDK should receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.

<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T10:45:50Z

VenkataDodla: /* 1.4: DCR Video - Start Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

SDK should receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T10:45:22Z

VenkataDodla: /* 1.1: Add Nielsen AppSDK Dependency */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}
</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

SDK should receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T10:44:38Z

VenkataDodla: /* 1.1: Add Nielsen AppSDK Dependency */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

SDK should receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T10:44:18Z

VenkataDodla: /* 1.8: User Opt-Out Implementation */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

SDK should receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T10:43:42Z

VenkataDodla: /* 1.5: DCR Video - Stop/End Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

SDK should receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2: Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T10:40:56Z

VenkataDodla:

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

SDK should receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T10:39:43Z

VenkataDodla:

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

SDK should receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T10:38:45Z

VenkataDodla:

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

SDK should receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-18T10:38:21Z

VenkataDodla:

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.

<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.

<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.

<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

SDK should receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.

<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.

<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.

<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.

<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state.

<syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.

<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T10:20:48Z

VenkataDodla: /* 1.4: DCR Video - Start Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

SDK should receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state. <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T09:04:40Z

VenkataDodla: /* 1.6: DCR Static - Non Video Content Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

Receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state. <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T09:03:41Z

VenkataDodla: /* 1.4: DCR Video - Start Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

Receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content.

<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state. <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T09:00:07Z

VenkataDodla:

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

Receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content. <syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state. <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T08:59:45Z

VenkataDodla:

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

Receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content. <syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state. <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T08:59:19Z

VenkataDodla: /* 1.4: DCR Video - Start Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call [https://engineeringportal.nielsen.com/wiki/play() play()] and [https://engineeringportal.nielsen.com/wiki/loadMetadata() loadMetadata()] when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

Receive a [https://engineeringportal.nielsen.com/wiki/setPlayheadPosition() playhead position] update every one second on the playback of content. <syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state. <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T08:50:30Z

VenkataDodla:

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call play() and loadMetadata() when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

Receive a playhead position update every one second on the playback of content. The playhead position is the current location of the player from the beginning of the asset in seconds; When streaming live content, the playhead position passed to the AppSDK is the current Unix timestamp.<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state. <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T08:38:35Z

VenkataDodla: /* 1.7: DTVR - ID3 Tag Processing */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call play() and loadMetadata() when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

Receive a playhead position update every one second on the playback of content. The playhead position is the current location of the player from the beginning of the asset in seconds; When streaming live content, the playhead position passed to the AppSDK is the current Unix timestamp (seconds since Jan-1-1970 UTC).<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Extracting the ID3 Metadata events from ExoPlayer.<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state. <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T08:37:43Z

VenkataDodla: update setPlayheadp position

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call play() and loadMetadata() when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

Receive a playhead position update every one second on the playback of content. The playhead position is the current location of the player from the beginning of the asset in seconds; When streaming live content, the playhead position passed to the AppSDK is the current Unix timestamp (seconds since Jan-1-1970 UTC).<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

This sample code for extracting the ID3 Metadata events from ExoPlayer.<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state. <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T08:32:45Z

VenkataDodla: /* 1.9: Close AppSDK API */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call play() and loadMetadata() when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

Reporting playhead position every 1 second during active playback.<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

This sample code for extracting the ID3 Metadata events from ExoPlayer.<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state. <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Call this API to close the SDK instance on when App is closing.<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T08:26:21Z

VenkataDodla: updated content

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call play() and loadMetadata() when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

Reporting playhead position every 1 second during active playback.<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Used when playback is paused and when switching between ad and content or content and ad.<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

Used when content playback is complete. This is triggered 1) at the end of the content stream, 2) if the user switches to another piece of content.<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Used to send the metadata for the static page.<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

Used with DCR Static duration in between loadMetadata calls for static content when section name is the same but a new static view event and duration measurement restart is desired.<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

This sample code for extracting the ID3 Metadata events from ExoPlayer.<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Used to send the ID3 metadata to AppSDK.<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Used to fetch the Nielsen opt-out web page URL.<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Used to supply the response message from opt-out webpage to the SDK.<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Call this API to retrieve the Opt-Out or Opt-In state. <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Close SDK (App Exit Only) :<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T08:04:22Z

VenkataDodla: sub point 1.6 updated

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call play() and loadMetadata() when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

Reporting playhead position every 1 second during active playback.<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Pause Playback :<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

End Content Session (Video End) :<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Start Static Measurement :<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

End Static Measurement :<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Listen for ID3 Metadata (ExoPlayer) :<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Send ID3 Tags to Nielsen SDK :<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Get Opt-Out URL :<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Handle Opt-Out Response :<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Check Opt-Out Status : <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Close SDK (App Exit Only) :<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T07:56:33Z

VenkataDodla: install the apk section has updated

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call play() and loadMetadata() when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

Reporting playhead position every 1 second during active playback.<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Pause Playback :<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

End Content Session (Video End) :<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

1.6: DCR Static - Non Video Content Measurement

The following example code is for measuring non video content like WebViews and articles.

Start Static Measurement :<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

End Static Measurement :<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Listen for ID3 Metadata (ExoPlayer) :<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Send ID3 Tags to Nielsen SDK :<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Get Opt-Out URL :<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Handle Opt-Out Response :<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Check Opt-Out Status : <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Close SDK (App Exit Only) :<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

==== 3.4: Install the AndroidTV sample video player App ====
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T07:51:37Z

VenkataDodla: /* 1.10: Android AppSDK Getter Methods */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call play() and loadMetadata() when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

Reporting playhead position every 1 second during active playback.<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Pause Playback :<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

End Content Session (Video End) :<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

1.6: DCR Static - Non Video Content Measurement

The following example code is for measuring non video content like WebViews and articles.

Start Static Measurement :<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

End Static Measurement :<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Listen for ID3 Metadata (ExoPlayer) :<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Send ID3 Tags to Nielsen SDK :<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Get Opt-Out URL :<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Handle Opt-Out Response :<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Check Opt-Out Status : <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Close SDK (App Exit Only) :<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

=== Install the AndroidTV sample video player App ===
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T07:49:49Z

VenkataDodla: /* Quick Reference - Android AppSDK Methods */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call play() and loadMetadata() when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

Reporting playhead position every 1 second during active playback.<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Pause Playback :<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

End Content Session (Video End) :<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

1.6: DCR Static - Non Video Content Measurement

The following example code is for measuring non video content like WebViews and articles.

Start Static Measurement :<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

End Static Measurement :<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Listen for ID3 Metadata (ExoPlayer) :<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Send ID3 Tags to Nielsen SDK :<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Get Opt-Out URL :<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Handle Opt-Out Response :<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Check Opt-Out Status : <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Close SDK (App Exit Only) :<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

==== 1.10: Android AppSDK Getter Methods ====
These methods provide information like Android AppSDK Version, NielsenId details.

Get Nielsen ID :<syntaxhighlight lang="kotlin">
fun getNielsenId(): String = mAppSdk?.nielsenId ?: ""
</syntaxhighlight>Get Device ID :<syntaxhighlight lang="kotlin">
fun getDeviceId(): String = mAppSdk?.deviceId ?: ""
</syntaxhighlight>Get Demographic ID :<syntaxhighlight lang="kotlin">
fun getDemographicId(): String = mAppSdk?.demographicId ?: ""
</syntaxhighlight>Get SDK Meter Version :<syntaxhighlight lang="kotlin">
fun getMeterVersion(): String = AppSdk.getMeterVersion()
</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|-
|getNielsenId()
|Retrieve Nielsen ID
|When you need to access the unique Nielsen identifier.
|-
|getDeviceId()
|Retrieve Device ID
|When you need to access the unique device identifier.
|-
|getDemographicId()
|Retrieve Demographic ID
|When you need to access the AppSDK session identifier.
|-
|getMeterVersion()
|Retrieve SDK Meter Version
|When you need to check the current SDK version.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

=== Install the AndroidTV sample video player App ===
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T07:34:40Z

VenkataDodla: /* 1.4: DCR Video - Start Measurement */

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call play() and loadMetadata() when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adloadtype", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

Reporting playhead position every 1 second during active playback.<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Pause Playback :<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

End Content Session (Video End) :<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

1.6: DCR Static - Non Video Content Measurement

The following example code is for measuring non video content like WebViews and articles.

Start Static Measurement :<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

End Static Measurement :<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Listen for ID3 Metadata (ExoPlayer) :<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Send ID3 Tags to Nielsen SDK :<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Get Opt-Out URL :<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Handle Opt-Out Response :<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Check Opt-Out Status : <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Close AppSDK API ====
Close SDK (App Exit Only) :<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

==== 1.10: Android AppSDK Getter Methods ====
These methods provide information like Android AppSDK Version, NielsenId details.

Get Nielsen ID :<syntaxhighlight lang="kotlin">
fun getNielsenId(): String = mAppSdk?.nielsenId ?: ""
</syntaxhighlight>Get Device ID :<syntaxhighlight lang="kotlin">
fun getDeviceId(): String = mAppSdk?.deviceId ?: ""
</syntaxhighlight>Get Demographic ID :<syntaxhighlight lang="kotlin">
fun getDemographicId(): String = mAppSdk?.demographicId ?: ""
</syntaxhighlight>Get SDK Meter Version :<syntaxhighlight lang="kotlin">
fun getMeterVersion(): String = AppSdk.getMeterVersion()
</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

=== Install the AndroidTV sample video player App ===
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]

AndroidTV

2026-06-17T07:31:00Z

VenkataDodla: section title updated

{{Breadcrumb|}} {{Breadcrumb|Digital}}{{Breadcrumb|DCR & DTVR}}{{CurrentBreadcrumb}}

== Introduction ==
This guide provides step-by-step instructions for integrating the Nielsen Android AppSDK into Android TV application.

The SDK supports three measurement types: DCR (Digital Content Ratings) Video for measuring VOD and live streaming video content by tracking playhead positions during playback, DCR Static for measuring non-video content such as web views, articles, and informational screens, and DTVR (Digital TV Ratings) for measuring live streams by processing Nielsen ID3 tags watermarks embedded in the broadcast signal.

=== Android AppSDK Integrations into Android TV App ===
This steps covers the complete integration process including AppSDK initialization, content metadata configuration, playhead tracking, ID3 tag processing, and user opt-out/in implementation.

==== 1.1: Add Nielsen AppSDK Dependency ====
Add the Nielsen Android AppSDK Jar maven dependency to the App module and configure build.gradle.

In the app-level configuration file (build.gradle), add this below dependencies.<syntaxhighlight lang="kotlin">
dependencies {
implementation 'com.nielsenappsdk.global:ad:10.2.0.0'
implementation 'com.google.android.gms:play-services-ads-identifier:18.2.0'
implementation "androidx.work:work-runtime:2.11.2"
}

</syntaxhighlight>

==== 1.2: Configure Android AppSDK Parameters ====
Build the JSON configuration with Nielsen credentials.<syntaxhighlight lang="kotlin">
val config = JSONObject()
.put("appid", "NIELSEN_APP_ID") // Nielsen-provided App ID [required]
.put("nol_devDebug", "DEBUG") // only for debug builds

</syntaxhighlight>

==== 1.3: Initialize Android AppSDK ====
The following example code is for creating a singleton manager and initializing the Android AppSDK when the app starts.<syntaxhighlight lang="kotlin">
private var mAppSdk: AppSdk? = null

fun initializeAppSdk(context: Context, config: JSONObject) {
mAppSdk = AppSdk(context, config, object : IAppNotifier {
override fun onAppSdkEvent(timestamp: Long, code: Int, description: String?) {
if (code == AppSdk.EVENT_STARTUP) {
Log.d("Nielsen", "AppSdk initialized successfully")
}
}
})

if (mAppSdk?.isValid != true) {
Log.e("Nielsen", "Failed to initialize AppSdk")
}
}

</syntaxhighlight>

==== '''1.4: DCR Video - Start Measurement''' ====
The following example code is to call play() and loadMetadata() when video playback begins.

<syntaxhighlight lang="kotlin">
fun appStartMeteringVideo(video: Video) {
// Build content metadata
val metaData = JSONObject()
.put("type", "content") // type of content [required]
.put("assetid", "uniqueassetid") // unique ID for each asset [required]
.put("program", "Program Name") // name of program [required]
.put("title", "Episode Title") // ex: S1E3 [required]
.put("length", "3600") // length of content [required]
.put("category", "Entertainment") // content category [required]
.put("adModel", "2") // 1=linear, 2=dynamic [required]

// Build channel information
val channelInfo = JSONObject()
.put("channelName", "channelName")
.put("mediaURL", "videoUrl")

// Start measurement
mAppSdk?.play(channelInfo)
mAppSdk?.loadMetadata(metaData)
}

</syntaxhighlight>

Reporting playhead position every 1 second during active playback.<syntaxhighlight lang="kotlin">
fun monitorPlayhead(exoPlayer: ExoPlayer) {
monitorJob = lifecycle.coroutineScope.launch(Dispatchers.Main) {
var ticks = 0
while (isActive) {
if (exoPlayer.isPlaying) {
val positionMs = exoPlayer.currentPosition
val durationMs = exoPlayer.duration

ticks++
// Report every 1 second (since loop runs every 500ms)
if (ticks % 2 == 0) {
val playheadToReport: Long = if (videoDuration <= 0) {
System.currentTimeMillis() / 1000 // Live: UTC time
} else {
videoPosition.toLong() // VOD: Position from start
}

mAppSdk?.setPlayheadPosition(playheadSeconds)
}
delay(500)
}
}
}

</syntaxhighlight>

==== 1.5: DCR Video - Stop/End Measurement ====
The following example code is for signal playback state changes for accurate measurement.

Pause Playback :<syntaxhighlight lang="kotlin">
fun appStopMeteringVideo() {
mAppSdk?.stop()
}

</syntaxhighlight>

End Content Session (Video End) :<syntaxhighlight lang="kotlin">
fun appEndMeteringVideo() {
mAppSdk?.end()
}

</syntaxhighlight>

Close SDK (App Exit Only) :<syntaxhighlight lang="kotlin">
fun appCloseMeteringVideo() {
mAppSdk?.close()
mAppSdk = null
}

</syntaxhighlight>

==== 1.6: DCR Static - Non Video Content Measurement ====
The following example code is for measuring non video content like WebViews and articles.

Start Static Measurement :<syntaxhighlight lang="kotlin">
fun staticLoadMetadata() {
val metadata = JSONObject()
.put("type", "static") // type of content [required]
.put("section", "Web View Screen") // section of site [required]
.put("segA", "CustomSegmentA") // custom segment [optional]
.put("segB", "CustomSegmentB") // custom segment [optional]
.put("segC", "CustomSegmentC") // custom segment [optional]
.put("crossId1", "Standard Episode ID") // [optional]
.put("crossId2", "Content Originator") // [optional]

mAppSdk?.loadMetadata(metadata)
}

</syntaxhighlight>

End Static Measurement :<syntaxhighlight lang="kotlin">
fun staticEnd() {
mAppSdk?.staticEnd()
}

</syntaxhighlight>

==== 1.7: DTVR - ID3 Tag Processing ====
The following example code is for processing Nielsen ID3 tags from live streams for DTVR measurement.

Listen for ID3 Metadata (ExoPlayer) :<syntaxhighlight lang="kotlin">
inner class PlayerEventListener : Player.Listener {
override fun onMetadata(metadata: Metadata) {
for (i in 0 until metadata.length()) {
val entry = metadata.get(i)
if (entry is PrivFrame) {
val owner = entry.owner
val data = String(entry.privateData, Charsets.UTF_8)

// Check if it's a Nielsen ID3 tag
if (owner.contains("nielsen", ignoreCase = true) ||
owner.contains("www.nielsen.com", ignoreCase = true)) {
appProcessID3tag(owner + data)
}
}
}
}
}

</syntaxhighlight>

Send ID3 Tags to Nielsen SDK :<syntaxhighlight lang="kotlin">
fun appProcessID3tag(id3String: String?) {
try {
mAppSdk?.sendID3(id3String)
} catch (e: Exception) {
Log.e("Nielsen", "Cannot process ID3 tag: ${e.message}")
}
}

</syntaxhighlight>

==== 1.8: User Opt-Out Implementation ====
The following example code is to provide users the ability to opt out of Nielsen measurement via WebView.

Get Opt-Out URL :<syntaxhighlight lang="kotlin">
fun getOptOutUrl(): String {
return mAppSdk?.userOptOutURLString() ?: ""
}
// Load this URL in a WebView
webView.loadUrl(getOptOutUrl())

</syntaxhighlight>

Handle Opt-Out Response :<syntaxhighlight lang="kotlin">
webView.webViewClient = object : WebViewClient() {
override fun shouldOverrideUrlLoading(view: WebView, request: WebResourceRequest): Boolean {
val url = request.url.toString()

// Check for Nielsen opt-out response
if (url.startsWith("nielsenappsdk://")) {
mAppSdk?.userOptOut(url)
// Navigate back or show confirmation
return true
}
return false
}
}

</syntaxhighlight>

Check Opt-Out Status : <syntaxhighlight lang="kotlin">
fun getOptOutStatus(): Boolean {
return mAppSdk?.optOutStatus ?: false
}

</syntaxhighlight>

==== 1.9: Android AppSDK Getter Methods ====
These methods provide information like Android AppSDK Version, NielsenId details.

Get Nielsen ID :<syntaxhighlight lang="kotlin">
fun getNielsenId(): String = mAppSdk?.nielsenId ?: ""
</syntaxhighlight>Get Device ID :<syntaxhighlight lang="kotlin">
fun getDeviceId(): String = mAppSdk?.deviceId ?: ""
</syntaxhighlight>Get Demographic ID :<syntaxhighlight lang="kotlin">
fun getDemographicId(): String = mAppSdk?.demographicId ?: ""
</syntaxhighlight>Get SDK Meter Version :<syntaxhighlight lang="kotlin">
fun getMeterVersion(): String = AppSdk.getMeterVersion()
</syntaxhighlight>

=== Quick Reference - Android AppSDK Methods ===
The table below provides a summary of the core Android AppSDK methods, their primary functions, and the appropriate triggers for calling them within your application lifecycle.
{| class="wikitable"
!Method
!Purpose
!When to Call
|-
|play(channelInfo)
|Start content session
|Video playback begins.
|-
|loadMetadata(metadata)
|Send content/Ad/static info
|After play API call or for static content.
|-
|setPlayheadPosition(video playback pos)
|Report playhead position
|setPlayheadPosition(pos) - sets the playhead position in AppSDK as video playback time (seconds) in the content (VOD Video On Demand) or the current UTC time for live stream.
|-
|sendID3(tag)
|Process DTVR videos
|When ID3 tag received from stream.
|-
|stop()
|Pause measurement
|Video paused.
|-
|end()
|End content session
|Video playback ends.
|-
|staticEnd()
|End static session
|Leave static content screen.
|-
|close()
|Destroy SDK instance
|App exit only.
|-
|userOptOutURLString()
|Get opt-out URL
|Display opt-out WebView.
|-
|userOptOut(url)
|Set opt-out preference
|When the user completes the opt-out.
|}

=== Sample App: Download, Build, and Emulator Setup ===
The following section provides instructions for downloading the sample application, building the APK within Android Studio, and setting up the necessary Android TV emulator environment for testing.

==== 3.1: Download the package here ====
Click [[Main Page|here]] to download the project and open the project in Android Studio IDE.

==== 3.2: Build the APK from this Project ====
Before building the apk, create an AndroidTV emulator from the IDE and install the App directly through Android Studio.

Follow the steps to test AndroidTV sample Apps in TV Emulators and how to build the app from the client package.

==== 3.3: Create the Android TV Emulator ====
To create an Android TV emulator, you primarily use [https://developer.android.com/studio Android Studio] to set up an Android Virtual Device (AVD).

=== Install the AndroidTV sample video player App ===
Once you have built the APK and configured your Android TV emulator, use either of the following methods to install the sample video player application.

Method 1: Drag and Drop (Easiest)

Use your mouse to drag and drop the APK onto the running emulator :

# Launch the Android TV emulator.
# Locate the .apk file on your computer.
# Drag the file and drop it directly onto the emulator window.
# Wait for the installation to automatically complete.

Method 2 : Use ADB (Command Line)

Use the Android Debug Bridge (ADB) if you have the Android SDK Platform-Tools installed :

# Open the terminal or command prompt.
# Ensure emulator is running and detected by typing: -> adb devices.
# Install the APK by running the following command: -> adb install path/to/your/sample_app.apk.

=== Open up Android TV Emulator ===
After installing the sample app, follow these steps to launch the Nielsen Sample TV application on your emulator.

Select Nielsen Sample TV App -> Select Legacy Option

[[File:Screenshot 20260527 133449.png|center|720x720px]]
[[File:Screenshot 20260527 133705.png|center|720x720px]]
[[File:Screenshot 20260527 134418.png|center|720x720px]]
[[File:Screenshot 20260529 152139.png|center|720x720px]]

Setting page for Select Opt out/in options

[[File:Screenshot 20260527 134647.png|center|720x720px|border]]

=== Next Steps ===
If there are any questions or concerns then please reach out to the AppSDK team. Reference the following guides for product specific information :

* [[DCR Video Android SDK|DCR Video]]
* [[DCR Static Android SDK|DCR Static]]
* [[DTVR Android SDK|DTVR]]

For further technical details , please contact your Technical Account Manager (TAM).

__NOTOC__
[[Category:Digital]]