Martez

Pourquoi vos captures d'ecran de heatmaps Matomo sont cassees (et comment les corriger)

Les captures d'ecran des heatmaps Matomo se cassent parce que votre page est re-rendue sur un autre serveur, sans cookies, sans polices et sans acces CORS. Voici ce qui cause chaque probleme et comment le corriger.

La capture d'ecran de Matomo se fait en deux temps, et c'est entre les deux que ca deraille.

Quand un visiteur arrive sur votre page, le JavaScript de suivi de Matomo serialise le DOM en une chaine HTML (via une bibliotheque qui s'appelle TreeMirror) et l'envoie a votre serveur Matomo. Le serveur effectue ensuite le rendu de ce HTML pour produire l'image d'arriere-plan qu'on voit dans la vue heatmap.

Le souci, c'est que votre page est re-rendue dans un contexte totalement different. Le serveur Matomo n'a pas vos cookies, pas de session, une origine differente, et il ignore tout de ce que vos frameworks JavaScript ont fait sur la page apres le chargement initial. Tout ce qui marchait parce que ca tournait dans un vrai navigateur avec les identifiants de votre domaine peut casser quand ce meme HTML est rendu a froid sur un autre serveur.

Une fois qu'on a compris ca, la plupart des bugs de captures d'ecran de heatmaps s'expliquent d'eux-memes.

A quoi ca ressemble, une capture de heatmap cassee

Voici les problemes qu'on croise le plus souvent :

  • L'image hero s'affiche bien dans le navigateur, mais apparait comme une icone cassee dans la heatmap
  • Une grille de produits avec defilement ne montre que la premiere ligne, le reste est coupe
  • La navigation sticky vient se coller par-dessus le contenu dans la capture
  • Les polices de marque sont remplacees par des polices systeme moches
  • Les ressources avec des chemins relatifs comme /assets/banner.webp ne se chargent pas du tout
  • Les pages SPA sont capturees en plein rendu, avec la moitie du contenu qui manque

Chacun de ces problemes a une cause technique precise. On les passe en revue.

CORS qui bloque vos images et polices

C'est le probleme numero un. Votre image hero, vos photos de produits ou vos images d'arriere-plan apparaissent sous forme de cadres vides ou d'icones cassees dans la capture.

Vos images se chargent sans probleme dans le navigateur, parce qu'il a vos cookies et le contexte de session. Mais quand le serveur Matomo essaie de charger https://cdn.yoursite.com/hero.jpg, le CDN voit une origine qu'il ne reconnait pas et refuse la requete. Du CORS classique.

Cote serveur, la correction est simple : ajoutez Access-Control-Allow-Origin: * aux en-tetes de reponse de votre CDN. La doc de Matomo en parle dans son guide de configuration des heatmaps.

Si vous ne controlez pas le CDN ou que vous ne voulez pas toucher a la config serveur, l'alternative est d'embarquer les ressources directement dans le DOM sous forme de data URIs en base64 avant que Matomo ne fasse sa capture. Comme ca, le HTML serialise contient chaque image en inline et le serveur n'a jamais besoin de telecharger quoi que ce soit. Ca vaut pour les attributs src, srcset, les images CSS en arriere-plan, les references SVG et les images poster des videos.

Les conteneurs avec defilement qui tronquent le contenu

Vous avez une section avec une hauteur fixe et une barre de defilement. Dans la capture de la heatmap, seule la partie visible est rendue. Tout ce qui se trouve en dessous disparait.

Les elements avec overflow: hidden ou overflow: auto tronquent le contenu a leur hauteur de rendu. Matomo serialise le DOM dans son etat visuel courant, donc le HTML capture reflete clientHeight, pas le scrollHeight complet.

Pour corriger ca, evitez les hauteurs fixes sur les conteneurs de contenu. Preferez min-height a height, et n'appliquez pas overflow: hidden sur les elements qui contiennent du contenu scrollable.

En-tetes sticky et fixes qui se superposent a la page

Votre navigation sticky marche parfaitement dans le navigateur, mais dans la capture elle se place au-dessus du contenu et recouvre ce qu'il y a dessous.

Les elements en position: fixed et position: sticky sont positionnes par rapport au viewport. Cote serveur, il n'y a pas de viewport, alors ils retombent sur le contenu en dessous.

Matomo ajoute une classe matomoHeatmap a l'element <html> pendant le rendu cote serveur des captures d'ecran. On peut s'en servir pour ecrire des regles CSS qui ne s'appliquent que pendant la capture :

css
html.matomoHeatmap .your-sticky-header {
  position: relative;
  top: auto;
}

Ca fait passer votre en-tete sticky en flux normal dans la capture, sans changer l'apparence de la page pour les vrais utilisateurs. La doc de Matomo couvre le sujet dans sa FAQ sur la correction des en-tetes qui se superposent dans les heatmaps et l'application de feuilles de style personnalisees pendant la capture.

Si vous preferez ne pas maintenir ces regles CSS en plus, l'idee generale est de detecter les elements header et nav qui ont un positionnement fixed ou sticky, de les passer en position: relative, de remettre a zero leurs valeurs top/bottom/left/right, et pour les elements fixes d'inserer un div de remplacement pour eviter les decalages de mise en page. Apres la capture, on remet tout comme avant.

Les URLs relatives qui ne marchent plus

Des images et des feuilles de style se chargent bien sur votre site mais manquent dans la capture Matomo, alors qu'elles ne sont meme pas cross-origin. Ca parait bizarre jusqu'a ce qu'on comprenne le mecanisme.

Votre page utilise des URLs relatives comme /images/banner.jpg. Dans le navigateur, ca se resout par rapport a votre domaine. Dans le contexte de rendu de Matomo, /images/banner.jpg se resout par rapport au serveur Matomo. Le fichier n'existe pas la-bas.

Pour corriger, utilisez des URLs absolues partout, ou ajoutez une balise <base href="https://yoursite.com/"> dans votre <head>. Si aucune de ces solutions ne convient, un script de pre-capture peut parcourir le document a la recherche d'URLs relatives dans les attributs src, href, srcset et les proprietes CSS background-image, puis les reecrire en URLs absolues a partir de l'origine courante de la page.

Les polices personnalisees qui s'affichent en polices systeme

Vos polices de marque ont disparu. La capture affiche la police systeme par defaut du serveur, et c'est rarement joli.

Les regles @font-face referencent des fichiers de polices heberges sur des CDN ou sur votre serveur. Quand le serveur Matomo essaie de charger ces fichiers, il se fait bloquer par CORS ou le CDN exige un user agent de navigateur. Le serveur se rabat sur une police par defaut.

La solution : hebergez les polices sur un serveur avec des en-tetes CORS permissifs. Google Fonts fait deja ca, mais beaucoup de polices auto-hebergees ne le font pas. Si la modification des en-tetes n'est pas possible, vous pouvez embarquer les polices directement dans la page en recuperant les fichiers, en les convertissant en data URIs base64, puis en injectant des regles @font-face avec ces data URIs dans des balises <style> du <head>. Le HTML serialise embarque alors ses propres definitions de polices et s'affiche correctement peu importe le serveur qui le sert.

Iframes, videos et SPA

Quelques cas limites supplementaires qui valent le coup d'etre mentionnes.

Les iframes ont souvent des dimensions CSS fixes qui ne correspondent pas a leur contenu reel. Pour les iframes same-origin, on peut lire la hauteur reelle du contenu via contentDocument.body.scrollHeight et redimensionner en consequence. Pour les iframes cross-origin, il faut prevoir une hauteur de secours genereuse.

Les videos en lecture automatique sont capturees en cours de lecture, ce qui donne une image aleatoire. Mettez-les en pause et rembobinez a l'image 0 avant la capture pour que la capture d'ecran montre la premiere image.

Les applications monopage (SPA) sont les plus penibles. Les applis React, Vue ou Angular chargent le contenu dynamiquement, et Matomo peut capturer le DOM avant que votre framework ait fini son rendu. L'URL peut aussi ne pas correspondre a ce que votre routeur affiche. Il n'y a pas de recette miracle. Le mieux est de configurer les regles de correspondance d'URL de Matomo pour vos routes SPA et d'utiliser l'API JavaScript de Matomo pour declencher l'enregistrement une fois le rendu termine.

Tout corriger d'un coup avec Matomo Heatmap Helper

La plupart des sites reels cumulent plusieurs de ces problemes. Les corriger tous a la main implique de modifier les configurations CDN, de reecrire les URLs, de refactoriser le CSS et d'ecrire des scripts de capture sur mesure.

Matomo Heatmap Helper est une extension gratuite et open source pour Chrome et Firefox qui gere tout ca. Code source sur GitHub.

En pratique, ca se passe comme ca. Vous installez l'extension, vous entrez votre URL Matomo et votre token API, et vous choisissez les sites a activer. Sur les pages correspondantes, une barre d'outils apparait. Cliquez sur "Interactive" puis sur les elements a corriger : conteneurs avec defilement, en-tetes sticky, sections ou il manque des images. Ils recoivent une icone de verrouillage pour montrer qu'ils seront traites.

Quand vous appuyez sur le bouton de capture, l'extension deroule sa sequence. Elle commence par recuperer et embarquer les images et polices cross-origin, puis etend les elements contraints et desactive les en-tetes sticky, gere les iframes et les videos, convertit les URLs relatives en absolues, et declenche l'API de capture de Matomo. Apres la capture, chaque modification est annulee. Votre page retrouve son etat initial.

Avant de prendre une capture d'ecran

Une check-list rapide :

  1. Verifiez que la page a fini de se charger, surtout le contenu SPA et les sections en lazy loading
  2. Verrouillez les conteneurs qui tronquent le contenu ou qui ont besoin d'etre etendus
  3. Regardez s'il y a des en-tetes sticky ou fixes qui risquent de se superposer au contenu
  4. Verifiez que vos images et polices principales s'affichent bien
  5. Prenez la capture et confirmez que la verification passe
  6. Ouvrez la vue heatmap et verifiez le resultat avant de lancer l'analyse

Deux approches possibles

Ces problemes de captures d'ecran ne sont pas des bugs de votre site. Ce sont des effets de bord lies a la facon dont Matomo serialise votre page et la re-rend ailleurs. Tout site qui utilise des CDN, des polices web, des conteneurs avec defilement ou des en-tetes sticky va tomber sur une combinaison de ces problemes.

Vous pouvez corriger chaque probleme au niveau de l'infrastructure : ajouter des en-tetes CORS, passer aux URLs absolues, refactoriser les conteneurs avec overflow, basculer le positionnement sticky pendant la capture. C'est la bonne approche sur le long terme si vous controlez le serveur, mais ca prend du temps et certains problemes n'ont pas de solution propre cote serveur.

Ou alors vous pouvez les corriger au moment de la capture avec Matomo Heatmap Helper. Utilisez le mode interactif pour indiquer quelles parties de votre page ont besoin d'aide, et obtenez des captures d'ecran propres sans toucher au code en production.