OpenTV Analytics Agent for Android Integration Guide

As described in the OpenTV Analytics Agent Overview pages, there are two sets of API for using the agent which are mutually exclusive. The Wrapper API (OtvAnalyticsAgentWrapper) is for clients using then OpenTV Connect Player or Bitmovin Player SDK, and facilitates collecting events and metrics from the player and reporting this data to the analytics server(s). The Agent API (OtvAnalyticsAgent) is for clients who do not use either of the wrapper supported Players. Internally, OtvAnalyticsAgentWrapper controls an instance OtvAnalyticsAgent.

A client application should use either the agent API, or the wrapper API, but not a mixture of the two

The Wrapper API also supports collecting and reporting data from the player to the legacy Insight Analytics services. For this functionality OtvAa depends on an additional library - the Nagra Insight Agent (ni_agent) library.

In the OtvAa for Android package there are two zipped Android source code files of sample applications demonstrating how an application can report data in each of the two modes. These can be good starting points. When using the source code, don’t forget to add libraries to the Android project as advised in the top page.

1.1.1. Multi-instance support

For future compatibility, the two main classes OtvAnalyticsAgent and OtvAnalyticsAgentWrapper are not designed as singletons. However, the current implementation relies on there being a single instance (if the application runs more than one player instance, only one of them should report statistics to the agent). The main reason is because the wrapper still needs to support the legacy Insight agent.

1.1.2. Working with the Agent / Wrapper API

The simplified steps for working with either API is the same:

• Prepare a JSON configuration object with initialising parameters

  • For the Agent there is one JSON configuration object

  • To configure the Wrapper, you need one JSON configuration object for the wrapper in addition to the one for the Agent.

  • The JSON configuration object for the wrapper may contain, if required, configuration parameters of the Insight agent.

• Instantiate the agent / wrapper and initialise

• First activity to submit - appStart

  • Each appStart activity is associated with its unique appSessionId value.

• Subsequent activities to submit

  • Playback-related activities are associated with a unique playbackSessionId value that is explicitly provided to the Agent in a playbackStart activity's metadata, and optionally in consequent playback-related activities.

  • Activities are submitted one by one. However, the Wrapper attaches listeners to the Player to automatically report playback events and metrics, so when working with the Wrapper, there is no need to explicitly report any playback-related activities.

• Optionally update the agent / wrapper with some configuration parameters

And to end the lifecycle:

• Submit an appEnd acivity

• Release the Agent / Wrapper instance.

1.2. Next

Using the OtvAa Agent API

Using the OtvAa Wrapper API