12 min de lectura

Solución de problemas

Esta guía cubre los problemas comunes que puedes encontrar al usar Zenovay y cómo resolverlos.

Problemas del Script de Seguimiento

Script No Se Carga

Síntomas: No aparecen datos en tu panel después de instalar el script de seguimiento.

Causas Posibles y Soluciones:

1. Script No Instalado Correctamente

Verifica que el script esté en la sección <head> de tu página:

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

Comprueba que:

La URL del script es correcta
Tu data-tracking-code coincide con el código que aparece en la configuración del script de seguimiento de tu dominio
El script se carga antes de cerrar la etiqueta </head>

2. Política de Seguridad de Contenido (CSP) Bloqueando

Si tienes una cabecera CSP, añade Zenovay a tu lista de permitidos:

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

3. Bloqueador de Anuncios o Extensión de Privacidad

Algunas extensiones del navegador pueden bloquear scripts de análisis. Para verificar:

Abre DevTools (F12)
Comprueba la pestaña Console para solicitudes bloqueadas
Prueba en una ventana incógnita sin extensiones

A diferencia del análisis tradicional, Zenovay es amigable con la privacidad y sin cookies, por lo que es menos probable que sea bloqueado por herramientas de privacidad.

Script Se Carga Pero Sin Datos

Síntomas: El script se carga correctamente pero el panel no muestra visitantes.

Soluciones:

Comprueba la Consola del Navegador

Abre la consola de DevTools y busca errores:

// Deberías ver esto si funciona correctamente
[Zenovay] Tracking initialized for site: abc123
[Zenovay] Pageview tracked successfully

Verifica Solicitudes de Red

Abre DevTools → pestaña Network
Filtra por "zenovay" o "api.zenovay.com"
Busca solicitudes POST a /e/YOUR_TRACKING_CODE
Comprueba si las solicitudes devuelven 200 OK o códigos de error

Códigos de Error Comunes:

Código de Estado	Significado	Solución
401	ID de sitio inválido	Verifica tu `data-tracking-code`
403	Bloqueado por firewall	Comprueba cabeceras CSP o reglas de firewall
429	Límite de velocidad excedido	Demasiadas solicitudes, espera e intenta de nuevo
500	Error del servidor	Contacta con soporte si persiste

Problemas de Ubicación del Script

Zenovay detecta automáticamente errores comunes de instalación y muestra advertencias en la consola del navegador. También verás diagnósticos en el panel cuando hagas clic en Verify Installation.

Dónde colocar el script:

Siempre coloca el script de Zenovay en la sección <head> de tu HTML con el atributo defer:

Colocación correctaHTML

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

Errores comunes:

Error	Problema	Solución
Script en `<body>`	Puede perder la primera vista de página, se carga demasiado tarde	Mueve a `<head>`
Script al final de `<body>`	La página se carga completamente antes de que se ejecute el rastreador	Mueve a `<head>`
Falta `defer`	Bloquea la renderización de la página	Añade el atributo `defer`
Scripts duplicados	Infla las vistas de página y métricas	Elimina etiquetas de script adicionales
`data-id` incorrecto	Los eventos se envían al sitio web equivocado	Copia el fragmento de Domains → tu sitio → General

Orientación específica del framework:

React: Usa useEffect en tu componente raíz App, o añade a public/index.html <head>
Next.js (App Router): Usa el componente <Script> en app/layout.tsx con strategy="afterInteractive"
Next.js (Pages Router): Añade en pages/_document.tsx dentro de <Head>
Vue: Añade a public/index.html sección <head>
WordPress: Usa el plugin "Insert Headers and Footers" → Scripts in Header
Shopify: Añade a theme.liquid antes de </head>

Problemas del proxy de primera parte:

Si usas un proxy de primera parte (por ejemplo, /api/_z/script.js):

Verifica que la URL del proxy devuelve una respuesta 200 (no 404)
Comprueba que el proxy reenvía la cabecera X-Zenovay-Real-IP
Intenta cargar https://api.zenovay.com/z.js directamente para aislar problemas de proxy versus script
Asegúrate de que la Política de Seguridad de Contenido de tu servidor permite conexiones a api.zenovay.com

Diagnósticos de consola:

Cuando hay problemas de instalación, verás mensajes como:

