Plugins

Chaque événement produit par le SDK — appels track, $autocapture, $pageview, $identify — traverse un pipeline de plugins avant d’atteindre la file d’envoi :

track()/identify()/$autocapture/... → before → enrichment → after → send queue

Écrire un plugin

import type { KildenPlugin } from '@kilden/sdk';

const scrubEmails: KildenPlugin = {
  name: 'scrub-emails',
  stage: 'before',
  process(event) {
    if (typeof event.properties.email === 'string') {
      const { email, ...rest } = event.properties;
      return { ...event, properties: rest };
    }
    return event;
  },
};

kilden.use(scrubEmails);

interface KildenPlugin {
  name: string;
  stage: 'before' | 'enrichment' | 'after';
  setup?(client: KildenClient): void;
  process?(event: EventPayload): EventPayload | null; // null = supprimer
  teardown?(): void;
}

Sémantique des stages

Stage	Peut transformer	Peut supprimer (return null)	Usage typique
before	oui	oui	filtres, échantillonnage, nettoyage de PII
enrichment	oui	à éviter — supprimer ici est un signe de mauvaise conception	ajout de properties
after	non	non	observation uniquement ; la valeur de retour est ignorée

Au sein d’un même stage, les plugins s’exécutent dans l’ordre d’enregistrement.

Règles

• process est synchrone. Faites le travail asynchrone dans setup, ou dans un plugin after avec sa propre file d’attente.
• use(plugin) avec un nom existant remplace ce plugin (même position dans l’ordre).
• removePlugin(name) appelle le teardown() du plugin s’il en a un.
• use() avant init est mis en file d’attente comme tout appel pré-init.
• Un plugin qui lève une exception est isolé : l’erreur est interceptée (journalisée seulement avec debug: true) et l’événement continue avec le résultat du stage précédent. L’API publique ne lève jamais d’exception à cause d’un plugin.

beforeSend est du sucre syntaxique

InitOptions.beforeSend enregistre en coulisses un plugin before anonyme — le comportement observable est identique à écrire le plugin vous-même. C’est le moyen le plus rapide de transformer ou supprimer tout, y compris les événements automatiques :

kilden.init('YOUR_WRITE_KEY', {
  beforeSend(event) {
    if (event.event === '$autocapture') return null; // supprimer
    return event;
  },
});

Les fonctionnalités intégrées sont aussi des plugins

Les sessions ($session_id), les properties de contexte, l’extraction des $utm_* et l’autocapture sont implémentées comme des plugins internes sur ce même pipeline. L’autocapture s’enregistre tardivement, quand son chunk lazy finit de charger — les plugins que vous enregistrez ne sont jamais bloqués par elle.