Using the OtvAa Wrapper API

OtvAnalyticsAgentWrapper when integrated into your app will in turn:

instantiate, configure and communicate with an OtvAnalyticsAgent instance
configure the legacy Insight Agent (if required)
attach listeners to the provided OpenTV Connect Player, extract events and metrics and reports them to the Analytics Server (via OtvAnalyticsAgent).

As OtvAnalyticsAgent and OtvAnalyticsAgentWrapper are mutually exclusive in a single app. The API is very similar, and any submitActivity() call on OtvAnalyticsAgentWrapper is consequently passed on to the OtvAnalyticsAgent instance.

Initialising the wrapper

Similar to OtvAnalyticsAgent, the setting up of the OtvAnalyticsAgentWrapper is done in two steps. First, associate the singleton wrapper with the application:

SWIFT

import otvaaAppleAgent

struct AppStartView: View {

    // ... details omitted

    let otvaaAgentWrapper:OtvAnalyticsAgentWrapper = OtvAnalyticsAgentWrapper.shared

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

The first parameter of the initialisation is the wrapper and Insight configuration as a JSON object. If the Insight agent is not required, the only value required is samplePeriod. If Insight is required, then the Insight configuration parameters are added all in an insightConfig section:

SWIFT

        var wrapperConfiguration:[String : Any] = [:]
        var defaultInsightConfig:[String : Any] = [:]

        defaultInsightConfig = [
            "collectorURL": "https://collector.insight-stats.com/api/v1/",
            "deviceId":"iOSTestDeviceId",
            "operatorId":"yourOperatorId",
            "samplingInterval":20.0,
            "reportingInterval":0.5,
            "framedropsEnabled":true,
            "deviceType":deviceType,
            "appName":"Agent Wrapper Sample App",
            "appVersion":"1.0.0",
            "timezone":"Europe/Zurich",
            "integrationMode":true
        ]
        
        if insightEnableStatus {
            wrapperConfiguration = [
                "samplePeriod":  defaultSamplePeriod,
                "insightConfig": defaultInsightConfig
            ]
        } else {
            wrapperConfiguration = [
                "samplePeriod": defaultSamplePeriod,
            ]
        }

The other two parameters in the initialisation method are similar to the two parameters used for the Agent: configuration for the agent and a listener for asynchronous events coming from the agent. See Using the OtvAa Agent API | Initialising-the-agent in the previous page.

With the above three parameters we can now initialisae the wrapper (and the downstream agent):

SWIFT

var error:OTVAnalyticsAgentErrors?

error = otvaaAgentWrapper.initialise(wrapperConfig:wrapperConfiguration, agentConfig:agentConfiguration, errorProtocol: otvErrorProtocolImpl)

Note that you can check if initialisation is successful by checking

error == nil

Updating the Configuration

The configuration of the wrapper and agent may need to be changed. With the same caveats described in Using the OtvAa Agent API | Updating-the-Configuration in the previous page, you can update configuration as follows:

SWIFT

error = otvaaAgentWrapper.updateConfig(wrapperConfig: updatedWrapperConfig, agentConfig: updatedAgentConfig)

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 so that the initial playback events are already reported.

The player parameter is a reference to the OTVAVPlayer object created by the application.

SWIFT

otvaaAgentWrapper.setConnectPlayer(player: player)

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

Starting a Playback Session

playbackStart() must be called by the client application to provide stream information which is not available from 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.

playbackStart Metadata:

CODE

let metadata:[String : Any] = [:]

Insight Content info:

SWIFT

let insightContent:[String : Any] = [
    "contentId":id,
    "contentName":name,
    "type":type,
    "uri":url ?? ""
    ]

Insight User Info

SWIFT

let insightUserInfo:[String : Any] = [
    "userId": "refUserId",
    "accountId": "refAccountId"]

`playbackStart()`

SWIFT

otvaaAgentWrapper.playbackStart(metadata: metadata, insightUserInfo: insightUserInfo, insightContent: insightContent)

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:

SWIFT

error = otvaaAgentWrapper.submitActivity(activity: OtvActivity.AdDelivered, metadata: metaData)

see https://docs.nagra.com/otv-analytics-agent/latest/otv-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, but recommended if possible, 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

otvaaAgentWrapper.submitActivity(activity: OtvActivity.playbackStop, metadata: stopMetaData)
otvaaAgentWrapper.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 .