Maintenir et mettre à jour Heatlens

1. Sauvegardes et préparation
2. Mise à jour ordonnée
3. Checklist après changement
4. Retour arrière
5. Tâches, conservation et courrier
6. Désactivation et désinstallation
7. Capacité et surveillance

Ce guide s’adresse à l’exploitant de l’instance Matomo. Coderise fournit le plugin, ses guides et son support ; l’hébergement, le cron, les sauvegardes et le courrier restent gérés par l’exploitant.

Sauvegardes et préparation

Avant une modification, relever les versions, lire le changelog et vérifier le ZIP. Sauvegarder ensemble base Matomo, config/config.ini.php, dossier Heatlens et configuration de déploiement. Garder une copie hors du dossier servi par le web.

Vérifier qu’une restauration est réalisable, de préférence sur une copie isolée. Éviter les sauvegardes partielles pendant les écritures ou changements de schéma ; utiliser la procédure cohérente de votre administrateur de base. Sur une copie de production, neutraliser les envois d’e-mails vers les utilisateurs réels.

Une recette sur copie est recommandée avant un déploiement sur votre instance.

Mise à jour ordonnée

1. Vérifier la compatibilité, l’intégrité du nouveau paquet, ses notes et la sauvegarde. Conserver le ZIP de la version installée.
2. Désactiver Heatlens. Conserver l’ancien dossier hors de plugins/ et hors du répertoire web public, sans le supprimer.
3. Installer le dossier complet de la nouvelle version. Ne pas superposer des fichiers en conservant des modules obsolètes. Ne pas désinstaller comme étape de mise à jour.
4. Recharger le service PHP web qui sert Matomo (PHP-FPM ou Apache selon l’hébergement), puis réactiver, régénérer le tracker et vider le cache avec l’utilisateur web.
5. Invalider aussi les caches/CDN de matomo.js ou piwik.js. Recharger Matomo dans le navigateur.
6. Vérifier la version affichée, les campagnes et anciens enregistrements, puis exécuter la checklist ci-dessous.

Exemple Linux depuis la racine Matomo, avec l’utilisateur web www-data :

sudo -u www-data php console plugin:deactivate Heatlens

Remplacer le dossier et recharger PHP web selon votre hébergement, puis :

sudo -u www-data php console plugin:activate Heatlens
sudo -u www-data php console custom-piwik-js:update
sudo -u www-data php console cache:clear

Un opcache_reset en CLI ne purge pas l’OPcache du service web. Les ZIP reproductibles utilisent des dates fixes : se fier uniquement aux dates de fichiers peut laisser du code ancien en mémoire. Prévoir l’interruption courte liée au rechargement PHP.

Sous Docker

Mettre à jour la source persistante définie lors de l’installation : dossier hôte monté ou image avec sa stratégie de volumes. Une nouvelle image seule ne remplace pas nécessairement les fichiers d’un volume existant. Vérifier le chemin réellement lu dans le conteneur. Pour le montage d’exemple, désactiver avant de remplacer le dossier hôte, puis :

docker compose restart matomo
docker compose exec -T -u www-data matomo php console plugin:activate Heatlens
docker compose exec -T -u www-data matomo php console custom-piwik-js:update
docker compose exec -T -u www-data matomo php console cache:clear

Adapter matomo au service PHP concerné. Si l’image ou le Compose change, recréer le service avec votre procédure de déploiement au lieu d’un simple restart. Ne pas supprimer les volumes Matomo/base pour une mise à jour du plugin.

Checklist après changement

• Version et activation correctes dans Matomo, sans erreur de diagnostic.
• Suivi Matomo habituel toujours fonctionnel.
• Anciennes campagnes, compteurs et versions d’instantanés consultables avec les bons filtres.
• Sur une campagne dédiée : aucune collecte sans accord, puis une page et des points après accord ; arrêt après retrait.
• Texte privé fictif masqué ; instantané et exports JSON/PNG lisibles.
• Aucune erreur nouvelle Heatlens dans les journaux PHP/Matomo ou le navigateur.
• Planificateur opérationnel ; notifications uniquement vers une boîte de recette si elles sont testées.
• Sous Docker : version et données encore présentes après recréation du conteneur en recette.

