Developers » AS2 tagging » Android » Contenus de l'application » Media » AV Insights 2.16.0
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 version2.18.0
du Tracker pour surcharger la propriété standard communeav_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"); }} );
share
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 |