Solución de problemas

Pegaste el snippet, recargaste tu sitio, y la pantalla de onboarding sigue diciendo que espera tu primer evento. Todas las causas de abajo dejan esa pantalla en el mismo estado de espera — pero la mayoría sí deja una señal en las DevTools del navegador. Recorre la lista en orden y revisa cada una.

1. El write key no corresponde al proyecto

Cada proyecto tiene su propio write key wk_. Compara el key que tu página le pasa a kilden.init con el que muestra la pantalla de onboarding o de settings del proyecto, carácter por carácter.

Este caso es traicionero porque un key equivocado pero válido no falla: la request devuelve 200 y tus eventos aterrizan en el proyecto al que pertenece ese key (el de un compañero, uno de staging) — existen, solo que no donde estás mirando. Un key inválido o revocado es distinto: se rechaza con 401 (paso 5).

2. Ninguna request sale del navegador

Abre DevTools → Network, recarga la página y filtra por el host de captura (ingest.kilden.io). Deberías ver un POST en pocos segundos — cargar la página emite un $pageview automáticamente.

Si no aparece ninguna request:

• El snippet no está en la página. Revisa el HTML servido — clic derecho → Ver código fuente —, no la plantilla de tu framework. Layouts, herencia de plantillas, caches de CDN y pipelines de build sirven con frecuencia una página sin el cambio que acabas de hacer.
• Algo lo bloquea antes de enviar — las dos secciones siguientes.

3. Ad blockers y modos de privacidad

uBlock Origin, Brave Shields, la prevención estricta de tracking de Safari y Firefox, y los filtros DNS corporativos bloquean las requests hacia hosts con pinta de analytics. El POST aparece como bloqueado o fallido en DevTools, o directamente no aparece.

Prueba en un perfil de navegador limpio, o en una ventana de incógnito/privada con las extensiones desactivadas. Si ahí los eventos llegan, tu snippet está bien.

Ten en cuenta que esto no es solo un artefacto del debugging: una fracción de tus visitantes reales bloquea las mismas requests, así que los números del navegador siempre quedan levemente por debajo de la verdad del servidor. Es inherente a la analítica client-side, no una mala configuración.

4. Content-Security-Policy

Si tu sitio define un header Content-Security-Policy, debe permitir ambos hosts de Kilden: script-src para el CDN que sirve el SDK, connect-src para el endpoint de captura:

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

(Las instancias self-hosted usan sus propios hosts — ajusta según corresponda.) Las violaciones de CSP sí aparecen como errores explícitos en la Console de DevTools; es el único modo de falla que no es silencioso, si miras ahí.

5. La request se dispara pero devuelve un error

Haz clic en la request en la pestaña Network y lee el status:

• 401 — el write key es incorrecto o fue revocado (unknown write_key). Vuelve al paso 1.
• Otro 4xx — el body de texto plano de la respuesta dice exactamente qué está malformado. Mira la tabla de errores del API Capture.
• 5xx o un fallo de red — el SDK reintenta los errores transitorios en silencio; un parpadeo breve no pierde nada.

6. Envía un evento de prueba sin tocar tu sitio

La pantalla de onboarding tiene un botón Send a test event: empuja un evento por el pipeline real de tu proyecto desde el servidor, así que prueba la ingesta de punta a punta para el proyecto que estás mirando — incluso antes de que tu snippet funcione. Si el evento de prueba llega pero tus pageviews no, el pipeline está bien; eso no descarta un key equivocado, así que vuelve a revisar el paso 1 primero (tu página podría llevar el key válido de otro proyecto) y luego los pasos 2–4.

El equivalente desde una terminal — la forma del payload está documentada en el 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"
    }]
  }'

El $(uuidgen) genera un uuid nuevo en cada ejecución — es la clave de idempotencia, y un uuid repetido se deduplica en un solo evento, que se ve exactamente igual al problema que estás depurando.

¿Sigues atascado?

Mantén el live tail abierto junto a DevTools — los eventos aparecen ahí a los pocos segundos de llegar, así que tienes confirmación instantánea en el momento en que cualquiera de los pasos de arriba empiece a funcionar (el quickstart muestra dónde encontrarlo). Si ninguno funciona, escríbenos en GitHub e incluye el status y el body de la respuesta desde la pestaña Network.