Skip to content
This repository was archived by the owner on May 5, 2026. It is now read-only.

AV Insights 650e14

Jump to bottom
Benjamin Diolez edited this page May 5, 2026 · 1 revision

Data collection / Android / Content / 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 :

Tracker tracker = ATInternet.getInstance().getDefaultTracker();
Media myMedia = tracker.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 2.18.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.

Tracker tracker = ATInternet.getInstance().getDefaultTracker();
Media myMedia = tracker.AVInsights().Media(5, 5, "custom_session_id");

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

getSessionID() ⇒ 
String

Retrieve the session ID.

Example

String sessionID = myMedia.getSessionID(); // "custom_session_id" or "xxxxxxxx-xxxx-xxxx-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(String propKey, Object propValue)

Declare a media property.
Param Type Description
propKey String Media property key
propValue Object Media property value

Example

myMedia.set("av_content", "my_video");
myMedia.set("av_content_id", "fg456");

get

get(String propKey) ⇒  
Object

Retrieve a media property.
Param Type Description
propKey String Media property key

Example

Object contentId = myMedia.get("av_content_id"); // fg456

del

del(String propKey)

Delete a media property.
Param Type Description
propKey String Media property key

Example

myMedia.del("av_content_id");

setProps

setProps(Map<String,Object> properties)

Declare multiple media properties.
Param Type Description
properties Map<String,Object> Media properties

Example

myMedia.setProps(new HashMap<String, Object>() {{
    put("av_content", "My Content");
    put("av_content_id", "fg456");
}});

getProps

getProps() ⇒ 
Map<String, Object>

Retrieve multiple media properties.

Example

Map<String, Object> props = myMedia.getProps(); // {"av_content_id": "fg456", "av_content": "My Content"}

delProps

delProps()

Delete multiple media properties.

Example

myMedia.delProps();

!– wp:heading {“level”:3} –>

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(double playbackSpeed)

Declare a change in playback speed.
Param Type Description
playbackSpeed double Playback speed factor

Example

myMedia.setPlaybackSpeed(2.0); // 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(int cursorPosition, Map<String, Object> 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 int Current cursor position (ms)
extraProps Map<String, Object> Custom properties

Example

myMedia.bufferStart(
  0,
  new HashMap<String, Object>() {{
    put("customProp", "customValue");
  }}
);

play

Event name : av.play

play(int cursorPosition, Map<String, Object> extraProps)

Generate a play event (playback attempt).
Param Type Description
cursorPosition int Current cursor position (ms)
extraProps Map<String, Object> Custom properties

Example

myMedia.play(
  0,
  new HashMap<String, Object>() {{
    put("customProp", "customValue");
  }}
);

playbackPaused

Event name : av.pause

playbackPaused(int cursorPosition, Map<String, Object> extraProps)

Generate a pause event.
Param Type Description
cursorPosition int Current cursor position (ms)
extraProps Map<String, Object> Custom properties

Example

myMedia.playbackPaused(
  1000,
  new HashMap<String, Object>() {{
    put("customProp", "customValue");
  }}
);

playbackResumed

Event name : av.resume

playbackResumed(int cursorPosition, Map<String, Object> extraProps)

Generate a resume event, following a pause event.
Param Type Description
cursorPosition int Current cursor position (ms)
extraProps Map<String, Object> Custom properties

Example

myMedia.playbackResumed(
  1000,
  new HashMap<String, Object>() {{
    put("customProp", "customValue");
  }}
);

playbackStart

Event name : av.start

playbackStart(int cursorPosition, Map<String, Object> extraProps)

Generate a playback start event (first media frame).
Param Type Description
cursorPosition int Current cursor position (ms)
extraProps Map<String, Object> Custom properties

Example

myMedia.playbackStart(
  0,
  new HashMap<String, Object>() {{
    put("customProp", "customValue");
  }}
);

playbackStopped

Event name : av.stop

playbackStopped(int cursorPosition, Map<String, Object> extraProps)

Generate a stop event.
Param Type Description
cursorPosition int Current cursor position (ms)
extraProps Map<String, Object> Custom properties

