Les problèmes rencontrés en intégration et comment les résoudre.

​
La heatmap n’a pas le screenshot de la page

Symptôme — Pastilles sur un rectangle sombre, ou un message d’état à la place de la page. Vérifier
  1. L’URL du site du projet est renseignée et correspond au host tracké (www vs apex : OK).
  2. La page est publique. Login, 401/403 et cookie walls → « non joignable publiquement ».
  3. Chromium est installé sur l’API : uv run playwright install chromium.
  4. Recapturer le chemin, ou attendre le job quotidien POST /v1/internal/jobs/heatmap-captures.
Les clics s’affichent même sans screenshot. Voir Heatmaps.

​
CORS : OPTIONS → 400 Bad Request

Symptôme
Cause — Le SDK envoie un POST avec Content-Type: application/json et X-API-Key. En cross-origin, le navigateur déclenche un preflight OPTIONS. Si l’API locale ne gère pas correctement OPTIONS / les en-têtes CORS, le POST n’est jamais envoyé. Solution (dev) — Proxy same-origin :
Configurez NEXT_PUBLIC_ANALYTICS_ENDPOINT=/jichio et un rewrite (voir Intégration Next.js). Solution (prod / appel direct) — Côté API, accepter OPTIONS et renvoyer :

​
Les événements ne partent pas

Les événements partent en batch : attendez jusqu’à 5 s (ou 10 événements), ou appelez analytics.flush(). Un flush se déclenche aussi quand l’onglet passe en arrière-plan.
Si vous utilisez un provider conditionnel, une clé ou un endpoint absent désactive l’analytics silencieusement. Vérifiez vos variables d’environnement.
Clé API invalide : le retry est stoppé et la file conservée. Vérifiez X-API-Key et l’endpoint.

​
identify ne crée pas d’événement

Ce n’est pas un bug : identify() est silencieux sauf si debug: true. L’identité est stockée localement et les événements suivants portent userId. Voir Identifier les utilisateurs.

​
Variables d’env figées après changement

Avec des outils qui inlinent les variables à la compilation (Vite define, Webpack DefinePlugin, Next NEXT_PUBLIC_*), un changement de .env ou de proxy nécessite de redémarrer le serveur de dev pour être pris en compte.

​
Checklist de mise en service

1

Renseigner la clé (+ endpoint)

Dans l’environnement cible (NEXT_PUBLIC_ANALYTICS_KEY, ..._ENDPOINT).
2

En local, garder le proxy

NEXT_PUBLIC_ANALYTICS_ENDPOINT=/jichio et l’API sur :8000.
3

Redémarrer le serveur de dev

Pour recharger les variables inlinées et le proxy.
4

Vérifier l'ingestion

POST {endpoint}/v1/events → 200 avec { "accepted": n }.
5

Ne jamais committer de vraie clé

Utilisez des placeholders dans les fichiers versionnés.