Problemas del SDK del navegador
No aparece ninguna petición de red a /ct
Comprueba esto en orden:
- El fragmento está en el sitio equivocado: tiene que ir en
<head>, no en <body> ni después de </html>
- Falta el
site_id: comprueba que scanova('init', 'YOUR_SITE_ID', ...) lleva un ID de sitio real y no un marcador de posición
- La Content Security Policy (CSP) bloquea el script: añade
https://cdn.scanova.io (script source) y https://t.scanova.io (connect source) a tus cabeceras de CSP
- Una extensión del navegador bloquea la petición: pruébalo en una ventana de incógnito con todas las extensiones desactivadas
autoPageview: false y ninguna llamada manual: activa autoPageview o añade scanova('track', 'pageview')- El SDK está cargado dos veces: tener a la vez la instalación directa en HTML y la de GTM en la misma página da problemas. Quita una de las dos.
403 Domain not allowed
El origen de tu petición no está en la lista Allowed Domains del sitio de seguimiento.
- Ve a Análisis → Seguimiento de conversiones
- Haz clic en tu sitio de seguimiento → Edit
- Añade exactamente el nombre de host que ves en la barra de direcciones del navegador (por ejemplo
yoursite.com o www.yoursite.com)
- Guarda
www.yoursite.com y yoursite.com se tratan como dominios distintos. Añade los dos si usas ambos.
La lista de dominios permitidos se comprueba contra el Origin de la petición (y, en su defecto, contra Referer). Por eso, reproducir un evento del navegador con curl o desde el servidor devuelve 403 Domain not allowed for this site aunque el dominio esté permitido: no se envía ninguna de las dos cabeceras. Añade -H "Origin: https://yoursite.com" cuando reproduzcas un evento del navegador a mano.
400: petición incorrecta
El site_id no es válido, está vacío o el sitio se ha desactivado en el panel. Comprueba que:
- Usas el
site_id correcto de este sitio de seguimiento
- El sitio está activo (aparece como habilitado en el panel)
- Espera hasta 60 segundos: hay un pequeño retardo de procesamiento
- Asegúrate de estar mirando el sitio de seguimiento correcto en el panel
- Comprueba que el
site_id del contenido de la petición coincide con el sitio que estás viendo
Se disparan dos eventos por carga de página
Tienes a la vez autoPageview: true en las opciones de init y una llamada manual a scanova('track', 'page_view', ...) en algún punto de tu código. Eso genera dos eventos distintos. Quita uno: consulta Eventos registrados automáticamente.
Una visita concreta no genera ningún evento
Si una visita no produce ninguna petición a /ct, lo más probable es que la persona llegara sin escanear un código QR: no hay parámetro ?scnv= en la URL. El SDK comprueba que existe un scan_session_id antes de enviar cualquier evento y, si no lo hay, no envía nada.
El seguimiento de conversiones de Scanova solo mide el tráfico que viene de un escaneo. Las visitas directas u orgánicas no generan eventos: es intencionado.
Para probar la atribución, abre tu página con un parámetro ?scnv= y simula así un escaneo:
Problemas de los eventos de servidor
401: falta la clave de API
La petición no incluye la cabecera X-API-Key. Consulta Autenticación.
403: clave no válida o sitio equivocado
O la clave no es válida o está revocada, o el site_id de tu petición no corresponde al sitio que generó la clave. Comprueba que:
- Vuelves a copiar la clave desde el panel (las claves se muestran una vez; si la has perdido, genera otra)
- El
site_id de tu petición es el mismo ID de sitio que aparece en la lista de sitios de seguimiento de conversiones
- La clave no se ha revocado
422: error de validación
La respuesta indica exactamente qué campo ha fallado. Causas habituales:
Los eventos llegan pero no se atribuyen a ningún código QR
El scan_session_id que enviaste no se ha podido enlazar con ningún escaneo en la base de datos de Scanova. Esto ocurre cuando:
- El
scan_session_id era inventado o no válido
- La persona no llegó a escanear ningún código QR: entró directamente
- La sesión de escaneo ha caducado
Comprueba que lees el scan_session_id del navegador (en localStorage._scnv, una clave de almacenamiento interna del SDK) y que lo pasas correctamente a tu servidor. Consulta Enviar eventos de servidor for examples.
Problemas de atribución
Los eventos muestran null en qr_code_id
Es un registro huérfano: el evento llegó antes de que los datos de la sesión de escaneo se propagaran del todo en la base de datos de Scanova. Estos registros se eliminan automáticamente a las 24 horas si los datos de sesión no llegan nunca, o se completan en cuanto llegan.
Si ves muchos registros huérfanos, comprueba que:
- El
scan_session_id de tus eventos corresponde a una sesión de escaneo real (y no a un UUID de prueba)
- Tus códigos QR están bien enlazados con el sitio de seguimiento en el panel
Las conversiones aparecen en el código QR equivocado
Tu scan_session_id no se está leyendo bien: puede que estés recuperando un valor obsoleto o incorrecto de localStorage. Comprueba que tu frontend lee localStorage.getItem('_scnv') (la clave de almacenamiento interna del SDK) y extrae .sid del valor JSON. Consulta Enviar eventos de servidor for the full pattern.
Problemas de rendimiento
429: límite de frecuencia superado
Estás alcanzando el límite de frecuencia:
- Eventos del navegador: 100 peticiones por minuto y dirección IP
- Eventos de servidor: 1000 peticiones por minuto y clave de API
En los eventos de servidor, cambia al endpoint de lotes (POST /server-events/batch) para enviar hasta 100 eventos por petición y reducir tu ritmo de peticiones hasta cien veces.
En los eventos del navegador, ver un 429 en uso normal es raro. Si aparece durante pruebas de carga, espacia tus peticiones.
