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 and device Id to the Agent. If the specified deviceId is null then the final value for the device ID will be set to Settings.Secure.ANDROID_ID.

mInsightAgent = new Agent(mContext , deviceId,  false);

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("VOD"); // Options: VOD or LIVE
...

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: nagra.insight.agent.utils.ContentInfoHolder; nagra.otv.sdk.OTVVideoView

Public Member Functions
	Agent (Context xContext)

	Agent (Context xContext, String deviceId)

	Agent (Context xContext, String deviceId, boolean integrationMode)

	Agent (Context xContext, InsightConfig config)

	Agent (Context xContext, InsightConfig config, AgentConfig wrapperConfig)

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	addMediaPlayerError (MediaPlayer mp, int what, int extra)
	Notifies the agent of a playback error if the error is detected from a MediaPlayer.OnErrorListener. 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...

void	setBitrate (Integer bitrate)
	Notifies the agent that the bitrate has changed. More...

void	setBitrate (Integer bitrate, String resolution, String codecs)
	Notifies the agent that the bitrate has changed. More...

void	setFramesPerSecond (Integer frameCount)
	Notifies the agent of the current rendering fps. More...

void	addNetworkEvent (Integer statusCode, String originatingUrl, Map< String, String > httpHeaders, RequestType requestType, MediaType mediaType, Long loadStartedTimestamp, Long loadCompletedTimestamp)
	Adds network event. 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

Deprecated:: Will disappear as we strongly recommend to specify a device ID.

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,
		String	deviceId,
		boolean	integrationMode
	)

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
integrationMode	if set to true, it allows non valid operations to be detected during the integration by throwing RuntimeException exceptions. If set to false then the errors will only be logged.

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	wrapperConfig
	)

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
wrapperConfig	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 addMediaPlayerError	(	MediaPlayer	mp,
		int	what,
		int	extra
	)

Notifies the agent of a playback error if the error is detected from a MediaPlayer.OnErrorListener.

Note: normally the agent wrapper is automatically handling playback errors and report them to the backend using the Insight agent.

Parameters

mp	MediaPlayer
what	he type of error that has occurred
extra	an extra code, specific to the error

void addNetworkEvent	(	Integer	statusCode,
		String	originatingUrl,
		Map< String, String >	httpHeaders,
		RequestType	requestType,
		MediaType	mediaType,
		Long	loadStartedTimestamp,
		Long	loadCompletedTimestamp
	)

Adds network event.

Parameters

statusCode	http status code
originatingUrl	the URL related to the event
httpHeaders	the http headers present in the http response
requestType	type of the http request (licence, manifest, segment, time, ...)
mediaType	type of media (video, audio, subtitles, ...)
loadStartedTimestamp	network request start time in ms, that is the time from 1st Jan 1970
loadCompletedTimestamp	network request completed time in ms, that is the time from 1st Jan 1970

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)

void setBitrate ( Integer bitrate )

Notifies the agent that the bitrate has changed.

Parameters

bitrate the current bitrate

void setBitrate	(	Integer	bitrate,
		String	resolution,
		String	codecs
	)

Notifies the agent that the bitrate has changed.

The codec parameter refers to the CODECS parameters in the definition of the variant: #EXT-X-STREAM-INF:BANDWIDTH=640000,RESOLUTION=640x360,CODECS="avc1.42e00a,mp4a.40.2"

Parameters

bitrate	the current bitrate
resolution	the resolution of the content being played
codecs	String CODECS parameter of the variant definition

void setContentQuality ( ContentQuality contentQuality )

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

Parameters

contentQuality video quality of the content

void setFramesPerSecond ( Integer frameCount )

Notifies the agent of the current rendering fps.

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.

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