AV Insights

 

Avant-propos

Afin de bénéficier de AV Insights, vous devez d’abord activer la fonction. Si vous souhaitez l’activer, veuillez contacter notre centre support.

Le plugin AV Insights permet la collecte d’événements liés à la consommation de média sur votre site. Vous pourrez suivre les différentes interactions sur vos lecteurs et mesurer la performance de vos contenus.

 

Manipulation de média

 

Instanciation d’un média

Afin de pouvoir manipuler un média et en mesurer les événements, il est nécessaire de déclarer un objet de type Media :

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

Deux paramètres sont disponibles, afin d’activer les heartbeats automatiques.

 

Gestion des “heartbeats”

Le “heartbeat” permet de définir un intervalle de rafraîchissement qui peut évoluer au cours d’une lecture. Ce paramètre peut se présenter sous la forme d’un entier pour définir un intervalle simple ou sous la forme d’un objet plus complexe pour définir des paliers de rafraîchissement. Les intervalles doivent être exprimés en secondes.

Par exemple, pour avoir le schéma suivant :

  1. Du début de la lecture jusqu’à la 1ère minute, un intervalle de 5 secondes
  2. De la 1ère minute à la 5ème minute, un intervalle de 15 secondes
  3. De la 5ème minute à la 10ème minute, un intervalle de 30 secondes
  4. Au-delà de la 10ème minute, un intervalle d’une minute

On renseignera la configuration comme ceci :

ATInternet.getInstance().getDefaultTracker();
Media myMedia = tracker.AVInsights().Media(new SparseIntArray() {{
    append(0, 5);
    append(1, 15);
    append(5, 30);
    append(10, 60);
}}, null);

Des paliers de rafraîchissement peuvent aussi être définis dans le cadre du suivi d’une mise en mémoire tampon.

Le constructeur de média du Tracker peut en effet prendre deux paramètres lors de l’initialisation :

Media(heartbeatValue, bufferHeartbeatValue)

Instanciation of a Media object.

ParamTypeDescription
heartbeatValueSparseIntArray | intRefresh step(s) triggered during playback
bufferHeartbeatValueSparseIntArray | intRefresh step(s) triggered during buffering
Tracker tracker = ATInternet.getInstance().getDefaultTracker();
// Example with dynamic values
SparseIntArray heartbeatValue = new SparseIntArray() {{
    append(0, 5);
    append(1, 15);
    append(5, 30);
    append(10, 60);
}};
SparseIntArray bufferHeartbeatValue = new SparseIntArray() {{
    append(0, 5);
    append(1, 15);
    append(5, 30);
    append(10, 60);
}};
Media myMedia = tracker.AVInsights().Media(heartbeatValue, bufferHeartbeatValue);
// Example with simple values
// int heartbeatValue = 5;
// int bufferHeartbeatValue = 5;
// Media myMedia = tracker.AVInsights().Media(heartbeatValue, bufferHeartbeatValue);
 

Propriétés de média

Quelques règles doivent être observées concernant le format des propriétés utilisées pour la configuration d’un média :

  • La syntaxe des propriétés de base permettant de caractériser un média doit être respectée (présence éventuelle de caractères underscore _ ; voir la liste exhaustive des propriétés en bas de page).
  • Le symbole $ est un symbole réservé qui ne doit pas être utilisé dans le nom d’une propriété.
  • La durée des media ou les positions de la tête de lecture doivent être exprimées en millisecondes.

Le plugin fournit une série de fonctions utiles pour la gestion des propriétés d’un média :

 

set

set(propKey, propValue)

Déclarer une propriété de média.

ParamTypeDescription
propKeyStringNom d’une propriété de média
propValueObjectValeur d’une propriété de média

Exemple

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

get

get(String propKey) ⇒  Object

Récupérer une propriété de média.

ParamTypeDescription
propKeyStringNom d’une propriété de média

Exemple

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

del

del(String propKey)

Supprimer une propriété de média.

ParamTypeDescription
propKeyStringMedia property key

Exemple

myMedia.del("av_content_id");
 

setProps

setProps(Map<String,Object> properties)

Déclarer un ensemble de propriétés pour un média.

ParamTypeDescription
propertiesMap<String,Object>Propriétés d’un média

Exemple

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

getProps

getProps() ⇒ Map<String, Object>

Récupérer l’ensemble des propriétés d’un média.

Exemple

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

delProps

delProps()

Supprimer l’ensemble des propriétés d’un média.

Exemple

myMedia.delProps();
 

Vitesse de lecture

Lors d’un changement de vitesse de lecture vous devez faire appel à la méthode setPlaybackSpeed() en précisant le nouveau facteur de vitesse sous la forme d’un nombre décimal.

 

