Prise en main

Configuration

Tout est désactivé par défaut. Un fournisseur ne s'active que si sa variable *_ENABLED vaut true et que son URL est définie.

Variables navigateur (`NEXT_PUBLIC_*`)

Inlinées dans le bundle : aucun secret ne doit y figurer.

Variable	Effet
`NEXT_PUBLIC_ANALYTICS_ENV`	Nom d'environnement porté par les événements
`NEXT_PUBLIC_ANALYTICS_CONSENT_MODE`	`required` (défaut) ou `exempt`
`NEXT_PUBLIC_ANALYTICS_ALLOW_IDENTIFY`	`true` autorise `identify()`. Laisser faux ici (ADR 006)
`NEXT_PUBLIC_ANALYTICS_PERSIST_ANONYMOUS_ID`	`true` conserve l'identifiant anonyme entre visites
`NEXT_PUBLIC_ANALYTICS_MATOMO_ENABLED`	Active l'adaptateur Matomo
`NEXT_PUBLIC_ANALYTICS_MATOMO_PAGE_VIEWS`	`true` fait émettre les vues de page par l'adaptateur. Laisser faux tant que `MatomoTracker` est en place : sinon double comptage
`NEXT_PUBLIC_MATOMO_URL`, `NEXT_PUBLIC_MATOMO_SITE_ID`	Instance Matomo
`NEXT_PUBLIC_ANALYTICS_UMAMI_ENABLED`, `NEXT_PUBLIC_UMAMI_URL`, `NEXT_PUBLIC_UMAMI_WEBSITE_ID`	Umami
`NEXT_PUBLIC_ANALYTICS_RYBBIT_ENABLED`, `NEXT_PUBLIC_RYBBIT_URL`, `NEXT_PUBLIC_RYBBIT_SITE_ID`	Rybbit

Variables serveur

Jamais exposées au navigateur.

Variable	Effet
`MATOMO_TOKEN_AUTH`	Jeton d'écriture et de lecture Matomo
`RYBBIT_API_KEY`	Clé d'API Rybbit, obligatoire pour l'API HTTP serveur
`OBSERVABILITY_ENABLED`	Active le SDK OpenTelemetry
`OTEL_EXPORTER_OTLP_ENDPOINT`	Collecteur OTLP, sans suffixe de signal
`OTEL_EXPORTER_OTLP_HEADERS`	`clé=valeur,clé2=valeur2`
`OTEL_SERVICE_NAME`, `OTEL_SERVICE_VERSION`, `OTEL_ENVIRONMENT`	Identité du service
`OTEL_TRACES_SAMPLER_ARG`	Fraction échantillonnée, de 0 à 1
`OTEL_CAPTURE_LOGS`, `OTEL_CAPTURE_METRICS`, `OTEL_CAPTURE_TRACES`	Signaux à exporter

Côté serveur : le User-Agent n'est pas optionnel

Les adaptateurs Umami et Rybbit refusent de s'initialiser sans userAgent côté serveur. Ce n'est pas de la rigidité : sans lui, les deux services classent l'événement en robot en répondant succès (voir providers.md).

Diagnostic

NEXT_PUBLIC_ANALYTICS_DEBUG=true expose window.__analytics dans le navigateur :

Code
__analytics.mounted; // l'intégration est-elle montée
__analytics.reason; // pourquoi aucun client n'a été créé, le cas échéant
__analytics.consent(); // état du consentement
__analytics.stats(); // compteurs, par fournisseur
__analytics.diagnostics(); // erreurs avalées par l'isolation des pannes

diagnostics() est le point le plus utile : l'isolation des pannes empêche toute exception de remonter, donc une erreur d'envoi n'apparaît nulle part ailleurs. À laisser désactivé en production.

Réglages de file

maxSize, batchSize, flushIntervalMs, maxRetries, baseBackoffMs, maxBackoffMs, ttlMs. Valeurs par défaut : 500 événements, lots de 20, vidage toutes les 5 s, 5 réessais, durée de vie 24 h. Au débordement, les événements les plus anciens sont écartés et comptés.

Infrastructure

infra/analytics/compose/.env (créé depuis .env.example au premier démarrage) porte les mots de passe des services et les identifiants écrits par les scripts de provisionnement. Ce fichier n'est pas versionné.

Démarrage rapide Catalogue d'événements

Variables navigateur (NEXT_PUBLIC_*)