Insight Agent Native Integration
NAGRA Insight uses artificial intelligence to enable you to make better strategic decisions by understanding individual TV viewers’ behaviour and tastes, and to create actions that will improve the value proposition and increase customer satisfaction. To do so, Insight instruments the pay-TV end-user video player devices (i.e., STBs, Tablets, Smartphones or Web Players) with an Insight Agent. As shown below, the Insight Agent is responsible for collecting the relevant information from the client and sending it to the Insight Collector.
Reporting information to NAGRA Insight
The native Insight Agent enables you to post video playback-related events and metrics from end-user devices to obtain a solid audience and quality of service data set. The native reports the data in the following manner:
Creates a session id when a user starts watching given content on an end-user device video player.
Regularly reports data to the events and metrics endpoints. The submission interval is set in the configuration, but a random jitter of 10% of the duration of the interval is introduced automatically.
Reports the last time when the play is stopped.
Sessions
Generally, a session is defined as a playout of a given content. However, there are minor differences when dealing with Channel (Live) TV and On Demand (VOD) content. Each session is identified with a session ID. A session ID is a UUID generated on the fly by the Agent for each new session.
Please check the content types for additional information on the types of content that are supported and the required fields to report them.
On-Demand Content (VOD)
For On-Demand content playback such as VOD, a playback session occurs between the start of playing a video until it stops (or aborts or crashes). A playback session is not interrupted by pauses or seeks. A new session must be created every time a content item begins to be played.
To correctly report the content of a VOD session, you must include at least the following content Information (see additional details in the Content Information definition):
contentId: The unique identifier of the content according to the content catalogue or metadata server
contentName: The name of the content as described by the content catalogue
TV Channel Content
TV Channel content corresponds to content which has originated from a TV channel. This includes Linear TV (content consumed at the time of broadcast) and Replay TV (content consumed after it was originally broadcasted). For linear content playback, a new session is created when tuning in to a given channel. This means that a user switching among a given set of channels (zapping) will create a fairly high number of new sessions that can be very short.
To correctly report the content of a Linear TV session, you must include at least the following content Information:
channelId: The unique identifier of the channel according to the EPG (electronic program guide)
channelName: The name of the channel as described in the EPG
timestamp: The timestamp at which the session is happening
playbackTimezone: The timezone where the session is happening
See additional details in the Content Information definition
To correctly report the content of a Replay TV session, we must include at least the following content information:
channelId: The unique identifier of the channel according to the EPG (electronic program guide)
channelName: The name of the channel as described in the EPG
timestamp: The timestamp at which the session is happening
playbackTimezone: The timezone where the session is happening
contentName: The name of the original content
eventId: The ID corresponding to the original event at broadcast time
See additional details in the Content Information definition:
Reporting Interval
There are two types of information that the Agent reports: Metrics and Events; therefore, the Agent has two concurrent reporters running, each of which reports periodically and independently with a random jitter.
We suggest setting this random jitter to 10% of the reporting interval. This is important as failing to implement a jitter might result in Agent synchronizing and adding unnecessary load on the servers. For an average interval length set to 30 seconds, each random reporting period should be between 27 seconds and 33 seconds. Therefore, within the same session reports could, for example, occur at 20:09:02, 20:09:30, 20:10:02,
The Events Reporter collects the events that have occurred over the reporting period and submits the complete list to the Insight API.
The Metrics Reporter keeps track and aggregates the metrics over the reporting period.
Handling Connection Errors
Network errors can occur, or servers can fail unexpectedly. However, information can still be reported in this case by:
Keeping the data.
Keeping information about the error.
Reporting the data of the full period with the error at the next interval.
Repeating in the case of the error.
It is then possible to use the submissionErrors and submissionFailures fields to report these errors (see the API documentation for more info about these fields). Some playback metrics report an average over the last interval. In the case of a reporting error, you should average the values over the double-length interval.
Playback example
The figure below illustrates the sequence of events of a normal playback (VOD) example.
The user launches the app, which upon loading, initializes the Agent and starts listening to the player events.
The user starts to play a video.
The application calls the play method on the Agent and the video player.
The application listens to the different events that the video player dispatches and notifies the Agent about them (i.e., playing, buffering, etc.).
When the video playback is complete, the application tells the Agent to stop.
When the user quits the application, the application calls the terminate method of the Agent.
