9 min de lectura

Overlay de depuración

Un overlay flotante, dentro de la página, que transmite cada evento que envía tu rastreador de Zenovay — tipo, props, modo sin cookies, estado de GPC, estado de consentimiento y versión del script — sin que tengas que abrir las devtools del navegador. La PII se enmascara. El overlay tiene doble protección: nunca se activa a menos que hayas dado tu consentimiento en la página de configuración del sitio web y hayas añadido ?zenovay_debug=1 a una URL de tu sitio.

Ambas protecciones son obligatorias. Activar solo el ajuste del sitio web no hace nada. Añadir solo ?zenovay_debug=1 no hace nada. Ambas deben ser ciertas en la misma carga de página. Esto evita una exposición accidental a visitantes generales.

Por qué usarlo

Cuando verificas una instalación — desarrollo local, staging o smoke test en producción — normalmente quieres confirmar un solo hecho: "¿está el rastreador disparando los eventos correctos con las props correctas?". La respuesta tradicional es: abrir devtools → pestaña Red → filtrar por /e/ o /api/_z → hacer clic en cada petición → leer el cuerpo JSON. El overlay de depuración condensa todo eso en un vistazo: cada evento que el rastreador envía aparece como una fila, haz clic en cualquier fila para ver el JSON completo y haz clic en "Copy JSON" para pegarlo en un ticket de soporte.

También es útil para incorporar a nuevos compañeros de equipo ("esto es exactamente lo que enviamos") y para documentar comportamientos intencionales (graba una captura del overlay durante un flujo de usuario conocido como bueno y guárdala como referencia de regresión).

Cómo activarlo

Inicia sesión en app.zenovay.com y abre la página Dominios.
Haz clic en el dominio que quieres depurar.
Abre Configuración → Avanzada, desplázate hasta la sección Configuración básica.
Activa Allow Debug Overlay.
En tu propio sitio, navega a cualquier URL con ?zenovay_debug=1 añadido — por ejemplo https://tu-sitio.com/?zenovay_debug=1 o https://tu-sitio.com/checkout?zenovay_debug=1.

El overlay aparece en la esquina inferior derecha aproximadamente un segundo después de que el rastreador se cargue.

Propagación de la caché: la configuración del rastreador se almacena en caché en el edge hasta 5 minutos después de cambiar el interruptor. Si el overlay no aparece de inmediato, recarga la página forzadamente (Cmd/Ctrl + Shift + R) o espera unos minutos.

Lo que verás

El overlay tiene tres regiones:

Las chips de la cabecera muestran el estado en tiempo de ejecución del rastreador en la página actual:

cookieless ON | OFF — si el modo sin cookies está activo para este sitio web. ON significa que el rastreador está usando IDs en memoria con scope de ventana y no escribe ninguna cookie. OFF significa que se están usando IDs de sesión/visitante basados en cookies.
GPC ON | OFF — si el navegador del visitante envió una señal Global Privacy Control (Sec-GPC: 1 / navigator.globalPrivacyControl === true). Cuando está ON, se omite el enriquecimiento conductual (B2B, scoring) en el servidor.
consent: <state> — el último estado de consentimiento que observó el rastreador (opt-in, opt-out, unknown). Si usas una plataforma de gestión de consentimiento, esto refleja la elección del visitante.
v<version> — la versión del script del rastreador que se está ejecutando actualmente en la página.

La lista de eventos muestra los 20 eventos salientes más recientes, con el más nuevo primero. Cada fila muestra:

Marca de tiempo de reloj de pared (HH:MM:SS, hora local del navegador)
Tipo de evento
Hasta 4 claves de propiedad abreviadas

Haz clic en cualquier fila para abrir el modal con el JSON.

El modal de JSON muestra el JSON completo del evento (después del enmascaramiento de PII). Usa el botón Copy JSON para copiarlo al portapapeles — útil para compartirlo con un compañero o adjuntarlo a un ticket de soporte.

Lectura de los tipos de evento

Tipo de evento	Qué significa
`pageview`	Se vio una nueva página. Incluye URL, referrer, parámetros UTM, clase de dispositivo y tamaño de pantalla.
`heartbeat`	El visitante sigue en la página. Se dispara cada ~2 segundos mientras está inactivo para que podamos calcular con precisión el tiempo en página.
`page_exit`	El visitante cerró la pestaña o navegó a otro sitio. Delta final del tiempo en página.
`outbound_link`	Un clic en una etiqueta `<a>` cuyo `href` apunta fuera de tu dominio.
`goal_completion`	Se disparó un objetivo configurado. Incluye el nombre del objetivo y cualquier parámetro personalizado.
`funnel_step`	El visitante avanzó a un paso de un embudo configurado.
`custom_event`	Una llamada `zenovay.track('event_name', {...})` desde tu propio código.
`error`	Un error de JavaScript capturado por el rastreador (solo se envía si el seguimiento de errores está habilitado en tu plan).
`core_web_vitals`	Mediciones de LCP / CLS / INP para la página actual (se envían una vez por página cuando las métricas se estabilizan).
`session_replay`	Se subió un fragmento de datos de session replay. El overlay solo muestra que el fragmento se envió — nunca el contenido de la grabación.
`frustration_signal`	Se detectó una señal de rage-click, dead-click o de scroll-jitter excesivo.

