Suivi des événements

track()

kilden.track('checkout_completed', { plan: 'pro', total: 49.9 });

track(event: string, properties?: Properties, options?: TrackOptions): void

track renvoie void, pas une Promise — les événements sont mis en file d’attente et envoyés par batch en arrière-plan. Si vous devez attendre la livraison (rare ; le SDK flushe déjà au déchargement de la page), appelez flush().

• properties est un objet JSON (Record<string, JsonValue>). Kilden ne valide ni ne type jamais vos properties — l’enveloppe de l’événement est typée, le payload vous appartient.
• options.timestamp (Date | string) antidate l’événement. Sans elle, l’événement est horodaté au moment de l’appel à track, et le serveur corrige la dérive d’horloge du client.
• Les noms d’événements n’ont pas de schéma. Une seule convention est appliquée en douceur : les noms commençant par $ sont réservés aux événements système de Kilden. En envoyer un via track journalise un avertissement en mode debug, mais l’événement est quand même envoyé — le SDK ne casse jamais vos appels.

Chaque événement inclut automatiquement des properties de contexte : $current_url, $referrer, $session_id, $device_type, $screen_width, $screen_height, $lib, $lib_version, ainsi que $utm_source / $utm_medium / $utm_campaign / $utm_term / $utm_content extraits de l’URL. Voir Événements et properties.

Le payload d’événement

Voici la forme d’un événement au moment où il entre dans la file d’attente — et telle que beforeSend et les plugins la voient :

interface EventPayload {
  uuid: string;          // UUID v7, généré par le SDK
  event: string;
  distinct_id: string;
  properties: Properties; // les $-properties de contexte déjà fusionnées
  timestamp: string;      // ISO 8601
}

Super properties : register() / unregister()

Les super properties sont persistées et fusionnées dans chaque événement ultérieur :

kilden.register({ app_version: '3.2.0', experiment_wave: 'q3' });
kilden.unregister('experiment_wave');

Elles survivent aux rechargements (dans la persistence configurée) et sont effacées par reset().

flush()

await kilden.flush();

Envoie immédiatement tout ce qui se trouve dans la file d’attente. La seule méthode du client qui renvoie une Promise.

Lire les identifiants

kilden.getDistinctId(); // "anon_018f..." ou votre identifiant utilisateur après identify()
kilden.getSessionId();  // le $session_id courant (régénéré après 30 min d'inactivité)

Opt-out

kilden.optOut();       // persisté : arrête toute capture et tout trafic réseau
kilden.optIn();        // réactive
kilden.hasOptedOut();  // booléen

Pendant l’opt-out, rien n’est capturé ni envoyé, y compris les chargements de feature flags depuis /decide (les valeurs de flags déjà en cache continuent de répondre).

group() — réservé

group(groupType: string, groupKey: string, properties?: Properties): void

L’analytics de groupes B2B fait partie de la surface gelée mais n’est pas encore disponible : appeler group() est un no-op sûr qui journalise un avertissement en mode debug. La méthode existe pour que le snippet d’installation n’ait jamais à changer quand la fonctionnalité sortira.