AV Insights

 

Foreword

In order to benefit from AV Insights you should first activate the feature. If you want to activate it please contact our support centre.

The AV Insights plugin 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 manipulation

 

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 tag = new ATInternet.Tracker.Tag();
var myMedia = new tag.avInsights.Media(5, 5);

Two parameters are available, in order to activate the automatic heartbeats.

 

“heartbeats” management

The “heartbeat” allows you to define a refresh interval that can change during playback. This parameter can be in the form of an integer to define a simple interval or in the form of a more complex object to define refresh steps. Intervals should be expressed in seconds.

For example, to have the following diagram:

  1. From the beginning of the reading to the first minute, an interval of 5 seconds is allowed.
  2. From the 1st minute to the 5th minute, an interval of 15 seconds
  3. From the 5th minute to the 10th minute, a 30-second interval
  4. Beyond the 10th minute, a one-minute interval

The configuration will be filled in like this:

var tag = new ATInternet.Tracker.Tag();
var myMedia = new tag.avInsights.Media({0: 5, 1: 15, 5: 30, 10: 60});

Refresh increments can also be defined as part of buffering monitoring.

The media constructor of the Tracker can indeed take two parameters during initialization:

Media(heartbeatValue, bufferHeartbeatValue)

Instanciation of a Media object.

ParamTypeDescription
heartbeatValueObject | string | numberRefresh step(s) triggered during playback
bufferHeartbeatValueObject | string | numberRefresh step(s) triggered during buffering
var tag = new ATInternet.Tracker.Tag();
// Example with dynamic values
var heartbeatValue = {0: 5, 1: 15, 5: 30, 10: 60};
var bufferHeartbeatValue = {0: 5, 1: 15, 5: 30, 10: 60};
var myMedia = new tag.avInsights.Media(heartbeatValue, bufferHeartbeatValue);
// Example with simple values
// var heartbeatValue = 5;
// var bufferHeartbeatValue = 5;
// var myMedia = new tag.avInsights.Media(heartbeatValue, bufferHeartbeatValue);
// Example with combined values
// var heartbeatValue = {0: 5, 1: 15, 5: 30, 10: 60};
// var bufferHeartbeatValue = 5;
// var myMedia = new tag.avInsights.Media(heartbeatValue, bufferHeartbeatValue);
 

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 (possible presence of underscore _ characters; see the exhaustive list of properties at the bottom of the page).
  • The $ symbol is a reserved symbol that must not be used in the name of a property.
  • The duration of the media or the positions of the playback head must be expressed in milliseconds.

The plugin provides a series of useful functions for the management of Media properties:

 

set

set(propKey, propValue)

Declare a media property.

ParamTypeDescription
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.

ParamTypeDescription
propKeystringMedia property key

Example

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

del

del(propKey)

Delete a media property.

ParamTypeDescription
propKeystringMedia property key

Example

myMedia.del('av_content_id');
 

setProps

setProps(properties)

Declare multiple media properties.

ParamTypeDescription
propertiesObjectMedia properties

Example

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

getProps

getProps() ⇒ Object

Retrieve multiple media properties.

Example

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

delProps

delProps()

Delete multiple media properties.

Example

myMedia.delProps();
 

Events tracking

The Insights AV Plugin offers a series of 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.

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

ParamTypeDescription
cursorPositionnumberCurrent cursor position (ms)
[callback]functionCallback function to execute after hit sent
[extraProps]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).

ParamTypeDescription
cursorPositionnumberCurrent cursor position (ms)
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
cursorPositionnumberCurrent cursor position (ms)
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
cursorPositionnumberCurrent cursor position (ms)
[callback]functionCallback function to execute after hit sent
[extraProps]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).

ParamTypeDescription
cursorPositionnumberCurrent cursor position (ms)
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
cursorPositionnumberCurrent cursor position (ms)
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
oldCursorPositionnumberCursor position before seeking (ms)
newCursorPositionnumberCursor position after seeking (ms)
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
heartbeatObject | string | numberValeur de heartbeat

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.

ParamTypeDescription
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
[callback]functionCallback function to execute after hit sent
[extraProps]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

ParamTypeDescription
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
[callback]functionCallback function to execute after hit sent
[extraProps]ObjectCustom properties

Example

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

heartbeat

Event name : av.heartbeat

heartbeat([callback], [extraProps])

Generate an heartbeat event.

ParamTypeDescription
[callback]functionCallback function to execute after hit sent
[extraProps]ObjectCustom properties

Example

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

rebufferHeartbeat

Event name : av.rebuffer.heartbeat

rebufferHeartbeat([callback], [extraProps])

Generate a buffering heartbeat after the playback starts event.

ParamTypeDescription
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
oldCursorPositionnumberCursor position before seeking (ms)
newCursorPositionnumberCursor position after seeking (ms)
[callback]functionCallback function to execute after hit sent
[extraProps]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.

ParamTypeDescription
oldCursorPositionnumberCursor position before seeking (ms)
newCursorPositionnumberCursor position after seeking (ms)
[callback]functionCallback function to execute after hit sent
[extraProps]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.

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

ParamTypeDescription
oldCursorPositionnumberCursor position before seeking (ms)
[callback]functionCallback function to execute after hit sent
[extraProps]ObjectCustom properties

Example

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

Universal tracking method

 

track

The AV Insights universal event tagging 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.).

Event name : event value

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

Track standard or custom actions.

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

Example

var tag = new ATInternet.Tracker.Tag();
var myMedia = new tag.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 tag = new ATInternet.Tracker.Tag();
var myMedia = new tag.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'
};
// 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 (millisecondes -format 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?
 

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

Cet article a-t-il été utile ?

Last update: 24/03/2020