Dépanner Heatlens

1. Aucune page enregistrée
2. Le quota augmente, mais la carte est vide
3. Aucun instantané, ou un instantané ancien
4. La page reconstruite est incomplète
5. Points sans infobulle ou déplacés
6. Une SPA compte trop de pages ou capture trop tôt
7. PNG indisponible, réduit ou différent du JSON
8. Menu absent ou commandes refusées
9. Après mise à jour, l’ancienne interface apparaît encore
10. Pas de notification, de répétition ou de purge
11. Préparer une demande de support

Procéder dans cet ordre : vérifier la collecte Matomo, la campagne, puis les filtres du rapport. Utiliser une page synthétique et conserver les données existantes pendant le diagnostic.

Aucune page enregistrée

1. Vérifier le bon site Matomo (idSite) et la présence d’une page vue native. Si le suivi Matomo est bloqué, résoudre ce point avant Heatlens.
2. Vérifier que Heatlens est actif et que son réglage système de collecte est activé. Exécuter le diagnostic du tracker.
3. Vérifier campagne active, quota non atteint, échantillonnage à 100 % pour l’essai, appareil et ciblage pays éventuel. Tester l’URL dans le formulaire, notamment slash final, casse, paramètres et règles combinées.
4. Donner le consentement requis sur une page de test ; vérifier aussi l’opt-out Matomo. Un consentement aux cookies seul ne suffit pas.
5. Si un déclencheur personnalisé existe, il doit renvoyer exactement true de façon synchrone. Attendre le chargement de la configuration.
6. Dans l’onglet Réseau du navigateur, vérifier matomo.js, la requête index.php?module=Heatlens&action=trackingConfig et les envois au collecteur Matomo. Un bloqueur, une CSP, un proxy ou un pare-feu peut bloquer ces requêtes.

Résultat attendu : configuration Heatlens accessible, puis compteur de la campagne qui augmente après des interactions consenties. Un statut HTTP réussi sur le collecteur ne garantit pas l’écriture Heatlens : le suivi Matomo continue même si cette écriture échoue. Examiner alors les journaux Matomo/PHP côté serveur, notamment Heatlens collection failed. Ne pas désactiver globalement la CSP, le consentement ou le pare-feu pour contourner le problème.

Le quota augmente, mais la carte est vide

Choisir toute la collecte, retirer le segment, vérifier l’appareil et essayer la version d’instantané concernée. Tenir compte du fuseau horaire du site Matomo. Le quota est cumulatif ; les pages retenues dans le rapport dépendent des filtres et de la rétention.

Résultat attendu : le nombre de pages du rapport devient cohérent avec la sélection. Une purge peut laisser un quota non nul alors que les données détaillées ont expiré. Changer les filtres ou reprendre une campagne ne remet pas le quota à zéro.

Aucun instantané, ou un instantané ancien

Vérifier le mode automatique/manuelle, l’URL d’instantané et le délai. L’URL de référence ne lance pas de robot : une visite éligible doit la charger. En mode manuel, appeler Heatlens.captureSnapshot après consentement et démarrage de collecte.

Un instantané existant n’est jamais remplacé par cet appel. Créer une nouvelle version, recharger la page ou envoyer sa prochaine page vue Matomo, puis refaire la capture. La nouvelle version n’aura pas les interactions de l’ancienne ; les anciennes restent consultables. Un retour true indique une mise en file, pas une confirmation serveur. Voir le guide de capture.

La page reconstruite est incomplète

Lire les avertissements de la carte. Les CSS illisibles entre domaines, variables et constructions CSS complexes, médias protégés, iframes, vidéo ou contenu non chargé lors de la capture peuvent être absents ou remplacés par des blocs.

Attendre le rendu de la page, ajuster le délai ou utiliser la capture manuelle dans une nouvelle version. Vérifier d’abord la largeur d’origine ; une largeur personnalisée nécessite les métadonnées responsive. Heatlens conserve des styles autorisés issus des feuilles accessibles, mais le rapport ne recharge ni scripts ni feuilles externes. Une reconstruction n’est pas une capture vidéo pixel à pixel.

Points sans infobulle ou déplacés

