Developers » AS2 tagging » Apple » Contenus de l'application » Media » AV Insights 2.17.0
AV Insights
- iOS
- watchOS
- tvOS
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 AVMedia
:
let tracker = ATInternet.sharedInstance.defaultTracker /// Property /// let myMedia = tracker.avInsights.media let myMedia = tracker.avInsights.Media(heartbeat: 5, bufferHeartbeat: 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.19.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.
let tracker = ATInternet.sharedInstance.defaultTracker let myMedia = tracker.avInsights.Media(heartbeat: 5, bufferHeartbeat: 5, sessionId: "custom_session_id")
Une propriété sessionId
permet de récupérer la valeur du paramètre :
sessionId ⇒ String
Récupérer l’identifiant de session.
Exemple
let sessionID = myMedia.sessionId; // "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(key: String, value: Any)
Déclarer une propriété de média.
Param | Type | Description |
key | String | Nom d’une propriété de média |
value | Any | Valeur d’une propriété de média |
Exemple
_ = myMedia.set(key: "av_content", value: "my_video") _ = myMedia.set(key: "av_content_id", value: 12345)
get
get(key: String) ⇒ Any?
Récupérer une propriété de média.
Param | Type | Description |
key | String | Nom d’une propriété de média |
Exemple
let contentId = myMedia.get(key: "av_content_id") // 12345
del
del(key: String)
Supprimer une propriété de média.
Param | Type | Description |
key | String | Nom d’une propriété de média |
Exemple
myMedia.del(key: "av_content_id")
setProps
setProps(obj: [String: Any])
Déclarer un ensemble de propriétés pour un média.
Param | Type | Description |
obj | [String: Any] | Propriétés d’un média |
Exemple
myMedia.setProps(obj: [ "av_content": "My Content", "av_content_id": "fg456" ])
getProps
getProps() ⇒ [String: Any]
Récupérer l’ensemble des propriétés d’un média.
Exemple
let 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(playbackSpeed: Double)
Déclarer un changement de vitesse de lecture.
Param | Type | Description |
playbackSpeed | Double | Facteur de vitesse de lecture |
Exemple
myMedia.setPlaybackSpeed(playbackSpeed: 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(cursorPosition: Int, extraProps: [String: Any]?)
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 | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.bufferStart( cursorPosition: 0, extraProps: ["customProp": "customValue"] )
play
Nom de l’événement : av.play
play(cursorPosition: Int, extraProps: [String: Any]?)
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 | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.play( cursorPosition: 0, extraProps: ["customProp": "customValue"] )
playbackPaused
Nom de l’événement : av.pause
playbackPaused(cursorPosition: Int, extraProps: [String: Any]?)
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 | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.playbackPaused( cursorPosition: 1000, extraProps: ["customProp": "customValue"] )
playbackResumed
Nom de l’événement : av.resume
playbackResumed(cursorPosition: Int, extraProps: [String: Any]?)
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 | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.playbackResumed( cursorPosition: 1000, extraProps: ["customProp": "customValue"] )
playbackStart
Nom de l’événement : av.start
playbackStart(cursorPosition: Int, extraProps: [String: Any]?)
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 | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.playbackStart( cursorPosition: 0, extraProps: ["customProp": "customValue"] )
playbackStopped
Nom de l’événement : av.stop
playbackStopped(cursorPosition: Int, extraProps: [String: Any]?)
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 | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.playbackStopped( cursorPosition: 1000, extraProps: ["customProp": "customValue"] )
seek
Nom de l’événement : av.forward
ou av.backward
seek(oldCursorPosition: Int, newCursorPosition: Int, extraProps: [String: Any]?)
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 | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.seek( oldCursorPosition: 1000, newCursorPosition: 2000, extraProps: ["customProp": "customValue"] ) myMedia.seek( oldCursorPosition: 2000, newCursorPosition: 1000, extraProps: ["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(extraProps: [String: Any]?)
Générer un événement de mesure de clic sur une publicité.
Param | Type | Description |
extraProps | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.adClick( extraProps: ["customProp": "customValue"] )
adSkip
Nom de l’événement : av.ad.skip
adSkip(extraProps: [String: Any]?)
Générer un événement de saut d’une publicité.
Param | Type | Description |
extraProps | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.adSkip( extraProps: ["customProp": "customValue"] )
close
Nom de l’événement : av.close
close(extraProps: [String: Any]?)
Mesurer une fermeture.
Param | Type | Description |
extraProps | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.close( extraProps: ["customProp": "customValue"] )
display
Nom de l’événement : av.display
display(extraProps: [String: Any]?)
Mesurer une impression.
Param | Type | Description |
extraProps | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.display( extraProps: ["customProp": "customValue"] )
error
Nom de l’événement : av.buffer.start
ou av.error
error(message: String, extraProps: [String: Any]?)
Mesurer une erreur empêchant la lecture.
Param | Type | Description |
message | String | Message d’erreur |
extraProps | Map | Propriétés personnalisées |
Exemple
myMedia.error( message: "Error loading video", extraProps: ["customProp": "customValue"] )
fullscreenOff
Nom de l’événement : av.fullscreen.off
fullscreenOff(extraProps: [String: Any]?)
Mesurer une désactivation de plein écran.
Param | Type | Description |
extraProps | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.fullscreenOff( extraProps: ["customProp": "customValue"] )
fullscreenOn
Nom de l’événement : av.fullscreen.on
fullscreenOn(extraProps: [String: Any]?)
Mesurer un passage en plein écran.
Param | Type | Description |
extraProps | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.fullscreenOn( extraProps: ["customProp": "customValue"] )
quality
Nom de l’événement : av.quality
quality(extraProps: [String: Any]?)
Mesurer une action de changement de niveau de qualité.
Param | Type | Description |
extraProps | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.quality( extraProps: ["customProp": "customValue"] )
share
Nom de l’événement : av.share
share(extraProps: [String: Any]?)
Mesurer une action de partage.
Param | Type | Description |
extraProps | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.share( extraProps: ["customProp": "customValue"] )
speed
Nom de l’événement : av.speed
speed(extraProps: [String: Any]?)
Mesurer une action de changement de vitesse de lecture.
Param | Type | Description |
extraProps | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.speed( extraProps: ["customProp": "customValue"] )
subtitleOff
Nom de l’événement : av.subtitle.off
subtitleOff(extraProps: [String: Any]?)
Mesurer une désactivation de sous-titres.
Param | Type | Description |
extraProps | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.subtitleOff( extraProps: ["customProp": "customValue"] )
subtitleOn
Nom de l’événement : av.subtitle.on
subtitleOn(extraProps: [String: Any]?)
Mesurer une activation de sous-titres.
Param | Type | Description |
extraProps | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.subtitleOn( extraProps: ["customProp": "customValue"] )
volume
Nom de l’événement : av.volume
volume(extraProps: [String: Any]?)
Mesurer un changement de volume.
Param | Type | Description |
extraProps | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.volume( extraProps: ["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(extraProps: [String: Any]?)
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 | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.bufferHeartbeat( extraProps: ["customProp": "customValue"] )
heartbeat
Nom de l’événement : av.heartbeat
heartbeat(cursorPosition: Int, extraProps: [String: Any]?)
Générer un événement heartbeat.
Param | Type | Description |
cursorPosition | Int | Position courante de la tête de lecture (ms) |
extraProps | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.heartbeat( cursorPosition: 45, extraProps: ["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(extraProps: [String: Any]?)
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 | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.rebufferHeartbeat( extraProps: ["customProp": "customValue"] )
seekBackward
Nom de l’événement : av.backward
seekBackward(oldCursorPosition: Int, newCursorPosition: Int, extraProps: [String: Any]?)
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 | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.seekBackward( oldCursorPosition: 2000, newCursorPosition: 1000, extraProps: ["customProp": "customValue"] )
seekForward
Nom de l’évènement : av.forward
seekForward(oldCursorPosition: Int, newCursorPosition: Int, extraProps: [String: Any]?)
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 | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.seekForward( oldCursorPosition: 1000, newCursorPosition: 2000, extraProps: ["customProp": "customValue"] )
seekStart
Nom de l’évènement : av.seek.start
seekStart(oldCursorPosition: Int, extraProps: [String: Any]?)
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 | [String: Any]? | Propriétés personnalisées |
Exemple
myMedia.seekStart( oldCursorPosition: 1000, extraProps: ["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(event: String, options: [String: Any]?, extraProps: [String: Any]?)
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 | [String: Any]? | Options en fonction de l’événement courant (voir liste des options disponibles en bas de page) |
extraProps | [String: Any]? | Propriétés personnalisées |
Exemple
let tracker = ATInternet.sharedInstance.defaultTracker let myMedia = tracker.avInsights.Media(heartbeat: 5, bufferHeartbeat: 5) // Buffer tagging myMedia.track(event: "av.buffer.start", options: ["av_position": 0], extraProps: nil) // Re-buffer tagging myMedia.track(event: "av.rebuffer.start", options: ["av_position": 0], extraProps: nil) // Play tagging myMedia.track(event: "av.play", options: ["av_position": 0], extraProps: nil) // Playback start tagging myMedia.track(event: "av.start", options: ["av_position": 0], extraProps: nil) // Playback pause tagging myMedia.track(event: "av.pause", options: ["av_position": 10], extraProps: nil) // Playback resume tagging myMedia.track(event: "av.resume", options: ["av_position": 10], extraProps: nil) // Playback stop tagging myMedia.track(event: "av.stop", options: ["av_position": 20], extraProps: nil) // Seek forward tagging myMedia.track(event: "av.forward", options: ["av_previous_position": 10, "av_position": 20], extraProps: nil) // Seek backward tagging myMedia.track(event: "av.backward", options: ["av_previous_position": 20, "av_position": 10], extraProps: nil) // Ad click tagging myMedia.track(event: "av.ad.click", options: nil, extraProps: nil) // Ad skip tagging myMedia.track(event: "av.ad.skip", options: nil, extraProps: nil) // Error tagging myMedia.track(event: "av.error", options: ["av_player_error": "Player error"], extraProps: nil) // Display tagging myMedia.track(event: "av.display", options: nil, extraProps: nil) // Close tagging myMedia.track(event: "av.close", options: nil, extraProps: nil) // Volume tagging myMedia.track(event: "av.volume", options: nil, extraProps: nil) // Subtitle on tagging myMedia.track(event: "av.subtitle.on", options: nil, extraProps: nil) // Subtitle off tagging myMedia.track(event: "av.subtitle.off", options: nil, extraProps: nil) // Full screen on tagging myMedia.track(event: "av.fullscreen.on", options: nil, extraProps: nil) // Full screen off tagging myMedia.track(event: "av.fullscreen.off", options: nil, extraProps: nil) // Quality tagging myMedia.track(event: "av.quality", options: nil, extraProps: nil) // Speed tagging myMedia.track(event: "av.speed", options: nil, extraProps: nil) // Share tagging myMedia.track(event: "av.share", options: nil, extraProps: nil) // Custom tagging myMedia.track(event: "custom", options: nil, extraProps: ["customParam": "customValue"])
Marquage complet
let tracker = ATInternet.sharedInstance.defaultTracker let myMedia = tracker.avInsights.Media(heartbeat: 5, bufferHeartbeat: 5) // Set heartbeats value (5 seconds) let properties: [String: Any] = [ "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(obj: properties) // Play attempt (cursor position 0 second) myMedia.play(cursorPosition: 0, extraProps: nil) // Buffering before playback start (cursor position 0 second) myMedia.bufferStart(cursorPosition: 0, extraProps: nil) // Playback start (cursor position 0 second) myMedia.playbackStart(cursorPosition: 0, extraProps: nil) // Buffering after 5 seconds of playback myMedia.bufferStart(cursorPosition: 5000, extraProps: nil) // Seek action (backward from cursor position 5 seconds to cursor position 3 seconds) myMedia.seek(oldCursorPosition: 5000, newCursorPosition: 3000, extraProps: nil) // Playback resume (cursor position 3 seconds) myMedia.playbackResumed(cursorPosition: 3000, extraProps: nil) // Playback pause (cursor position 9 seconds) myMedia.playbackPaused(cursorPosition: 9000, extraProps: nil) // Playback resume (cursor position 9 seconds) myMedia.playbackResumed(cursorPosition: 9000, extraProps: nil) // Playback stop (cursor position 15 seconds) myMedia.playbackStopped(cursorPosition: 15000, extraProps: nil)
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 | [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 | Bool | 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 |