13 min de lecture

Dépannage

Ce guide couvre les problèmes courants que vous pourriez rencontrer en utilisant Zenovay et comment les résoudre.

Problèmes de Script de Suivi

Script ne se charge pas

Symptômes : Aucune donnée n'apparaît dans votre tableau de bord après l'installation du script de suivi.

Causes possibles et solutions :

1. Script mal installé

Vérifiez que le script se trouve dans la section <head> de votre page :

<head>
  <script defer data-tracking-code="YOUR_TRACKING_CODE" src="https://api.zenovay.com/z.js"></script>
</head>

Vérifiez que :

L'URL du script est correcte
Votre data-tracking-code correspond au code affiché dans les paramètres de script de suivi de votre domaine
Le script se charge avant la balise de fermeture </head>

2. Blocage par la Politique de Sécurité du Contenu (CSP)

Si vous disposez d'un en-tête CSP, ajoutez Zenovay à votre liste d'autorisation :

Content-Security-Policy: script-src 'self' https://api.zenovay.com; connect-src 'self' https://api.zenovay.com;

3. Bloqueur de publicités ou extension de confidentialité

Certaines extensions de navigateur peuvent bloquer les scripts d'analyse. Pour vérifier :

Ouvrez les outils de développement (F12)
Vérifiez l'onglet Console pour les demandes bloquées
Testez dans une fenêtre incognito sans extensions

Contrairement aux analyses traditionnelles, Zenovay respecte la vie privée et ne contient pas de cookies, donc il est moins susceptible d'être bloqué par les outils de confidentialité.

Script charge mais aucune donnée

Symptômes : Le script se charge avec succès mais le tableau de bord n'affiche aucun visiteur.

Solutions :

Vérifiez la Console du Navigateur

Ouvrez la Console des outils de développement et recherchez les erreurs :

// Vous devriez voir ceci si tout fonctionne correctement
[Zenovay] Tracking initialized for site: abc123
[Zenovay] Pageview tracked successfully

Vérifiez les Demandes Réseau

Ouvrez les outils de développement → onglet Réseau
Filtrez par "zenovay" ou "api.zenovay.com"
Recherchez les demandes POST vers /e/YOUR_TRACKING_CODE
Vérifiez si les demandes retournent 200 OK ou des codes d'erreur

Codes d'erreur courants :

Code d'état	Signification	Solution
401	ID de site invalide	Vérifiez à nouveau votre `data-tracking-code`
403	Bloqué par le pare-feu	Vérifiez les en-têtes CSP ou les règles du pare-feu
429	Limité en débit	Trop de demandes, attendez et réessayez
500	Erreur serveur	Contactez le support si cela persiste

Problèmes de placement du script

Zenovay détecte automatiquement les erreurs d'installation courantes et affiche des avertissements dans la console du navigateur. Vous verrez également des diagnostics dans le tableau de bord en cliquant sur Vérifier l'installation.

Où placer le script :

Placez toujours le script Zenovay dans la section <head> de votre HTML avec l'attribut defer :

Placement correctHTML

<head>
<!-- Autres balises head -->
<script defer data-id="YOUR_TRACKING_CODE" src="https://api.zenovay.com/z.js"></script>
</head>

Erreurs courantes :

Erreur	Problème	Solution
Script dans `<body>`	Peut manquer la première vue de page, charge trop tard	Déplacer vers `<head>`
Script à la fin de `<body>`	La page est complètement chargée avant que le suivi ne s'exécute	Déplacer vers `<head>`
`defer` manquant	Bloque le rendu de la page	Ajouter l'attribut `defer`
Scripts en double	Gonfle les vues de page et les métriques	Supprimer les balises de script supplémentaires
`data-id` incorrect	Les événements sont envoyés au mauvais site web	Copiez l'extrait depuis Domaines → votre site → Général

Guide spécifique au framework :

React : Utilisez useEffect dans votre composant App racine, ou ajoutez à public/index.html <head>
Next.js (App Router) : Utilisez le composant <Script> dans app/layout.tsx avec strategy="afterInteractive"
Next.js (Pages Router) : Ajoutez dans pages/_document.tsx à l'intérieur de <Head>
Vue : Ajoutez à public/index.html section <head>
WordPress : Utilisez le plugin "Insert Headers and Footers" → Scripts dans Header
Shopify : Ajoutez à theme.liquid avant </head>

