Événements et propriétés
Les événements sont immuables
Section intitulée « Les événements sont immuables »Un événement fige ses propriétés au moment de la capture. Rien ne le réécrit ensuite — ni les fusions d’identité, ni les mises à jour de traits, ni les décisions d’enforcement. Si le plan d’une personne change, c’est sa personne qui change ; les événements envoyés sous l’ancien plan continuent d’indiquer l’ancien plan. C’est la séparation : les événements sont l’histoire, les personnes sont l’état.
Chaque événement porte :
| Champ | Ce que c’est |
|---|---|
uuid |
UUID v7 généré par le client. La clé d’idempotence : le pipeline déduplique dessus, ce qui rend les réessais sûrs à chaque couche |
event |
Le nom. Vos noms sont libres ; les noms préfixés par $ appartiennent au système |
distinct_id |
Qui a agi, tel que connu au moment de la capture |
properties |
JSON arbitraire. Kilden ne le valide ni ne le type jamais — l’enveloppe est typée, le payload est à vous, par conception |
timestamp |
Quand c’est arrivé (fourni par le client, corrigé de la dérive d’horloge grâce au sent_at du batch) |
Le namespace $
Section intitulée « Le namespace $ »Les noms commençant par $ — événements comme propriétés — sont réservés au système. Le SDK avertit en mode debug si vous en envoyez un via track(), mais le livre quand même : le namespace est une convention, jamais une raison de jeter vos données.
Les événements système que vous verrez dans votre flux :
| Événement | Émis par |
|---|---|
$pageview, $pageleave |
Le SDK, automatiquement (y compris les changements de route en SPA) |
$autocapture |
L’autocapture : clics, soumissions, changements, décrits par $event_type et $elements |
$identify |
identify() — porte $anon_distinct_id pour lier les identités |
$set, $set_once |
Mises à jour des traits de personne |
$feature_flag_called |
Première lecture d’un flag par session — $flag_key, $flag_value (expositions) |
$session_recording_started |
Démarrage d’un enregistrement de replay |
$email_sent, $email_delivered, $email_opened, $email_clicked, $email_bounced, $email_complained |
Les campagnes et les webhooks du fournisseur d’email |
Propriétés de contexte apposées sur chaque événement du SDK : $current_url, $referrer, $session_id, $device_type, $screen_width, $screen_height, $lib, $lib_version, $utm_source, $utm_medium, $utm_campaign, $utm_term, $utm_content.
Localisation (GeoIP)
Section intitulée « Localisation (GeoIP) »Kilden déduit la localisation approximative côté serveur à partir de l’IP du visiteur et l’appose sur l’événement : $geoip_country_code, $geoip_subdivision_1_name, $geoip_city_name, $geoip_time_zone (plus $initial_geoip_* fixées une seule fois sur la personne, pour la géographie de premier contact). Le SDK n’envoie rien de plus — l’IP arrive simplement avec la requête.
La résolution utilise une base de données locale (aucun service de géolocalisation externe n’est appelé), et l’IP est transitoire : elle n’existe que le temps de déduire la localisation puis est supprimée — elle n’est jamais écrite dans les bases de données de Kilden. L’enrichissement de localisation peut être désactivé par projet dans le panneau.
Les données de localisation proviennent de la base IP Geolocation by DB-IP (CC BY 4.0).
Un seul chemin d’écriture
Section intitulée « Un seul chemin d’écriture »Chaque événement — navigateur, backend, webhook email, même les événements internes de Kilden — entre par le même endpoint capture et le même pipeline. Il n’y a pas de portes dérobées, et c’est ce qui fait que les garanties (déduplication, résolution d’identité, niveaux de confiance) tiennent uniformément pour tout.
Sessions
Section intitulée « Sessions »Le SDK maintient un $session_id (UUID v7) sur chaque événement, en le faisant tourner après 30 minutes d’inactivité. Les sessions relient entre eux les événements, la déduplication des expositions de feature flags et le session replay — un enregistrement est toujours joignable en 1:1 avec les événements de sa session.