Using the OTVAA Agent API

When the library is included in the HTML file, the agent API can be accessed in Javascript using the global object otvaa.agent.

Initialising the agent

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.

JS

function myErrorCallback(errorCode, errorDescription, extra) {
  // Handle the error
}

const agentConfig = {
  userId: “my-user-id”,
  accountId: “my-account-id”,
  deviceId: “my-device-id”,
  onError: myErrorCallback,
  destinations: [{
    name: “uav”,
    config: {
      url: “htpps://url-to-uav”,
      token: myUavAccessToken
    }
  }]
};

otvaa.agent.initialise(agentConfig);
const appStartMetadata = { appSessionId: “my-app-session-id” };
otvaa.agent.appStart(appStartMetadata);

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, except that only the changed fields should be included. For example, to refresh the UAV access token:

JS

const updatedAgentConfig = {
  destinations: [{
    name: “uav”,
    config: {
      token: myUpdatedUavAccessToken
  }}]};
otvaa.agent.updateConfig(upatedAgentConfig);

Submitting Activities

All activities other than appStart are submitted using otvaa.agent.submitActivity(activity, metadata). See OpenTV Analytics Activities for details of which metadata is automatically populated when using the agent API:

CODE

const metadata = {
  // 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: "..."
};

otvaa.agent.submitActivity(otvaa.OtvActivity.PlaybackStart, metadata);

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:

JS

const playbackStopMetadata = {
  Position: getPlaybackPosition()
};
otvaa.agent.submitActivity(otvaa.OtvActivity.PlaybackStop, playbackStopMetadata);
otvaa.agent.submitActivity(otvaa.OtvActivity.AppEnd);
otvaa.agent.close();