AS2 tagging » Android » Contenus de l'application » Media » AV Insights

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. Le premier permet d’activer les heartbeats de suivi de lecture et le deuxième permet d’activer les heartbeats de suivi de buffering. Les valeurs fournies ne sont plus utilisées, les paliers d’évolution des heartbeat sont aujourd’hui définis par nos soins. La présence des valeurs ne fera qu’activer la fonctionnalité.

Le « heartbeat » est un intervalle de rafraîchissement qui évolue automatiquement au cours d’une lecture.

Gestion de l’identifiant de session

Un troisième paramètre facultatif sessionId est disponible depuis la version 2.18.0 du Tracker pour surcharger la propriété standard commune av_session_id présente dans chaque événement généré par les marqueurs AV Insights. Veuillez noter que ce paramètre ne doit être utilisé que dans des cas particuliers, lorsque vous devez transférer des sessions entre différents supports.
Le paramètre est généré de façon automatique par le Tracker pour tous les cas standards.

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

Une fonction getSessionID permet de récupérer la valeur du paramètre :

getSessionID() ⇒ String

Récupérer l’identifiant de session.

Exemple

String sessionID = myMedia.getSessionID(); // "custom_session_id" or "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"

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.

Param	Type	Description
propKey	`String`	Nom d’une propriété de média
propValue	`Object`	Valeur d’une propriété de média

Exemple

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

get

get(String propKey) ⇒  Object

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

Param	Type	Description
propKey	`String`	Nom d’une propriété de média

Exemple

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

del

del(String propKey)

Supprimer une propriété de média.

Param	Type	Description
propKey	`String`	Media 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.

Param	Type	Description
properties	`Map<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.

Param	Type	Description
playbackSpeed	`double`	Facteur 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.

Param	Type	Description
cursorPosition	`int`	Position courante de la tête de lecture (ms)
extraProps	`Map<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).

Param	Type	Description
cursorPosition	`int`	Position courante de la tête de lecture (ms)
extraProps	`Map<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.

Param	Type	Description
cursorPosition	`int`	Position courante de la tête de lecture (ms)
extraProps	`Map<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.

Param	Type	Description
cursorPosition	`int`	Position courante de la tête de lecture (ms)
extraProps	`Map<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).

Param	Type	Description
cursorPosition	`int`	Position courante de la tête de lecture (ms)
extraProps	`Map<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.

Param	Type	Description
cursorPosition	`int`	Position courante de la tête de lecture (ms)
extraProps	`Map<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.

Param	Type	Description
oldCursorPosition	`int`	Position de la tête de lecture avant déplacement (ms)
newCursorPosition	`int`	Position de la tête de lecture après déplacement (ms)
extraProps	`Map<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é.

Param	Type	Description
extraProps	`Map<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é.

Param	Type	Description
extraProps	`Map<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.

Param	Type	Description
extraProps	`Map<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.

Param	Type	Description
extraProps	`Map<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.

Param	Type	Description
message	`String`	Message d’erreur
extraProps	`Map<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.

Param	Type	Description
extraProps	`Map<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.

Param	Type	Description
extraProps	`Map<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é.

Param	Type	Description
extraProps	`Map<String, Object>`	Propriétés personnalisées

Exemple

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

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

share(Map<String, Object> extraProps)

Mesurer une action de partage.

Param	Type	Description
extraProps	`Map<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.

Param	Type	Description
extraProps	`Map<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.

Param	Type	Description
extraProps	`Map<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.

Param	Type	Description
extraProps	`Map<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.

Param	Type	Description
extraProps	`Map<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.

Param	Type	Description
extraProps	`Map<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.

Param	Type	Description
cursorPosition	`int`	Position courante de la tête de lecture (ms)
extraProps	`Map<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.

Param	Type	Description
extraProps	`Map<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.

Param	Type	Description
oldCursorPosition	`int`	Position de la tête de lecture avant déplacement (ms)
newCursorPosition	`int`	Position de la tête de lecture après déplacement (ms)
extraProps	`Map<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.

Param	Type	Description
oldCursorPosition	`int`	Position de la tête de lecture avant déplacement (ms)
newCursorPosition	`int`	Position de la tête de lecture après déplacement (ms)
extraProps	`Map<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()

Param	Type	Description
oldCursorPosition	`int`	Position de la tête de lecture avant déplacement (ms)
extraProps	`Map<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.

Param	Type	Description
event	`String`	Evénement à générer (voir liste des événements standard en bas de page)
options	`Map<String, Object>`	Options en fonction de l’événement courant (voir liste des options disponibles en bas de page)
extraProps	`Map<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");
    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

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

Propriété	Type	Description
av_player	String	Identifiant du lecteur
av_player_version	String	Version du lecteur
av_player_position	String	Position du lecteur
av_content	String	Titre du contenu
av_content_id	String	Identifiant du contenu
av_content_type	String	Type de contenu (Audio/Video/Gaming…)
av_content_duration	int	Durée de contenu en millisecondes
av_content_version	String	Version du contenu
av_content_genre	ArrayList<String>	Catégorie de contenu (news/entertainment…)
av_content_linked	String	Contenu lié
av_content_duration_range	String	Plage de durée du contenu (« 0-10″…)
av_broadcasting_type	String	Contenu live/à la demande
av_ad_type	String	Type pour une publicité (Pre-roll/Mid-Roll/Post-Roll)
av_publication_date	long	Date de publication du contenu en secondes (format UTC)
av_show	String	Nom de l’émission
av_show_season	String	Nom de la saison
av_episode_id	String	Identifiant de l’épisode
av_episode	String	Nom de l’épisode
av_channel	String	Chaîne
av_author	String	Nom de l’auteur
av_broadcaster	String	Nom de l’entité de diffusion
av_auto_mode	boolean	Mode de lecture automatique
av_language	String	Langue du media
av_subtitles	String	Sous-titres
av_launch_reason	String	Motif du lancement

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

Option	Description
av_position	Position courante de la tête de lecture (ms)
av_previous_position	Position précédente de la tête de lecture (ms)
av_player_error	Erreur empêchant une lecture

Dernière mise à jour : 05/06/2023

Developers » AS2 tagging » Android » Contenus de l'application » Media » AV Insights 2.16.0