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.

ParamTypeDescription
keyStringNom d’une propriété de média
valueAnyValeur 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.

ParamTypeDescription
keyStringNom 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.

ParamTypeDescription
keyStringNom 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.

ParamTypeDescription
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.

ParamTypeDescription
playbackSpeedDoubleFacteur 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.

ParamTypeDescription
cursorPositionIntPosition 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).

ParamTypeDescription
cursorPositionIntPosition 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.

ParamTypeDescription
cursorPositionIntPosition 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.

ParamTypeDescription
cursorPositionIntPosition 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).

ParamTypeDescription
cursorPositionIntPosition 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.

ParamTypeDescription
cursorPositionIntPosition 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.

ParamTypeDescription
oldCursorPositionIntPosition de la tête de lecture avant déplacement (ms)
newCursorPositionIntPosition 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é.

ParamTypeDescription
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é.

ParamTypeDescription
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.

ParamTypeDescription
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.

ParamTypeDescription
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.

ParamTypeDescription
messageStringMessage d’erreur
extraPropsMapProprié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.

ParamTypeDescription
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.

ParamTypeDescription
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é.

ParamTypeDescription
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.

ParamTypeDescription
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.

ParamTypeDescription
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.

ParamTypeDescription
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.

ParamTypeDescription
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.

ParamTypeDescription
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.

ParamTypeDescription
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.

ParamTypeDescription
cursorPositionIntPosition 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.

ParamTypeDescription
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.

ParamTypeDescription
oldCursorPositionIntPosition de la tête de lecture avant déplacement (ms)
newCursorPositionIntPosition 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.

ParamTypeDescription
oldCursorPositionIntPosition de la tête de lecture avant déplacement (ms)
newCursorPositionIntPosition 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()

ParamTypeDescription
oldCursorPositionIntPosition 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.

ParamTypeDescription
eventStringEvé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é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_genre[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_modeBoolMode de lecture automatique
av_languageStringLangue du media
av_subtitlesStringSous-titres
av_launch_reasonStringMotif 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

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
Dernière mise à jour : 06/01/2021