Comment fonctionne l'événement av.heartbeat ?

av.heartbeat permet de maintenir une session AV active entre les actions de play/stop, et permet de calculer précisément les métriques de temps passé.

Ce que fait av.heartbeat

Pendant la lecture d'un contenu, le SDK Piano déclenche des événements av.heartbeat à intervalle régulier. Chaque heartbeat :

• Indique que la session est toujours active.

• Transporte la valeur actuelle d'av_position (position du curseur dans le contenu).

• Fournit le timestamp que les calculs ultérieurs de la durée passée utilisent comme point de référence pour l'« événement précédent ».

Sans les heartbeats, AV Insights ne sait que quand les sessions commencent et se terminent ; il ne peut pas mesurer la quantité de contenu réellement consommée entre ces deux moments.

Configurer le délai du heartbeat

Le délai du heartbeat n'est pas défini par défaut — vous devez le configurer. Sans valeur explicite, les heartbeats ne se déclenchent pas et les métriques de temps passé sur les contenus longs seront sous-évaluées. Le délai minimum autorisé est de 5 secondes.

La configuration accepte deux formats : une valeur unique (délai constant pour toute la lecture) ou un objet (délais par paliers qui évoluent à mesure que la lecture progresse).

Délai constant (entier)

Transmettez un seul nombre entier (en secondes). Ce délai s'applique à l'ensemble de la lecture.

Exemple : une valeur de 10 déclenche un heartbeat toutes les 10 secondes, du début à la fin de la lecture.

Délai par paliers (objet)

Transmettez un objet dont les clés sont des minutes de lecture, chaque valeur étant le délai du heartbeat (en secondes) à partir de cette minute.

Exemple:

{ 0: 5, 1: 10, 5: 60 }

À lire comme suit :

• De la minute 0 à la minute 1 : un heartbeat toutes les 5 secondes.

• De la minute 1 à la minute 5 : un heartbeat toutes les 10 secondes.

• À partir de la minute 5 : un heartbeat toutes les 60 secondes.

Ce schéma par paliers est utile pour les contenus longs, lorsque vous souhaitez une résolution élevée au début (pour détecter les abandons précoces) et un volume d'événements plus faible une fois l'utilisateur réellement engagé.

Arrêter les heartbeats avec 0

Une valeur de 0 signifie aucun heartbeat — ni le minuteur ne se déclenche, ni l'événement n'est envoyé.

• Au format entier, 0 désactive les heartbeats pour toute la lecture. N'utilisez cette option que si vous avez décidé de ne pas avoir besoin de métriques de temps passé sur ce contenu.

• Au format objet, un 0 à n'importe quel palier arrête les heartbeats pour le reste de la lecture, à partir de cette minute. Exemple : { 0: 5, 10: 0 } un heartbeat toutes les 5 secondes pendant les 10 premières minutes, puis arrêt complet.

Compromis

Réduire le délai améliore la résolution temporelle mais augmente le volume d'événements (et le coût analytics / la charge CPU client qui l'accompagnent). Augmenter le délai réduit le volume mais rend la mesure plus grossière — les sessions qui se terminent entre deux heartbeats perdent leur temps de consommation de fin. Le format objet par paliers est la manière standard d'obtenir le meilleur des deux : une résolution fine au début, plus grossière ensuite.

Limite supérieure stricte : 2 heures

Quel que soit le délai configuré, maintenez-le bien en dessous de 2 heures. Par mesure de protection de la qualité des données, le traitement de Piano exclut tout événement AV dont l'av_duration (l'écart avec l'événement AV précédent) dépasse 2 heures. Un délai de heartbeat configuré au-delà de ce plafond — que ce soit sous forme d'entier constant ou de palier élevé au format objet — entraînera l'exclusion de l'événement suivant des rapports.

Server-side (AV Light Advanced)

