SDK: resumen e instalación

@kilden/sdk es el SDK web de Kilden: captura de eventos, identidad, autocapture, feature flags y session replay en un solo cliente. El core no tiene dependencias y es pequeño (menos de 15 KB gzip; autocapture y replay se cargan como chunks lazy separados solo cuando se usan).

Instalación con el snippet

Pega esto antes de </head>. Crea window.kilden con una cola stub antes de que cargue el bundle, así ninguna llamada se pierde — el SDK reproduce las llamadas encoladas en su orden original una vez que carga:

<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 página de onboarding del proyecto en el panel te da este mismo snippet con tu write key y el host de la API ya completados.

Instalación con npm

npm install @kilden/sdk

import kilden from '@kilden/sdk';

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

El export por defecto es un singleton — llama init una vez e impórtalo donde quieras. Si necesitas clientes aislados (varios proyectos en una misma página, tests), usa createClient:

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

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

La superficie del cliente

Método	Qué hace
`init(writeKey, options?)`	Inicializa. Ver Configuración
`track(event, properties?, options?)`	Encola un evento. Ver Tracking de eventos
`identify(userId, traits?, options?)`	Vincula al visitante anónimo con tu user id. Ver Métodos de identidad
`setPersonProperties(set, setOnce?)`	Actualiza los traits de la persona
`reset()`	Logout: rota el id anónimo, limpia el token y las super properties
`register(properties)` / `unregister(key)`	Super properties persistidas que se mezclan en cada evento
`getDistinctId()` / `getSessionId()`	El distinct id / session id actual
`optOut()` / `optIn()` / `hasOptedOut()`	Interruptor de captura persistido
`setIdentityToken(token)`	Setea o limpia el JWT de verificación de identidad
`flush()`	Fuerza el envío de la cola. El único método que devuelve una `Promise`
`use(plugin)` / `removePlugin(name)`	Plugins del pipeline de eventos. Ver Plugins
`isFeatureEnabled(key)` / `getFeatureFlag(key)` / `onFeatureFlags(cb)`	Feature flags. Ver Feature flags
`startSessionRecording()` / `stopSessionRecording()` / `getReplayId()`	Session replay. Ver Session replay
`group(groupType, groupKey, properties?)`	Reservado. El analytics de grupos aún no está disponible; llamarlo es un no-op seguro que loguea un warning en modo debug

Garantías

Estos comportamientos son contractuales — la superficie pública del SDK está congelada y versionada:

La API pública nunca lanza excepciones. El input inválido se descarta, con un warning solo cuando debug: true.
Tus datos nunca se mutan — nada de trims, lowercase ni normalización.
Las llamadas hechas antes de init se encolan y se procesan al inicializar, en orden. No se pierde nada.
Los eventos se envían en batches y se reintentan con backoff exponencial. Cada evento lleva un UUID v7 generado en el cliente, así los reintentos son idempotentes — el pipeline deduplica por UUID.
Al descargar la página, la cola se hace flush con fetch(keepalive) (o sendBeacon como fallback) para que los últimos eventos sobrevivan la navegación.
optOut() persiste y detiene toda captura y todo tráfico de red.