Example

myMedia.playbackStopped(
  1000,
  new HashMap<String, Object>() {{
    put("customProp", "customValue");
);

seek

Event name : av.forward ou av.backward

seek(int oldCursorPosition, int newCursorPosition, Map<String, Object> extraProps)

Generate a seek event.
Param Type Description
oldCursorPosition int Cursor position before seeking (ms)
newCursorPosition int Cursor position after seeking (ms)
extraProps Map<String, Object> Custom properties

Example

myMedia.seek(
  1000,
  2000,
  new HashMap<String, Object>() {{
    put("customProp", "customValue");
  }}
);
myMedia.seek(
  2000,
  1000,
  new HashMap<String, Object>() {{
    put("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(Map<String, Object> extraProps)

Generate an ad click event.
Param Type Description
extraProps Map<String, Object> Custom properties

Example

myMedia.adClick(
  new HashMap<String, Object>() {{
      put("customProp", "customValue");
  }}
);

adSkip

Event name : av.ad.skip

adSkip(Map<String, Object> extraProps)

Generate an ad skip event.
Param Type Description
extraProps Map<String, Object> Custom properties

Example

myMedia.adSkip(
  new HashMap<String, Object>() {{
      put("customProp", "customValue");
  }}
);

close

Event name : av.close

close(Map<String, Object> extraProps)

Measure a closing.
Param Type Description
extraProps Map<String, Object> Custom properties

Example

myMedia.close(
  new HashMap<String, Object>() {{
      put("customProp", "customValue");
  }}
);

display

Event name : av.display

display(Map<String, Object> extraProps)

Measure a display.
Param Type Description
extraProps Map<String, Object> Custom properties

Example

myMedia.display(
  new HashMap<String, Object>() {{
      put("customProp", "customValue");
  }}
);

error

Event name : av.buffer.start ou av.error

error(String message, Map<String, Object> extraProps)

Measure an error preventing playback.
Param Type Description
message String Error message
extraProps Map<String, Object> Custom properties

Example

myMedia.error(
  "Error loading video",
  new HashMap<String, Object>() {{
    put("customProp", "customValue");
  }}
);

fullscreenOff

Event name : av.fullscreen.off

fullscreenOff(Map<String, Object> extraProps)

Measure full screen deactivation.
Param Type Description
extraProps Map<String, Object> Custom properties

Example

myMedia.fullscreenOff(
  new HashMap<String, Object>() {{
      put("customProp", "customValue");
  }}
);

fullscreenOn

Event name : av.fullscreen.on

fullscreenOn(Map<String, Object> extraProps)

Measure full screen activation.
Param Type Description
extraProps Map<String, Object> Custom properties

Example

myMedia.fullscreenOn(
  new HashMap<String, Object>() {{
      put("customProp", "customValue");
  }}
);

quality

Event name : av.quality

quality(Map<String, Object> extraProps)

Measure a quality change.
Param Type Description
extraProps Map<String, Object> Custom properties

Example

myMedia.quality(
  new HashMap<String, Object>() {{
      put("customProp", "customValue");
  }}
);

share

Event name : av.share

share(Map<String, Object> extraProps)

Measure a sharing.
Param Type Description
extraProps Map<String, Object> Custom properties

Example

myMedia.share(
  new HashMap<String, Object>() {{
      put("customProp", "customValue");
  }}
);

speed

Event name : av.speed

speed(Map<String, Object> extraProps)

Measure a speed change.
Param Type Description
extraProps Map<String, Object> Custom properties

Example

myMedia.speed(
  new HashMap<String, Object>() {{
      put("customProp", "customValue");
  }}
);

subtitleOff

Event name : av.subtitle.off

subtitleOff(Map<String, Object> extraProps)

Measure subtitles deactivation
Param Type Description
extraProps Map<String, Object> Custom properties

Example

myMedia.subtitleOff(
  new HashMap<String, Object>() {{
      put("customProp", "customValue");
  }}
);

subtitleOn

Event name : av.subtitle.on

subtitleOn(Map<String, Object> extraProps)

Measure subtitles activation.
Param Type Description
extraProps Map<String, Object> Custom properties

Example

myMedia.subtitleOn(
  new HashMap<String, Object>() {{
      put("customProp", "customValue");
  }}
);

volume

Event name : av.volume

volume(Map<String, Object> extraProps)

Measure sound volume change.
Param Type Description
extraProps Map<String, Object> Custom properties

Example

myMedia.volume(
  new HashMap<String, Object>() {{
      put("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(Map<String, Object> extraProps)

Generate a buffering heartbeat before the playback starts event.
Param Type Description
extraProps Map<String, Object> Custom properties

Example

myMedia.bufferHeartbeat(
  new HashMap<String, Object>() {{
      put("customProp", "customValue");
  }}
);

heartbeat

Event name: av.heartbeat

heartbeat(int cursorPosition, Map<String, Object> extraProps)

Generate a heartbeat event.
Param Type Description
cursorPosition int Current cursor position (ms)
extraProps Map<String, Object> Custom properties

Example

myMedia.heartbeat(
  45,
  new HashMap<String, Object>() {{
      put("customProp", "customValue");
  }}
);

The cursor position is not required for tagging a heartbeat event. By forcing the parameter value to -1, the cursor position will be automatically calculated according to the context (playback speed factor, cursor position of the previous event).

rebufferHeartbeat

Event name : av.rebuffer.heartbeat

rebufferHeartbeat(Map<String, Object> extraProps)

Generate a buffering heartbeat after the playback starts event.
Param Type Description
extraProps Map<String, Object> Custom properties

Example

myMedia.rebufferHeartbeat(
  new HashMap<String, Object>() {{
      put("customProp", "customValue");
  }}
);

seekBackward

Event name : av.backward

seekBackward(int oldCursorPosition, int newCursorPosition, Map<String, Object> extraProps)

Generate a backward seeking event.
Param Type Description
oldCursorPosition int Cursor position before seeking (ms)
newCursorPosition int Cursor position after seeking (ms)
extraProps Map<String, Object> Custom properties

Example

myMedia.seekBackward(
  2000,
  1000,
  new HashMap<String, Object>() {{
      put("customProp", "customValue");
  }}
);

seekForward

Event name : av.forward

seekForward(int oldCursorPosition, int newCursorPosition, Map<String, Object> extraProps)

Generate a forward seeking event.
Param Type Description
oldCursorPosition int Cursor position before seeking (ms)
newCursorPosition int Cursor position after seeking (ms)
extraProps Map<String, Object> Custom properties

Example

myMedia.seekForward(
  1000,
  2000,
  new HashMap<String, Object>() {{
      put("customProp", "customValue");
  }}
);

seekStart

Event name : av.seek.start

seekStart(int oldCursorPosition, Map<String, Object> extraProps)

Generate a beginning of seeking event.

This event is automatically raised when calling the seek(), seekBackward() or seekForward() methods.
Param Type Description
oldCursorPosition int Cursor position before seeking (ms)
extraProps Map<String, Object> Custom properties

Example

myMedia.seekStart(
  1000,
  new HashMap<String, Object>() {{
      put("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(String event, Map<String, Object> options, Map<String, Object> 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 Map<String, Object> Options depending on the event (see list of available options at the bottom of the page)
extraProps Map<String, Object> Custom properties

Example

Tracker tracker = ATInternet.getInstance().getDefaultTracker();
Media myMedia = tracker.AVInsights().Media(5, 5);
// Buffer tagging
myMedia.track("av.buffer.start", new HashMap<String, Object>() {{
    put("av_position", 0);
}}, null);
// Re-buffer tagging
myMedia.track("av.rebuffer.start", new HashMap<String, Object>() {{
    put("av_position", 10);
}}, null);
// Play tagging
myMedia.track("av.play", new HashMap<String, Object>() {{
    put("av_position", 0);
}}, null);
// Playback start tagging
myMedia.track("av.start", new HashMap<String, Object>() {{
    put("av_position", 0);
}}, null);
// Playback pause tagging
myMedia.track("av.pause", new HashMap<String, Object>() {{
    put("av_position", 10);
}}, null);
// Playback resume tagging
myMedia.track("av.resume", new HashMap<String, Object>() {{
    put("av_position", 10);
}}, null);
// Playback stop tagging
myMedia.track("av.stop", new HashMap<String, Object>() {{
    put("av_position", 20);
}}, null);
// Seek forward tagging
myMedia.track("av.forward", new HashMap<String, Object>() {{
    put("av_previous_position", 10);
    put("av_position", 20);
}}, null);
// Seek backward tagging
myMedia.track("av.backward", new HashMap<String, Object>() {{
    put("av_previous_position", 20);
    put("av_position", 10);
}}, null);
// Ad click tagging
myMedia.track("av.ad.click", null, null);
// Ad skip tagging
myMedia.track("av.ad.skip", null, null);
// Error tagging
myMedia.track("av.error", new HashMap<String, Object>() {{
    put("av_player_error", "Player error");
}}, null);
// Display tagging
myMedia.track("av.display", null, null);
// Close tagging
myMedia.track("av.close", null, null);
// Volume tagging
myMedia.track("av.volume", null, null);
// Subtitle on tagging
myMedia.track("av.subtitle.on", null, null);
// Subtitle off tagging
myMedia.track("av.subtitle.off", null, null);
// Full screen on tagging
myMedia.track("av.fullscreen.on", null, null);
// Full screen off tagging
myMedia.track("av.fullscreen.off", null, null);
// Quality tagging
myMedia.track("av.quality", null, null);
// Speed tagging
myMedia.track("av.speed", null, null);
// Share tagging
myMedia.track("av.share", null, null);
// Custom tagging
myMedia.track("custom", null, new HashMap<String, Object>() {{
    put("customParam", "customValue");
}});

Complete tagging example

Tracker tracker = ATInternet.getInstance().getDefaultTracker();
Media myMedia = tracker.AVInsights().Media(5, 5); // Set heartbeats value (5 seconds)
Map<String, Object> properties = new HashMap<String, Object>() {{
    put("av_content_id", "fge234");
    put("av_content", "myContent");
    put("av_content_type", "Video");
    put("av_content_duration", 10000);
    put("av_content_genre", new ArrayList<String>() {{
        add("entertainment");
    }});
    put("av_content_version", "short");
    put("av_player", "HTML5_V123");
    put("av_player_version", "1b");
    put("av_player_position", "top");
    put("av_broadcasting_type", "On Demand");
    put("av_publication_date", 1562055880);
    put("av_show", "The gist of the game");
    put("av_show_season", "Season 1");
    put("av_episode_id", "3134");
    put("av_channel", "INFO");
    put("av_author", "AT Internet");
    put("av_broadcaster", "Direction 123");
    put("av_language", "EN");
    put("av_subtitles", "FR");
    put("av_launch_reason", "Auto");
}};
// Set media properties
myMedia.setProps(properties);
// Play attempt (cursor position 0 second)
myMedia.play(0, null);
// Buffering before playback start (cursor position 0 second)
myMedia.bufferStart(0, null);
// Playback start (cursor position 0 second)
myMedia.playbackStart(0, null);
// Buffering after 5 seconds of playback
myMedia.bufferStart(5000, null);
// Seek action (backward from cursor position 5 seconds to cursor position 3 seconds)
myMedia.seek(5000, 3000, null);
// Playback resume (cursor position 3 seconds)
myMedia.playbackResumed(3000, null);
// Playback pause (cursor position 9 seconds)
myMedia.playbackPaused(9000, null);
// Playback resume (cursor position 9 seconds)
myMedia.playbackResumed(9000, null);
// Playback stop (cursor position 15 seconds)
myMedia.playbackStopped(15000, null);

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 int Content duration (milliseconds)
av_content_version String Content version
av_content_genre ArrayList 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 int 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: 05/06/2023

Wiki contents

Clone this wiki locally