Dépannage

Trois causes expliquent la quasi-totalité des cas où « ça ne marche pas ». Elles se distinguent en trente secondes dans l'onglet réseau du navigateur.

1. Vous travaillez en local

Symptôme : aucune requête vers /api/collectn'apparaît, et la console ne dit rien.

La librairie se désactive d'elle-même sur localhost, 127.0.0.1 et les domaines en .localhost. C'est délibéré : sans ça, le développement pollue les statistiques de production, et c'est pénible à nettoyer après coup.

sarutobi.init({ projectToken, enabled: true, debug: true });

2. Le domaine n'est pas déclaré

Symptôme : la requête part et répond 403, ou la console affiche une erreur CORS.

Ajoutez le domaine dans les réglages du site. Le joker est accepté en préfixe de sous-domaine — *.vercel.app pour couvrir les déploiements de prévisualisation — mais jamais seul : un *isolé annulerait la seule barrière qui empêche qu'une clé volée pollue vos chiffres.

3. Un bloqueur filtre la requête

Symptôme :aucune requête ne part, et elle n'apparaît nulle part dans l'onglet réseau — pas même en erreur.

Les listes de filtres bloquent tout ce qui ressemble à de l'analytics. Servir le script depuis notre propre domaine limite la casse, mais on ne joue pas au chat et à la souris : vos chiffres sont un plancher, pas une vérité absolue. Testez en navigation privée sans extension pour confirmer.

Autres situations

Les pages vues arrivent, la durée reste à zéro

La durée est portée par l'event pageleave, envoyé à la fermeture de la page via sendBeacon. Vérifiez que trackDurationn'est pas désactivé, et que vous fermez réellement l'onglet plutôt que de rester dessus.

Une navigation SPA ne compte pas

Les changements de query string seulene déclenchent rien, volontairement : sans cette règle, un filtre branché sur l'URL générerait un pageview à chaque frappe clavier. Si votre routeur n'utilise ni pushState ni popstate, appelez pageview() à la main.

Les courbes s'arrêtent à une heure passée

Le compteur temps réel lit les données brutes, les courbes lisent des agrégats recalculés toutes les dix minutes. Un décalage de quelques minutes est normal ; au-delà d'une demi-heure, l'agrégation est en retard.

Les chiffres semblent gonflés

Un bandeau d'anomalie apparaît sur la vue d'ensemble quand une heure dépasse vingt fois la médiane. La clé d'un site est publique, donc rejouable : un outil de purge permet de supprimer les events d'une plage selon un filtre, et les agrégats se recalculent dans la foulée.

Le mode debug

sarutobi.init({ projectToken, debug: true });

Chaque event est alors tracé dans la console, ainsi que le code HTTP de chaque envoi et les tentatives de renvoi.