10 min de lecture

Surcouche de débogage

Une surcouche flottante intégrée à la page qui diffuse en continu chaque événement envoyé par votre traceur Zenovay — type, propriétés, mode sans cookie, état GPC, état de consentement et version du script — sans avoir à ouvrir les outils de développement du navigateur. Les données personnelles (PII) sont masquées. La surcouche est doublement protégée : elle ne s'active jamais sauf si vous l'avez activée dans les paramètres du site et ajouté ?zenovay_debug=1 à une URL de votre site.

Les deux conditions sont obligatoires. Activer le paramètre du site seul ne fait rien. Ajouter ?zenovay_debug=1 seul ne fait rien. Les deux doivent être vraies pour le même chargement de page. Cela évite toute exposition accidentelle aux visiteurs ordinaires.

Pourquoi l'utiliser

Lorsque vous vérifiez une installation — en local, en pré-production ou lors d'un test de mise en production — vous voulez généralement répondre à une seule question : « le traceur déclenche-t-il les bons événements avec les bonnes propriétés ? » La réponse traditionnelle consiste à : ouvrir les outils de développement → onglet Réseau → filtrer sur /e/ ou /api/_z → cliquer sur chaque requête → lire le corps JSON. La surcouche de débogage condense tout cela en un coup d'œil : chaque événement envoyé par le traceur apparaît sous forme de ligne, cliquez sur n'importe quelle ligne pour voir le JSON complet, cliquez sur « Copy JSON » pour le coller dans un ticket de support.

C'est également utile pour intégrer de nouveaux collègues (« voici exactement ce que nous envoyons ») et pour documenter un comportement intentionnel (capturez une capture d'écran de la surcouche pendant un parcours utilisateur connu et fiable, puis stockez-la comme référence pour détecter d'éventuelles régressions).

Comment l'activer

Connectez-vous sur app.zenovay.com et ouvrez la page Domaines.
Cliquez sur le domaine que vous souhaitez déboguer.
Ouvrez Paramètres → Avancé, faites défiler jusqu'à la section Paramètres de base.
Activez Allow Debug Overlay.
Sur votre propre site, accédez à n'importe quelle URL en y ajoutant ?zenovay_debug=1 — par exemple https://votre-site.com/?zenovay_debug=1 ou https://votre-site.com/checkout?zenovay_debug=1.

La surcouche apparaît dans le coin inférieur droit environ une seconde après le chargement du traceur.

Propagation du cache : la configuration du traceur est mise en cache à l'edge pendant jusqu'à 5 minutes après l'activation de la bascule. Si la surcouche n'apparaît pas immédiatement, rechargez la page sans cache (Cmd/Ctrl + Shift + R) ou patientez quelques minutes.

Ce que vous verrez

La surcouche comporte trois zones :

Pastilles d'en-tête qui affichent l'état d'exécution du traceur sur la page courante :

cookieless ON | OFF — indique si le mode sans cookie est actif pour ce site. ON signifie que le traceur utilise des identifiants en mémoire limités à la fenêtre et n'écrit aucun cookie. OFF signifie que des identifiants de session/visiteur basés sur les cookies sont utilisés.
GPC ON | OFF — indique si le navigateur du visiteur a envoyé un signal Global Privacy Control (Sec-GPC: 1 / navigator.globalPrivacyControl === true). Lorsqu'il est ON, l'enrichissement comportemental (B2B, scoring) est ignoré côté serveur.
consent: <state> — le dernier état de consentement observé par le traceur (opt-in, opt-out, unknown). Si vous utilisez une plateforme de gestion du consentement, cela reflète le choix du visiteur.
v<version> — la version du script du traceur actuellement exécutée sur la page.

Liste des événements qui affiche les 20 événements sortants les plus récents, du plus récent au plus ancien. Chaque ligne indique :

L'horodatage (HH:MM:SS, heure locale du navigateur)
Le type d'événement
Jusqu'à 4 clés de propriétés abrégées

Cliquez sur n'importe quelle ligne pour ouvrir la fenêtre modale JSON.

Fenêtre modale JSON qui affiche le JSON complet de l'événement (après masquage des données personnelles). Utilisez le bouton Copy JSON pour le copier dans votre presse-papiers — pratique pour le partager avec un collègue ou l'attacher à un ticket de support.

Comprendre les types d'événements

Type d'événement	Signification
`pageview`	Une nouvelle page a été consultée. Inclut l'URL, le referrer, les paramètres UTM, la classe d'appareil, la taille d'écran.
`heartbeat`	Le visiteur est toujours sur la page. Se déclenche toutes les ~2 secondes pendant l'inactivité afin de calculer précisément le temps passé sur la page.
`page_exit`	Le visiteur a fermé l'onglet ou navigué ailleurs. Delta final pour le temps passé sur la page.
`outbound_link`	Un clic sur une balise `<a>` dont le `href` pointe en dehors de votre domaine.
`goal_completion`	Un objectif configuré s'est déclenché. Inclut le nom de l'objectif et tout paramètre personnalisé.
`funnel_step`	Le visiteur a franchi une étape d'un entonnoir configuré.
`custom_event`	Un appel `zenovay.track('event_name', {...})` depuis votre propre code.
`error`	Une erreur JavaScript capturée par le traceur (envoyée uniquement si le suivi des erreurs est activé sur votre offre).
`core_web_vitals`	Mesures LCP / CLS / INP pour la page courante (envoyées une seule fois par page une fois les métriques stabilisées).
`session_replay`	Un fragment de données de session replay a été envoyé. La surcouche indique uniquement que le fragment a été expédié — jamais le contenu de l'enregistrement.
`frustration_signal`	Un rage-click, un dead-click ou un signal de défilement saccadé excessif a été détecté.

