Configuração

init(writeKey, options?) aceita um objeto InitOptions. Todos os campos são opcionais.

import kilden from '@kilden/sdk';

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

InitOptions

Opção	Tipo	Default	Notas
apiHost	string	https://ingest.kilden.io	URL base de ingestão. O padrão é o Kilden Cloud — defina apenas se você faz self-hosting. Um único host serve /capture, /decide e /replay — não há host separado para feature flags ou replay
flushAt	number	20	Tamanho da fila que dispara um flush
flushIntervalMs	number	5000	Tempo máximo que um evento espera na fila
persistence	'localStorage' | 'cookie' | 'memory'	'localStorage'	Onde vivem o id anônimo, as super properties e o estado de opt-out. Recorre automaticamente a memory quando o storage escolhido não está disponível
autocapture	boolean | AutocaptureOptions	true	Captura automática de cliques/submits/pageviews. Com false, o código de autocapture nem sequer é baixado. Veja Autocapture e privacidade
debug	boolean	false	Registra avisos no console (entrada inválida, eventos customizados com prefixo $, chamadas no-op). O SDK nunca lança exceções de qualquer forma
beforeSend	(event: EventPayload) => EventPayload | null	—	Transforma ou descarta (retorne null) cada evento antes de ele entrar na fila — inclusive $autocapture e outros eventos automáticos
identityToken	string	—	JWT de verificação de identidade, enviado como Authorization: Bearer com cada batch. Veja Verificação de identidade
getIdentityToken	() => Promise<string | null>	—	Callback de refresh do token: chamado antes de o token atual expirar e após um 401
sessionRecording	boolean | SessionRecordingOptions	não definido	Session replay. Por padrão, a config remota do projeto decide; false é um opt-out duro que nunca baixa o código de gravação. Veja Session replay

AutocaptureOptions

Passe um objeto em vez de true para ajustar o autocapture:

Opção	Tipo	Default	Notas
captureClicks	boolean	true	Emite $autocapture em cliques
captureSubmits	boolean	true	Emite $autocapture em submits de formulários
captureChanges	boolean	false	Emite $autocapture em mudanças de inputs. Só o fato de que algo mudou é registrado — nunca o valor
ignoreSelectors	string[]	—	Seletores CSS a excluir da captura
maskAllText	boolean	false	Substitui todo o texto dos elementos em $elements por "*"
allowUrls	(string | RegExp)[]	—	Restringe o autocapture às URLs que casarem

SessionRecordingOptions

Passe um objeto em vez de true para ajustar o replay:

Opção	Tipo	Default	Notas
sampleRate	number	0.1	Fração das sessões a gravar, 0..1. Decidida uma vez por sessão e mantida entre reloads
minimumDurationMs	number	2000	Gravações mais curtas que isso são descartadas
maskAllInputs	boolean	true	Mascara tudo o que o usuário digita. Deliberadamente o default oposto ao do autocapture: um replay mostra as teclas digitadas, então o mascaramento é opt-out
maskAllText	boolean	false	Mascara todo o texto da página
blockSelectors	string[]	—	Seletores CSS a excluir por completo da gravação
recordCanvas	boolean	false	Grava o conteúdo de <canvas> (pesado, raramente útil)

Batching e entrega

• Os eventos entram numa fila em memória e são enviados quando a fila atinge flushAt eventos ou quando o evento mais antigo completa flushIntervalMs, o que ocorrer primeiro.
• Em pagehide/visibilitychange a fila é descarregada imediatamente. Com um token de identidade presente, o SDK usa fetch(url, { keepalive: true }) (que consegue carregar o header Authorization); sem token — ou sem suporte a keepalive — usa sendBeacon, com o token dentro do corpo da requisição como fallback documentado.
• Flushes que falham são reenviados com backoff exponencial. Cada evento tem um UUID v7 gerado no cliente, então os reenvios são idempotentes de ponta a ponta.
• Os batches são comprimidos com gzip via CompressionStream quando o navegador suporta.

Identificadores que o SDK gerencia

• Id anônimo: anon_ + UUID v7, gerado na primeira visita e persistido no storage configurado.
• Session id ($session_id em todos os eventos): UUID v7, rotacionado após 30 minutos de inatividade.