Modèle d'événement

Un événement se compose de trois parties :

une enveloppe : quelques champs fixes, présents sur tous les événements ;
un contexte dans properties, rempli par le SDK selon le type d’événement ;
une partie serveur, properties.server, ajoutée par l’API à la réception.

Enveloppe

{
  "eventId": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
  "eventName": "click",
  "source": "sdk-react",
  "anonymousId": "7bac4caf-c18d-406e-830d-9187b03c188f",
  "userId": "user_42",
  "sessionId": "9e1d9f79-9e06-42d8-a00d-a4f492cb2fde",
  "timestamp": "2026-07-15T10:30:45.123Z",
  "properties": { "schemaVersion": 1 }
}

Champ	Description
`eventId`	UUID v4 unique, conservé à chaque nouvelle tentative d’envoi. Sert au dédoublonnage.
`eventName`	Nom de l’événement : automatique (`pageview`, `click`…) ou personnalisé.
`source`	Plateforme émettrice : `sdk-react`, `sdk-wordpress`, `sdk-core`…
`anonymousId`	Identifiant du navigateur, stocké dans le `localStorage`.
`userId`	Présent après `identify()`.
`sessionId`	Identifiant de la session, stocké dans le `sessionStorage`.
`timestamp`	Date de l’événement côté client, ISO 8601.

Le projet et l’environnement ne figurent pas dans l’événement : ils sont déduits de la clé d’ingestion.

Contexte : `properties`

Clé	Contenu
`schemaVersion`	Toujours `1`
`sdk`	`version`, `coreVersion`, `adapter`, `adapterVersion`, `autoCapture`, `debug`, `sentAt`, `queueSeq`
`session`	`id`, `startedAt`, `eventIndex`, `isFirstEvent`, `referrerDomain`, `entryUrl`, `entryPath`
`user`	`id` et traits passés à `identify()`
`page`	`url`, `path`, `pathname`, `search`, `hash`, `title`, `referrer`, `referrerPath`, `documentVisibility`, `loadType`
`campaign`	`utmSource`, `utmMedium`, `utmCampaign`, `utmTerm`, `utmContent`
`acquisition`	Canal d’acquisition déduit du référent et des UTM
`viewport`	Taille de la fenêtre, `devicePixelRatio`, position de scroll, taille du document
`screen`	Taille de l’écran
`device`	Navigateur, système, user-agent
`locale`	`language`, `languages`, `timezone`, `timezoneOffset`
`network`	Type de connexion, en ligne ou non
`element`	Élément cliqué : balise, sélecteur, texte tronqué, `dataTrack`, position
`pointer`	Coordonnées du clic, bouton, `isTrusted`
`custom`	Propriétés de `track()` et données des événements automatiques

Données selon le type d’événement

Clé	`pageview`	`click`	`track()` et autres automatiques	`identify`
`sdk`, `session`, `page`	✅	✅	✅	✅
`campaign`	Si UTM	Si UTM	Si UTM	Si UTM
`user`	Si identifié	Si identifié	Si identifié	✅
`viewport`	✅	✅
`screen`, `acquisition`, `device`, `locale`, `network`	✅
`element`, `pointer`		✅
`custom`			✅

device, locale et network sont mesurés une fois au premier pageview, puis réutilisés pour les suivants.

Partie serveur : `properties.server`

Ajoutée par l’API à la réception. Une valeur envoyée par le client pour ces champs est ignorée.

{
  "server": {
    "ingestedAt": "2026-07-15T10:30:46.002Z",
    "requestId": "5b0e6a2c-…",
    "clientIp": "197.x.x.x",
    "ipHash": "sha256:…",
    "geo": { "country": "CM", "countryName": "Cameroon", "region": "Centre", "city": "Yaoundé" },
    "tls": true,
    "apiKeyId": "…",
    "acceptLanguage": "fr-FR,fr;q=0.9",
    "userAgent": "Mozilla/5.0 …"
  }
}

La géolocalisation provient de la base MaxMind GeoLite2. Pour une IP privée ou inconnue, country vaut "unknown".

Exemple complet : un clic

{
  "eventId": "a1b2c3d4-e5f6-4890-abcd-ef1234567890",
  "eventName": "click",
  "source": "sdk-react",
  "anonymousId": "7bac4caf-c18d-406e-830d-9187b03c188f",
  "userId": "user_42",
  "sessionId": "9e1d9f79-9e06-42d8-a00d-a4f492cb2fde",
  "timestamp": "2026-07-15T10:30:45.123Z",
  "properties": {
    "schemaVersion": 1,
    "sdk": { "version": "0.2.1", "adapter": "sdk-react", "adapterVersion": "0.1.5", "queueSeq": 12, "debug": false },
    "session": { "id": "9e1d9f79-…", "eventIndex": 12, "isFirstEvent": false, "entryPath": "/pricing" },
    "page": { "url": "https://app.example.com/pricing", "path": "/pricing", "title": "Pricing", "loadType": "initial" },
    "viewport": { "width": 1440, "height": 900, "devicePixelRatio": 2 },
    "element": {
      "tagName": "button",
      "dataTrack": "pricing_start_trial",
      "selector": "#cta-start-trial",
      "text": "Start free trial",
      "boundingRect": { "x": 480, "y": 612, "width": 220, "height": 48 }
    },
    "pointer": { "clientX": 590, "clientY": 636, "button": 0, "isTrusted": true },
    "user": { "id": "user_42", "plan": "pro" }
  }
}

Les types TypeScript complets sont dans Schéma d’événement.

​Enveloppe

​Contexte : properties

​Données selon le type d’événement

​Partie serveur : properties.server

​Exemple complet : un clic

Enveloppe

Contexte : `properties`

Données selon le type d’événement

Partie serveur : `properties.server`

Exemple complet : un clic