setPlaybackSpeed

setPlaybackSpeed(double playbackSpeed)

Déclarer un changement de vitesse de lecture.

ParamTypeDescription
playbackSpeeddoubleFacteur de vitesse de lecture

Exemple

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

Le nouveau facteur de vitesse de lecture sera pris en compte dans le calcul des positions de curseur des événements automatisés heartbeats pendant une lecture.

Vous pouvez si vous le souhaitez marquer l’événement associé à ce changement de vitesse en faisant appel à la méthode myMedia.speed();

 

Suivi des événements

Le plugin AV Insights propose une série de fonctions utiles pour la mesure d’événements relatifs aux interactions de vos utilisateurs avec vos contenus :

 

Evénements media

 

bufferStart

Nom de l’événement : av.buffer.start ou av.rebuffer.start

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

Générer un événement de mise en mémoire tampon au lancement d’un média ou en cours de lecture.

Un marquage de mise en mémoire tampon entraînera une génération automatique d’événements de type  buffering.heartbeat ou rebuffering.heartbeat en fonction du contexte.

ParamTypeDescription
cursorPositionintPosition courante de la tête de lecture (ms)
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

play

Nom de l’événement : av.play

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

Générer un événement play (tentative de lecture).

ParamTypeDescription
cursorPositionintPosition courante de la tête de lecture (ms)
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

playbackPaused

Nom de l’événement : av.pause

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

Générer un événement de mise en pause.

ParamTypeDescription
cursorPositionintPosition courante de la tête de lecture (ms)
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

playbackResumed

Nom de l’événement : av.resume

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

Générer un événement de reprise de lecture après une pause.

ParamTypeDescription
cursorPositionintPosition courante de la tête de lecture (ms)
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

playbackStart

Nom de l’événement : av.start

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

Générer un événement de début de lecture effective (première frame du média).

ParamTypeDescription
cursorPositionintPosition courante de la tête de lecture (ms)
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

playbackStopped

Nom de l’événement : av.stop

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

Générer un événement d’arrêt de lecture.

ParamTypeDescription
cursorPositionintPosition courante de la tête de lecture (ms)
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

seek

Nom de l’événement : av.forward ou av.backward

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

Générer un événement lié au déplacement de la tête de lecture.

ParamTypeDescription
oldCursorPositionintPosition de la tête de lecture avant déplacement (ms)
newCursorPositionintPosition de la tête de lecture après déplacement (ms)
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

Evénements contextuels

La liste des événements qui suit ne rentre pas en compte dans le calcul des durées de consommation de media. Il s’agit d’événements contextuels ponctuels.

 

adClick

Nom de l’événement : av.ad.click

adClick(Map<String, Object> extraProps)

Générer un événement de mesure de clic sur une publicité.

ParamTypeDescription
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

adSkip

Nom de l’événement : av.ad.skip

adSkip(Map<String, Object> extraProps)

Générer un événement de saut d’une publicité.

ParamTypeDescription
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

close

Nom de l’événement : av.close

close(Map<String, Object> extraProps)

Mesurer une fermeture.

ParamTypeDescription
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

display

Nom de l’événement : av.display

display(Map<String, Object> extraProps)

Mesurer une impression.

ParamTypeDescription
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

error

Nom de l’événement : av.buffer.start ou av.error

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

Mesurer une erreur empêchant la lecture.

ParamTypeDescription
messageStringMessage d’erreur
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

fullscreenOff

Nom de l’événement : av.fullscreen.off

fullscreenOff(Map<String, Object> extraProps)

Mesurer une désactivation de plein écran.

ParamTypeDescription
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

fullscreenOn

Nom de l’événement : av.fullscreen.on

fullscreenOn(Map<String, Object> extraProps)

Mesurer un passage en plein écran.

ParamTypeDescription
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

quality

Nom de l’événement : av.quality

quality(Map<String, Object> extraProps)

Mesurer une action de changement de niveau de qualité.

ParamTypeDescription
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

share

Nom de l’événement : av.share

share(Map<String, Object> extraProps)

Mesurer une action de partage.

ParamTypeDescription
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

speed

Nom de l’événement : av.speed

speed(Map<String, Object> extraProps)

Mesurer une action de changement de vitesse de lecture.

ParamTypeDescription
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

subtitleOff

Nom de l’événement : av.subtitle.off

subtitleOff(Map<String, Object> extraProps)

Mesurer une désactivation de sous-titres.

ParamTypeDescription
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

subtitleOn

Nom de l’événement : av.subtitle.on

