> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanova.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cómo funciona el seguimiento de conversiones

> El flujo de datos completo, del escaneo del código QR al informe de conversiones: modelo de atribución, vida de la sesión y procesamiento de los eventos.

## El recorrido del escaneo al informe

Esto es lo que ocurre desde que alguien escanea tu código QR hasta que ese evento aparece en tus informes.

```mermaid theme={null}
sequenceDiagram
  participant User as Visitante
  participant QR as Código QR
  participant Scanova as Redirección de Scanova
  participant Site as Tu web
  participant SDK as SDK del navegador
  participant API as API de seguimiento
  participant Reports as Analítica / Informes

  User->>QR: Escanea el código QR
  QR->>Scanova: Abre la URL corta scnv.io
  Scanova->>Site: Redirige a tu URL con ?scnv=<session_id>
  Site->>SDK: El SDK carga y lee el parámetro ?scnv
  SDK->>SDK: Guarda scan_session_id en localStorage
  SDK->>API: Envía el evento page_view con scan_session_id
  User->>Site: Hace clic, rellena un formulario, se desplaza
  SDK->>API: Envía eventos click / form_submit / scroll
  Site->>API: Tu servidor envía el evento purchase (desde el servidor)
  API->>Reports: Los eventos se procesan y se atribuyen al código QR
```

## La sesión de escaneo

El parámetro `scnv` de la URL es la clave de la atribución. Contiene un **ID de sesión de escaneo**: un UUID que identifica de forma única un escaneo concreto de un código QR concreto, hecho por una persona concreta en un momento concreto.

```
https://yoursite.com/landing?scnv=7ad26d4f-3181-4ef8-b6ca-b8f59499dd43
                                    └─────────────────────────────────────┘
                                           scan_session_id
```

Cuando el SDK del navegador carga en una página con ese parámetro, hace lo siguiente:

1. Lee el valor de `scnv` de la URL
2. Lo guarda en `localStorage` con una caducidad de 60 días
3. Lo adjunta como `scan_session_id` a cada evento que sale de ese navegador

Es decir: si la persona se marcha y vuelve dentro de esos 60 días, sus acciones posteriores se siguen atribuyendo al escaneo original.

## Atribución entre páginas y sesiones

El ID de sesión de escaneo se mantiene al navegar entre páginas del mismo dominio. Si alguien:

1. Escanea un código QR → llega a `/landing`
2. Hace clic hasta `/pricing`
3. Se registra en `/signup`

las tres páginas vistas se atribuyen al mismo escaneo, siempre que el SDK esté instalado en todas ellas.

## Eventos del navegador y eventos de servidor

Hay dos tipos de eventos:

| Tipo                      | Se envía desde                      | Autenticación         | Ideal para                                                   |
| ------------------------- | ----------------------------------- | --------------------- | ------------------------------------------------------------ |
| **Eventos del navegador** | El navegador del visitante, vía SDK | Ninguna (pública)     | Páginas vistas, clics, desplazamiento, envíos de formularios |
| **Eventos de servidor**   | Tu backend, vía API                 | Requiere clave de API | Compras, registros, leads y cualquier acción del servidor    |

Ambos tipos aceptan un `scan_session_id`, que los enlaza con el escaneo del código QR. Para los eventos de servidor, tu backend necesita recibir el `scan_session_id` del navegador, normalmente en un campo de formulario, una cookie de sesión o una llamada a tu API.

## Cómo se procesan los eventos

Cuando la API de seguimiento recibe un evento, este pasa por varias fases de procesamiento:

1. **Validación**: comprueba los campos obligatorios, el tamaño del contenido y la autorización del sitio y el dominio
2. **Deduplicación**: marca como duplicados los valores repetidos de `event_id` (se siguen guardando, no se descartan)
3. **Datos del dispositivo**: analiza el user-agent para extraer tipo de dispositivo, navegador y sistema operativo
4. **Datos de ubicación**: resuelve la dirección IP en país y ciudad mediante GeoIP
5. **Enlace de identidad**: resuelve el `scan_session_id` al ID del código QR y al ID de usuario en la base de datos de Scanova
6. **Detección de fraude**: puntuación heurística para señalar comportamientos propios de bots
7. **Privacidad y RGPD**: elimina los campos de datos personales si `consent` es `denied` o `pending`

Los eventos procesados aparecen en los informes del panel con un pequeño retardo de ingesta (normalmente menos de 10 segundos).

## Identidad y sesiones

Cada evento que envía el SDK lleva tres valores de identidad distintos. Entender la diferencia ayuda a leer los informes:

| Identidad         | Clave de cookie o almacenamiento | Duración                  | Qué representa                                                                                                        |
| ----------------- | -------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `scan_session_id` | `localStorage._scnv`             | 60 días                   | El escaneo concreto del código QR que inició este recorrido. Es la clave principal de atribución.                     |
| `web_session_id`  | Cookie `_scnv_ws`                | 30 minutos de inactividad | Una sesión de navegación continua. Se reinicia tras 30 minutos sin actividad, como cualquier sesión.                  |
| `visitor_id`      | Cookie `_scnv_vid`               | 1 año                     | Un identificador anónimo persistente del navegador. Permite reconocer a quien vuelve tras varias sesiones de escaneo. |

Un mismo visitante puede tener muchas sesiones web, y una sesión web muchos eventos. Todos los eventos de los 60 días siguientes a un escaneo comparten el mismo `scan_session_id`.

## Disponibilidad de los datos

* Los eventos se ingieren y se encolan en cuanto llegan
* Con carga normal, los eventos procesados aparecen en los informes en cuestión de segundos
* En picos de tráfico puede haber retrasos cortos, de hasta unos minutos
