Dépannage

Vous avez collé le snippet, rechargé votre site, et l’écran d’onboarding dit toujours qu’il attend votre premier événement. Toutes les causes ci-dessous laissent cet écran dans le même état d’attente — mais la plupart laissent bel et bien un signal dans les DevTools du navigateur. Descendez la liste dans l’ordre et vérifiez chacune.

1. La write key ne correspond pas au projet

Chaque projet a sa propre write key wk_. Comparez la key que votre page passe à kilden.init avec celle affichée sur l’écran d’onboarding ou de settings du projet, caractère par caractère.

Ce cas est vicieux parce qu’une key erronée mais valide n’échoue pas : la requête renvoie 200 et vos événements atterrissent dans le projet auquel cette key appartient (celui d’un collègue, un projet de staging) — ils existent, mais pas là où vous regardez. Une key invalide ou révoquée, c’est différent : elle est rejetée avec 401 (étape 5).

2. Aucune requête ne quitte le navigateur

Ouvrez les DevTools → Network, rechargez la page et filtrez par l’hôte de capture (ingest.kilden.io). Vous devriez voir un POST en quelques secondes — le chargement de la page émet automatiquement un $pageview.

Si aucune requête n’apparaît :

• Le snippet n’est pas sur la page. Vérifiez le HTML servi — clic droit → Afficher le code source —, pas le template de votre framework. Layouts, héritage de templates, caches CDN et pipelines de build servent régulièrement une page sans le changement que vous venez de faire.
• Quelque chose le bloque avant l’envoi — les deux sections suivantes.

3. Bloqueurs de publicité et modes de confidentialité

uBlock Origin, Brave Shields, la protection stricte contre le pistage de Safari et Firefox, et les filtres DNS d’entreprise bloquent les requêtes vers les hôtes qui ressemblent à de l’analytics. Le POST apparaît comme bloqué ou en échec dans les DevTools, ou n’apparaît pas du tout.

Testez dans un profil de navigateur propre, ou dans une fenêtre de navigation privée avec les extensions désactivées. Si les événements arrivent là, votre snippet est bon.

Notez que ce n’est pas qu’un artefact de débogage : une fraction de vos vrais visiteurs bloque les mêmes requêtes, donc les chiffres côté navigateur restent toujours légèrement en dessous de la vérité serveur. C’est inhérent à l’analytics côté client, pas une mauvaise configuration.

4. Content-Security-Policy

Si votre site définit un header Content-Security-Policy, il doit autoriser les deux hôtes de Kilden : script-src pour le CDN qui sert le SDK, connect-src pour l’endpoint de capture :

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

(Les instances auto-hébergées utilisent leurs propres hôtes — ajustez en conséquence.) Les violations de CSP apparaissent bel et bien comme des erreurs explicites dans la Console des DevTools ; c’est le seul mode d’échec qui n’est pas silencieux, si vous regardez là.

5. La requête part mais renvoie une erreur

Cliquez sur la requête dans l’onglet Network et lisez le statut :

• 401 — la write key est erronée ou a été révoquée (unknown write_key). Retour à l’étape 1.
• Autre 4xx — le body en texte brut de la réponse dit exactement ce qui est malformé. Voir la table des erreurs de l’API Capture.
• 5xx ou un échec réseau — le SDK réessaie silencieusement les erreurs transitoires ; une brève coupure ne perd rien.

6. Envoyez un événement de test sans toucher à votre site

L’écran d’onboarding a un bouton Send a test event : il pousse un événement à travers le vrai pipeline de votre projet côté serveur, donc il prouve l’ingestion de bout en bout pour le projet que vous regardez — avant même que votre snippet fonctionne. Si l’événement de test arrive mais pas vos pageviews, le pipeline va bien ; cela n’exclut pas pour autant une key qui ne correspond pas, donc revérifiez d’abord l’étape 1 (votre page peut porter la key valide d’un autre projet), puis les étapes 2–4.

L’équivalent depuis un terminal — la forme du payload est documentée dans l’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"
    }]
  }'

Le $(uuidgen) génère un uuid neuf à chaque exécution — c’est la clé d’idempotence, et un uuid répété est dédupliqué en un seul événement, ce qui ressemble exactement au problème que vous êtes en train de déboguer.

Toujours bloqué ?

Gardez le live tail ouvert à côté des DevTools — les événements y apparaissent quelques secondes après leur arrivée, donc vous avez une confirmation instantanée dès qu’une des étapes ci-dessus commence à fonctionner (le quickstart montre où le trouver). Si aucune ne fonctionne, écrivez-nous sur GitHub en incluant le statut et le body de la réponse depuis l’onglet Network.