Configuración

init(writeKey, options?) acepta un objeto InitOptions. Todos los campos son opcionales.

import kilden from '@kilden/sdk';

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

InitOptions

Opción	Tipo	Default	Notas
apiHost	string	https://ingest.kilden.io	URL base de la ingesta. El default es Kilden Cloud — configúralo solo si haces self-hosting. Un solo host sirve /capture, /decide y /replay — no hay un host separado para feature flags ni replay
flushAt	number	20	Tamaño de cola que dispara un flush
flushIntervalMs	number	5000	Tiempo máximo que un evento espera en la cola
persistence	'localStorage' | 'cookie' | 'memory'	'localStorage'	Dónde viven el id anónimo, las super properties y el estado de opt-out. Cae automáticamente a memory cuando el storage elegido no está disponible
autocapture	boolean | AutocaptureOptions	true	Captura automática de clicks/submits/pageviews. Con false el código de autocapture ni siquiera se descarga. Ver Autocapture y privacidad
debug	boolean	false	Loguea warnings en la consola (input inválido, eventos custom con prefijo $, llamadas no-op). El SDK nunca lanza excepciones en ningún caso
beforeSend	(event: EventPayload) => EventPayload | null	—	Transforma o descarta (devuelve null) cada evento antes de encolarlo — incluyendo $autocapture y demás eventos automáticos
identityToken	string	—	JWT de verificación de identidad, enviado como Authorization: Bearer con cada batch. Ver Verificación de identidad
getIdentityToken	() => Promise<string | null>	—	Callback de refresco del token: se llama antes de que expire el token actual y después de un 401
sessionRecording	boolean | SessionRecordingOptions	sin setear	Session replay. Por defecto decide la config remota del proyecto; false es un opt-out duro que nunca descarga el código de grabación. Ver Session replay

AutocaptureOptions

Pasa un objeto en lugar de true para ajustar el autocapture:

Opción	Tipo	Default	Notas
captureClicks	boolean	true	Emite $autocapture en clicks
captureSubmits	boolean	true	Emite $autocapture en submits de formularios
captureChanges	boolean	false	Emite $autocapture en cambios de inputs. Solo se registra el hecho de que algo cambió — nunca el valor
ignoreSelectors	string[]	—	Selectores CSS a excluir de la captura
maskAllText	boolean	false	Reemplaza todo el texto de los elementos en $elements con "*"
allowUrls	(string | RegExp)[]	—	Restringe el autocapture a las URLs que matcheen

SessionRecordingOptions

Pasa un objeto en lugar de true para ajustar el replay:

Opción	Tipo	Default	Notas
sampleRate	number	0.1	Fracción de sesiones a grabar, 0..1. Se decide una vez por sesión y se mantiene entre recargas
minimumDurationMs	number	2000	Las grabaciones más cortas que esto se descartan
maskAllInputs	boolean	true	Enmascara todo lo que el usuario escribe. Deliberadamente el default opuesto al de autocapture: un replay muestra las teclas, así que el enmascarado es opt-out
maskAllText	boolean	false	Enmascara todo el texto de la página
blockSelectors	string[]	—	Selectores CSS a excluir por completo de la grabación
recordCanvas	boolean	false	Graba el contenido de <canvas> (pesado, rara vez útil)

Batching y entrega

• Los eventos se encolan en memoria y se hace flush cuando la cola llega a flushAt eventos o el evento más antiguo cumple flushIntervalMs, lo que ocurra primero.
• En pagehide/visibilitychange la cola se hace flush de inmediato. Con un identity token presente, el SDK usa fetch(url, { keepalive: true }) (puede llevar el header Authorization); sin token — o sin soporte de keepalive — usa sendBeacon, con el token dentro del cuerpo de la request como fallback documentado.
• Los flushes fallidos se reintentan con backoff exponencial. Cada evento tiene un UUID v7 generado en el cliente, así los reintentos son idempotentes de punta a punta.
• Los batches se comprimen con gzip vía CompressionStream cuando el navegador lo soporta.

Identificadores que maneja el SDK

• Id anónimo: anon_ + UUID v7, generado en la primera visita y persistido en el storage configurado.
• Session id ($session_id en cada evento): UUID v7, rotado tras 30 minutos de inactividad.