Insight reporting

The application can report player metrics to the Insight servers using the AnalyticsAgent class. It uses the agent to manage playback sessions, during which content information and playback monitoring information are collated. A session lifecycle typically equates with 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 agent is responsible for:

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

Prerequisites

The NAGRA Insight metrics tool.

Procedure

The Insight client agent needs the AnalyticsConfig.plist configuration file, which is read on object creation. The AnalyticsConfig.plist configuration file is located in the application's main bundle. Before instantiating the class, the app must make sure the following parameters are defined in the configuration file.

Creating the agent

The application fetches the singleton AnalyticsAgent instance:

AnalyticsAgent *analyticsAgent = [AnalyticsAgent sharedAgent];

The same agent may be reused for multiple playback sessions. Because there is only one instance of the NMPAVPlayer, and only one content being played back at any particular time, there can only be one playback session that can be started and stopped multiple times.

As a session’s lifecycle corresponds typically to the playback of one content, this usually removes the need to instantiate this class more than once.

Starting a session

The application must start a session on the agent for it to send playback metrics and events. A session needs to be configured with two parameters:

• A player to listen to.
• Information about the content being played.

The content information object is an NSDictionary collection used as an integration point for application developers that need to pass metadata to the Insight agent. Application developers populate this object with the content-related metadata they have access to at the application level, for example, content metadata, EPG, and so on. The object is then passed to the Insight agent and used in playback metrics and events reporting.

NSDictionary *contentInfo = [NSMutableDictionary dictionary];
[contentInfo setValue:mId forKey:@"id"];
[contentInfo setValue:mContentId forKey:@"contentId"];
[contentInfo setValue:mChannelId forKey:@"channelId"];
[contentInfo setValue:mStreamName forKey:@"name"];
[contentInfo setValue:mChannelName forKey:@"channelName"];
[contentInfo setValue:mUri forKey:@"url"];
[contentInfo setValue:mEventId forKey:@"eventId"];
[contentInfo setValue:mEventName forKey:@"eventName"];
[contentInfo setValue:mGenre forKey:@"genre"];
[contentInfo setValue:[1000000,2000000,3000000] forKey:@"bitrates"];
[contentInfo setValue:(isfinite([mStream getDuration]) ? @"VOD" : @"LIVE" forKey:@"type"];
[contentInfo setValue:@(YES) forKey:@"scrambled"];
[contentInfo setValue:[mStream getDuration] forKey:@"duration"]; // in seconds

After gathering the content information, the application can start the session using the NMPAVPlayer and the content information objects.

[analyticsAgent startNewSessionWithPlayer:mPlayer andContent:contentInfo];

Stopping a session

To stop a session, call exitCurrentSession.

[analyticsAgent exitCurrentSession];

Updating content information

The application might need to update content information when on a live channel. Such updates commonly involve event transitions, where the application provides a new event name or event ID. The application needs to stop the session and start a new session on the same player to update content information, including the new content information.

[[AnalyticsAgent sharedAgent] exitCurrentSession];
[contentInfo setValue: mEventId forKey:@"eventId"];
[contentInfo setValue: mEventName forKey:@"eventName"];
[[AnalyticsAgent sharedAgent] startNewSessionWithPlayer:self.player andContent:contentInfo];