Pruebas en Localhost

De manera predeterminada, Zenovay bloquea el rastreo en localhost y otros entornos locales para evitar que los datos de prueba contaminen tu analítica. Puedes habilitar el rastreo local para desarrollo y pruebas.

Habilitar el Rastreo en Localhost

Opción 1: Alternancia del Panel de Control (Recomendado)

1. Ve a tu Panel de Control de Zenovay
2. Abre Dominios y haz clic en tu sitio
3. En la configuración del dominio, abre la sección Avanzado
4. Habilita el alternador "Permitir Localhost"
5. Haz clic en guardar

Opción 2: Atributo de Script

Si prefieres controlar esto por entorno a través de tu HTML, añade data-allow-localhost="true" a la etiqueta del script:

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

Nota: la configuración del panel de control anterior es el control efectivo. El servidor solo acepta eventos de localhost cuando está habilitada, y la carga de configuración del tracker tiene prioridad sobre este atributo. Conserva el atributo para el desarrollo sin conexión (cuando la carga de configuración no puede completarse); no tiene efecto en dominios de producción.

Opción 3: Carga Dinámica de Script

Para frameworks como React o Next.js donde cargas el script dinámicamente:

const script = document.createElement('script');
script.src = 'https://api.zenovay.com/z.js';
script.defer = true;
script.setAttribute('data-tracking-code', 'YOUR_TRACKING_CODE');
script.setAttribute('data-allow-localhost', 'true');
document.head.appendChild(script);

Cómo Funciona

El rastreador de Zenovay detecta entornos locales comprobando el nombre de host:

Cuando se detecta un entorno local, el rastreador verifica dos cosas (en orden):

1. Configuración del servidor — El rastreador obtiene la configuración de tu sitio web desde la API de Zenovay. Si allow_localhost está habilitado en el panel de control, el rastreo continúa.
2. Atributo del script — Si la llamada a la API falla o no se ha completado, el atributo data-allow-localhost="true" en la etiqueta del script actúa como respaldo.

Si ninguno está configurado, el rastreo se bloquea y verás este mensaje en la consola del navegador:

[Zenovay] Environment blocked — Localhost blocked (use data-allow-localhost='true' to enable)

Verificar que Funciona

Consola del Navegador

Abre DevTools (F12) → pestaña Consola. Con el rastreo en localhost habilitado, deberías ver:

Zenovay Analytics loaded { trackingCode: "ZV_...", reason: "Active" }

Si localhost está bloqueado, verás:

[Zenovay] Environment blocked { reason: "Localhost blocked (use data-allow-localhost='true' to enable)" }

Pestaña Red

Abre DevTools → pestaña Red y filtra por zenovay o api.zenovay.com:

1. GET z.js — Script cargado (200 OK)
2. GET /api/websites/settings/ZV_... — Obtención de configuración (200 OK, la respuesta incluye allow_localhost: true)
3. POST /e/ZV_... — Evento de vista de página rastreado (200 OK)

Si el paso 3 devuelve 403, tu verificación de dominio está bloqueando la solicitud. Asegúrate de que allow_localhost está habilitado en la configuración de tu panel de control.

Panel de Control

Después de una carga de página en localhost, ve a tu panel de control de Zenovay. Abre Dominios, selecciona tu sitio, y abre la pestaña Analíticas. En el desglose de Hosts, deberías ver localhost (o 127.0.0.1) listado como una fuente.

Modo de Depuración vs Permitir Localhost

Estas son dos configuraciones separadas con diferentes propósitos:

Puedes habilitar ambas durante el desarrollo para máxima visibilidad, pero funcionan de forma independiente.

• Permitir Localhost solo controla si el rastreo se ejecuta en localhost
• Modo de Depuración solo controla si la salida de depuración aparece en la consola

Usar con el Endpoint de Carga

Si usas el endpoint /load (recomendado para producción), la configuración de localhost se inyecta automáticamente por el servidor:

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

Con el endpoint /load, solo necesitas habilitar "Permitir Localhost" en el panel de control — no se requiere el atributo data-allow-localhost.

Proxy de Primera Parte en Localhost

Si tu configuración de producción usa un proxy de primera parte (p. ej., /api/_z/script.js), el proxy típicamente no funcionará en localhost ya que es una ruta del lado del servidor que reenvía a api.zenovay.com.

Soluciones:

1. Usar el script directo en localhost: Cambia a https://api.zenovay.com/z.js en desarrollo
2. Configurar un proxy local: Configura tu servidor de desarrollo para reenviar /api/_z/ a https://api.zenovay.com/
3. Usar URL de script basado en entorno: Carga desde tu proxy en producción, directo en desarrollo

const isDev = window.location.hostname === 'localhost';
const script = document.createElement('script');
script.src = isDev
? 'https://api.zenovay.com/z.js'
: '/api/_z/script.js';
script.defer = true;
script.setAttribute('data-tracking-code', 'YOUR_TRACKING_CODE');
if (isDev) script.setAttribute('data-allow-localhost', 'true');
document.head.appendChild(script);

Resolución de Problemas

El rastreo no funciona en localhost

1. Comprueba la configuración del panel de control: Abre Dominios, selecciona tu sitio, abre la sección Avanzado y verifica que "Permitir Localhost" está habilitado
2. Actualización forzada: Los cambios tardan hasta 30 segundos. Haz Ctrl+Mayús+R para limpiar los scripts en caché
3. Comprueba la consola: Abre DevTools y busca mensajes [Zenovay]
4. Verifica que el script se carga: Comprueba la pestaña Red para que z.js devuelva 200
5. Comprueba los bloqueadores de anuncios: Las extensiones del navegador pueden bloquear analíticas incluso en localhost

Los eventos devuelven 403

La API rechazó tu solicitud de rastreo debido a la verificación de dominio. Esto significa:

• allow_localhost no está habilitado en la configuración de tu sitio web, O
• La configuración aún no se ha propagado (espera 30 segundos e intenta de nuevo)

Los eventos se activan pero los datos no aparecen en el panel de control

Los datos de localhost aparecen en tu analítica junto a los datos de producción. Comprueba:

• Pestaña Hosts en Analíticas — busca entradas de localhost
• Filtros — asegúrate de que no estés filtrando el tráfico de localhost
• Rango de tiempo — asegúrate de que estés viendo datos de hoy