Enmascaramiento de PII

El overlay aplica una máscara del lado de la visualización a cada evento antes de mostrarlo en pantalla. La máscara cubre dos casos:

Coincidencia por nombre de campo (clave) — cualquier prop con uno de estos nombres de clave se sustituye por [MASKED]:

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

Coincidencia por patrón en el valor — se aplica incluso si el nombre de la clave no coincide:

Las cadenas que coinciden con la forma de un email ([email protected]) se redactan parcialmente (a***@b***.tld).
Las cadenas que coinciden con IPv4 (1.2.3.4) se reemplazan por [IP].
Las cadenas de más de 80 caracteres que contienen Mozilla|WebKit|Chrome|Safari|Firefox se truncan y se etiquetan como [UA truncated].

El enmascaramiento ocurre únicamente en la capa de visualización del overlay. El payload bruto del evento que el rastreador envía realmente a Zenovay no se modifica — eso es lo que alimenta tus paneles. La máscara solo afecta a lo que ves en pantalla, así que las capturas y el copy-paste del JSON desde el overlay son seguros para compartir.

Privacidad y cumplimiento

El overlay está diseñado para ser seguro de habilitar en cualquier entorno, pero aun así deberías entender exactamente qué hace y qué no:

Cero cookies, cero localStorage. El bus de eventos es un simple array de JavaScript en window (window._zenovayDebugBus). Desaparece cuando se cierra la pestaña.
Sin logging remoto. El overlay nunca hace una llamada de red. Todo lo que ves se renderiza a partir de datos que ya están en la memoria del navegador.
Carga diferida. La interfaz del overlay es un recurso HTTP independiente (/debug-overlay.js) que solo se descarga cuando ambas protecciones se cumplen. Los visitantes sin el parámetro de URL descargan cero bytes del overlay.
El invariante del rastreador sin cookies se preserva. Si tu sitio web está en modo sin cookies, habilitar el overlay no cambia el comportamiento del rastreador — no se escriben cookies, se usan los mismos IDs temporales con scope de ventana, y la chip de cookieless en la cabecera muestra ON.
GPC se respeta en todo caso. El overlay lee el estado de GPC desde la configuración del rastreador pero no lo omite.

Solución de problemas

"Añadí ?zenovay_debug=1 y no pasa nada."

Verifica que el ajuste del sitio web está activado. Ambas protecciones deben ser verdaderas.
Recarga la página forzadamente (Cmd/Ctrl + Shift + R) — la configuración del rastreador se almacena en caché hasta 5 minutos después de cambiar el interruptor.
Confirma que la versión de tu rastreador admite el overlay abriendo las devtools y ejecutando window.ZENOVAY_TRACKER_CONFIG — si allowDebugOverlay es false aunque el interruptor esté activado, la caché aún no se ha invalidado.
Comprueba que ninguna Content-Security-Policy en tu sitio bloquee scripts desde api.zenovay.com.

"El overlay aparece pero no se ven eventos."

Provoca una interacción en la página (haz clic en un enlace, desplaza, navega) para que el rastreador dispare algo.
Si sigues sin ver nada, puede que el rastreador no esté enviando — compáralo con Estado de la instalación, que sondea la misma ruta desde el lado del servidor.

"El overlay desaparece al cambiar de ruta en una SPA."

El overlay debería volver a montarse automáticamente al cambiar de ruta. Si no lo hace, es un caso extremo conocido con frameworks que podan agresivamente los hijos de document.body — por favor reporta una reproducción en help.zenovay.com.

"Tengo varios rastreadores de Zenovay en mi página."

Solo se monta un overlay. Gana el primer rastreador que se inicialice (guarda window._zenovayDebugOverlayMounted).

"Veo [MASKED] en campos que envié intencionalmente."

Eso es lo esperado. La máscara se aplica de forma incondicional a una lista de nombres de clave de PII comunes. Si necesitas mostrar un campo no-PII con un nombre que parezca sensible (p. ej. usaste name para una etiqueta no personal), renombra la prop y vuelve a probar.

"El overlay tapa una parte importante de mi UI."

Haz clic en la × en la cabecera para ocultar el overlay hasta la siguiente carga de página.

Cuándo desactivarlo

Recomendamos desactivar el interruptor Allow debug overlay en producción una vez que hayas verificado tu instalación. Aunque la doble protección evita la exposición accidental a visitantes ordinarios (que nunca añaden ?zenovay_debug=1), mantener desactivado el flag del lado del sitio web por defecto elimina por completo el segundo factor y hace imposible una exposición accidental — incluso si un desarrollador comparte por error una URL de depuración.

Compatibilidad con navegadores

El overlay funciona en todos los navegadores evergreen (Chrome, Firefox, Safari, Edge) y falla con elegancia en navegadores antiguos sin URLSearchParams o con CSP restrictiva — nunca lanza un error no controlado en la página anfitriona.

Relacionado

Estado de la instalación — sonda del lado del servidor de la actividad reciente de tu rastreador.
Script de seguimiento — referencia completa del snippet del rastreador, incluidos todos los atributos data-*.
Cumplimiento de privacidad — modo sin cookies, gestión de GPC, registro de consentimiento.