Agent Class Reference

Detailed Description

The Agent class can be used to report playback metrics to the Insight servers.

The application can use an Agent 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:

res/raw/analytics.json
 

That configuration file typically looks like this:

{
 "insightCollectorURL": "https://collector.insight-stats.com/api/v1",
 "reportingPeriodInitialDelay": "3000",
 "reportingPeriod": "30000",
 "samplingPeriod" : "10000",
 "appName": "OpenTV Player Sample App",
 "appVersion": "5.x",
 "deviceType": "handheld",
 "osType": "Android",
 "videoDecoderType": "H.264",
 "audioDecoderType": "AAC",
 "streamingFormat": "HLS",
 "drmName": "PRM",
 "drmVersion": "3.7_std_rc1",
 "gpuModel": "None",
 "operatorId": "a794e075c09c"
}
 

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

• insightCollectorURL - the base URL of the Insight server collecting the statistics
• reportingPeriodInitialDelay - delay (ms) before agent starts sending reports
• reportingPeriod - interval between regular reports (ms)

Creating the agent

To create an agent, all the application needs to do is provide the application Context to the Agent:

mInsightAgent = new Agent(mContext);
 

The same agent can be reused for multiple playback sessions. 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 things:

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

The content information object 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.

ContentInfoHolder contentInfoHolder = new ContentInfoHolder();
contentInfoHolder.setName(streamName);
contentInfoHolder.setUri(videoUri);
contentInfoHolder.setDuration(mOTVVideoView.getDuration());
contentInfoHolder.setChannelName(videoUri);
contentInfoHolder.setType((mOTVVideoView.getDuration() == -1) ? "LIVE" : "VOD");
...
 

After gathering the content information, the application can start the session using the ContentInfoHolder, UserInfoHolder and the OTVVideoView objects. Be careful about timing when starting the session – make sure session is started after OTVVideoView is created, but before the video URI is passed to it for playing.

mInsightAgent.startSession(mOTVVideoView, contentInfoHolder, userInfoHolder);
 

Stopping a session

Use the following method to stop the session:

mInsightAgent.stopSession();
 

Updating content information

The Application may want to update the content information when on a live channel, as time passes. The most obvious case is transition events, where the Application is likely to provide a new event name or event id. To update content information, the Application needs to stop the session and start a new session on the same player along with the new content information. The easiest way is to update the existing ContentInfoHolder instead of creating a new one.

The following code illustrates a change of content information:

mInsightAgent.stopSession();
contentInfoHolder.setEventName(eventName);
contentInfoHolder.setEventId(eventId);
mInsightAgent.startSession(mOTVVideoView, contentInfoHolder, userInfoHolder);
 

See also

nagra.insight.agent.utils.ContentInfoHolder

nagra.otv.sdk.OTVVideoView

Public Member Functions
	Agent (Context xContext)
	Construct the Agent. More...
void	startSession (OTVVideoView xVideoView, ContentInfoHolder xContentInfoHolder)
	Starts a session without a information from the user. More...
void	startSession (OTVVideoView xVideoView, ContentInfoHolder xContentInfoHolder, UserInfoHolder xUserInfoHolder)
	Start the session with the content information and OTVVideoView. More...
void	stopSession ()
	Stop the session (if started) More...
void	setOffsetFromLive (Integer xOffsetFromLive)
	Sets the offset of the playback, as in when Seeking on Linear TV. More...
void	setSubtitleLanguage (String xSubtitleLanguage)
	Sets the Subtitle Language (may change during the course of a session) More...
void	setAudioLanguage (String xAudioLanguage)
	Sets the Audio Language (may change during the course of a session) More...
void	addAgentDispatchListener (IAgentDispatchListener listener)
	Adds a listener for agent dispatch. More...
void	removeAgentDispatchListener (IAgentDispatchListener listener)
	Removes a listener for agent dispatchs. More...
void	removeAllAgentDispatchListeners ()
	Removes all agent dispatch listeners. More...

Package Functions
	Agent (JSONObject configParameters, Device device, Dispatcher dispatcher, String uniqueId, String networkClass, PlaybackSession playbackSession, MetricsReporter metricsReporter, EventsReporter eventsReporter)
	Construct the Agent for unit tests. More...

Constructor & Destructor Documentation

Agent() [1/2]

Agent

(

Context

xContext

)

Construct the Agent.

Parameters

xContext

the context used by the SDK

Agent() [2/2]

Agent ( JSONObject  configParameters, Device  device, Dispatcher  dispatcher, String  uniqueId, String  networkClass, PlaybackSession  playbackSession, MetricsReporter  metricsReporter, EventsReporter  eventsReporter  )

package

Construct the Agent for unit tests.

Member Function Documentation

addAgentDispatchListener()

void addAgentDispatchListener

(

IAgentDispatchListener

listener

)

Adds a listener for agent dispatch.

Parameters

listener

removeAgentDispatchListener()

void removeAgentDispatchListener

(

IAgentDispatchListener

listener

)

Removes a listener for agent dispatchs.

Parameters

listener

removeAllAgentDispatchListeners()

void removeAllAgentDispatchListeners

(

)

Removes all agent dispatch listeners.

setAudioLanguage()

void setAudioLanguage

(

String

xAudioLanguage

)

Sets the Audio Language (may change during the course of a session)

Parameters

xAudioLanguage

setOffsetFromLive()

void setOffsetFromLive

(

Integer

xOffsetFromLive

)

Sets the offset of the playback, as in when Seeking on Linear TV.

Parameters

xOffsetFromLive

setSubtitleLanguage()

void setSubtitleLanguage

(

String

xSubtitleLanguage

)

Sets the Subtitle Language (may change during the course of a session)

Parameters

xSubtitleLanguage

startSession() [1/2]

void startSession	(	OTVVideoView	xVideoView,
		ContentInfoHolder	xContentInfoHolder
	)

Starts a session without a information from the user.

Parameters

xVideoView	The Video View
xContentInfoHolder	The content info holder

startSession() [2/2]

void startSession	(	OTVVideoView	xVideoView,
		ContentInfoHolder	xContentInfoHolder,
		UserInfoHolder	xUserInfoHolder
	)

Start the session with the content information and OTVVideoView.

Parameters

xVideoView	the OTVVideoView instance on which the content is played
xContentInfoHolder	the content metadata info container
xUserInfoHolder	the user metadata info container

stopSession()

void stopSession

(

)

Stop the session (if started)