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

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 version 2.19.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.

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"]
)

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

Dernière mise à jour : 06/01/2021

Developers » AS2 tagging » Apple » Contenus de l'application » Media » AV Insights 2.17.0