ben-to/docs/matomo-analytics.md

Matomo et consentement cookies

Activation Matomo

Le chargement de matomo.js et toute mesure d’audience ne sont possibles que si les deux variables Vite suivantes sont définies au build :

Variable	Exemple	Rôle
VITE_MATOMO_URL	https://analytics.example.com/	URL du répertoire hébergeant matomo.js (slash final recommandé ; il est ajouté sinon).
VITE_MATOMO_SITE_ID	1	Identifiant du site dans Matomo.

Sans ces variables, aucune mesure Matomo n’est initialisée (même après acceptation du bandeau).

Le bandeau cookies s’affiche toutefois dès qu’aucun choix n’est stocké dans localStorage, afin de recueillir le consentement avant toute activation possible du tracker.

Copier apps/web/.env.example vers apps/web/.env.local pour les essais locaux avec Matomo réel.

Image Docker / CapRover

Les mêmes variables doivent être disponibles pendant npm run build:web. Le Dockerfile expose des ARG (valeurs vides par défaut) puis les recopie en ENV avant le build, sur le même principe que PUBLIC_* sur un autre projet.

Exemple en local :

docker build \
  --build-arg VITE_MATOMO_URL=https://analytics.example.com/ \
  --build-arg VITE_MATOMO_SITE_ID=1 \
  -t ben-to-web .

Sur CapRover, configurer les build arguments équivalents pour l’image (pas seulement les variables d’environnement runtime du conteneur).

Comportement

1. Premier chargement : si aucun choix n’est enregistré dans localStorage (clé ben-to-cookie-consent-v1), le bandeau s’affiche.
2. Accepter : enregistrement du consentement ; si Matomo est configuré, chargement asynchrone de matomo.js, puis suivi des pages vues (SPA incluse) et des événements (trackEvent dans apps/web/src/infra/analytics.ts).
3. Refuser : pas de chargement du script ; pas de cookies / hits Matomo.

Le choix est persisté localement ; pour retester le bandeau, supprimer la clé dans les outils développeur ou utiliser une fenêtre privée.

Liens utiles

• Package consent pur : @ben-to/privacy/cookie-consent
• Issue produit / conformité : #39