The application can use an AnalyticsAgent to manage sessions. More...

#import <AnalyticsAgent.h>

Inheritance diagram for AnalyticsAgent:

Instance Methods
(void)	- startNewSessionWithPlayer:andContent:
	Start an Analytics session associated with a player and the content it is playing. More...

(void)	- exitCurrentSession
	End the Analytics playback listening session. More...

Class Methods
(AnalyticsAgent *)	+ sharedAgent
	Fetch (and construct if necessary) the Analytics Agent. More...

Detailed Description

The application can use an AnalyticsAgent to manage sessions.

Each session aggregates:

Content information
Playback monitoring information

It is the application's responsibility to:

Instantiate and drive the player
Provide some metadata about the content

It is the Agent's responsibility to:

Observe metrics and events on the player
Report metrics and events to the Insight servers

Configuring the application

The Insight client Agent needs a configuration file, which will be read on object creation. The file is expected to be located in the application's main bundle (add the file to the list in the Copy Bundle Resources build phase).

That configuration file typically looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
 <dict>
   <key>eventsWindow</key>
   <integer>25</integer>
   <key>metricsWindow</key>
   <integer>30</integer>
   <key>applicationVersion</key>
   <string>v0.2</string>
   <key>applicationName</key>
   <string>Demo iOS</string>
   <key>operatorId</key>
   <string>e04505d0ea7a</string>
   <key>collectorURL</key>
   <string>http://dev-collector.insight-stats.com/api/v1</string>
   <key>globalProperties</key>
   <dict>
   <key>subOperatorId</key>
   <string>main</string>
   </dict>
 </dict>
</plist>

Before instantiating the class, the app must make sure the following parameters are defined in the configuration file:

collectorURL - the base URL of the Insight server collecting the statistics
applicationName
applicationVersion
metricsWindow - interval (seconds) between regular metrics reports
eventsWindow - interval (seconds) between regular events reports
operatorId - used in the HTTP header field X-Operator-Id
globalProperties/subOperatorId (optional) - added to each metrics and events report

Creating the agent

To create an agent, all the application needs to do is fetch the singleton AnalyticsAgent instance:

AnalyticsAgent *analyticsAgent = [AnalyticsAgent sharedAgent];

The same agent can be reused for multiple playback sessions. As there is no more than one content being played back at any particular time, and as there is no more than one instance of the NMPAVPlayer, there can only be one playback session, which can be started and stopped multiple times.

The lifecycle of a session normally corresponds to the playback of one content, from the moment the content is loaded into the player to the moment it is unloaded from the player. Therefore, there is usually no need to instantiate this class more than once.

Starting a session

For the agent to send playback metrics and events, the application must start a session on the agent.

A session must be configured with two parameters:

A player to listen to
Information about the content being played

The content information object is an NSDictionary collection. It is used as an integration point for application developers that need to pass metadata to the Insight agent. It is therefore up to application developers to populate this object with the content-related metadata that they have access to at the application level, e.g., content metadata, EPG, etc...

This object is then passed to the Insight agent and is used in playback metrics and events reporting.

Example:

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

Simply call exitCurrentSession
[analyticsAgent exitCurrentSession];

Definition at line 161 of file AnalyticsAgent.h.

Method Documentation

◆ exitCurrentSession()

- (void) exitCurrentSession

End the Analytics playback listening session.

◆ sharedAgent()

+ (AnalyticsAgent *) sharedAgent

Fetch (and construct if necessary) the Analytics Agent.

Returns: a pointer to the AnalyticsAgent instance

◆ startNewSessionWithPlayer:andContent:()

- (void) startNewSessionWithPlayer:	(NMPAVPlayer *)	player
andContent:	(NSDictionary *)	contentInfo

Start an Analytics session associated with a player and the content it is playing.

Parameters

player	a reference to the NMPAVPlayer instance
contentInfo	an *NSDictionary* collection of the content's metadata

The contentInfo dictionary should contain content metadata values for the following keys:

id
name (Describing the content)
uri (e.g. of the .m3u8 manifest)
type (VOD or LIVE)

Instance Methods

Class Methods