Configuration

init(writeKey, options?) accepte un objet InitOptions. Tous les champs sont optionnels.

import kilden from '@kilden/sdk';

kilden.init('YOUR_WRITE_KEY', {
  flushAt: 20,
  flushIntervalMs: 5000,
  autocapture: true,
  debug: false,
});

InitOptions

Option	Type	Défaut	Notes
apiHost	string	https://ingest.kilden.io	URL de base pour l’ingestion. La valeur par défaut est Kilden Cloud — ne la définissez que si vous êtes en self-hosting. Un seul hôte sert /capture, /decide et /replay — il n’y a pas d’hôte séparé pour les feature flags ou le replay
flushAt	number	20	Taille de la file d’attente qui déclenche un flush
flushIntervalMs	number	5000	Temps maximal qu’un événement attend dans la file
persistence	'localStorage' | 'cookie' | 'memory'	'localStorage'	Où vivent l’identifiant anonyme, les super properties et l’état d’opt-out. Bascule automatiquement sur memory quand le stockage choisi est indisponible
autocapture	boolean | AutocaptureOptions	true	Capture automatique des clics, soumissions de formulaires et pageviews. Avec false, le code d’autocapture n’est même pas téléchargé. Voir Autocapture et confidentialité
debug	boolean	false	Journalise les avertissements (entrées invalides, événements custom préfixés par $, appels no-op) dans la console. Le SDK ne lève jamais d’exception dans un cas comme dans l’autre
beforeSend	(event: EventPayload) => EventPayload | null	—	Transforme ou supprime (retour null) chaque événement avant sa mise en file d’attente — y compris $autocapture et les autres événements automatiques
identityToken	string	—	JWT de vérification d’identité, envoyé en Authorization: Bearer avec chaque batch. Voir Vérification d’identité
getIdentityToken	() => Promise<string | null>	—	Callback de rafraîchissement du token : appelé avant l’expiration du token courant et après un 401
sessionRecording	boolean | SessionRecordingOptions	non défini	Session replay. Par défaut, la config distante du projet décide ; false est un opt-out dur qui ne télécharge jamais le code d’enregistrement. Voir Session replay

AutocaptureOptions

Passez un objet à la place de true pour ajuster l’autocapture :

Option	Type	Défaut	Notes
captureClicks	boolean	true	Émet $autocapture sur les clics
captureSubmits	boolean	true	Émet $autocapture sur les soumissions de formulaires
captureChanges	boolean	false	Émet $autocapture sur les changements de champs. Seul le fait qu’un changement a eu lieu est enregistré — jamais la valeur
ignoreSelectors	string[]	—	Sélecteurs CSS à exclure de la capture
maskAllText	boolean	false	Remplace tout le texte des éléments dans $elements par "*"
allowUrls	(string | RegExp)[]	—	Restreint l’autocapture aux URL correspondantes

SessionRecordingOptions

Passez un objet à la place de true pour ajuster le replay :

Option	Type	Défaut	Notes
sampleRate	number	0.1	Fraction des sessions à enregistrer, 0..1. Décidée une fois par session et conservée à travers les rechargements
minimumDurationMs	number	2000	Les enregistrements plus courts que cette durée sont écartés
maskAllInputs	boolean	true	Masque tout ce que l’utilisateur tape. Volontairement l’inverse du défaut de l’autocapture : un replay montre les frappes clavier, donc le masquage est opt-out
maskAllText	boolean	false	Masque tout le texte de la page
blockSelectors	string[]	—	Sélecteurs CSS à exclure entièrement de l’enregistrement
recordCanvas	boolean	false	Enregistre le contenu des <canvas> (lourd, rarement utile)

Batching et livraison

• Les événements sont mis en file d’attente en mémoire et flushés quand la file atteint flushAt événements ou que l’événement le plus ancien a flushIntervalMs d’âge, selon la première échéance.
• Sur pagehide/visibilitychange, la file d’attente est flushée immédiatement. Quand un token d’identité est présent, le SDK utilise fetch(url, { keepalive: true }) (qui peut transporter l’en-tête Authorization) ; sans token — ou sans support de keepalive — il utilise sendBeacon, avec le token dans le corps de la requête, un repli documenté.
• Les flushs échoués sont réessayés avec backoff exponentiel. Chaque événement a un UUID v7 généré côté client, donc les réessais sont idempotents de bout en bout.
• Les batchs sont compressés en gzip via CompressionStream quand le navigateur le supporte.

Les identifiants gérés par le SDK

• Identifiant anonyme : anon_ + UUID v7, généré à la première visite et persisté dans le stockage configuré.
• Identifiant de session ($session_id sur chaque événement) : UUID v7, régénéré après 30 minutes d’inactivité.