View source for Digital Measurement Video 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 [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|link=https://nielsentest.mywikis.net/wiki/File:Screenshot_20260527_133449.png]][[File:Screenshot 20260527 133705.png|center|720x720px|link=https://nielsentest.mywikis.net/wiki/File:Screenshot_20260527_133705.png]][[File:Screenshot 20260527 134418.png|center|720x720px|link=https://nielsentest.mywikis.net/wiki/File:Screenshot_20260527_134418.png]][[File:Screenshot 20260529 152139.png|center|720x720px|link=https://nielsentest.mywikis.net/wiki/File:Screenshot_20260529_152139.png]]Setting page for  select  Opt out/in options[[File:Screenshot 20260527 134647.png|center|720x720px|border|link=https://nielsentest.mywikis.net/wiki/File:Screenshot_20260527_134647.png]]
===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__