En clics/mouvements, l’infobulle apparaît seulement sur un élément identifié avec une statistique positive pour la mesure choisie. En défilement, une profondeur sans visite reste silencieuse. Le clavier (Tab puis flèches) et le toucher permettent aussi l’inspection.

Les anciens points sans identité d’élément peuvent être dessinés à la largeur d’origine sans infobulle. Ils sont omis et signalés à une largeur personnalisée. Vérifier le compteur de couverture, la version et les changements de structure DOM. Après une refonte, créer une nouvelle version ; ne pas effacer les précédentes pour tenter de réaligner les points.

Une SPA compte trop de pages ou capture trop tôt

Vérifier une seule page vue Matomo par navigation et éviter de cumuler intégration du routeur, balise Tag Manager et appels manuels. Heatlens.trackPageView redémarre une collecte : ne pas l’ajouter systématiquement à trackPageView ni à chaque rendu de composant.

Tester navigation suivante, précédent/suivant du navigateur et chargement différé sur une campagne dédiée. Préférer délai, déclencheur ou capture manuelle lorsque seul l’état visuel doit être attendu. Voir le parcours SPA.

PNG indisponible, réduit ou différent du JSON

Un PNG nécessite un instantané ; une campagne avec des pages sans capture ne suffit pas. Vérifier les erreurs navigateur et essayer la largeur originale. Le PNG contient l’instantané reconstruit, la mesure affichée et les pointillés ; le JSON conserve les données originales du rapport filtré.

Les limites PNG sont 2000 px de largeur, 32760 px de hauteur et 16 millions de pixels. Une longue page peut donc être réduite. Les limites de médias et CSS s’appliquent aussi au PNG. Le rapport limite chaque mesure à 20000 cellules distinctes et indique sa troncature.

Menu absent ou commandes refusées

Vérifier activation, bon idSite et accès au site. Un lecteur consulte ; un utilisateur ayant les droits écriture/admin gère les campagnes. Une copie vers un autre site demande l’écriture sur ce site aussi.

Seules les dix campagnes récentes ont un raccourci dans le menu. Recharger Matomo après création, renommage ou suppression ; les autres restent dans la liste de gestion. Si le site vient d’être créé, utiliser le lien Matomo pour masquer temporairement son écran de configuration du suivi. Une session expirée ou une protection CSRF refusée exige une reconnexion/actualisation ; ne pas désactiver cette protection.

Après mise à jour, l’ancienne interface apparaît encore

Vérifier le dossier et la version réellement utilisés par PHP, les montages Docker éventuels et l’absence de répertoire imbriqué. Recharger le service PHP web pour son OPcache, régénérer matomo.js, vider le cache Matomo sous l’utilisateur web et invalider le CDN du tracker. Une purge OPcache en CLI ne purge pas PHP-FPM/Apache. Voir la procédure de mise à jour.

Pas de notification, de répétition ou de purge

Les notifications/répétitions sont traitées toutes les heures, la purge quotidiennement, lorsque le planificateur Matomo les exécute. Vérifier les passages réels du planificateur et les journaux.

Une notification exige une campagne achevée, la préférence personnelle activée, l’accès au site et un transport e-mail Matomo fonctionnel ; vérifier aussi le filtrage du courrier. Les notifications vont aux utilisateurs Matomo, jamais aux visiteurs. La répétition exige son délai configuré, une campagne achevée et active ; elle crée une nouvelle campagne. Le quota historique ne baisse pas après purge. Ne pas lancer une purge comme simple essai : elle efface les données éligibles. Voir la maintenance.

Préparer une demande de support

Fournir les éléments suivants, après anonymisation :

• Versions Heatlens, Matomo, PHP et navigateur ; Docker ou installation classique.
• Étapes de reproduction, résultat attendu/obtenu, date/heure et fuseau.
• idSite/id de campagne, état, quota, règle testée, appareil, période, segment et révision.
• Messages affichés et extraits pertinents des journaux ; codes HTTP et noms des requêtes bloquées.
• Une page de test et, si utile, une capture ne contenant que des données fictives.

Ne pas joindre de mot de passe, cookie, token_auth, export de visiteurs, fichier de configuration complet ou HAR brut. Le support peut demander un extrait nettoyé. Utiliser le portail de support ; s’il est indisponible, écrire à contact@coderise.fr. Voir la politique de support.