# 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](/analytics/conception/providers)).

## Diagnostic

`NEXT_PUBLIC_ANALYTICS_DEBUG=true` expose `window.__analytics` dans le navigateur :

```js
__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é.**