⚠️ [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

Estas advertencias aparecen una vez por sesión del navegador y están diseñadas para ayudarte a corregir tu configuración.

Eventos No Se Rastrean

Síntomas: Las vistas de página funcionan pero los eventos personalizados no aparecen.

Comprueba la Sintaxis del Evento:

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

// Incorrecto (falta el nombre del evento)
window.zenovay('track',{
  button_name: 'signup'
});

Verifica que el Script Se Cargó:

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

Usa Callback Listo:

window.addEventListener('zenovay:ready', function() {
  // Zenovay está ahora listo
  window.zenovay('track', 'page_load_complete');
});

Problemas del Panel

Los Datos No Se Actualizan

Síntomas: El panel muestra datos antiguos o no se actualiza en tiempo real.

Soluciones:

1. Limpia la Caché del Navegador

Presiona Ctrl+Shift+R (Windows/Linux) o Cmd+Shift+R (Mac) para hacer una actualización dura.

2. Comprueba el Rango de Fechas

Asegúrate de que el selector de rango de fechas muestre el período correcto:

Haz clic en la lista desplegable de rango de fechas
Selecciona "Hoy" o "Últimas 24 horas"
Verifica la zona horaria es correcta en Settings → Account → Preferences

3. Espera el Procesamiento

Los datos en tiempo real normalmente aparecen en 1-2 segundos, pero:

Las métricas agregadas pueden tardar 5-10 minutos
Los informes históricos se actualizan cada hora

Cero Visitantes Mostrándose

Síntomas: El panel muestra "0 visitantes" a pesar del tráfico a tu sitio.

Pasos de Diagnóstico:

Verifica ID del Sitio: Abre Domains → tu sitio → General y confirma que el código de seguimiento coincide con lo que está en tu script
Comprueba Filtros: Elimina los filtros activos (ubicación, dispositivo, fuente)
Prueba Localmente: Visita tu sitio y comprueba si apareces en la vista en tiempo real
Revisa Exclusiones: Abre la configuración de tu dominio y comprueba la configuración de exclusiones para ver si tu IP está excluida

Por defecto, Zenovay excluye localhost y 127.0.0.1 del seguimiento para evitar contar el tráfico de desarrollo.

Números de Visitantes Incorrectos

Síntomas: Los recuentos de visitantes no coinciden con las expectativas u otras herramientas de análisis.

Razones Comunes:

1. Diferencias de Definición

Zenovay cuenta:

Visitantes Únicos: Basado en ID de visitante anonimizado (ventana de 24 horas)
Visitas: Sesiones separadas (tiempo de espera de 30 minutos)
Vistas de Página: Cada carga de página

Otras herramientas pueden usar definiciones diferentes o tiempos de espera de sesión diferentes.

2. Impacto del Bloqueador de Anuncios

Algunos visitantes usan bloqueadores de anuncios que pueden:

Bloquear análisis tradicional pero no Zenovay (amigable con la privacidad)
Bloquear todo análisis incluyendo Zenovay (configuración agresiva)

3. Filtrado de Bots

Zenovay filtra automáticamente bots y rastreadores conocidos. Otras herramientas pueden:

Incluir el tráfico de bots en los recuentos
Usar métodos diferentes de detección de bots

Problemas de Integración

Plugin de WordPress No Funciona

Síntomas: La integración de WordPress no rastrea visitantes.

Soluciones:

1. Verifica la Instalación del Plugin

Ve a Plugins → Plugins Instalados
Asegúrate de que "Zenovay Analytics" está activado
Comprueba que la versión es la más reciente

2. Comprueba la Configuración del ID del Sitio

Ve a Settings → Zenovay
Verifica que ID del Sitio se ingresó correctamente
Guarda los cambios y limpia la caché

3. Compatibilidad del Tema

Algunos temas pueden entrar en conflicto con la inyección de encabezado/pie de página:

// Añade a tu functions.php del tema como alternativa
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. Conflictos de Plugin de Caché

Si usas WP Super Cache, W3 Total Cache, o similar:

Limpia todas las cachés
Excluye el script de Zenovay de minificación/combinación
Prueba en modo incógnito

React/SPA No Rastrea Cambios de Ruta

Síntomas: Solo se rastrea la carga inicial de la página, los cambios de ruta no se cuentan.

Solución: Implementa el rastreo de enrutamiento del lado del cliente:

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

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

  useEffect(() => {
    // Rastrea cambios de ruta
    if (window.zenovay) {
      window.zenovay('track', 'pageview', {
        path: location.pathname + location.search
      });
    }
  }, [location]);

  return <YourApp />;
}

Para 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;
}

Problemas de API

Fallos de Autenticación

Síntomas: Las solicitudes de API devuelven 401 No Autorizado.

Comprueba la Clave de API:

# Prueba tu clave de API
curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.zenovay.com/api/external/v1/websites

Errores Comunes:

Usar ID de sitio en lugar de clave de API
Falta la cabecera X-API-Key
Clave de API expirada o revocada
Clave de API incorrecta para el entorno (prueba versus producción)

Genera Nueva Clave de API:

Ve a Settings → Security → API keys
Haz clic en "Create New Key"
Copia la clave inmediatamente (se muestra solo una vez)
Reemplaza la clave antigua en tu aplicación

Límite de Velocidad

Síntomas: API devuelve 429 Demasiadas Solicitudes.

Comprueba Cabeceras de Límite de Velocidad:

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

Busca:

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

