Using the OtvAa Agent API

The agent-app source code demonstrates the basic functionality described below. It is designed in a form of tabs to save screen real-estate and to separate functionality, where when traversing from the left tab to the right, we go through the steps described earlier at Working with the Agent / Wrapper API.

Most operations begin with setting check-boxes and filling in some fields (pre-filled with default values that can be overridden), and then tapping a button that starts an operations based on the field values. The management of those values is UI and application specific and therefore skipped in the guide below.

Initialising the agent

The setting up of the OtvAnalyticsAgent is done in two steps. First, we instantiate the agent with the application context:

JAVA

OtvAnalyticsAgent agent = new OtvAnalyticsAgent(getApplicationContext());

The second step is initialising the newly-created instance. The OtvAnalyticsAgent.initialise() takes two parameters, and returns an OtvAaError value, which, if successful, returns OK value.

The first parameter of the initialisation is the agent configuration as a JSON object with 4 string parameters and an array of destinations:

JSON

{
  "deviceId":"myDeviceId",
  "userId":"myUserId",
  "accountId":"12345",
  "destinations":[
    {
      "name":"uav",
      "config":{
        "url":"https://url-to-uav",
        "token":"myUavAccessToken"
      }
    }
  ]
}

The agent configuration contains an array of destinations. Currently only one type of destination is supported: uav. It is envisaged that multiple activity destinations may be supported in the future.

The second intialisation parameter is a listener for asynchronous events coming from the agent. The application needs to implement a OtvAaReportListener with two callback methods to override. For example:

JAVA

  OtvAnalyticsAgent.OtvAaReportListener reportListener = new OtvAnalyticsAgent.OtvAaReportListener() {
    // Capture errors reported by the agent. Perhaps report it to the user.
    @Override
    public void onError(OtvAaError xErrorCode, int xExtra) {
      doSomethingWith(xErrorCode, xExtra);
    }
    
    // This method captures activity reports coming from the agent. It is not essential
    // to do anything with this method. It is useful for debugging E2E operations.
    @Override
    public void onActivityReport(@NonNull String xActivityName, @NonNull String xUrl, @NonNull String xMetadata, int xHttpResponseCode, @NonNull String xResponse) {
      reportActivity(xActivityName, xUrl, xMetadata, xHttpResponseCode, xResponse);
    }
  };

With the above two parameters we can now initialise the agent.

CODE

OtvAaError result = agent.initialise(agentConfigJson, reportListener);

Note that you can check if initialisation is successful in two ways: either by checking that

result == OtvAaError.OK

or by checking

boolean success == Agent.isInitialised()

Updating the Configuration

The configuration may need to be changed in the case of the userId changing, or to refresh the UAV access token before it expires. The format of the configuration is the same as for initialisation, and only the allowed fields will have an effect. Changed values for fields not open for reconfiguration would be discarded by the agent.

CODE

OtvAaError result = agent.updateConfig(agentConfigJson);

Submitting Activities

appStart

All activities other than appStart are submitted using:

JAVA

OtvAnalyticsAgent.submitActivity(OtvActivity xActivity, JSONObject xMetadata)

The first activity to submit is appStart, and it has a dedicated method to call

JAVA

OtvAaError appStart(JSONObject xMetadata)

The typical metadata will look something like:

JSON

{
  "appSessionId":"mySessionId",
  "activityDateTime":"1970-01-01 00:00:00"
}

Errors reported can be synchronous (in the return value of the call, for example if metadata validation encounters an error) or may be anynchronous (reported in the onError() callback, for example due to a network glitch).

submitActivity

The first parameter for submitActivity() is an enumeration for available known activities

JAVA

OtvActivity xActivity

The second parameter is the metadata values for the specific activity. See https://docs.nagra.com/otv-analytics-agent/latest/otv-analytics-activities for details of which metadata is automatically populated when using the agent API:

JSON

{
  // The following are important as they're used to
  // identify the playback session in subsequent activities
  playbackSessionId: "<UUID/GUID>",
  editorialID: "editorialChannelId",
  contentSource: "<IPTV/OTT/Blend>",
  ContentType: "live-event",
  
  railId: "...",
  Depth: "...",
  hdepth: "...",
  vdepth: "...",
  templateId: "...",
  technicalId: "...",
  programmeId: "...",
  seriesId: "...",
  deepLinkId: "..."
}

Once the acivity and its metadata are set, we can submit the activity:

JAVA

OtvAaError result = agent.submitActivity(OtvActivity.PlaybackStart, metadata);

Errors reported can be synchronous (in the return value of the call, for example if metadata validation encounters an error) or may be anynchronous (reported in the onError() callback, for example due to a network glitch).

Stop Playing and Clean-up

A playbackStop activity is optional when stopping one playback and starting another. The next playbackStart activity will be used to find when the previous session stopped.

Sometimes it is not possible to guarantee clean up at the end of a playback or application session (e.g., if the user navigates away from the application, closes the browser, or the application is sent to the background), however the client application should endeavour to clean up using the following sequence to ensure no loss of data:

JAVA

JSONObject stopMetadata = // Create a metadata object with at least the Position field

agent.submitActivity(OtvActivity.PlaybackStop, stopMetadata);
agent.submitActivity(otvaa.OtvActivity.AppEnd);
agent = null;

Error Handling

Synchronous errors are the OtvAaError return values from method calls to the agent.

Other asynchronous errors, mostly the results of network operations and calls to the server, would be sent to the OtvAnalyticsAgent.tvAaReportListener.onError(OtvAaError xErrorCode, int xExtra) callback.

See the API documentation at OpenTV Analytics Agent for Android APIs .