Modèle d'événement

Un événement Jichio se lit en trois couches : une envelope plate, un contexte structuré dans properties, et une couche serveur ajoutée à l’ingestion.

Couche 1 — Envelope

Champs plats, toujours présents. Ils deviennent des colonnes dans ClickHouse.

{
  "eventId": "uuid-v4",
  "eventName": "pageview | click | <custom>",
  "source": "sdk-react | sdk-wordpress | sdk-core | ...",
  "anonymousId": "uuid",
  "userId": "optionnel",
  "sessionId": "uuid",
  "timestamp": "ISO 8601 client"
}

Champ	Notes
`eventId`	UUID immuable, jamais regénéré au retry (garantit l’idempotence).
`source`	Identifie le connecteur émetteur.
`anonymousId`	UUID anonyme persistant (localStorage).
`userId`	Présent après `identify()`.
`sessionId`	UUID de session (sessionStorage).
`timestamp`	Horodatage client ISO-8601.

projectId n’est pas envoyé par le SDK : il est résolu côté serveur à partir de la clé API.

Couche 2 — Context (`properties.*`)

Namespaces structurés, remplis automatiquement par le SDK.

Namespace	Contenu
`schemaVersion`	Toujours `1`
`sdk`	version, adapter, queueSeq, debug, sentAt
`session`	eventIndex, startedAt, entryUrl, isFirstEvent
`page`	url, path, pathname, title, referrer, loadType
`device`	userAgent, browser, os (1× par session)
`viewport`	dimensions, scroll (pageview + click)
`locale`	language, timezone (1× par session)
`network`	effectiveType, online (1× par session)
`campaign`	UTM parsés depuis l’URL
`element`	selector, boundingRect, text (click uniquement)
`pointer`	clientX/Y, pageX/Y (click uniquement)
`user`	traits persistés après `identify()`
`custom`	propriétés explicites passées à `track()`

Les namespaces présents dépendent du type d’événement — voir Profils de capture.

Couche 3 — Server (`properties.server`)

Injectée uniquement par l’API à l’ingestion — jamais envoyée par le client.

{
  "server": {
    "ingestedAt": "ISO 8601",
    "requestId": "uuid",
    "clientIp": "197.x.x.x",
    "ipHash": "sha256:...",
    "geo": { "country": "unknown", "countryName": "Unknown" },
    "tls": true,
    "apiKeyId": "project_uuid",
    "acceptLanguage": "fr-FR,...",
    "userAgent": "..."
  }
}

L’IP et la géolocalisation sont toujours collectées côté serveur. Le SDK client ne collecte jamais l’IP (précision, vie privée, latence).

Exemple — click enrichi

{
  "eventId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "eventName": "click",
  "source": "sdk-react",
  "anonymousId": "anon_...",
  "userId": "user_42",
  "sessionId": "sess_...",
  "timestamp": "2026-07-15T10:30:45.123Z",
  "properties": {
    "schemaVersion": 1,
    "sdk": { "version": "0.1.0", "adapter": "sdk-react", "queueSeq": 12, "debug": false },
    "session": { "id": "sess_...", "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" }
  }
}

Décisions figées (V1)

Décision	Choix
Résolution de `track()` / `page()`	Quand l’événement est persisté en file (non-bloquant réseau)
`identify()`	Silencieux : met à jour l’état local ; événement `identify` seulement si `debug: true`
`eventId`	UUID immuable, jamais regénéré au retry
`projectId`	Résolu côté serveur via la clé API
IP / géo	Serveur uniquement → `properties.server`

Prise en main

SDK

Concepts

Guides

Modèle d'événement

Couche 1 — Envelope

Couche 2 — Context (`properties.*`)

Couche 3 — Server (`properties.server`)

Exemple — click enrichi

Décisions figées (V1)

​Couche 1 — Envelope

​Couche 2 — Context (properties.*)

​Couche 3 — Server (properties.server)

​Exemple — click enrichi

​Décisions figées (V1)

Couche 1 — Envelope

Couche 2 — Context (`properties.*`)

Couche 3 — Server (`properties.server`)

Exemple — click enrichi

Décisions figées (V1)