AS2 tagging » JavaScript » Content » Media » AV Insights

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. The first one enables playback tracking heartbeats and the second one enables buffering tracking heartbeats. The values provided are no longer used, the heartbeat evolution steps are now defined by us. The presence of the values will only activate the functionality.

The “heartbeat” is a refresh interval that changes automatically during playback.

Session ID management

An optional third parameter sessionId is available since Tracker version 5.22.0 to override the common standard property av_session_id present in each event generated by AV Insights tags. Please note that this parameter should be used only in special cases when you need to transfer sessions between different device.
The parameter is automatically generated by the Tracker for all standard cases.

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

Param	Type	Description
propKey	`string`	Media property key
propValue	`string` \| `number`	Media property value

Example

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

get

get(propKey) ⇒  string | number

Retrieve a media property.

Param	Type	Description
propKey	`string`	Media property key

Example

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

del

del(propKey)

Delete a media property.

Param	Type	Description
propKey	`string`	Media property key

Example

myMedia.del('av_content_id');

setProps

setProps(properties)

Declare multiple media properties.

Param	Type	Description
properties	`Object`	Media 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();

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.

Param	Type	Description
playbackSpeed	`number`	Playback 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 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 or during the playing.

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

Param	Type	Description
cursorPosition	`number`	Current cursor position (ms)
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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).

Param	Type	Description
cursorPosition	`number`	Current cursor position (ms)
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
cursorPosition	`number`	Current cursor position (ms)
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
cursorPosition	`number`	Current cursor position (ms)
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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).

Param	Type	Description
cursorPosition	`number`	Current cursor position (ms)
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
cursorPosition	`number`	Current cursor position (ms)
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
oldCursorPosition	`number`	Cursor position before seeking (ms)
newCursorPosition	`number`	Cursor position after seeking (ms)
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom properties

Example

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

display

Event name : av.display

display([callback], [extraProps])

Measure a display.

Param	Type	Description
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
heartbeat	`Object` \| `string` \| `number`	Valeur 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.

Param	Type	Description
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom properties

Example

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

Event name : av.share

share([callback], [extraProps])

Measure a sharing.

Param	Type	Description
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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

Param	Type	Description
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
[cursorPosition]	`number`	Current cursor position (ms)
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom properties

Example

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

The cursor position is not required for tagging a heartbeat event. Without any precision on your part, the value 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.

Param	Type	Description
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
oldCursorPosition	`number`	Cursor position before seeking (ms)
newCursorPosition	`number`	Cursor position after seeking (ms)
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
oldCursorPosition	`number`	Cursor position before seeking (ms)
newCursorPosition	`number`	Cursor position after seeking (ms)
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
oldCursorPosition	`number`	Cursor position before seeking (ms)
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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.

Param	Type	Description
event	`string`	Event to be generated (see list of standard events at the bottom of the page)
[options]	`Object`	Options depending on the event (see list of available options at the bottom of the page)
[callback]	`function`	Callback function to execute after hit sent
[extraProps]	`Object`	Custom 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',
    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

Property	Type	Description
av_player	string	Player identifier
av_player_version	string	Player version
av_player_position	string	Player position
av_content	string	Content label
av_content_id	string	Content identifier
av_content_type	string	Content type (Audio/Video/Gaming…)
av_content_duration	number	Content duration (milliseconds)
av_content_version	string	Content version
av_content_genre	string array	Content genre (news/entertainment…)
av_content_linked	string	Linked content
av_content_duration_range	string	Content duration range (‘0-10’…)
av_broadcasting_type	string	Broadcasting type (live, VOD)
av_ad_type	string	Ad type (Pre-roll/Mid-Roll/Post-Roll)
av_publication_date	number	Publication date (seconds – format UTC)
av_show	string	Show label
av_show_season	string	Show season
av_episode_id	string	Episode identifier
av_episode	string	Episode label
av_channel	string	Channel
av_author	string	Author name
av_broadcaster	string	Broadcaster label
av_auto_mode	boolean	Is playback auto?
av_language	string	Media language
av_subtitles	string	Subtitles
av_launch_reason	string	Launch 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

Option	Description
av_position	Current cursor position (ms)
av_previous_position	Previous cursor position (ms)
av_player_error	Error preventing playback

Last update: 14/01/2022

Developers » AS2 tagging » JavaScript » Content » Media » AV Insights 5.20.0