En mode server-side AV Light Advanced, vous déclenchez les événements heartbeat manuellement plutôt que de configurer le SDK. La cadence recommandée est à chaque quartile de la vidéo (25 %, 50 %, 75 %, 100 %) pour les contenus longs, ou toutes les quelques secondes pour les clips courts. La même règle 0 = aucun heartbeat s'applique — si vous ne déclenchez pas de heartbeats, la session n'a aucune donnée de temps passé.

Heartbeats à J+1 : fusion et effets sur le décompte d'événements

Les heartbeats consécutifs sont fusionnés en un seul événement par la routine d'optimisation quotidienne (J+1). Deux effets concrets :

• Les métriques m_events et m_events_all excluent les heartbeats. Une visite composée uniquement d'événements heartbeat et refresh peut apparaître dans les rapports comme une visite avec 0 événement et 0 page vue — c'est normal, pas un bug.

• Les changements de propriété pendant des séquences composées uniquement de heartbeats peuvent être perdus. Si une propriété (par exemple av_language) change de valeur sur un heartbeat et qu'aucun événement non-heartbeat ne suit pour « ancrer » la nouvelle valeur, le changement est supprimé lors de la fusion des heartbeats à J+1. Pour préserver les changements de propriété en cours de lecture, déclenchez un événement non-heartbeat (par exemple av.pause ou un événement statique comme av.subtitle.on, etc.) immédiatement après le changement de propriété.

Quand le minuteur se met en pause et reprend

Le minuteur du heartbeat :

• Se met en pause lorsque l'utilisateur met le lecteur en pause (av.pause se déclenche).

• Reprend lorsque l'utilisateur reprend la lecture (av.resume se déclenche).

• Se réinitialise sur une nouvelle session lorsque l'utilisateur navigue vers une nouvelle page ou lorsqu'un nouvel av_content_id démarre.

• S'arrête lorsque le contenu atteint sa fin ou lorsque av.stop est déclenché explicitement.

Si vous constatez que les heartbeats continuent alors que le lecteur est en pause, cela signifie que le SDK n'est pas informé de la pause — généralement parce que l'événement av.pause n'est pas associé au gestionnaire de pause du lecteur.

Comportement lors d'un changement de page

Lorsque l'utilisateur navigue vers une nouvelle page alors qu'un média est en cours de lecture en arrière-plan (un lecteur audio en barre latérale, par exemple), le minuteur du heartbeat se poursuit si le SDK reste actif d'une navigation à l'autre (single-page application), et se réinitialise sur une nouvelle session si la page se recharge réellement.

Si votre site est une SPA mais que les heartbeats se réinitialisent malgré tout à la navigation, le SDK est probablement réinitialisé à chaque changement de route au lieu de persister — c'est un problème de configuration qu'il vaut la peine de corriger, en particulier pour AV Insights.

Heartbeat dans les scénarios multi-onglets / onglet en arrière-plan

Les navigateurs modernes limitent (throttling) les minuteurs JavaScript dans les onglets en arrière-plan pour économiser le CPU. Cela signifie que :

• Un heartbeat configuré sur de courts intervalles (le minimum de 5 secondes, par exemple) peut se déclencher beaucoup moins souvent dans un onglet en arrière-plan — certains navigateurs plafonnent les minuteurs à une fois par minute, voire moins.

• Le traitement historique d'AV Insights en tient compte en s'appuyant sur les positions rapportées par chaque heartbeat plutôt que sur le nombre de heartbeats déclenchés, mais des écarts très longs peuvent malgré tout sous-estimer le temps consommé.

Pour les cas d'usage d'audio en arrière-plan où un suivi précis du temps importe même lorsque l'onglet n'est pas au premier plan, envisagez de déclencher les heartbeats depuis un Web Worker, ou de vous appuyer sur des hooks d'événements natifs du lecteur qui ne sont pas soumis au throttling.

Problèmes de heartbeat courants

Last updated: June 30, 2026