Enregistrement de sessions — Heatlens 1.1.0

1. Installer et vérifier
2. Créer et lire une campagne
3. Consentement et SPA
4. Démasquage sélectif
5. Conservation et exploitation
6. Limites et dépannage
7. Lecteur et navigation

Heatlens 1.1.0 réunit heatmaps et replay dans le même plugin Matomo 5. Le rendu a des limites explicites ; aucune parité exhaustive n’est annoncée. Voir la compatibilité.

Installer et vérifier

Utiliser le ZIP correspondant au cœur Matomo : édition 1.x pour Matomo 5.14.1–5.x, édition 2.x pour Matomo 6 bêta. PHP 8.1 minimum. L'instance doit utiliser le tracker HTTP natif et le plugin Heartbeat fourni avec Matomo, activé. Un handler de tracking remplacé par une file externe n'est pas pris en charge : le replay refuse de confirmer un stockage qu'il ne maîtrise pas.

Avant mise à jour, sauvegarder la base complète, la configuration et le plugin, puis vérifier la restauration sur une copie. Installer le ZIP dans plugins/Heatlens, conserver les permissions de l'utilisateur web et exécuter :

php console core:update --yes
php console custom-piwik-js:update
php console cache:clear

La migration ajoute cinq tables replay (campagnes, pages, lots, suppressions temporaires, notifications). Elle ne convertit pas les heatmaps en replays. Les enregistrements commencent après activation d'une campagne et consentement. Tester d'abord une page synthétique. Un retour à la stable s'effectue avec la sauvegarde cohérente de la base et des fichiers ; ne pas désinstaller pour revenir en arrière.

Vérifier que le proxy accepte des POST encodés de 2 Mio vers matomo.php, sans redirection, que les requêtes ne sont pas mises en cache, et que le navigateur peut charger les modules sous plugins/Heatlens/javascripts/replay/. Le tracker ne doit pas contenir de paramètres, fragment ou identifiants dans son URL. Une installation derrière proxy peut utiliser HeatlensReplay.setConfigurationUrl avec l'URL index.php de la même installation ; ses modules sont chargés depuis ce répertoire. La CSP du site doit autoriser ces scripts et les connexions au Matomo choisi. Les données ne passent pas par un CDN tiers.

Désactiver le debug du tracker et la journalisation des corps de requête sur le serveur/proxy. Le plugin évite les payloads dans ses erreurs et ses URL ; il ne contrôle pas les journaux HTTP de l'hébergeur.

Créer et lire une campagne

Dans Enregistrements de session, un administrateur du site crée une campagne : nom, description, ciblage URL/chemin/paramètre et pays, échantillonnage, quota de pages, durée minimale, activité exigée, conservation et répétition. Les droits de simple écriture ne suffisent pas à administrer les replays. Un utilisateur identifié avec accès en lecture peut consulter les pages ; l'accès anonyme reste interdit, même sur un site Matomo public.

L'échantillonnage (0,1 à 100 %, par pas de 0,1 %) est stable pour une visite Matomo dans une campagne. Le quota compte les pages effectivement admises, y compris celles supprimées ensuite. Une admission seule ne consomme pas le quota. Le seuil d'activité exige un clic et un défilement, après la durée minimale. Avant ce seuil, le journal reste uniquement en RAM et peut être abandonné. Ce seuil est évalué par le navigateur, comme les conditions de ciblage portant sur une query string.

Pause, reprise, fin définitive, copie vers un site administré et suppression sont disponibles. Modifier ou suspendre une campagne invalide immédiatement ses autorisations serveur ; la capture navigateur constate le changement au prochain contrôle (toutes les 30 secondes, avec arrêt après 45 secondes sans configuration fraîche). Sans configuration fraîche, elle s'arrête au plus tard après 45 secondes. Une campagne terminée doit être copiée pour redémarrer. La répétition crée une nouvelle campagne après le délai choisi, une seule fois par campagne achevée. Maximum : 100 campagnes conservées par site ; supprimer les campagnes inutiles pour permettre les répétitions suivantes.

Les rapports suivent période, segment natif, appareil, durée et état. La vue distingue pages enregistrées et visites. Le bouton Visite filtre ses pages, dans l’ordre chronologique. Précédent/suivant parcourt cette visite, y compris au-delà des 50 lignes chargées. L’enchaînement automatique est facultatif ; il reste dans la même visite et la même campagne. La date utilise le fuseau du site. Appareil, navigateur, résolution d’écran, pays et nombre d’événements complètent chaque ligne ; les informations natives indisponibles après purge des logs sont omises. Le journal des visites fournit aussi un lien vers les replays disponibles. Le lecteur offre pause, vitesse, recherche temporelle, saut des périodes inactives et export JSON de la page. Un trou de transmission est signalé ; la lecture reprend au prochain instantané valide.

