Insight analytics

The application can report player metrics to the Insight servers using the Insight Agent wrapper class. The wrapper class uses the Insight Agent to manage Insight sessions alongside playback, during which content information and playback monitoring information is collated and uploaded to the Insight servers. A session lifecycle equates typically to the playback of one content, starting when the content is loaded into the player and ending when the content is unloaded.

The application is responsible for:

Instantiating and driving the player
Providing metadata about the content

The Insight Agent wrapper is responsible for:

Observing metrics and events on the player
Reporting metrics and events to the Insight servers

Exposed classes in Insight Agent wrapper

The following classes are exposed inside the Insight Agent wrapper for the application:

OTVInsightAgent
This is the main Insight Agent wrapper class. The application instantiates this class and calls the exposed APIs.
OTVInsightConfig
The instance of this class used to pass the Insight configuration information to OTVInsightAgent.
ContentInfoHolder
The instance of this class used to pass the content information to OTVInsightAgent.
UserInfoHolder
The instance of this class used to pass the user information to OTVInsightAgent.

Example code

Insight Framework dependency

To enable this feature, the application needs the Insight Framework library InsightAgent.xcframework , which is delivered separately.

Insight configuration Information

The application needs the following Insight configuration information to create an instance of OTVInsightConfig class.

CODE

  "insightCollectorURL" : "https://collector.insight-stats.com/api/v1/",
  "samplingInterval" : "10",
  "reportingPeriod" : "30",
  "appName":"OpenTV Player Sample App",
  "appVersion":"5.x",
  "deviceType":"handheld",
  "operatorId":"9c703ed0309f"

Content information

The following information is required to create an instance of ContentInfoHolder class. Some of the parameters with ? are optional.

Live content

CODE

channelId: String,   
channelName: String,
eventId: String, 
eventName: String, 
genre: [String]?, 
bitrates: [Int]?,
uri: String?,
duration: Int?,
type: String

VOD content

CODE

contentId: String,
contentName: String,
genre: [String]?,
bitrates: [Int]?,
uri: String?,
duration: Int?

User information

The following information is required to create an instance of UserInfoHolder class.

CODE

userId: String,
accountId: String,
fullName: String,
gender: String,
age: Int,
ageRange: String,
category: String,
street: String,
city: String,
state: String,
postCode: String,
country: String

Creating an Insight Agent wrapper instance

The application can create the Insight Agent wrapper instance in the correct place as follows:

CODE

mInsightAgent = new OTVInsightAgent(xConfig);

Here xConfig is the object of OTVInsightConfig class. The same Agent can be reused for multiple playback sessions during zapping, so there is usually no need to instantiate this class more than once.

Preparing the Insight configuration instance

The OTVInsightConfig instance is prepared as follows:

CODE

var xConfig = OTVInsightConfig(collectorURL: "https://collector.insight-stats.com/api/v1/",
                               deviceId: "iOSTestDeviceId", 
                               operatorId: "9c703ed0309f", 
                               samplingInterval: 10, 
                               reportingInterval: 30, 
                               framedropsEnabled: true, 
                               deviceType: OTVDeviceType.handheld,
                               appName: "Insight Reference Application",
                               timezone: "Europe/Zurich")

Session control

The OTVInsightAgent is only responsible for collating the analytics data; it needs the application to control an Insight session alongside playback. The application should start the session to align with the playback of the stream.

For both live and VOD, a session should start when playback commences.
For VOD streams, a session should stop when the playback finishes, whether by error, user action or play-out.
A session should end for live streams when the stream is switched or stopped by an error.

Prepare content Information

When starting the session, the application should prepare the content information the session will need; this includes metadata related to the content.

CODE

var contentInfoHolder = ContentInfoHolder(channelId: "ChannelID-1",
                                          channelName: "ChannelName-1",
                                          type: "VOD")

Preparing user information

When starting the session, the application should prepare the user information which the session will need; this includes metadata related to the user account.

CODE

var userInfoHolder = UserInfoHolder(userId: "user id", 
                                    accountId: "account id", 
                                    fullName: "Full Name", 
                                    gender: "Male", 
                                    age: 20, 
                                    ageRange: "10-30", 
                                    category: "Category",
                                    street: String, 
                                    city: String, 
                                    state: String, 
                                    postCode: String, 
                                    country: String)

Start session

After getting all the content information and user information available, the application can start the session with OTVAVPlayer instance, content information and user information.

CODE

mInsightAgent.startSession(xPlayer: otvPlayer, xContentInfoHolder: contentInfoHolder, xUserInfoHolder: userInfoHolder)

Stop session

The application can stop the session when playback is stopped or zapping to another content before starting the session.

CODE

mInsightAgent.stopSession()