Skip to main content
View as Markdown

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.

# 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.

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.

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).

Pages connexes