Le bouton Partager fournit un lien vers la page enregistrée, utilisable dans une iframe selon les règles de framing/cookies de l’instance. Il exige une connexion et les droits de lecture ; aucun jeton ne figure dans le lien. La vue intégrée masque la gestion. Les liens du journal/profil visiteur sont retirés lorsque les profils natifs sont désactivés.

Au clavier : Tab parcourt les commandes, Espace active les boutons de lecture et les cases, les flèches modifient la recherche temporelle lorsqu’elle a le focus.

La case de notification de fin est indépendante de celle des heatmaps. Seuls les utilisateurs ayant encore accès au site et ayant activé cette préférence reçoivent un courriel. Les liens imposent une connexion Matomo et n'embarquent pas de jeton ni de données de visite.

Consentement et SPA

Le replay respecte le consentement natif et le refus de suivi. Avec requireConsent, setConsentGiven ou rememberConsentGiven autorise la capture après la page vue native. Si le site n'exige pas le consentement natif, le replay nécessite son propre accord explicite :

_paq.push(['HeatlensReplay.setConsentGiven']);
// Au retrait :
_paq.push(['HeatlensReplay.forgetConsentGiven']);

Le retrait natif ou spécifique coupe capture et envois, vide la RAM et annule les requêtes en vol lorsque c'est encore possible. Le marqueur de retrait natif est vérifié aussi entre onglets. Cela n'efface pas les données déjà reçues : utiliser les fonctions de suppression Matomo/Heatlens pour cela. Aucun stockage local persistant du journal n'est utilisé.

Pour une SPA, conserver l'intégration native setCustomUrl + trackPageView à chaque navigation. Heatlens ferme la page précédente et crée un nouveau journal rattaché à la visite native ; il ne crée pas une visite artificielle après expiration. Une navigation détectée ne remplace pas le suivi natif de page vue. Le retour depuis le cache de navigation démarre un nouveau journal. Le dernier beacon reste de livraison incertaine ; l'état « interrompu » est normal si la fin n'a pas pu être confirmée.

Démasquage sélectif

Par défaut, tous les champs et leurs valeurs sont masqués. Pour autoriser un champ : activer l'option de campagne, ajouter sa clé autorisée, puis marquer ce champ sur le site. Exemple avec la clé query :

<input type="search" data-heatlens-field="query" autocomplete="off">

Le marqueur seul ne suffit pas. Les masques data-heatlens-mask, data-matomo-mask, data-matomo-ignore et les zones contenteditable restent prioritaires. Types permis : texte, recherche, textarea, select, checkbox et radio. Les mots de passe, champs cachés, fichiers, coordonnées, paiement, authentification et champs reconnus sensibles par type, autocomplete, clé, attributs ou libellé sont exclus. Aucun événement de frappe brut n'est enregistré. Les états autorisés sont relevés lors des changements/instantanés ; les adresses e-mail et suites d'au moins quatre chiffres sont remplacées. Ce filtrage n'est pas un détecteur universel de données personnelles : ne marquer que des champs de recette ou des données dont l'enregistrement est réellement voulu.

Conservation et exploitation

Conservation : 1 à 365 jours, réduite si la rétention native des logs est plus courte. Les tâches habituelles Heatlens purge (quotidienne) et processLifecycle (horaire) gèrent aussi le replay. L'exploitant Matomo doit exécuter ses tâches planifiées et configurer ses e-mails ; le fournisseur du plugin n'héberge pas l'instance.

Dans une visite filtrée, « Supprimer les enregistrements de la visite » efface les pages de toutes ses campagnes replay, après confirmation. La visite native et ses heatmaps sont conservées. L’API équivalente est Heatlens.deleteReplayVisit(idSite, idVisit), en POST sécurisé avec un administrateur du site.

La suppression d'une page, d'une campagne, d'un site ou d'une visite supprime ses lots. Des marqueurs temporaires bloquent la réapparition d'un lot retardé jusqu'à expiration de son autorisation. La suppression ne reconstitue pas le quota. L'export PrivacyManager inclut le replay sous une limite mémoire explicite ; pour une visite trop volumineuse utiliser la commande heatlens:export-visit décrite dans le guide avancé. Le fichier complet contient recordings et replaySummary, en plus du format heatmap existant. Stocker les exports hors du répertoire web.

Limites et dépannage

• 10 minutes, 8 Mio, 20 000 événements et 1 000 lots maximum par page ; 5 000 nœuds et profondeur 40 par instantané.
• 1 Mio/64 lots de file RAM par campagne, cinq tentatives au maximum, expiration après deux minutes. Un dépassement arrête la capture ; il n'abandonne pas silencieusement un lot intermédiaire.
• Styles calculés limités à une liste sûre. Images, canvas, SVG, vidéos, iframes et composants shadow DOM ne sont pas reproduits fidèlement ; les éléments sensibles/actifs sont masqués ou omis. Polices distantes, pseudo-éléments et animations complètes ne sont pas rejoués. Le lecteur n'exécute jamais les scripts, formulaires ou liens d'origine.
• Aucun enregistrement rétroactif ; un journal incomplet ne permet pas de retrouver des événements perdus. Le lecteur charge une page bornée, pas une visite entière en mémoire.