El valor de X-RateLimit-Limit refleja el límite por minuto de tu plan (por ejemplo, 10 para Free, 30 para Pro, 60 para Scale, 120 para Enterprise).

Soluciones:

Implementa retroceso exponencial (ver Rate Limits)
Cachea respuestas de API donde sea posible
Agrupa solicitudes en lugar de llamadas individuales
Considera actualizar tu plan para límites más altos

Problemas de Rendimiento

Script Ralentiza la Carga de Página

Síntomas: Los tiempos de carga aumentaron después de añadir Zenovay.

Verifica Carga Asincrónica:

Asegúrate de que el script tiene el atributo async:

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

Prueba Impacto:

Usa DevTools del navegador o Lighthouse:

Ejecuta auditoría Lighthouse con y sin script
Compara métricas "Time to Interactive"
Comprueba "Blocking Time"

El script de Zenovay típicamente es < 5KB comprimido y se carga de forma asincrónica, añadiendo < 50ms a la carga de página.

Panel Se Carga Lentamente

Síntomas: El panel tarda mucho tiempo en cargar gráficos y datos.

Soluciones:

1. Reduce Rango de Fechas

Cargar 12 meses de datos es más lento que 7 días:

Usa rangos de fechas más cortos cuando sea posible
Aplica filtros para reducir el volumen de datos

2. Limpia Datos del Navegador

Limpia caché y cookies del navegador
Desactiva extensiones del navegador que puedan interferir
Prueba con un navegador diferente

3. Comprueba la Red

Prueba la velocidad de tu conexión a internet
Intenta en una red diferente
Comprueba si el firewall corporativo está limitando

Problemas de Precisión de Datos

Datos Geográficos Faltantes

Síntomas: Algunos visitantes muestran ubicación "Unknown".

Causas:

Uso de VPN o proxy por el visitante
Navegadores centrados en privacidad que enmascaran ubicación
Redes corporativas con direcciones IP centralizadas

Este es un comportamiento esperado y afecta el 5-15% de visitantes dependiendo de tu audiencia.

Referencia Muestra como "Direct"

Síntomas: La mayoría del tráfico muestra como "Direct" en lugar de fuente real.

Causas Comunes:

1. Transiciones HTTPS → HTTP

El referencia se elimina al pasar de HTTPS a HTTP. Solución: Usa HTTPS en tu sitio.

2. Política de Referencia

Algunos sitios usan políticas de referencia estrictas:

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

Esta es la política del sitio de envío, no algo que puedas controlar.

3. Aplicaciones Móviles y Correo Electrónico

El tráfico desde aplicaciones móviles y clientes de correo electrónico a menudo aparece como directo - esto es normal y esperado.

Obteniendo Ayuda

Si aún experimentas problemas después de intentar estas soluciones:

Comprueba Estado del Servicio

Visita status.zenovay.com para ver si hay una interrupción o incidente conocido.

Recopila Información de Diagnóstico

Antes de contactar con soporte, recopila:

Registros de Consola del Navegador:
- Abre DevTools → Console
- Copia cualquier mensaje de error
- Toma una captura de pantalla
Solicitudes de Red:
- Abre DevTools → Network
- Filtra por "zenovay"
- Captura de pantalla de solicitudes fallidas con códigos de estado
Información del Sitio:
- URL de tu sitio
- ID del Sitio del panel
- Plataforma/CMS (WordPress, personalizado, etc.)
- Volumen de tráfico aproximado

Contacta con Soporte

Email: [email protected]

Incluye:

Descripción detallada del problema
Pasos que ya has intentado
Información de diagnóstico de arriba
Capturas de pantalla o grabaciones de pantalla

Tiempos de Respuesta:

Plan Gratuito: 48-72 horas
Planes Pagados: 24 horas
Enterprise: 4 horas (SLA)

Ayuda de la Comunidad

GitHub: github.com/zenovay
Documentación: Busca en nuestros documentos temas específicos
Asistente de IA: Usa el widget de chat en cualquier página de documentación

Solución de problemas

Problemas del Script de Seguimiento

Script No Se Carga

Script Se Carga Pero Sin Datos

Problemas de Ubicación del Script

Eventos No Se Rastrean

Problemas del Panel

Los Datos No Se Actualizan

Cero Visitantes Mostrándose

Números de Visitantes Incorrectos

Problemas de Integración

Plugin de WordPress No Funciona

React/SPA No Rastrea Cambios de Ruta

Problemas de API

Fallos de Autenticación

Límite de Velocidad

Problemas de Rendimiento

Script Ralentiza la Carga de Página

Panel Se Carga Lentamente

Problemas de Precisión de Datos

Datos Geográficos Faltantes

Referencia Muestra como "Direct"

Obteniendo Ayuda

Comprueba Estado del Servicio

Recopila Información de Diagnóstico

Contacta con Soporte

Ayuda de la Comunidad

Recursos Adicionales