Solução de problemas

Você colou o snippet, recarregou seu site, e a tela de onboarding continua dizendo que espera seu primeiro evento. Todas as causas abaixo deixam essa tela no mesmo estado de espera — mas a maioria deixa, sim, um sinal no DevTools do navegador. Percorra a lista em ordem e verifique cada um.

1. A write key não corresponde ao projeto

Cada projeto tem sua própria write key wk_. Compare a key que sua página passa para kilden.init com a que aparece na tela de onboarding ou de settings do projeto, caractere por caractere.

Esse caso é traiçoeiro porque uma key errada mas válida não falha: a request retorna 200 e seus eventos aterrissam no projeto ao qual essa key pertence (o de um colega, um de staging) — eles existem, só não onde você está olhando. Uma key inválida ou revogada é diferente: é rejeitada com 401 (passo 5).

2. Nenhuma request sai do navegador

Abra o DevTools → Network, recarregue a página e filtre pelo host de captura (ingest.kilden.io). Você deve ver um POST em poucos segundos — carregar a página emite um $pageview automaticamente.

Se nenhuma request aparecer:

• O snippet não está na página. Verifique o HTML servido — clique direito → Exibir código-fonte —, não o template do seu framework. Layouts, herança de templates, caches de CDN e pipelines de build servem com frequência uma página sem a mudança que você acabou de fazer.
• Algo bloqueia antes do envio — as duas seções seguintes.

3. Ad blockers e modos de privacidade

uBlock Origin, Brave Shields, a prevenção estrita de rastreamento do Safari e do Firefox, e filtros DNS corporativos bloqueiam requests para hosts com cara de analytics. O POST aparece como bloqueado ou com falha no DevTools, ou simplesmente não aparece.

Teste em um perfil de navegador limpo, ou em uma janela anônima/privada com as extensões desativadas. Se os eventos chegarem ali, seu snippet está bem.

Note que isso não é só um artefato do debugging: uma fração dos seus visitantes reais bloqueia as mesmas requests, então os números do navegador sempre ficam um pouco abaixo da verdade do servidor. É inerente à analítica client-side, não uma configuração errada.

4. Content-Security-Policy

Se o seu site define um header Content-Security-Policy, ele precisa permitir os dois hosts do Kilden: script-src para o CDN que serve o SDK, connect-src para o endpoint de captura:

Content-Security-Policy: script-src 'self' https://cdn.kilden.io; connect-src 'self' https://ingest.kilden.io

(Instâncias self-hosted usam seus próprios hosts — ajuste conforme o caso.) Violações de CSP aparecem, sim, como erros explícitos no Console do DevTools; é o único modo de falha que não é silencioso, se você olhar lá.

5. A request dispara mas retorna um erro

Clique na request na aba Network e leia o status:

• 401 — a write key está errada ou foi revogada (unknown write_key). Volte ao passo 1.
• Outro 4xx — o body em texto puro da resposta diz exatamente o que está malformado. Veja a tabela de erros da API Capture.
• 5xx ou uma falha de rede — o SDK tenta de novo os erros transitórios em silêncio; uma instabilidade breve não perde nada.

6. Envie um evento de teste sem tocar no seu site

A tela de onboarding tem um botão Send a test event: ele empurra um evento pelo pipeline real do seu projeto a partir do servidor, então prova a ingestão de ponta a ponta para o projeto que você está olhando — mesmo antes do seu snippet funcionar. Se o evento de teste chega mas seus pageviews não, o pipeline está bem; isso não descarta uma key trocada, então verifique de novo o passo 1 primeiro (sua página pode carregar a key válida de outro projeto) e depois os passos 2–4.

O equivalente em um terminal — o formato do payload está documentado na API Capture:

curl -X POST https://ingest.kilden.io/capture \
  -H 'Content-Type: application/json' \
  -d '{
    "write_key": "wk_YOUR_KEY",
    "sent_at": "2026-01-01T00:00:00Z",
    "batch": [{
      "uuid": "'"$(uuidgen)"'",
      "event": "test_event",
      "distinct_id": "curl-test",
      "properties": {},
      "timestamp": "2026-01-01T00:00:00Z"
    }]
  }'

O $(uuidgen) gera um uuid novo a cada execução — ele é a chave de idempotência, e um uuid repetido é deduplicado em um único evento, o que se parece exatamente com o problema que você está depurando.

Ainda travado?

Mantenha o live tail aberto ao lado do DevTools — os eventos aparecem lá poucos segundos depois de chegarem, então você tem confirmação instantânea no momento em que qualquer passo acima começar a funcionar (o quickstart mostra onde encontrá-lo). Se nenhum funcionar, fale com a gente no GitHub e inclua o status e o body da resposta da aba Network.