OTV Analytics Agent for Apple Integration Guide

As described in the https://docs.nagra.com/otv-analytics-agent/latest/ pages, there are two sets of API for using the agent which are mutually exclusive. If you don’t use a Nagra player, you must use the Agent API and OtvAnalyticsAgent. If you use https://docs.nagra.com/connect-player-sdk-5-for-apple-fps-docs/5.11.x/Default/, then Wrapper API, using OtvAnalyticsAgentWrapper, could be more useful as it facilitates collecting events and metrics from the player and reporting this data to the analytics server(s). Internally, OtvAnalyticsAgentWrapper controls an instance of 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 https://docs.nagra.com/insight-agent-for-apple/1.0.x/ (ni_agent) library.

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 OpenTV Connect 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 activity
Release the Agent / Wrapper instance.

Working with the Agent / Wrapper API

Next