Problèmes de proxy first-party :

Si vous utilisez un proxy first-party (par exemple, /api/_z/script.js) :

Vérifiez que l'URL du proxy retourne une réponse 200 (pas 404)
Vérifiez que le proxy transmet l'en-tête X-Zenovay-Real-IP
Essayez de charger https://api.zenovay.com/z.js directement pour isoler les problèmes de proxy et de script
Assurez-vous que la Politique de Sécurité du Contenu de votre serveur autorise les connexions à api.zenovay.com

Diagnostics de console :

Quand il y a des problèmes d'installation, vous verrez des messages comme :

⚠️ [Zenovay] Installation issue: Script should be in <head> for accurate tracking. Currently in <body>.
   → Fix: Move the <script> tag into your website's <head> section.
   → Docs: https://docs.zenovay.com/guides/troubleshooting#script-placement

Ces avertissements apparaissent une seule fois par session de navigateur et sont conçus pour vous aider à corriger votre configuration.

Événements non suivis

Symptômes : Les vues de page fonctionnent mais les événements personnalisés n'apparaissent pas.

Vérifiez la Syntaxe de l'Événement :

// Correct
window.zenovay('track', 'button_click', {
  button_name: 'signup',
  page: '/pricing'
});

// Incorrect (nom d'événement manquant)
window.zenovay('track',{
  button_name: 'signup'
});

Vérifiez que le Script est chargé :

// Vérifiez si Zenovay est disponible
if (window.zenovay) {
  console.log('Zenovay loaded');
  window.zenovay('track', 'custom_event');
} else {
  console.error('Zenovay not loaded yet');
}

Utilisez un Rappel Ready :

window.addEventListener('zenovay:ready', function() {
  // Zenovay est maintenant prêt
  window.zenovay('track', 'page_load_complete');
});

Problèmes de Tableau de Bord

Données ne mettant pas à jour

Symptômes : Le tableau de bord affiche des données anciennes ou ne met pas à jour en temps réel.

Solutions :

1. Vider le Cache du Navigateur

Appuyez sur Ctrl+Shift+R (Windows/Linux) ou Cmd+Shift+R (Mac) pour un rechargement forcé.

2. Vérifiez la Plage de Dates

Assurez-vous que le sélecteur de plage de dates affiche la période correcte :

Cliquez sur la liste déroulante de la plage de dates
Sélectionnez "Aujourd'hui" ou "Dernières 24 heures"
Vérifiez que le fuseau horaire est correct dans Paramètres → Compte → Préférences

3. Attendez le Traitement

Les données en temps réel apparaissent généralement en 1-2 secondes, mais :

Les métriques agrégées peuvent prendre 5-10 minutes
Les rapports historiques se mettent à jour toutes les heures

Zéro visiteur affichés

Symptômes : Le tableau de bord affiche "0 visiteur" malgré le trafic vers votre site.

Étapes de Diagnostic :

Vérifiez l'ID du Site : Ouvrez Domaines → votre site → Général et confirmez que le code de suivi correspond à celui de votre script
Vérifiez les Filtres : Supprimez tous les filtres actifs (localisation, appareil, source)
Testez Localement : Visitez votre site et vérifiez si vous apparaissez dans la vue en temps réel
Vérifiez les Exclusions : Ouvrez les paramètres de votre domaine et consultez la configuration des exclusions pour voir si votre IP est exclue

Par défaut, Zenovay exclut localhost et 127.0.0.1 du suivi pour éviter de compter le trafic de développement.

Nombres de visiteurs incorrects

Symptômes : Les compteurs de visiteurs ne correspondent pas aux attentes ou à d'autres outils d'analyse.

Raisons courantes :

1. Différences de Définition

Zenovay compte :

