Visão geral e instalação do SDK

@kilden/sdk é o SDK web do Kilden: captura de eventos, identidade, autocapture, feature flags e session replay em um único client. O núcleo não tem dependências e é pequeno (menos de 15 KB com gzip; autocapture e replay carregam como chunks lazy separados apenas quando usados).

Instalar com o snippet

Cole isto antes de </head>. Ele cria window.kilden com uma fila stub antes de o bundle carregar, então nenhuma chamada se perde — o SDK reproduz as chamadas enfileiradas na ordem original assim que carrega:

<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>

A página de onboarding do projeto no painel te dá exatamente esse snippet, com sua write key e o host da API já preenchidos.

Instalar com npm

npm install @kilden/sdk

import kilden from '@kilden/sdk';

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

O export default é um singleton — chame init uma vez e importe-o em qualquer lugar. Se você precisa de clients isolados (vários projetos em uma mesma página, testes), use createClient:

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

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

A superfície do client

Método	O que faz
init(writeKey, options?)	Inicializa. Veja Configuração
track(event, properties?, options?)	Enfileira um evento. Veja Rastreando eventos
identify(userId, traits?, options?)	Vincula o visitante anônimo ao id do seu usuário. Veja Métodos de identidade
setPersonProperties(set, setOnce?)	Atualiza os traits da pessoa
reset()	Logout: rotaciona o id anônimo, limpa o token e as super properties
register(properties) / unregister(key)	Super properties persistidas e mescladas em todos os eventos
getDistinctId() / getSessionId()	Distinct id / session id atuais
optOut() / optIn() / hasOptedOut()	Interruptor persistido que desliga a captura
setIdentityToken(token)	Define ou limpa o JWT de verificação de identidade
flush()	Força o envio da fila. O único método que retorna uma Promise
use(plugin) / removePlugin(name)	Plugins do pipeline de eventos. Veja Plugins
isFeatureEnabled(key) / getFeatureFlag(key) / onFeatureFlags(cb)	Feature flags. Veja Feature flags
startSessionRecording() / stopSessionRecording() / getReplayId()	Session replay. Veja Session replay
group(groupType, groupKey, properties?)	Reservado. O analytics de grupos ainda não está disponível; chamá-lo é um no-op seguro que registra um aviso em modo debug

Garantias

Estes comportamentos são contratuais — a superfície pública do SDK é congelada e versionada:

• A API pública nunca lança exceções. Entrada inválida é descartada, com aviso apenas quando debug: true.
• Seus dados nunca são alterados — sem trim, lowercase ou normalização.
• Chamadas feitas antes de init são enfileiradas e processadas no init, em ordem. Nada se perde.
• Eventos são enviados em batches e reenviados com backoff exponencial. Cada evento carrega um UUID v7 gerado no cliente, então os reenvios são idempotentes — o pipeline deduplica por UUID.
• No unload da página a fila é descarregada com fetch(keepalive) (ou sendBeacon como fallback), para que os últimos eventos sobrevivam à navegação.
• optOut() persiste e interrompe toda captura e todo tráfego de rede.