Using the OtvAa Agent API

Initialising the agent

The setting up of the OtvAnalyticsAgent is done in two steps. First, associate the singleton agent with the application:

SWIFT

import otvaaAppleAgent

struct OTVActivityAppStart: View {

    // ... details omitted

    let otvaaAgent:OtvAnalyticsAgent = OtvAnalyticsAgent.shared

The second step is initialising the instance. The initialise() takes two parameters and returns nil or an error from OTVAnalyticsAgentErrors.

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

SWIFT

        var initialConfig:[String : Any] = [:]
        initialConfig = [
                          "accountID": "12345",
                          "deviceID": "myDeviceId,
                          "userID": "myUserId",
                          "appVersion": "appVersion",
                          "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 initialisation parameter is a listener for asynchronous events coming from the agent. The application needs to implement a OTVAnalyticsAgentErrorListener, see this trivial example:

SWIFT

class OtvErrorProtocolImpl: OTVAnalyticsAgentErrorListener {
    var errorCode:Int?
    var desc:String?
    
    func onError(errorCode: Int, description: String, extra: String?) {

        self.errorCode = errorCode
        self.desc = description
        print("#########mockOtvaErrorProtocol: error code received: \(self.errorCode!)")
     }
}

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

SWIFT

let otvErrorProtocolImpl:OtvErrorProtocolImpl? = OtvErrorProtocolImpl()

// ... details omitted

var error:OTVAnalyticsAgentErrors?

error = otvaaAgent.initialise(config:initialConfig, otvaAErrorProtocol: otvErrorProtocolImpl)

Note that you can check if initialisation is successful by checking

error == nil

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.

SWIFT

        var error:OTVAnalyticsAgentErrors?

        let updatedConfig = [
          "destinations": [
              [
                  "name": "uav",
                  "config": [ "token": "updated token" ],
              ]
            ],
        ] as [String : Any]
        
        error = otvaaAgent.updateConfig(config: updatedConfig)

Submitting Activities

appStart

All activities other than appStart are submitted using:

SWIFT

var error:OTVAnalyticsAgentErrors?

error = otvaaAgent.appStart(metadata: metaData)

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

SWIFT

error = otvaaAgent.submitActivity(activity: activity, metadata: metaData)

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 asynchronous (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

SWIFT

activity: OtvActivity

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 activity and its metadata are set, we can submit the activity:

SWIFT

  error = otvaaAgent.submitActivity(activity: activity, metadata: metaData)

Errors reported can be synchronous (in the return value of the call, for example if metadata validation encounters an error) or may be asynchronous (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, 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:

SWIFT

otvaaAgent.submitActivity(activity: OtvActivity.playbackStop, metadata: stopMetaData)
otvaaAgent.submitActivity(activity: OtvActivity.appEnd, metadata: endMetaData)

Error Handling

Synchronous errors are the OTVAnalyticsAgentErrors 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 onError callback.

See the API documentation at OTV Analytics Agent for Apple APIs .