Insight analytics

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 normally equates to playback of one content, starting when the content is loaded into the player and ending when the content is unloaded from the player.

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.

JS

{
  "insightCollectorURL" : "http://validator.insight-stats.com",
  "reportingPeriodInitialDelay" : "3000",
  "reportingPeriod" : "30000",
  "appName":"Sample App",
  "appVersion":"1.0.0",
  "deviceType":"handheld",
  "osType":"Android",
  "videoDecoderType":"H.264",
  "audioDecoderType":"AAC",
  "streamingFormat":"HLS",
  "drmName":"DRM",
  "drmVersion":"1",
  "gpuModel":"None",
  "operatorId":"opId",
  "accessToken":"token"
}

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.

JAVA

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

Create Agent

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

JAVA

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 will be needed by the session; this includes metadata related to the stream currently playing. If the application has the 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 following snippet would need to be called after receiving the OnPreparedListener.onPrepared event.

JAVA

ContentInfoHolder contentInfoHolder = new ContentInfoHolder();
contentInfoHolder.setName(mStream.getStreamName());
contentInfoHolder.setUri(mLastVideoUri);
contentInfoHolder.setDuration(mNmpVideoView.getDuration());
contentInfoHolder.setChannelName(mLastVideoUri);
contentInfoHolder.setType((mNmpVideoView.getDuration() == -1) ? "LIVE" : "VOD");
ArrayList<Integer> bitrateList = new ArrayList<Integer>() {{ for (int i : NetworkStatistics.getAdaptiveStreaming().getAvailableBitrates()) add(i); }};
contentInfoHolder.setBitrates(bitrateList);
if(DRMHandler.getInstance() != null){
  if(!DRMHandler.getInstance().getContentId().isEmpty()) {
    contentInfoHolder.setScrambled(true);
    contentInfoHolder.setContentId(DRMHandler.getInstance().getContentId());
    contentInfoHolder.setChannelName(DRMHandler.getInstance().getContentName());
  }
}

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.

JAVA

mInsightAgent.startSession(mNmpVideoView, contentInfoHolder);

Stop Session

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

JAVA

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