Visiteurs Uniques : Basé sur l'ID de visiteur anonymisé (fenêtre de 24 heures)
Visites : Sessions séparées (délai d'expiration de 30 minutes)
Vues de Page : Chaque chargement de page

D'autres outils peuvent utiliser des définitions ou des délais d'expiration de session différents.

2. Impact des Bloqueurs de Publicités

Certains visiteurs utilisent des bloqueurs de publicités qui peuvent :

Bloquer les analyses traditionnelles mais pas Zenovay (respectueux de la vie privée)
Bloquer toutes les analyses incluant Zenovay (paramètres agressifs)

3. Filtrage des Bots

Zenovay filtre automatiquement les bots et robots connus. D'autres outils peuvent :

Inclure le trafic des bots dans les compteurs
Utiliser des méthodes de détection de bots différentes

Problèmes d'Intégration

Plugin WordPress ne fonctionne pas

Symptômes : L'intégration WordPress ne suit pas les visiteurs.

Solutions :

1. Vérifiez l'Installation du Plugin

Allez à Plugins → Plugins Installés
Assurez-vous que "Zenovay Analytics" est activé
Vérifiez que la version est à jour

2. Vérifiez la Configuration de l'ID du Site

Allez à Paramètres → Zenovay
Vérifiez que l'ID du Site est entré correctement
Sauvegardez les modifications et videz le cache

3. Compatibilité du Thème

Certains thèmes peuvent entrer en conflit avec l'injection d'en-tête/pied de page :

// Ajoutez à votre functions.php du thème comme solution de secours
function zenovay_tracking_script() {
  ?>
  <script defer data-tracking-code="YOUR_TRACKING_CODE" src="https://api.zenovay.com/z.js"></script>
  <?php
}
add_action('wp_head', 'zenovay_tracking_script');

4. Conflits avec les Plugins de Mise en Cache

Si vous utilisez WP Super Cache, W3 Total Cache, ou similaire :

Videz tous les caches
Excluez le script Zenovay de la minification/combinaison
Testez en mode incognito

React/SPA ne suivant pas les changements de route

Symptômes : Seul le chargement de la page initiale est suivi, les changements de route ne sont pas comptés.

Solution : Mettez en œuvre le suivi de routage côté client :

import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function App() {
  const location = useLocation();

  useEffect(() => {
    // Track route changes
    if (window.zenovay) {
      window.zenovay('track', 'pageview', {
        path: location.pathname + location.search
      });
    }
  }, [location]);

  return <YourApp />;
}

Pour Next.js App Router :

'use client';
import { usePathname, useSearchParams } from 'next/navigation';
import { useEffect } from 'react';

export function AnalyticsTracker() {
  const pathname = usePathname();
  const searchParams = useSearchParams();

  useEffect(() => {
    if (window.zenovay) {
      window.zenovay('track', 'pageview');
    }
  }, [pathname, searchParams]);

  return null;
}

Problèmes d'API

Échecs d'Authentification

Symptômes : Les demandes API retournent 401 Non autorisé.

Vérifiez la Clé API :

# Testez votre clé API
curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.zenovay.com/api/external/v1/websites

Erreurs courantes :

Utilisation de l'ID du site au lieu de la clé API
En-tête X-API-Key manquant
Clé API expirée ou révoquée
Mauvaise clé API pour l'environnement (test vs production)

Générer une Nouvelle Clé API :

Allez à Paramètres → Sécurité → Clés API
Cliquez sur "Créer une Nouvelle Clé"
Copiez la clé immédiatement (affichée une seule fois)
Remplacez l'ancienne clé dans votre application

Limitation de Débit

Symptômes : L'API retourne 429 Trop de Demandes.

Vérifiez les En-têtes de Limite de Débit :

curl -I -H "X-API-Key: YOUR_API_KEY" \
  https://api.zenovay.com/api/external/v1/websites

Recherchez :

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1673456789

La valeur X-RateLimit-Limit reflète la limite par minute de votre plan (par exemple, 10 pour Free, 30 pour Pro, 60 pour Scale, 120 pour Enterprise).

Solutions :

Mettez en œuvre un backoff exponentiel (voir Limites de Débit)
Mettez en cache les réponses de l'API si possible
Regroupez les demandes au lieu de demandes individuelles
Envisagez de passer à un plan supérieur pour des limites plus élevées

Problèmes de Performance

Script ralentit le chargement de la page

Symptômes : Les temps de chargement de la page ont augmenté après l'ajout de Zenovay.

Vérifiez le Chargement Asynchrone :

Assurez-vous que le script dispose de l'attribut async :

<script defer data-tracking-code="YOUR_TRACKING_CODE" src="https://api.zenovay.com/z.js"></script>

Testez l'Impact :

Utilisez les outils de développement du navigateur ou Lighthouse :

Exécutez un audit Lighthouse avec et sans le script
Comparez les métriques "Temps d'interactivité"
Vérifiez le "Temps de Blocage"

Le script Zenovay fait généralement moins de 5 KB compressé et se charge de manière asynchrone, ajoutant moins de 50 ms au temps de chargement.

Tableau de bord charge lentement

Symptômes : Le tableau de bord prend beaucoup de temps pour charger les graphiques et les données.

Solutions :

1. Réduire la Plage de Dates

Le chargement de 12 mois de données est plus lent que 7 jours :

Utilisez des plages de dates plus courtes si possible
Appliquez des filtres pour réduire le volume de données

2. Vider les Données du Navigateur

Videz le cache et les cookies du navigateur
Désactivez les extensions du navigateur qui pourraient interférer
Essayez un navigateur différent

3. Vérifiez le Réseau

Testez la vitesse de votre connexion Internet
Essayez sur un réseau différent
Vérifiez si le pare-feu d'entreprise limite la bande passante

Problèmes de Précision des Données

Données géographiques manquantes

Symptômes : Certains visiteurs affichent une localisation "Inconnue".

Causes :

Utilisation d'un VPN ou d'un proxy par le visiteur
Navigateurs axés sur la vie privée qui masquent la localisation
Réseaux d'entreprise avec des adresses IP centralisées

Ce comportement est normal et affecte 5-15 % des visiteurs selon votre audience.

Le Référent Affiche comme "Direct"

Symptômes : La plupart du trafic s'affiche comme "Direct" au lieu de la source réelle.

Causes courantes :

1. Transitions HTTPS → HTTP

Le référent est supprimé lors du passage de HTTPS à HTTP. Solution : Utilisez HTTPS sur votre site.

2. Politique de Référent

Certains sites utilisent des politiques de référent strictes :

<meta name="referrer" content="no-referrer">

Il s'agit de la politique du site d'envoi, pas de quelque chose que vous pouvez contrôler.

3. Applications Mobiles et Email

Le trafic provenant des applications mobiles et des clients de messagerie s'affiche souvent comme direct - c'est normal et attendu.

Obtenir de l'Aide

Si vous rencontrez toujours des problèmes après avoir essayé ces solutions :

Vérifiez l'État du Service

Visitez status.zenovay.com pour voir s'il y a une panne connue ou un incident.

Collectez les Informations de Diagnostic

Avant de contacter le support, rassemblez :

Journaux de la Console du Navigateur :
- Ouvrez Outils de Développement → Console
- Copiez tous les messages d'erreur
- Prenez une capture d'écran
Demandes Réseau :
- Ouvrez Outils de Développement → Réseau
- Filtrez par "zenovay"
- Capture d'écran des demandes échouées avec codes d'état
Informations du Site :
- L'URL de votre site
- L'ID du site depuis le tableau de bord
- Plateforme/CMS (WordPress, personnalisé, etc.)
- Volume de trafic approximatif

Contactez le Support

Email : [email protected]

Incluez :

Description détaillée du problème
Étapes que vous avez déjà essayées
Informations de diagnostic ci-dessus
Captures d'écran ou enregistrements d'écran

Temps de Réponse :

Plan Free : 48-72 heures
Plans Payants : 24 heures
Enterprise : 4 heures (SLA)

Aide Communautaire

GitHub : github.com/zenovay
Documentation : Recherchez dans notre documentation des sujets spécifiques
Assistant IA : Utilisez le widget de chat sur n'importe quelle page de documentation

Dépannage

Problèmes de Script de Suivi

Script ne se charge pas

Script charge mais aucune donnée

Problèmes de placement du script

Événements non suivis

Problèmes de Tableau de Bord

Données ne mettant pas à jour

Zéro visiteur affichés

Nombres de visiteurs incorrects

Problèmes d'Intégration

Plugin WordPress ne fonctionne pas

React/SPA ne suivant pas les changements de route

Problèmes d'API

Échecs d'Authentification

Limitation de Débit

Problèmes de Performance

Script ralentit le chargement de la page

Tableau de bord charge lentement

Problèmes de Précision des Données

Données géographiques manquantes

Le Référent Affiche comme "Direct"

Obtenir de l'Aide

Vérifiez l'État du Service

Collectez les Informations de Diagnostic

Contactez le Support

Aide Communautaire

Ressources Supplémentaires