Évaluer les heatmaps

Une heatmap répond à la question « où les utilisateurs interagissent-ils avec cette page ? » — clics, rage clicks, mouvements de souris, et jusqu'où ils font défiler. Les données sont purement géométriques : pointer_relative_x (0..1 dans la fenêtre d'affichage), pointer_y (pixels absolus vers le bas de la page), et un compte par point. Elle ne sait pas ce qui a été cliqué. Transformer « beaucoup de clics à (0,5, 220) » en « beaucoup de clics sur le lien de navigation Tarifs » est tout l'enjeu, et cela vient du croisement avec l'autocapture sur la même URL.

Principe fondamental : coordonnées + sens

Vous ne pouvez pas voir la page — il n'y a pas de capture d'écran dans votre contexte. Une bonne évaluation fusionne deux sources et s'appuie sur l'autocapture pour fournir la mise en page/l'identité que vous ne pouvez pas voir :

1. Données de heatmap — où les interactions se produisent et jusqu'où les utilisateurs font défiler (heatmaps-list).
2. Autocapture — quel élément se trouve sous les zones chaudes, selon le texte/sélecteur de l'élément sur la même page. C'est ce qui transforme les coordonnées en sens ; sans cela, vous n'avez que des points.

Quand l'utilisateur veut voir la heatmap, créez une heatmap sauvegardée (Étape 4) — qui rend la page avec les données superposées pour qu'il puisse les ouvrir dans PostHog. Vous raisonnez à partir des données ; lui regarde l'image.

Le flux

Étape 1 : Épingler la page et la fenêtre

Vous avez besoin d'un exact url_exact (une seule page) ou d'un url_pattern (regex, pour agréger sur les chaînes de requête). Confirmez l'URL auprès de l'utilisateur si elle est ambiguë. Par défaut, les 7 derniers jours ; élargissez à 30 si le volume est faible. Les données de heatmap sont conservées pendant 90 jours.

Étape 2 : Récupérer les données

Appelez heatmaps-list une fois par signal qui vous intéresse (ou interrogez la table heatmaps directement via SQL — voir la compétence querying-posthog-data, models-heatmaps) :

• type: "click" — la carte principale « ce qui attire l'attention ».
• type: "rageclick" — clics répétés frustrés. **Le signal unique le plus fort « quelque chose est cassé ou trompeur ». Tout cluster de rageclick significatif mérite une callout.
• type: "scrolldepth" — jusqu'où les utilisateurs vont. Utilisez-le pour trouver la limite et repérer les CTA qui se situent sous l'endroit où la plupart des utilisateurs arrêtent le défilement.

Utilisez aggregation: "unique_visitors" quand vous voulez savoir combien de personnes (et non combien de clics) ; total_count exagère le poids des cliqueurs intensifs.

Étape 2b : Au-dessus de la limite — lisez le résumé fold

Pour les types de clics, heatmaps-list retourne un objet fold en plus de results :

• pct_below_fold — part des interactions non-fixed qui ont atterri sous la fenêtre d'affichage initiale de l'utilisateur (ils ont dû faire défiler pour les atteindre). C'est l'une des découvertes ayant la plus haute valeur : le contenu que les utilisateurs cliquent activement et qui se situe sous la limite est un excellent candidat pour le remonter.
• below_fold_count / total_count — les comptes bruts derrière le pourcentage (les éléments en position fixe sont exclus, puisqu'ils sont toujours à l'écran).
• median_viewport_height — la ligne de limite typique en pixels CSS, à recommander d'éviter.

Rapportez-le concrètement, par exemple « la limite est ~600px pour la plupart des visiteurs, pourtant 35 % des clics se produisent sous elle, donc les utilisateurs font défiler avant d'interagir — ce contenu est un candidat pour le premier écran. » Segmentez par appareil avec viewport_width_min/viewport_width_max (le bureau et le mobile ont des limites très différentes) et lisez fold par bande plutôt que de les fusionner.

Vous avez besoin d'une distribution plutôt qu'un seul pourcentage (par exemple, les clics regroupés par la distance sous la limite) ? Passez à SQL sur la table brute heatmaps, qui a y et viewport_height dans les mêmes unités d'échelle — voir la compétence querying-posthog-data, models-heatmaps.

Étape 3 : Nommer les éléments chauds (chevauchement autocapture)

