Detailed Description

Wrapper for the new Insight Android agent.

The Agent Wrapper 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://validator.insight-stats.com/api/v1",
 "samplingInterval": "10",
 "reportingPeriod": "30",
 "appName": "OTV Sample App",
 "appVersion": "2.21.0",
 "deviceType": "handheld",
 "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
samplingInterval - interval between the generation of playback metrics samples [s]
reportingPeriod - interval between regular reports [s])

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 is 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 – the application may only start the session after the onPrepared event has been sent.

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 obivous case is event transitions, 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: ContentInfoHolder; nagra.otv.sdk.OTVVideoView

Public Member Functions
	Agent (Context xContext)

	Agent (Context xContext, String deviceId)

	Agent (Context xContext, InsightConfig config)

	Agent (Context xContext, InsightConfig config, AgentConfig agentConfig)

void	startSession (OTVVideoView xVideoView, ContentInfoHolder xContentInfoHolder)
	Starts a session without user information. More...

void	startSession (OTVVideoView xVideoView, ContentInfoHolder xContentInfoHolder, UserInfoHolder xUserInfoHolder)
	Starts the session with the content information and OTVVideoView. More...

void	stopSession ()
	Stops the session (if started) More...

void	release ()
	Stops the session and releases all agent resources. 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	addErrorEvent (final Integer code, final String message)
	Notifies the agent of a playback error. More...

void	setAudioLanguage (String xAudioLanguage)
	Sets the Audio Language (may change during the course of a session) More...

void	setContentQuality (ContentQuality contentQuality)
	Sets the Content Quality (may change during the course of a session). More...

void	updateContent (ContentInfoHolder contentInfoHolder)
	Updates the content information. More...

Constructor & Destructor Documentation

Agent ( Context xContext )

Constructs the Agent Wrapper.

The value of the device ID will be set to Settings.Secure.ANDROID_ID. Please choose another constructor if you want to specify your own device ID,

Parameters

xContext the context used by the SDK

Agent	(	Context	xContext,
		String	deviceId
	)

Constructs the Agent Wrapper.

If the specified deviceId is null then the final value for the device ID will be set to Settings.Secure.ANDROID_ID.

Parameters

xContext	the context used by the SDK
deviceId	custom device id

Agent	(	Context	xContext,
		InsightConfig	config
	)

Constructs the Agent Wrapper.

This constructor gives the ability to programmatically configure the agent instead of using the analytics.json configuration file that normally stands in the /res/raw/ folder of the player application. The file can exist but will just be ignored.

If the specified deviceId in the InsightConfig object is null then the final value for the device ID will be set to Settings.Secure.ANDROID_ID.

Parameters

xContext	the context used by the SDK
config	configuration to be passed to the agent

Agent	(	Context	xContext,
		InsightConfig	config,
		AgentConfig	agentConfig
	)

Constructs the Agent Wrapper.

This constructor gives the ability to programmatically configure the agent instead of using the analytics.json configuration file that normally stands in the /res/raw/ folder of the player application. The file can exist but will just be ignored.

If the specified deviceId in the InsightConfig object is null then the final value for the device ID will be set to Settings.Secure.ANDROID_ID.

Parameters

xContext	the context used by the SDK
config	configuration to be passed to the agent
agentConfig	additional configuration only related to the wrapper

Member Function Documentation

void addErrorEvent	(	final Integer	code,
		final String	message
	)

Notifies the agent of a playback error.

Parameters

code	error code
message	error message

void release ( )

Stops the session and releases all agent resources.

Note: to be able to use the agent again then you would need to instantiate a new wrapper.

void setAudioLanguage ( String xAudioLanguage )

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

Parameters

xAudioLanguage

void setContentQuality ( ContentQuality contentQuality )

Sets the Content Quality (may change during the course of a session).

Parameters

contentQuality video quality of the content

void setOffsetFromLive ( Integer xOffsetFromLive )

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

Parameters

xOffsetFromLive

void setSubtitleLanguage ( String xSubtitleLanguage )

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

Parameters

xSubtitleLanguage

void startSession	(	OTVVideoView	xVideoView,
		ContentInfoHolder	xContentInfoHolder
	)

Starts a session without user information.

Parameters

xVideoView	The Video View
xContentInfoHolder	The content info holder

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

Starts 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

void stopSession ( )

Stops the session (if started)

void updateContent ( ContentInfoHolder contentInfoHolder )

Updates the content information.

Some information might not be know before the playback starts (such the duration) and needs to be updated afterwards.

Parameters

contentInfoHolder

Detailed Description

Configuring the application

Creating the agent

Starting a session

Stopping a session

Updating content information

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation