Vue d'ensemble et installation du SDK

@kilden/sdk est le SDK web de Kilden : capture d’événements, identité, autocapture, feature flags et session replay dans un seul client. Le noyau est sans dépendances et léger (moins de 15 Ko gzippé ; l’autocapture et le replay se chargent comme des chunks lazy séparés, uniquement quand ils sont utilisés).

Installation avec le snippet

Collez ceci avant </head>. Le snippet crée window.kilden avec une file d’attente stub avant le chargement du bundle, de sorte qu’aucun appel n’est jamais perdu — le SDK rejoue les appels en attente dans leur ordre d’origine une fois chargé :

<script>
  !(function (w, d) {
    if (w.kilden) return;
    function stub(o, names) {
      o._q = [];
      names.split(' ').forEach(function (m) {
        o[m] = function () { o._q.push([m].concat([].slice.call(arguments))); };
      });
      return o;
    }
    var k = (w.kilden = stub({}, 'init track identify setPersonProperties reset register unregister getDistinctId getSessionId optOut optIn hasOptedOut setIdentityToken flush use removePlugin startSessionRecording stopSessionRecording getReplayId group isFeatureEnabled getFeatureFlag onFeatureFlags'));
    k.flags = stub({}, 'isFeatureEnabled getFeatureFlag getAllFlags onFeatureFlags reload override');
    k.messenger = stub({}, 'open close show hide toggle showNewMessage on off update');
    var s = d.createElement('script');
    s.async = true;
    s.src = 'https://cdn.kilden.io/kilden.iife.js';
    d.head.appendChild(s);
  })(window, document);

  kilden.init('YOUR_WRITE_KEY');
</script>

La page d’onboarding du projet dans le panel vous fournit exactement ce snippet, avec votre write key et votre hôte API déjà renseignés.

Installation avec npm

npm install @kilden/sdk

import kilden from '@kilden/sdk';

kilden.init('YOUR_WRITE_KEY');
kilden.track('signup_completed', { plan: 'pro' });

L’export par défaut est un singleton — appelez init une seule fois et importez-le n’importe où. Si vous avez besoin de clients isolés (plusieurs projets sur une même page, tests), utilisez createClient :

import { createClient } from '@kilden/sdk';

const analytics = createClient('YOUR_WRITE_KEY', { debug: true });
analytics.track('signup_completed');

La surface du client

Méthode	Ce qu’elle fait
init(writeKey, options?)	Initialise le client. Voir Configuration
track(event, properties?, options?)	Met un événement en file d’attente. Voir Suivi des événements
identify(userId, traits?, options?)	Relie le visiteur anonyme à votre identifiant utilisateur. Voir Méthodes d’identité
setPersonProperties(set, setOnce?)	Met à jour les traits de la personne
reset()	Déconnexion : régénère l’identifiant anonyme, efface le token et les super properties
register(properties) / unregister(key)	Super properties persistées, fusionnées dans chaque événement
getDistinctId() / getSessionId()	Distinct id / identifiant de session courants
optOut() / optIn() / hasOptedOut()	Interrupteur de capture persisté
setIdentityToken(token)	Définit ou efface le JWT de vérification d’identité
flush()	Force l’envoi de la file d’attente. La seule méthode qui renvoie une Promise
use(plugin) / removePlugin(name)	Plugins du pipeline d’événements. Voir Plugins
isFeatureEnabled(key) / getFeatureFlag(key) / onFeatureFlags(cb)	Feature flags. Voir Feature flags
startSessionRecording() / stopSessionRecording() / getReplayId()	Session replay. Voir Session replay
group(groupType, groupKey, properties?)	Réservé. L’analytics de groupes n’est pas encore disponible ; l’appeler est un no-op sûr qui journalise un avertissement en mode debug

Garanties

Ces comportements sont contractuels — la surface publique du SDK est gelée et versionnée :

• L’API publique ne lève jamais d’exception. Les entrées invalides sont ignorées, avec un avertissement seulement quand debug: true.
• Vos données ne sont jamais modifiées — aucun trim, aucune mise en minuscules, aucune normalisation.
• Les appels effectués avant init sont mis en file d’attente et traités à l’initialisation, dans l’ordre. Rien n’est perdu.
• Les événements sont envoyés par batch et réessayés avec backoff exponentiel. Chaque événement porte un UUID v7 généré côté client, donc les réessais sont idempotents — le pipeline déduplique par UUID.
• Au déchargement de la page, la file d’attente est flushée avec fetch(keepalive) (ou sendBeacon en solution de repli) pour que les derniers événements survivent à la navigation.
• optOut() est persisté et arrête toute capture et tout trafic réseau.