Pour chaque cluster notable, trouvez ce qui est réellement là. Interrogez l'autocapture sur la même URL — soit via la compétence exploring-autocapture-events, soit directement :

SELECT properties.$el_text AS text, count() AS clicks
FROM events
WHERE event = '$autocapture'
  AND properties.$current_url = 'https://example.com/pricing'
  AND timestamp >= now() - INTERVAL 7 DAY
GROUP BY text
ORDER BY clicks DESC
LIMIT 25

elements_chain donne le sélecteur/chemin DOM quand vous avez besoin de désambiguïser deux éléments avec le même texte. Associez les éléments principaux de l'autocapture aux coordonnées chaudes de la heatmap : les clics concentrés sur quelque chose qui n'est pas un lien ou un bouton (texte brut, une image, un contrôle désactivé) est une découverte classique « les utilisateurs s'attendent à ce que ce soit cliquable ».

Étape 4 : Donner à l'utilisateur une heatmap à regarder (optionnel)

Vous ne pouvez pas voir la page, mais l'utilisateur le peut. Quand un visuel l'aiderait à suivre vos découvertes, créez une heatmap sauvegardée pour qu'il puisse ouvrir la page rendue avec les données superposées dans PostHog :

1. heatmaps-saved-create avec l'url de la page (le type par défaut est screenshot). Cela enfile un rendu headless — c'est asynchrone. Passez widths correspondant à la bande de fenêtre d'affichage que vous avez analysée à l'Étape 2.
2. Interrogez heatmaps-saved-get (par le short_id retourné) jusqu'à ce que le status soit completed, puis informez l'utilisateur qu'il est prêt à être consulté dans PostHog.

C'est pour le bénéfice du humain — votre propre raisonnement provient toujours des données de l'Étape 2 et de l'identité autocapture de l'Étape 3, pas de l'image.

Étape 5 : Approfondir les hotspots (quand vous avez besoin du « pourquoi »)

Pour un cluster surprenant, heatmaps-events retourne les sessions individuelles derrière des points spécifiques. Remettez les ID de session à la compétence investigating-replay pour regarder ce que les gens ont réellement fait.

Étape 6 : Résumer et recommander

Produisez un rapport court et concret :

• Ce que montre la heatmap — éléments les plus engagés, zones mortes, portée du défilement, et la répartition des clics au-dessus/sous la limite (par exemple « la fenêtre d'affichage est ~600px pour la plupart des visiteurs, pourtant 35 % des clics se produisent sous elle »).
• Problèmes, classés par force du signal — clusters de rage clicks d'abord, puis clics sur des éléments non-interactifs, puis CTA importants assis sous la falaise de défilement, puis actions principales ignorées.
• Recommandations liées à la preuve — déplacer/remonter un CTA au-dessus de la limite, faire d'un élément cliqué-mais-mort un vrai lien, couper les éléments concurrents près d'un cluster de rage clicks, etc. Chaque recommandation doit citer le signal dont elle provient.

Lire les signaux

Pièges

• Les heatmaps doivent être activées (Team.heatmaps_opt_in). Si heatmaps-list ne retourne rien pour une page qui clairement reçoit du trafic, la capture peut être désactivée ou l'URL est incorrecte — vérifiez les deux avant de conclure « pas d'engagement ».
• Les coordonnées sont mises à l'échelle d'un facteur de 16 en stockage ; l'API retourne déjà les pixels CSS pointer_y et x relatifs, donc utilisez directement les valeurs API/outil plutôt que les colonnes de table brutes.
• Vous ne pouvez pas voir la capture d'écran. Le rendu de la heatmap sauvegardée est pour que l'utilisateur l'ouvre dans PostHog ; ne prétendez pas avoir regardé la page. Fondez chaque affirmation de mise en page sur l'identité autocapture + coordonnées, pas sur la vision.
• Le rendu de la heatmap sauvegardée est asynchrone. Après heatmaps-saved-create, interrogez heatmaps-saved-get jusqu'à ce que le status soit completed avant d'informer l'utilisateur que c'est consultable. Seules les heatmaps de type screenshot rendent une image ; les types iframe et recording ne le font pas.
• Attention à la fenêtre d'affichage. Une carte de clics de bureau et une de mobile sont un comportement très différent — filtrez avec viewport_width_min/viewport_width_max plutôt que de les fusionner.