Skip to main content

AV Insights (audio video)

  AV Insights allows the collection of events related to media consumption on your site. You will be able to follow the different interactions on your players and measure the performance of your content.

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‚Äč

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.

warning

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

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 syntax of the basic properties allowing to characterize a media must be respected (see the exhaustive list of properties at the bottom of the page).
  • 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‚Äč

set(propKey, propValue)

Declare a media property.

ParameterTypeDescription
propKeystringMedia property key
propValuestring, numberMedia property value

Example

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

get‚Äč

get(propKey) ⇒  string | number

Retrieve a media property.

ParameterTypeDescription
propKeystringMedia property key

Example

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

del‚Äč

del(propKey)

Delete a media property.

ParameterTypeDescription
propKeystringMedia property key

Example

myMedia.del('av_content_id');

setProps‚Äč

setProps(properties)

Declare multiple media properties.

ParameterTypeDescription
propertiesObjectMedia properties

Example

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

#### getProps

`getProps() ⇒ Object`

_Retrieve all media properties._

Example

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

delProps‚Äč

delProps()

Delete all media properties.

Example

myMedia.delProps();

Playback speed‚Äč

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

setPlaybackSpeed‚Äč

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 myMedia.speed() method.

Events tracking‚Äč

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

Media events‚Äč

bufferStart‚Äč

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

bufferStart(cursorPosition[, callback, extraProps])

Generate an event of buffering at the launch of a media or during the playing.

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" }
);

play‚Äč

Event name : av.play

play(cursorPosition[, callback, extraProps])

Generate a play event (playback attempt).

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" }
);

playbackPaused‚Äč

Event name : av.pause

playbackPaused(cursorPosition[, callback, extraProps])

Generate a pause event.

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

playbackResumed(cursorPosition[, callback, extraProps])

Generate a resume event, following a pause event.

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" }
);

playbackStart‚Äč

Event name : av.start

playbackStart(cursorPosition[, callback, extraProps])

Generate a playback start event (first media frame).

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" }
);

playbackStopped‚Äč

Event name : av.stop

playbackStopped(cursorPosition[, callback, extraProps])

Generate a stop event.

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

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

Generate a seek event.

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.

adClick‚Äč

Event name : av.ad.click

adClick([callback, extraProps])

Generate an ad click event.

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

adSkip([callback, extraProps])

Generate an ad skip event.

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

close([callback, extraProps])

Measure a closing.

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

display([callback, extraProps])

Measure a display.

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

`error(message[, callback, extraProps])

Measure an error preventing playback.

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

fullscreenOff([callback, extraProps])

Measure full screen deactivation.

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

fullscreenOn([callback, extraProps])

Measure full screen activation.

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

quality([callback, extraProps])

Measure a quality change.

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

share([callback, extraProps])

Measure a sharing.

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

speed([callback, extraProps])

Measure a speed change.

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

subtitleOff([callback, extraProps])

Measure subtitles deactivation

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

subtitleOn([callback, extraProps])

Measure subtitles activation.

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

volume([callback, extraProps])

Measure sound volume change.

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.

bufferHeartbeat‚Äč

Event name : av.buffer.heartbeat

bufferHeartbeat([callback, extraProps])

Generate a buffering heartbeat before the playback starts event.

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

heartbeat([cursorPosition, callback, extraProps])

Generate an heartbeat event.

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

rebufferHeartbeat([callback, extraProps])

Generate a buffering heartbeat after the playback starts event.

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" }
);

seekBackward‚Äč

Event name : av.backward

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

Generate a backward seeking event.

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

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

Generate a forward seeking event.

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" }
);

seekStart‚Äč

Event name : av.seek.start

seekStart(oldCursorPosition, [callback, extraProps])

Generate a beginning of seeking event.

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" }
);

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(event, [options, callback, extraProps])

Track standard or custom actions.

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'});

Complete tagging example

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

var properties = {
av_content_id: 'fge234',
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: 'AT Internet',
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 properties list‚Äč

PropertyTypeDescription
av_playerstringPlayer identifier
av_player_versionstringPlayer version
av_player_positionstringPlayer position
av_contentstringContent label
av_content_idstringContent identifier
av_content_typestringContent type (Audio/Video/Gaming…)
av_content_durationnumberContent duration (milliseconds)
av_content_versionstringContent version
av_content_genrestring arrayContent genre (news/entertainment…)
av_content_linkedstringLinked content
av_content_duration_rangestringContent duration range (‚Äė0-10‚Äô‚Ķ)
av_broadcasting_typestringBroadcasting type (live, VOD)
av_ad_typestringAd type (Pre-roll/Mid-Roll/Post-Roll)
av_publication_datenumberPublication date (seconds ‚Äď UTC)
av_showstringShow label
av_show_seasonstringShow season
av_episode_idstringEpisode identifier
av_episodestringEpisode label
av_channelstringChannel
av_authorstringAuthor name
av_broadcasterstringBroadcaster label
av_auto_modebooleanIs playback auto?
av_languagestringMedia language
av_subtitlesstringSubtitles
av_launch_reasonstringLaunch reason

List of standard events‚Äč

Event
av.heartbeat
av.buffer.heartbeat
av.rebuffer.heartbeat
av.play
av.buffer.start
av.rebuffer.start
av.start
av.resume
av.pause
av.stop
av.forward
av.backward
av.seek.start
av.ad.click
av.ad.skip
av.error
av.display
av.close
av.volume
av.subtitle.on
av.subtitle.off
av.fullscreen.on
av.fullscreen.off
av.quality
av.speed
av.share

List of available options‚Äč

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