To test this feature and view the example code, please see the Android SDK 5 Example Code Quick Start guide.

The application can report player metrics to the Insight servers using the Insight Agent class. It uses the Agent to manage Insight sessions alongside playback, during which content information and playback monitoring information are collated and uploaded to the Insight servers. A session lifecycle equates typically to the playback of one content, starting when the content is loaded into the player and ending when the content is unloaded.

The application is responsible for:

  • Instantiating and driving the player
  • Providing metadata about the content

The Agent is responsible for:

  • Observing metrics and events on the player
  • Reporting metrics and events to the Insight servers

Example code

Configuration file

For Insight to be available, a configuration file must be present at src/res/raw/analytics.json of the integrating application. The Insight Agent will read the configuration file when the application creates the Agent. An example configuration file is shown below.

  "insightCollectorURL" : "",
  "reportingPeriodInitialDelay" : "3000",
  "reportingPeriod" : "30000",
  "appName":"Sample App",

When using this as a reference, be sure to update fields specific to your account and application.

Import classes

The Insight Analytics Agent is delivered along with the Android SDK. To use the Insight Agent, the integrating application needs to import the classes.

import nagra.insight.agent.Agent;
import nagra.insight.agent.utils.ContentInfoHolder;

Request READ_PHONE_STATE permission (API 29 and above)

Before setting up Insight, runtime permission requests for `READ_PHONE_STATE` are necessary when both of the following conditions are true:

  • The application will run on Android Q devices
  • The application's targetSdkVersion is 29 (Android Q) or higher

The following code will, if necessary, show a system dialogue box requesting approval from the user. If permission has not already been granted, the user's approval comes back asynchronously in the onRequestPermissionsResult() callback, which is an Activity override.

if (checkReadPhoneStatePermission()) {
  // Permission granted. Can continue.
} else {
  // Permission not granted yet. Need to wait for user's approval.

public boolean checkReadPhoneStatePermission() {
  boolean hasPermission = (ActivityCompat.checkSelfPermission(this, Manifest.permission.READ_PHONE_STATE) == PackageManager.PERMISSION_GRANTED);
  if (!hasPermission) {
  return hasPermission;

public void requestReadPhoneStatePermission() {
  if (shouldShowRequestPermissionRationale(Manifest.permission.READ_PHONE_STATE)) {
	// Show our own request permission dialog before popping the system one.
	AlertDialog.Builder dialogBuilder = new AlertDialog.Builder(this);
	dialogBuilder.setTitle("External permission required for Read Phone State");
	dialogBuilder.setPositiveButton("Ok", (dialog, which) ->
	  requestPermissions(new String[]{Manifest.permission.READ_PHONE_STATE}, 1))
  } else {
	// Show system dialog to request permission
	requestPermissions(new String[]{Manifest.permission.READ_PHONE_STATE}, 1);

public void onRequestPermissionsResult(int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults) {
  // Dialogue results callback
  if (requestCode != 1) {
	// Not coming from our request, tagged as 1
  if (grantResults.length == 0 || grantResults[0] != PackageManager.PERMISSION_GRANTED) {
	// Permission refused/not granted by user
  } else {
	// Permission granted by user

Create Agent

Once the package has been imported, the application can create the Agent in the correct place:

mInsightAgent = new Agent(mContext);

The same Agent can be reused for multiple playback sessions, so there is usually no need to instantiate this class more than once.

Session control

The Agent is only responsible for collating the analytics data; it needs the application to control an Insight session alongside playback. The application should start and end the session to align with the playback of the stream.

  • For both live and VOD, a session should start when playback commences.
  • For VOD streams, a session should stop when the playback finishes, whether by error, user action or playout.
  • For live streams, a session should end when the stream is switched or is stopped by an error.

Prepare content information

When starting the session, the application should prepare the content information which the session will need; this includes metadata related to the stream currently playing. If the application has all metadata available before a stream is selected, this can be created on stream selection. If not, some can be obtained from the video view once it is prepared, in which case something similar to the following snippet would need to be called after receiving the OnPreparedListener.onPrepared event.

ContentInfoHolder contentInfoHolder = new ContentInfoHolder();
contentInfoHolder.setType((mNmpVideoView.getDuration() == -1) ? "LIVE" : "VOD");
ArrayList<Integer> bitrateList = new ArrayList<Integer>() {{ for (int i : NetworkStatistics.getAdaptiveStreaming().getAvailableBitrates()) add(i); }};
if(DRMHandler.getInstance() != null){
  if(!DRMHandler.getInstance().getContentId().isEmpty()) {

Start session

After getting all the content information available, the application can start the session with the content information and the OTVVideoView. Beware of the timing of starting the session; the application should only start the session after the onPrepared event has been received.

mInsightAgent.startSession(mNmpVideoView, contentInfoHolder);

Stop Session

The application should stop the session when the playback finishes, whether by error or user stopping the playback.

// Stop the Insight session when playback completes
mOTVVideoView.setOnCompletionListener(mp -> {
  OTVLog.i(TAG, "Playback complete");
// Stop the Insight session when there is an error during playback
mOTVVideoView.setOnErrorListener((mp, what, extra) -> {
  OTVLog.i(TAG, "Playback error");
  return true;