Si aucune page n'apparaît, vérifier d'abord période/segment, ciblage (y compris pays fourni par Matomo), consentement, durée minimale, clic + défilement, quota, statut et échantillonnage. Puis vérifier Heartbeat, les fichiers matomo.js/modules, POST et JSON d'acquittement dans l'onglet Réseau. Un HTTP 2xx sans acquittement JSON ne prouve pas la persistance. Un refus peut provenir du blocage natif, d'une visite absente/expirée ou d'un handler incompatible.

Matomo.getAsyncTracker().HeatlensReplay.getDiagnostics()

Ce diagnostic retourne uniquement un état (waiting, buffering, recording, sampled-out, admission-failed, policy-changed, configuration-unavailable, configuration-expired ou limit), le nombre de campagnes et la taille de file. Il n'expose ni valeur de champ ni jeton. Après modification du plugin, régénérer matomo.js et purger le cache avant de comparer les résultats.

Lecteur et navigation

Le rapport regroupe les pages par visite, avec entrée, sortie et durée cumulée des pages correspondant aux filtres. Les quotas restent exprimés en pages. Ouvrir une visite permet de filtrer sa liste de pages ; la lecture ouvre un écran dédié. Le retour au rapport conserve les filtres et la pagination. Le panneau « Détails » contient les informations disponibles, les options de lecture, le partage et l’export. Sur petit écran il est replié à l’ouverture du lecteur.

Le sélecteur de page indique la position dans la visite. Il charge 50 choix au plus ; les boutons « Précédent (50) » et « Suivant (50) » donnent accès aux autres groupes. Cette navigation dans une visite inclut toutes ses pages de la campagne, même hors filtres du rapport. La timeline distingue clics, mouvements, défilement, formulaire, redimensionnement et modifications DOM. Un repère regroupe une catégorie sur une seconde ; son infobulle indique le nombre d’événements. Les flèches d’activité sont accessibles au clavier.

Dans le lecteur, hors saisie : J/L reculent/avancent de 10 s ; K ou espace lance/met en pause ; N ouvre la page suivante ; A active la lecture successive ; B active le saut des pauses ; S change la vitesse. Les raccourcis ne capturent pas la saisie des champs ni les actions natives des contrôles.

Les nouvelles captures conservent la forme des champs masqués avec un masque fixe, sans valeur, longueur de saisie ni état coché. Les captures anciennes restent lisibles avec leur représentation d’origine. Les diagnostics ajoutent starts et lastStart, sans URL ni valeur. Une configuration périmée arrête la capture : sa récupération ne crée pas automatiquement une autre page. Une nouvelle navigation, ou un redémarrage explicite après vérification du consentement, peut relancer le collecteur.

Fidélité CSS

Le replay enregistre les styles calculés : couches et variables du site sont évaluées par le navigateur source. Les survols, changements de focus, chargements de polices et mutations de feuilles dans le DOM déclenchent désormais une capture différée de 100 ms. Écritures verticales, direction, ombres et typographie complémentaire sont conservées. Les transitions très brèves peuvent être échantillonnées ; une animation continue ou insertRule() sans mutation DOM n’est pas suivie image par image. Les fontes distantes ne sont pas embarquées : un chargement détecté actualise les métriques, mais ne garantit pas la disponibilité de cette police chez le lecteur. Les protections et budgets restent applicables.

La commande « Voir les pages de cette visite » ouvre une liste explicitement titrée avec le numéro de visite et le nombre de pages ; les numéros deviennent du texte dans cette vue. « Toutes les visites » revient à la liste regroupée.

La bande des événements est l’unique commande de positionnement : cliquer ou glisser son curseur à la souris ou au toucher. Une fois focalisée avec Tab, les flèches déplacent de 1 s (Maj : 10 s), Page précédente/suivante de 10 s, Début/Fin vont aux extrémités. Les boutons d’activité permettent de rejoindre précisément le repère précédent ou suivant.

Le bouton lecture du tableau ouvre la page et démarre la lecture à zéro. Le saut des périodes inactives est désactivé par défaut. La commande du lecteur alterne lecture et pause ; après la fin, lecture redémarre à zéro. Une page de durée nulle reste consultable mais sa commande de lecture est désactivée.

Le volet « Actions », replié par défaut, donne la liste chronologique complète avec horodatage à la milliseconde, type et détails disponibles (cible, coordonnées ou dimensions). Sa hauteur est limitée et les entrées se chargent progressivement au défilement. Un clic positionne le lecteur sur l’événement et le met en pause. Les valeurs des champs ne sont pas reprises dans cette liste.