Skip to main content

AV Insights (audio video)

AV Insights allows the collection of events related to media consumption. You will be able to follow the different interactions on your players and measure the performance of your content. The AV Insight tracker is designed to give you options on the level of information you want to measure.

Media management

Media instanciation

In order to be able to manipulate a media and measure its events, it is necessary to declare an object of type Media :

var myMedia = new pa.avInsights.Media([heartbeatDuration, bufferingHeartbeatDuration, sessionId]);
ParameterTypeDescriptionExample
heartbeatDuration (optional)int, objectDelay between two heartbeat during playback (minimum delay is 5sec). If the value is a int, this will be the delay for the whole playback. You can also set an object such as { 0:5, 1:10, 5:60 }, meaning the first minute will be 5sec delay, starting from minute 1, 10sec, and after the 5th minute, the delay will be 60sec5 or { 0:5, 1:10, 5:60 }
bufferingHeartbeatDuration (optional)int, objectDelay between two heartbeat during buffering (minimum delay is 1sec). If the value is a int, this will be the delay for the whole buffering. You can also set an object such as { 0:5, 1:10, 5:60 }, meaning the first minute will be 5sec delay, starting from minute 1, 10sec, and after the 5th minute, the delay will be 60sec5 or { 0:5, 1:10, 5:60 }
sessionId (optional)stringSession ID of the playback. This ID is automatically managed by the SDK, but you can override it if you know what you are doing. More details in the next section.`
var myMedia = new pa.avInsights.Media(5, 5);
// or
var myMedia = new pa.avInsights.Media({ 0:5, 1:10, 5:60 }, 5);
note

Two parameters are available, in order to activate the heartbeats. The first one enables playback tracking heartbeats and the second one enables buffering tracking heartbeats.

Session ID management

danger

Please note that this setup should be used only in special cases, when you need to transfer sessions between different device for example.

An optional third parameter sessionId is available to override the common standard property av_session_id present in each event generated by AV Insights tags.

The parameter is automatically managed by the Tracker for all standard cases.

var myMedia = new pa.avInsights.Media(5, 5, 'custom_session_id');

A function getSessionID can be used to retrieve the value of the parameter:

getSessionID() ⇒ string | number

Retrieve the session ID.

Example

var sessionID = myMedia.getSessionID(); // 'custom_session_id' or 'xxxxxxxx-xxxx-4xxx-xxxx-xxxxxxxx'

Media properties

Some rules must be observed regarding the format of the properties used for the configuration of a media :

  • The av_content_id is a mandatory property that must be used for all media instances (see complete tagging example section).
  • The duration of the media or the positions of the playback head must be expressed in milliseconds.

The SDK provides useful functions for the management of Media properties:

set(propKey, propValue)

Declare a media property.

ParameterTypeDescription
propKeystringMedia property key
propValuestringnumberMedia property value

Example

myMedia.set('av_content_id', '12345'); // mandatory
myMedia.set('av_content', 'my_video');

get(propKey) ⇒  string | number

Retrieve a media property.

ParameterTypeDescription
propKeystringMedia property key

Example

var content_id = myMedia.get('av_content_id'); // 12345

del(propKey)

Delete a media property.

ParameterTypeDescription
propKeystringMedia property key

Example

myMedia.del('av_content_id');

setProps(properties)

Declare multiple media properties.

ParameterTypeDescription
propertiesObjectMedia properties

Example

myMedia.setProps({'av_content_id': 'fg456', 'av_content': 'My Content'});

getProps() ⇒ Object

Retrieve all media properties.

Example

var props = myMedia.getProps(); // {'av_content_id': 'fg456', 'av_content': 'My Content'}

delProps()

Delete all media properties.

Example

myMedia.delProps();

Events tracking

The SDK offers useful functions for measuring events related to your users’ interactions with your content:

Media events

play

Event name : av.play

Generate a play event (playback attempt).

play(cursorPosition[, callback, extraProps])

ParameterTypeDescription
cursorPositionnumberCurrent cursor position (ms)
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.play(
0,
function() { console.log("Event av.play generated");},
{ customProp: "customValue" }
);

bufferStart

Event name : av.buffer.start or av.rebuffer.start

Generate an event of buffering at the launch of a media or during the playing. The buffering.heartbeat is sent before the av.start while the rebuffering.heartbeat is sent after an av.start is recorded on the av_session_id.

bufferStart(cursorPosition[, callback, extraProps])

A buffering flag will automatically generate buffering.heartbeat or rebuffering.heartbeat events depending on the context.

ParameterTypeDescription
cursorPositionnumberCurrent cursor position (ms)
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.bufferStart(
0,
function() { console.log("Event av.buffer.start or av.rebuffer.start generated depending on the playback launch"); },
{ customProp: "customValue" }
);

playbackStart

Event name : av.start

Generate a playback start event (first media frame). This allows the automatic av.heartbeat events to be sent. These av.heartbeat events follow the media instance configuration.

playbackStart(cursorPosition[, callback, extraProps])

ParameterTypeDescription
cursorPositionnumberCurrent cursor position (ms)
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.playbackStart(
0,
function() { console.log("Event av.start generated"); },
{ customProp: "customValue" }
);

playbackPaused

Event name : av.pause

Generate a pause event.

playbackPaused(cursorPosition[, callback, extraProps])

ParameterTypeDescription
cursorPositionnumberCurrent cursor position (ms)
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.playbackPaused(
1000,
function() { console.log("Event av.pause generated"); },
{ customProp: "customValue" }
);

playbackResumed

Event name : av.resume

Generate a resume event, following a pause event.

playbackResumed(cursorPosition[, callback, extraProps])

ParameterTypeDescription
cursorPositionnumberCurrent cursor position (ms)
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.playbackResumed(
1000,
function() { console.log("Event av.resume generated"); },
{ customProp: "customValue" }
);

playbackStopped

Event name : av.stop

Generate a stop event. Automatically changes the av_session_id.

playbackStopped(cursorPosition[, callback, extraProps])

ParameterTypeDescription
cursorPositionnumberCurrent cursor position (ms)
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.playbackStopped(
1000,
function() { console.log("Event av.stop generated"); },
{ customProp: "customValue" }
);

seek

Event name : av.forward ou av.backward

Generate a seek event. av.backward is sent whenever the user goes back to an already seen cursorPosition. av.forward whenever the user goes past the current cursorPosition.

seek(oldCursorPosition, newCursorPosition[, callback, extraProps])

ParameterTypeDescription
oldCursorPositionnumberCursor position before seeking (ms)
newCursorPositionnumberCursor position after seeking (ms)
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.seek(
1000,
2000,
function() { console.log("Event av.forward generated"); },
{ customProp: "customValue" }
);

myMedia.seek(
2000,
1000,
function() { console.log("Event av.backward generated"); },
{ customProp: "customValue" }
);

Contextual events

The following list of events is not taken into account in the calculation of media consumption times. They are one-time contextual events.

Playback speed

When changing the playback speed you have to use the dedicated method specifying the new speed factor as a decimal number.

Method:

setPlaybackSpeed(playbackSpeed)

Declare a change in playback speed.

ParameterTypeDescription
playbackSpeednumberPlayback speed factor

Example

myMedia.setPlaybackSpeed(2); // Media playback speed increased by a factor of two

The new playback speed factor will be taken into account when calculating the cursor positions of automated heartbeats events during playback. If necessary, you can tag the event associated with this speed change by using the speed() method.

adClick

Event name : av.ad.click

Generate an ad click event.

adClick([callback, extraProps])

ParameterTypeDescription
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.adClick(
function() { console.log("Event av.ad.click generated"); },
{ customProp: "customValue" }
);

adSkip

Event name : av.ad.skip

Generate an ad skip event.

adSkip([callback, extraProps])

ParameterTypeDescription
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.adSkip(
function() { console.log("Event av.ad.skip generated"); },
{ customProp: "customValue" }
);

close

Event name : av.close

Measure a closing.

close([callback, extraProps])

ParameterTypeDescription
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.close(
function() { console.log("Event av.close generated"); },
{ customProp: "customValue" }
);

display

Event name : av.display

Measure a display.

display([callback, extraProps])

ParameterTypeDescription
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.display(
function() { console.log("Event av.display generated"); },
{ customProp: "customValue" }
);

error

Event name : av.error

Measure an error preventing playback.

error(message[, callback, extraProps])

ParameterTypeDescription
messagestringError message
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.error(
"Error loading video",
function() { console.log("Event av.error generated"); },
{ customProp: "customValue" }
);

fullscreenOff

Event name : av.fullscreen.off

Measure full screen deactivation.

fullscreenOff([callback, extraProps])

ParameterTypeDescription
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.fullscreenOff(
function() { console.log("Event av.fullscreen.off generated"); },
{ customProp: "customValue" }
);

fullscreenOn

Event name : av.fullscreen.on

Measure full screen activation.

fullscreenOn([callback, extraProps])

ParameterTypeDescription
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.fullscreenOn(
function() { console.log("Event av.fullscreen.on generated"); },
{ customProp: "customValue" }
);

quality

Event name : av.quality

Measure a quality change.

quality([callback, extraProps])

ParameterTypeDescription
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.quality(
function() { console.log("Event av.quality generated"); },
{ customProp: "customValue" }
);

share

Event name : av.share

Measure a sharing.

share([callback, extraProps])

ParameterTypeDescription
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.share(
function() { console.log("Event av.share generated"); },
{ customProp: "customValue" }
);

speed

Event name : av.speed

Measure a speed change.

speed([callback, extraProps])

ParameterTypeDescription
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.speed(
function() { console.log("Event av.speed generated"); },
{ customProp: "customValue" }
);

subtitleOff

Event name : av.subtitle.off

Measure subtitles deactivation

subtitleOff([callback, extraProps])

ParameterTypeDescription
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.subtitleOff(
function() { console.log("Event av.subtitle.off generated"); },
{ customProp: "customValue" }
);

subtitleOn

Event name : av.subtitle.on

Measure subtitles activation.

subtitleOn([callback, extraProps])

ParameterTypeDescription
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.subtitleOn(
function() { console.log("Event av.subtitle.on generated"); },
{ customProp: "customValue" }
);

volume

Event name : av.volume

Measure sound volume change.

volume([callback, extraProps])

ParameterTypeDescription
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.volume(
function() { console.log("Event av.volume generated"); },
{ customProp: "customValue" }
);

Technical events

The following events are automatically generated by the Tracker. You can, however, call up the associated public marking methods if you need spot marking. Should the implementation be done without the SDK (server-side), you would have to generate the following events manually.

bufferHeartbeat

Event name : av.buffer.heartbeat

Generate a buffering heartbeat before the playback starts event.

bufferHeartbeat([callback, extraProps])

ParameterTypeDescription
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.bufferHeartbeat(
function() { console.log("Event av.buffer.heartbeat generated"); },
{ customProp: "customValue" }
);

heartbeat

Event name: av.heartbeat

Generate an heartbeat event.

heartbeat([cursorPosition, callback, extraProps])

ParameterTypeDescription
cursorPosition (optional)numberCurrent cursor position (ms)
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.heartbeat(
45,
function() { console.log("Event av.heartbeat generated"); },
{ customProp: "customValue" }
);
note

The cursor position is not required for tagging a heartbeat event. Without any value, it will be automatically calculated according to the context (playback speed factor, cursor position of the previous event).

rebufferHeartbeat

Event name : av.rebuffer.heartbeat

Generate a buffering heartbeat after the playback starts event.

rebufferHeartbeat([callback, extraProps])

ParameterTypeDescription
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.rebufferHeartbeat(
function() { console.log("Event av.rebuffer.heartbeat generated"); },
{ customProp: "customValue" }
);

seekStart

Event name : av.seek.start

Generate a beginning of seeking event.

seekStart(oldCursorPosition, [callback, extraProps])

note

This event is automatically raised when calling the seek(), seekBackward() or seekForward() methods.

ParameterTypeDescription
oldCursorPositionnumberCursor position before seeking (ms)
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.seekStart(
1000,
function() { console.log("Event av.seek.start generated"); },
{ customProp: "customValue" }
);

seekBackward

Event name : av.backward

Generate a backward seeking event.

seekBackward(oldCursorPosition, newCursorPosition, [callback, extraProps])

ParameterTypeDescription
oldCursorPositionnumberCursor position before seeking (ms)
newCursorPositionnumberCursor position after seeking (ms)
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.seekBackward(
2000,
1000,
function() { console.log("Event av.backward generated"); },
{ customProp: "customValue" }
);

seekForward

Event name : av.forward

Generate a forward seeking event.

seekForward(oldCursorPosition, newCursorPosition, [callback, extraProps])

ParameterTypeDescription
oldCursorPositionnumberCursor position before seeking (ms)
newCursorPositionnumberCursor position after seeking (ms)
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

myMedia.seekForward(
1000,
2000,
function() { console.log("Event av.forward generated"); },
{ customProp: "customValue" }
);

Complete tagging example

var myMedia = new pa.avInsights.Media(5, 5); // Set heartbeats value (5 seconds)

var properties = {
av_content_id: 'fge234', //mandatory
av_content: 'myContent',
av_content_type: 'Video',
av_content_duration: 10000,
av_content_genre: ['entertainment'],
av_content_version: 'short',
av_player: 'HTML5_V123',
av_player_version: '1b',
av_player_position: 'top',
av_broadcasting_type: 'On Demand',
av_publication_date: 1562055880,
av_show: 'The gist of the game',
av_show_season: 'Season 1',
av_episode_id: '3134',
av_channel: 'INFO',
av_author: 'Piano',
av_broadcaster: 'Direction 123',
av_language: 'EN',
av_subtitles: 'FR',
av_launch_reason: 'Auto'
};

// Set media properties
myMedia.setProps(properties);

// Play attempt (cursor position 0 second)
myMedia.play(0);

// Buffering before playback start (cursor position 0 second)
myMedia.bufferStart(0);

// Playback start (cursor position 0 second)
myMedia.playbackStart(0);

// Buffering after 5 seconds of playback
myMedia.bufferStart(5000);

// Seek action (backward from cursor position 5 seconds to cursor position 3 seconds)
myMedia.seek(5000, 3000);

// Playback resume (cursor position 3 seconds)
myMedia.playbackResumed(3000);

// Playback pause (cursor position 9 seconds)
myMedia.playbackPaused(9000);

// Playback resume (cursor position 9 seconds)
myMedia.playbackResumed(9000);

// Playback stop (cursor position 15 seconds)
myMedia.playbackStopped(15000);

Annexes

Media sequence example

This represents the ideal sequence for a media playback. As this does not include ads, there will be adjustments needed to cover this scenario.

data model

Seek sequence example

data model

Media properties list

PropertyDescriptionTypeMandatoryExample
av_content_idContent IDstringYes'bc35'
av_session_idSession ID (generated by the SDK)uuid*Yes'799d9f3b-7307-5113-a260-2e1371e35fe6'
av_contentContent Labelstring'Broadchurch 3.5'
av_content_typeContent Typestring'TV Show'
av_content_durationContent Duration (in milliseconds)int2760000
av_content_linkedLinked Content Labelstring'myLinkedContent'
av_publication_datePublication Date (timestamp)date1501065673
av_content_genreContent genre(s)array of string["Crime","Drama","Mystery"]
av_showShow Labelstring'Broadchurch'
av_show_seasonShow Season Labelstring'3'
av_episode_idEpisode IDstring'5'
av_episodeEpisode Labelstring'Episode #3.5'
av_channelChannel Labelstring'ITV'
av_authorAuthor Namestring'Chris Chibnall'
av_content_versionContent Version (full length, …)string'Full
av_content_duration_rangeDuration rangestring'0-10'
av_broadcasting_typeBroadcasting Typestring'Live'
av_broadcasterBroadcaster Namestring'ITV'
av_ad_typeAd Typestring'Mid-roll'
av_playerPlayer Labelstring'Main'
av_player_versionPlayer Versionstring'1.55'
av_player_positionPlayer Positionstring'Homepage'
av_auto_modeAuto play modebooleantrue
av_languageMedia languagestring'fr'
av_subtitlesSubtitlesstring'en'
av_launch_reasonLaunch reasonstring'auto'

List of available options

OptionDescription
av_positionCurrent cursor position (ms)
av_previous_positionPrevious cursor position (ms)
av_player_errorError preventing playback

List of standard events

EventType
av.playManual
av.buffer.startManual
av.buffer.heartbeatAutomatic
av.startManual
av.heartbeatAutomatic
av.pauseManual
av.rebuffer.startManual
av.rebuffer.heartbeatAutomatic
av.resumeManual
av.stopManual
av.seek.startManual
av.forwardManual
av.backwardManual
av.ad.clickManual
av.ad.skipManual
av.errorManual
av.displayManual
av.closeManual
av.volumeManual
av.subtitle.onManual
av.subtitle.offManual
av.fullscreen.onManual
av.fullscreen.offManual
av.qualityManual
av.speedManual
av.shareManual

Custom events tracking method 

track

The AV Insights track() method allows standard or custom events to be tracked. This function can be used to replace calls to other event tagging methods (play, playbackStart, bufferStart, etc.), it is however not recommended since it will not trigger automatic processes.

Event name : event value

Track standard or custom actions.

track(event, [options, callback, extraProps])

ParameterTypeDescription
eventstringEvent to be generated (see list of standard events at the bottom of the page)
options (optional)ObjectOptions depending on the event (see list of available options at the bottom of the page)
callback (optional)functionCallback function to execute after hit sent
extraProps (optional)ObjectCustom properties

Example

var myMedia = new pa.avInsights.Media(5, 5);

// Buffer tagging
myMedia.track('av.buffer.start', {av_position: 0}, function() {console.log('Event "av.buffer.start" generated');}, null);

// Re-buffer tagging
myMedia.track('av.rebuffer.start', {av_position: 10}, function() {console.log('Event "av.rebuffer.start" generated');}, null);

// Play tagging
myMedia.track('av.play', {av_position: 0}, function() {console.log('Event "av.play" generated');}, null);

// Playback start tagging
myMedia.track('av.start', {av_position: 0}, function() {console.log('Event "av.start" generated');}, null);

// Playback pause tagging
myMedia.track('av.pause', {av_position: 10}, function() {console.log('Event "av.pause" generated');}, null);

// Playback resume tagging
myMedia.track('av.resume', {av_position: 10}, function() {console.log('Event "av.resume" generated');}, null);

// Playback stop tagging
myMedia.track('av.stop', {av_position: 20}, function() {console.log('Event "av.stop" generated');}, null);

// Seek forward tagging
myMedia.track('av.forward', {av_previous_position: 10, av_position: 20}, function() {console.log('Event "av.forward" generated');}, null);

// Seek backward tagging
myMedia.track('av.backward', {av_previous_position: 20, av_position: 10}, function() {console.log('Event "av.backward" generated');}, null);

// Ad click tagging
myMedia.track('av.ad.click', null, function() {console.log('Event "av.ad.click" generated');}, null);

// Ad skip tagging
myMedia.track('av.ad.skip', null, function() {console.log('Event "av.ad.skip" generated');}, null);

// Error tagging
myMedia.track('av.error', {av_player_error: "Player error"}, function() {console.log('Event "av.error" generated');}, null);

// Display tagging
myMedia.track('av.display', null, function() {console.log('Event "av.display" generated');}, null);

// Close tagging
myMedia.track('av.close', null, function() {console.log('Event "av.close" generated');}, null);

// Volume tagging
myMedia.track('av.volume', null, function() {console.log('Event "av.volume" generated');}, null);

// Subtitle on tagging
myMedia.track('av.subtitle.on', null, function() {console.log('Event "av.subtitle.on" generated');}, null);

// Subtitle off tagging
myMedia.track('av.subtitle.off', null, function() {console.log('Event "av.subtitle.off" generated');}, null);

// Full screen on tagging
myMedia.track('av.fullscreen.on', null, function() {console.log('Event "av.fullscreen.on" generated');}, null);

// Full screen off tagging
myMedia.track('av.fullscreen.off', null, function() {console.log('Event "av.fullscreen.off" generated');}, null);

// Quality tagging
myMedia.track('av.quality', null, function() {console.log('Event "av.quality" generated');}, null);

// Speed tagging
myMedia.track('av.speed', null, function() {console.log('Event "av.speed" generated');}, null);

// Share tagging
myMedia.track('av.share', null, function() {console.log('Event "av.share" generated');}, null);

// Custom tagging
myMedia.track('custom', null, null, {'customParam': 'customValue'});