Comment on gère les captures d'écran de heatmaps Matomo cassées

Si tu as déjà ouvert une heatmap Matomo et trouvé un rectangle blanc à la place de ton image hero, ou une grille produit qui s'arrête après la première ligne, ou un header sticky qui s'affiche pile sur le contenu de la page, tu n'es pas le premier. Les captures d'écran des heatmaps cassent sur la plupart des sites modernes dès le départ. La raison est structurelle — ce n'est pas quelque chose qu'on règle en ajustant sa config de tracking.

Le script de suivi de Matomo sérialise le DOM de ta page en HTML et l'envoie à ton serveur Matomo. Le serveur re-rend ensuite ce HTML dans un contexte complètement différent pour produire la capture que tu vois. Pas de cookies. Pas de session. Une origine différente. Rien du runtime que ton framework JavaScript a mis en place. Beaucoup de choses qui fonctionnaient parce qu'elles tournaient dans un vrai navigateur échouent silencieusement quand le même HTML est re-rendu à froid ailleurs.

Une fois qu'on a compris ça, la liste de bugs commence à faire sens.

Les patterns qu'on croise en boucle

La plupart des sites en cumulent au moins trois. Certains en cumulent les six.

• CORS qui bloque tes images et polices hébergées sur CDN, parce que le serveur Matomo n'a pas les credentials de ton domaine. Les images s'affichent en icônes cassées. Les polices tombent sur les valeurs système par défaut.
• Les conteneurs avec défilement (overflow: hidden ou overflow: auto avec une hauteur fixe) qui tronquent tout ce qui est en dessous de leur zone visible. Matomo sérialise le DOM dans son état courant, donc ce qui n'était pas à l'écran au moment de la capture n'est pas dans le snapshot.
• Les headers sticky et fixed qui s'effondrent sur le contenu en dessous. Leurs positions sont calculées par rapport à un viewport, et il n'y a pas de viewport côté serveur, donc ils retombent à l'endroit où ils se trouvent dans le DOM.
• Les URLs relatives comme /images/hero.jpg qui se résolvent par rapport au serveur Matomo plutôt que par rapport au tien. Le fichier n'existe pas là-bas, donc ça échoue silencieusement.
• Les polices personnalisées chargées via @font-face qui tombent sur les valeurs système par défaut quand les fichiers de polices sont protégés par CORS ou qu'ils bloquent le user-agent du serveur Matomo.
• Les single-page apps capturées avant que React ou Vue aient fini leur rendu, ce qui laisse la moitié de la page absente du snapshot.

La plupart de ces problèmes ont des corrections au niveau de l'infrastructure. Ajouter des headers CORS sur ton CDN. Passer aux URLs absolues. Utiliser un hook CSS matomoHeatmap pour neutraliser le positionnement sticky pendant la capture. La doc de Matomo en couvre plusieurs, et on a écrit un post plus complet qui détaille chaque problème et comment le corriger côté serveur si c'est la voie que tu veux prendre.

Le souci, c'est que le travail s'éparpille entre la config CDN, le CSS et ton setup de tracking, et certaines choses ne se corrigent pas du tout si tu ne contrôles pas les assets. On a buté sur ce mur sur suffisamment de sites clients pour qu'on finisse par faire autrement.

Ce qu'on a fini par construire

On a commencé avec un petit script qu'on collait dans DevTools avant chaque capture. Il embarquait les images et polices en data URIs, étendait les conteneurs avec défilement, désactivait les headers sticky, réécrivait les URLs relatives en absolues. Avec le temps, il a évolué en une extension Chrome qu'on utilisait en interne sur chaque client.

C'est ça, Matomo Heatmap Helper. On l'a mis en open source.

La configuration tient en un seul écran. Tu entres ton URL Matomo, un token API, et tu choisis sur quels sites tu veux que la barre d'outils apparaisse. Sur chaque page correspondante, une petite barre s'affiche.

Le travail se fait au moment de la capture. Quand tu appuies sur le bouton de capture, l'extension fait ce qui est long à faire de façon statique. Elle embarque les images et polices en data URIs base64 pour que le serveur Matomo n'ait jamais besoin de charger quoi que ce soit en cross-origin. Elle étend les conteneurs avec défilement à leur hauteur de contenu complète. Elle convertit les headers sticky et fixed en flux normal. Elle réécrit les URLs relatives en absolues, redimensionne les iframes, met les vidéos en pause sur la première image, et laisse le contenu des SPA le temps de se rendre. Ensuite elle appelle l'API de capture de Matomo, attend le résultat, et annule chaque modification. Ta page live redevient exactement comme elle était.

La raison pour laquelle ça marche, c'est qu'on peut interagir avec les éléments avant la capture. Des conteneurs avec défilement personnalisés, un header sticky qui se comporte mal, une section où les assets ne se chargent pas : tu cliques dessus en mode Interactif, ils reçoivent une icône de verrouillage, et le pipeline sait quoi en faire. Le script de tracking seul ne peut pas faire ça, parce qu'il capture l'état dans lequel le DOM se trouvait au moment où il a tourné. Laisser quelqu'un indiquer à l'extension quels éléments ont besoin d'être gérés, c'est ce qui résout les cas que le script n'aurait jamais pu corriger.

L'extension ne parle qu'à ton instance Matomo. Ton token API est stocké dans chrome.storage.local, qui est isolé des pages que tu visites. Pas de télémétrie, pas de tracking d'usage. Le code est sur GitHub. Les issues et pull requests sont les bienvenues.

Pourquoi on l'a mis à disposition

En tant qu'agence Partenaire Officiel Matomo, les heatmaps cassées étaient un problème qu'on rencontrait sur presque chaque mission client. Les événements étaient trackés correctement, mais les captures d'écran étaient inutilisables — et c'est justement la partie que la plupart des stakeholders regardent.

Matomo nous a beaucoup apporté en tant qu'agence. On utilise l'extension quotidiennement sur le travail client, et on continue à corriger les cas limites qu'on découvre sur les sites. Si tu tombes sur des problèmes de heatmap non résolus, ouvre une issue GitHub et on verra si on peut ajouter une correction dans l'extension.

Sur quoi on travaille

Matomo Heatmap Helper a grandi dans le cadre d'un projet plus large. Martez connecte Matomo avec Meta Ads et Google Ads, pour que le ROAS, la CLV et l'attribution multi-touch se retrouvent côté analytics web plutôt que dans un tableur séparé. C'est en bêta privée. Si ça te parle, tu peux rejoindre la liste d'attente.

Dans tous les cas, l'extension heatmap est une chose à part, et elle le reste. On l'a construite parce qu'on en avait besoin.