subtitleOn(Map<String, Object> extraProps)

Mesurer une activation de sous-titres.

ParamTypeDescription
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

volume

Nom de l’événement : av.volume

volume(Map<String, Object> extraProps)

Mesurer un changement de volume.

ParamTypeDescription
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

Evénements techniques

Les événements suivants sont générés de façon automatique par le Tracker. Vous pouvez toutefois appeler les méthodes de marquage publiques associées en cas de besoin de marquage ponctuel.

 

bufferHeartbeat

Nom de l’événement : av.buffer.heartbeat

bufferHeartbeat(Map<String, Object> extraProps)

Générer un événement heartbeat de mise en mémoire tampon avant le début effectif de la lecture.

ParamTypeDescription
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

heartbeat

Nom de l’événement : av.heartbeat

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

Générer un événement heartbeat.

ParamTypeDescription
cursorPositionintPosition courante de la tête de lecture (ms)
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

La position de curseur n’est pas obligatoire pour le marquage d’un événement heartbeat. En forçant la valeur du paramètre à -1, la position du curseur sera automatiquement calculée en fonction du contexte (facteur de vitesse de lecture, position de curseur de l’événement précédent).

 

rebufferHeartbeat

Nom de l’événement : av.rebuffer.heartbeat

rebufferHeartbeat(Map<String, Object> extraProps)

Générer un événement heartbeat de mise en mémoire tampon après le début effectif de la lecture.

ParamTypeDescription
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

seekBackward

Nom de l’événement : av.backward

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

Générer un événement lié à un déplacement arrière de la tête de lecture.

ParamTypeDescription
oldCursorPositionintPosition de la tête de lecture avant déplacement (ms)
newCursorPositionintPosition de la tête de lecture après déplacement (ms)
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

seekForward

Nom de l’événement : av.forward

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

Générer un évènement lié à un déplacement avant de la tête de lecture.

ParamTypeDescription
oldCursorPositionintPosition de la tête de lecture avant déplacement (ms)
newCursorPositionintPosition de la tête de lecture après déplacement (ms)
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

seekStart

Nom de l’événement : av.seek.start

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

Générer un événement de début de déplacement de la tête de lecture.

Cet événement est automatiquement levé lors d’un appel aux méthodes seek(), seekBackward() ou seekForward()

ParamTypeDescription
oldCursorPositionintPosition de la tête de lecture avant déplacement (ms)
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

Méthode de marquage universelle

 

track

La méthode de marquage universelle d’événements AV Insights permet le suivi d’événements standards ou personnalisés. Cette fonction peut être utilisée pour remplacer les appels aux autres méthodes de marquage d’événements (play, playbackStart, bufferStart, etc.).

Nom de l’événement : valeur de event

track(String event, Map<String, Object> options, Map<String, Object> extraProps)

Suivre des actions standard ou personnalisées.

ParamTypeDescription
eventStringEvénement à générer (voir liste des événements standard en bas de page)
optionsMap<String, Object>Options en fonction de l’événement courant (voir liste des options disponibles en bas de page)
extraPropsMap<String, Object>Propriétés personnalisées

Exemple

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

Marquage complet

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

 

Liste des propriétés d’un média

PropriétéTypeDescription
av_playerStringIdentifiant du lecteur
av_player_versionStringVersion du lecteur
av_player_positionStringPosition du lecteur
av_contentStringTitre du contenu
av_content_idStringIdentifiant du contenu
av_content_typeStringType de contenu (Audio/Video/Gaming…)
av_content_durationintDurée de contenu en millisecondes
av_content_versionStringVersion du contenu
av_content_genreArrayList<String>Catégorie de contenu (news/entertainment…)
av_content_linkedStringContenu lié
av_content_duration_rangeStringPlage de durée du contenu (“0-10″…)
av_broadcasting_typeStringContenu live/à la demande
av_ad_typeStringType pour une publicité (Pre-roll/Mid-Roll/Post-Roll)
av_publication_datelongDate de publication du contenu en secondes (format UTC)
av_showStringNom de l’émission
av_show_seasonStringNom de la saison
av_episode_idStringIdentifiant de l’épisode
av_episodeStringNom de l’épisode
av_channelStringChaîne
av_authorStringNom de l’auteur
av_broadcasterStringNom de l’entité de diffusion
av_auto_modebooleanMode de lecture automatique
 

Liste des événements standards

Evénements
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
 

Liste des options disponibles

OptionDescription
av_positionPosition courante de la tête de lecture (ms)
av_previous_positionPosition précédente de la tête de lecture (ms)
av_player_errorErreur empêchant une lecture

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

Dernière mise à jour : 28/05/2020