Using the OTVAA Wrapper API

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

Initialising the wrapper

otvaa.wrapper includes Insight analytics functionality, so requires an Insight initialisation object. Details of insight can be found in Integrating with and reporting activity and event metrics to Insight

Where the application is running on a very low performance device, it may be necessary to disable the Insight functionality. This may be achieved by omitting the insightConfig from the wrapperConfig.

JS

const myInsightConfig = {
  collectorURL: "https://url-to-insight-collector",
  reportingInterval: 60, // seconds: default 1800 (30 minutes)
  samplingInterval: 20, // seconds (15-reportingInterval, default 30)
  appName: "OTVAA Sample",
  appVersion: "5.x",
  deviceType: "desktop",
  operatorId: "my-op-id",
  deviceId: “my-device-id”
};
const wrapperConfig = {
  insightConfig: myInsightConfig,
  samplePeriod: 15 // seconds (default 20)
};
const agentConfig = {
  userId: “my-user-id”,
  accountId: “my-account-id”,
  deviceId: “my-device-id”,
  onError: myErrorCallback,
  destinations: [{
    name: “uav”,
    config: {
      url: “https://url-to-uav”,
      token: myUavAccessToken
    }
  }]
};

otvaa.wrapper.initialise(wrapperConfig, agentConfig);
const appStartMetadata = { appSessionId: “my-app-session-id” };
otvaa.wrapper.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
  }}]};
const updatedWrapperConfig = {}; // Nothing updated for wrapper config

otvaa.wrapper.updateConfig(updatedWrapperConfig, upatedAgentConfig);

Setting the Player

Set the player so that the wrapper can automatically detect some activities from the player, and automatically populate some of the metadata for other activities. The player should be set before the playbackStart() function is called.

The player parameter is a reference to the otvplayer object created from the opy-sdk-js library.

JS

otvaa.wrapper.setPlayer(myPlayer);

If the player is set (changed) during a playback session, then no further actions will be detected for that playback session.

A player may be removed by calling:

CODE

otvaa.wrapper.setPlayer(null);

Starting a Playback Session

playbackStart() must be called by the client application to provide stream information which is not available from the player. If possible, the playback session should be started immediately before calling the src() function on the player to request playback. If this is not possible then it should be started as soon as possible after the playback is requested on the player.

The parameters of playbackStart() are:

metadata
insightContent
insightUserInfo

If Insight is not enabled, then the two insight parameters may be omitted.

If Insight is enabled, insightUserInfo may be omitted if Insight is required to run in anonymous mode.

JS

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: "..."
};

const insightContent = {
  channelId: "123456",
  channelName: "BBC1",
  eventId: "abcdef", // optional
  eventName: "live tv", // optional
  type: "LIVE", // optional (default is LIVE)
  genre: ["animation"], // optional
  scrambled: false, // optional
};

const insightUserInfo = {
  userId: "User001",
  accountId: "account001",
  fullName: "Homer J Simpson",
  gender: "male",
  age: 37,
  ageRange: "AlwaysTheSame",
  category: "D'oh",
  street: "Evergreen Terrace",
  city: "Springfield",
  state: "Idono",
  postCode: "1DK",
  country: "US"
};

otvaa.wrapper.playbackStart(metadata, insightContent, insightUserInfo);

Submitting Non-Playback Actions

Non-playback actions will not be automatically detected by the wrapper, so must be submitted by the client application, for example:

JS

const adDeliveredMetadata = {
  // No need for appSessionId as it is auto populated
  // No need for playbackSessionId as it is auto populated
  adID: “my-ad-id”,
  trackingAssetId: “my-tracking-asset-id”,
  adSupplier: “my-ad-supplier”
};
otvaa.wrapper.submitActivity(otvaa.OtvActivity.AdDelivered, adDeliveredMetadata);

see OpenTV Analytics Activities to find which activities are automatically generated by the wrapper as well as which metadata is automatically populated.

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

// Metadata automatically populated
otvaa.wrapper.submitActivity(otvaa.OtvActivity.PlaybackStop);
otvaa.wrapper.submitActivity(otvaa.OtvActivity.AppEnd);
otvaa.wrapper.close();