# Analytique Sovrium fournit un moteur d'analytique intégré et propriétaire. Il suit les vues de pages, les sessions, les référents, les campagnes UTM et les répartitions par appareil sur un modèle d'événements unifié unique — sans cookies, sans empreinte digitale et sans services externes. Toutes les données restent sur votre serveur, ce qui le rend compatible GDPR par défaut. L'analytique est configurée via la propriété `analytics` dans le schéma de l'application. Lorsqu'elle est activée, Sovrium injecte un script de suivi léger (~1 Ko) qui enregistre les vues de pages via `navigator.sendBeacon()` vers `POST /api/analytics/collect`. ## Configuration `analytics` accepte un raccourci booléen ou un objet pour un contrôle fin. ```yaml # Boolean shorthand — enable with all defaults analytics: true # Object form — override individual settings, keep defaults for the rest analytics: enabled: true retentionDays: 365 excludedPaths: - /admin/* - /api/* respectDoNotTrack: true sessionTimeout: 30 ``` | Propriété | Par défaut | Plage / Valeurs | Description | | ------------------- | ---------- | ------------------- | ------------------------------------------------------------------------------------------------------ | | `enabled` | `true` | boolean | Active/désactive le suivi analytique. | | `retentionDays` | `365` | `1`–`730` | Jours de conservation des données analytiques. Les lignes plus anciennes sont automatiquement purgées. | | `excludedPaths` | `[]` | string[] (glob) | Motifs d'URL exclus du suivi (par ex. `/admin/*`, `/api/*`). | | `respectDoNotTrack` | `true` | boolean | Honore l'en-tête de navigateur `DNT:1` — ces visiteurs ne sont pas suivis. | | `sessionTimeout` | `30` | `1`–`120` (minutes) | Période d'inactivité après laquelle une nouvelle session commence. | :::callout **Booléen vs objet.** `analytics: true` active les valeurs par défaut (conservation de 365 jours, DNT respecté, sessions de 30 minutes). Utilisez la forme objet pour remplacer des réglages spécifiques tout en conservant les valeurs par défaut pour le reste. `analytics: false` (ou l'omission de la propriété) désactive l'analytique — aucun point de terminaison n'est monté. ::: ## Modèle d'événements unifié Tous les événements analytiques — vues de pages, appels de suivi personnalisés et sources futures — partagent une table `system.analytics_events` unique avec une colonne discriminante `event_type`. Cela suit le modèle standard de l'industrie utilisé par PostHog, Mixpanel et Amplitude, mais auto-hébergé sans dépendance externe (voir DEC-019). ``` system.analytics_events id UUID PRIMARY KEY DEFAULT gen_random_uuid() app_name TEXT NOT NULL event_type TEXT NOT NULL -- 'page_view' | 'track' | extensible event_name TEXT NOT NULL -- path for page_view, custom name for track org_id TEXT -- organization scope (nullable pre-auth) timestamp TIMESTAMPTZ NOT NULL DEFAULT now() visitor_hash TEXT NOT NULL -- privacy-preserving visitor identifier session_hash TEXT NOT NULL -- privacy-preserving session identifier properties JSONB NOT NULL DEFAULT '{}' ``` | Type d'événement | `event_name` | Charge utile `properties` | | ---------------- | ------------------------------- | --------------------------------------------------------------------------------------------------- | | `page_view` | Le chemin de la page | `path`, `referrer`, `utm_*`, `device_type`, `browser_*`, `os_*`, `screen_*`, `language`, `country`. | | `track` | Le nom d'événement personnalisé | Métadonnées clé-valeur arbitraires provenant d'une action d'automatisation ou de l'API de suivi. | Les colonnes promues (`event_type`, `event_name`, `org_id`, `visitor_hash`, `session_hash`, `timestamp`) pilotent des requêtes `WHERE`/`GROUP BY` efficaces ; tout le reste vit dans JSONB. Les mêmes primitives de confidentialité — hachage côté serveur du visiteur/de la session (SHA-256, aucune donnée personnelle stockée), respect de DNT et l'horizon de conservation — s'appliquent uniformément à chaque type d'événement, et chaque ligne est limitée à l'organisation pour l'isolation multi-locataires. :::callout **Parité des moteurs de stockage.** La table d'événements unifiée est exercée à la fois par les chemins de requête PostgreSQL (`->>` sur `system.analytics_events`) et [SQLite](/fr/docs/database-infrastructure) (`json_extract` sur `system_analytics_events`). Les deux produisent des formes de réponse identiques pour collect, la série temporelle de vue d'ensemble, les pages principales, les référents/UTM et la répartition par appareil. ::: ## Interrogation de l'analytique L'analytique agrégée est exposée via des points de terminaison de lecture protégés par administration. Inspectez les événements bruts pour le débogage ou des tableaux de bord personnalisés. | Point de terminaison | Renvoie | | ------------------------------ | ------------------------------------------------------------------------------------ | | `POST /api/analytics/collect` | Point de terminaison d'ingestion public sollicité par le script de suivi. | | `GET /api/analytics/overview` | Totaux + série temporelle quotidienne par paliers. | | `GET /api/analytics/pages` | Pages principales par nombre de vues. | | `GET /api/analytics/referrers` | Répartition des référents et des campagnes UTM. | | `GET /api/analytics/devices` | Répartition par type d'appareil et navigateur. | | `GET /api/analytics/campaigns` | Analyse des campagnes UTM. | | `GET /api/analytics/events` | Inspection d'événements bruts **réservée aux administrateurs** (paginée, filtrable). | ### Inspection des événements bruts `GET /api/analytics/events` offre une visibilité au niveau de la ligne sur le flux unifié — complétant les points de terminaison agrégés. Il est réservé aux administrateurs et prend en charge le filtrage par `event_type`, `event_name` et plage de dates. ``` GET /api/analytics/events?event_type=track&limit=50&offset=0&from=2026-01-01&to=2026-04-15 ``` | Paramètre | Description | | ------------- | ------------------------------------------------ | | `event_type` | Filtre par type (`page_view`, `track`, …). | | `event_name` | Nom d'événement à correspondance exacte. | | `from` / `to` | Plage de dates ISO 8601 (inclusive). | | `limit` | Résultats maximum (par défaut `50`, max `1000`). | | `offset` | Décalage de pagination (par défaut `0`). | ## Confidentialité & Conformité - **Sans cookies, sans empreinte digitale.** Les visiteurs sont identifiés par un hachage SHA-256 calculé côté serveur ; aucun identifiant côté client n'est stocké. - **DNT respecté par défaut.** Les visiteurs envoyant `DNT:1` ne sont pas suivis lorsque `respectDoNotTrack` est activé. - **Toutes les données sont locales.** Aucun service tiers et aucun appel externe — l'analytique ne quitte jamais votre serveur. - **Conservation bornée.** Les données plus anciennes que `retentionDays` sont automatiquement purgées, s'alignant sur la posture de minimisation des données de la plateforme (voir [Écoconception](/fr/docs/ecoconception)). ## Pages connexes - [Tableau de bord d'administration](/fr/docs/admin-dashboard) — API de lecture opérateur sur l'ensemble de la plateforme. - [Surveillance de l'activité](/fr/docs/activity-monitoring) — piste d'audit des actions des utilisateurs et des administrateurs. - [Automatisations](/fr/docs/automations-overview) — émettez des événements `track` personnalisés depuis les actions d'automatisation. - [Écoconception](/fr/docs/ecoconception) — conservation des données et empreinte environnementale. - [Infrastructure de base de données](/fr/docs/database-infrastructure) — la parité SQLite/PostgreSQL derrière la table d'événements.