Consigner date, versions, résultat et éventuelles anomalies. La checklist de première collecte fournit le scénario détaillé.

Retour arrière

Désactiver le plugin, restaurer l’ancien dossier depuis la sauvegarde et recharger PHP web. Restaurer la configuration précédente si elle a changé, réactiver et régénérer tracker/cache. Invalider le CDN puis refaire la checklist.

Si la nouvelle version a changé le schéma, suivre ses notes : une restauration de la base correspondante peut être nécessaire. Elle remplace aussi les données Matomo écrites depuis la sauvegarde. L’exploitant doit planifier cette perte éventuelle ; recopier des fichiers n’est pas un retour arrière universel de base.

RC1 n’introduit pas de migration de tables par rapport à l’édition commerciale déjà testée. Aucun outil de migration depuis le fork historique n’est fourni.

Tâches, conservation et courrier

Heatlens déclare purge chaque jour et processLifecycle chaque heure dans le planificateur Matomo. L’exploitant configure/surveille son exécution selon le guide Matomo d’archivage. Le rythme déclaré n’est pas une garantie d’exécution si le planificateur ne tourne pas.

Pour une intervention contrôlée après sauvegarde, les commandes Matomo suivantes exécutent les tâches Heatlens. Elles ne sont pas des diagnostics en lecture seule : purge supprime les données expirées ; processLifecycle peut envoyer des messages et créer une campagne de répétition.

sudo -u www-data php console scheduled-tasks:run 'Piwik\Plugins\Heatlens\Tasks.processLifecycle'
sudo -u www-data php console scheduled-tasks:run 'Piwik\Plugins\Heatlens\Tasks.purge'

Utiliser ces commandes ponctuellement pour une recette maîtrisée, pas comme un second cron ajouté sans vérifier celui de Matomo. Vérifier le code de sortie, les journaux et l’effet attendu sur les fixtures de test.

Conservation : 0 n’ajoute pas de durée propre à la campagne ; les suppressions des logs Matomo restent applicables. Une durée de 1 à 3650 jours ajoute une purge. Le compteur de quota est historique et ne diminue pas après effacement. Les instantanés partagés sont retirés conservativement lors de l’effacement de visites.

Les notifications exigent la préférence personnelle de l’utilisateur, ses droits et un transport e-mail Matomo opérationnel. La répétition crée une nouvelle campagne après le délai configuré lorsque la campagne achevée reste active ; elle ne remet pas à zéro l’historique de l’ancienne.

Désactivation et désinstallation

Désactiver et régénérer le tracker arrête la collecte en conservant les données. Purger également les caches de diffusion du tracker.

Dans RC1, la désinstallation Matomo retire les fichiers/réglages mais ne supprime pas automatiquement les cinq tables Heatlens. Pour effacer des campagnes, utiliser leur action de suppression pendant que le plugin est encore actif. La suppression est définitive.

Pour un retrait complet, l’administrateur de base identifie le préfixe réel et les cinq tables après sauvegarde et arrêt de collecte : heatlens_batch, heatlens_page, heatlens_snapshot, heatlens_notification, heatlens_campaign. Ne supprimer aucune table hors de cette liste et ne pas utiliser de suppression par joker. Aucun DROP TABLE automatique n’est fourni dans ce guide.

Capacité et surveillance

Commencer sur quelques pages avec échantillonnage/quota/rétention adaptés, puis mesurer l’espace occupé et les temps de collecte/rapport. La CI a enregistré 1600 pages sur 20 sites synthétiques et vérifié un quota de 10 sur 80 tentatives concurrentes ; ce n’est pas une garantie de débit en production. Les pages longues ou complexes et le nombre de campagnes influencent les besoins.

Surveiller erreurs, croissance de la base, exécution des tâches et caches du tracker. Suivre le dépannage et transmettre des éléments anonymisés si nécessaire.