Masquage des données personnelles

La surcouche applique un masque côté affichage à chaque événement avant de l'afficher à l'écran. Le masque couvre deux cas :

Correspondance par nom de champ (clé) — toute propriété portant l'un de ces noms de clé est remplacée par [MASKED] :

email, phone, first_name, last_name, name, customer_id, user_id, ip, ip_address, client_ip, user_agent, useragent, ua

Correspondance par motif sur la valeur — appliquée même si le nom de la clé ne correspond pas :

Les chaînes correspondant au format e-mail ([email protected]) sont partiellement masquées (a***@b***.tld).
Les chaînes correspondant à une IPv4 (1.2.3.4) sont remplacées par [IP].
Les chaînes de plus de 80 caractères contenant Mozilla|WebKit|Chrome|Safari|Firefox sont tronquées et étiquetées [UA truncated].

Le masquage n'a lieu que dans la couche d'affichage de la surcouche. La charge utile brute de l'événement réellement envoyée à Zenovay par le traceur est inchangée — c'est elle qui alimente vos tableaux de bord. Le masque n'affecte que ce que vous voyez à l'écran, ce qui rend les captures d'écran et le copier-coller de JSON depuis la surcouche sans risque à partager.

Confidentialité et conformité

La surcouche est conçue pour pouvoir être activée sans risque dans n'importe quel environnement, mais vous devez tout de même comprendre exactement ce qu'elle fait et ne fait pas :

Aucun cookie, aucun localStorage. Le bus d'événements est un simple tableau JavaScript sur window (window._zenovayDebugBus). Il disparaît à la fermeture de l'onglet.
Aucune journalisation distante. La surcouche n'effectue jamais d'appel réseau. Tout ce que vous voyez est rendu à partir de données déjà présentes en mémoire du navigateur.
Chargée à la demande. L'interface de la surcouche est une ressource HTTP distincte (/debug-overlay.js) qui n'est téléchargée que lorsque les deux conditions sont satisfaites. Les visiteurs sans le paramètre d'URL ne téléchargent aucun octet de la surcouche.
L'invariant du traceur sans cookie est préservé. Si votre site est en mode sans cookie, l'activation de la surcouche ne modifie pas le comportement du traceur — aucun cookie n'est écrit, les mêmes identifiants temporaires limités à la fenêtre sont utilisés, et la pastille cookieless dans l'en-tête affiche ON.
GPC est respecté quoi qu'il arrive. La surcouche lit l'état GPC depuis la configuration du traceur mais ne le contourne pas.

Dépannage

« J'ai ajouté ?zenovay_debug=1 et rien ne se passe. »

Vérifiez que le paramètre du site est activé. Les deux conditions doivent être vraies.
Rechargez la page sans cache (Cmd/Ctrl + Shift + R) — la configuration du traceur est mise en cache jusqu'à 5 minutes après l'activation de la bascule.
Vérifiez que votre version du traceur prend en charge la surcouche en ouvrant les outils de développement et en exécutant window.ZENOVAY_TRACKER_CONFIG — si allowDebugOverlay vaut false alors que la bascule est activée, c'est que le cache n'a pas encore été invalidé.
Vérifiez qu'aucune Content-Security-Policy de votre site ne bloque les scripts provenant de api.zenovay.com.

« La surcouche s'affiche mais aucun événement n'apparaît. »

Déclenchez une interaction sur la page (cliquez sur un lien, faites défiler, naviguez) pour que le traceur envoie quelque chose.
Si vous ne voyez toujours rien, c'est peut-être que le traceur n'envoie pas — recoupez avec État de l'installation qui sonde la même chaîne côté serveur.

« La surcouche disparaît lors d'un changement de route SPA. »

La surcouche devrait se remonter automatiquement entre les changements de route. Si ce n'est pas le cas, il s'agit d'un cas limite connu avec les frameworks qui élaguent agressivement les enfants de document.body — merci de signaler une reproduction sur help.zenovay.com.

« Plusieurs traceurs Zenovay sur ma page. »

Une seule surcouche est montée. Le premier traceur à s'initialiser l'emporte (garde window._zenovayDebugOverlayMounted).

« Je vois [MASKED] pour des champs que j'ai envoyés intentionnellement. »

C'est attendu. Le masque est appliqué inconditionnellement à une liste de noms de clés PII courants. Si vous avez besoin d'afficher un champ non sensible portant un nom à l'apparence sensible (par exemple, vous avez utilisé name pour un libellé non personnel), renommez la propriété et retestez.

« La surcouche masque une partie importante de mon interface. »

Cliquez sur la × dans l'en-tête pour masquer la surcouche jusqu'au prochain chargement de page.

Quand la désactiver

Nous vous recommandons de désactiver la bascule Allow debug overlay en production une fois votre installation vérifiée. Bien que la double protection empêche toute exposition accidentelle aux visiteurs ordinaires (qui n'ont jamais ajouté ?zenovay_debug=1), garder le drapeau côté site désactivé par défaut supprime entièrement le second facteur et rend toute exposition accidentelle impossible — même si un développeur partage par mégarde une URL de débogage.

Compatibilité navigateurs

La surcouche fonctionne sur tous les navigateurs evergreen (Chrome, Firefox, Safari, Edge) et échoue gracieusement sur les anciens navigateurs sans URLSearchParams ou avec une CSP restrictive — elle ne lève jamais d'erreur non gérée dans la page hôte.

Ressources connexes

État de l'installation — sonde côté serveur de l'activité récente de votre traceur.
Script de suivi — référence complète de l'extrait du traceur, incluant tous les attributs data-*.
Conformité et confidentialité — mode sans cookie, gestion du GPC, enregistrement du consentement.