> ## 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.

# How Conversion Tracking Works

> Understand the full data flow from QR Code scan to conversion report — attribution model, session lifecycle, and event pipeline explained.

## The scan-to-report journey

Here is what happens from the moment a user scans your QR Code to the moment that event appears in your reports.

```mermaid theme={null}
sequenceDiagram
  participant User
  participant QR as QR Code
  participant Scanova as Scanova Redirect
  participant Site as Your Website
  participant SDK as Browser SDK
  participant API as Tracking API
  participant Reports as Analytics / Reports

  User->>QR: Scans QR Code
  QR->>Scanova: Opens scnv.io short URL
  Scanova->>Site: Redirects to your URL with ?scnv=<session_id>
  Site->>SDK: SDK loads, reads ?scnv parameter
  SDK->>SDK: Saves scan_session_id to localStorage
  SDK->>API: Sends page_view event with scan_session_id
  User->>Site: Clicks a button, fills a form, scrolls
  SDK->>API: Sends click / form_submit / scroll events
  Site->>API: Your server sends purchase event (server-side)
  API->>Reports: Events processed and attributed to QR Code
```

## The scan session

The `scnv` query parameter is the key to attribution. It contains a **scan session ID** — a UUID that uniquely identifies a single scan of a single QR Code by a single user at a specific moment in time.

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

The Browser SDK does the following when it loads on a page with this parameter:

1. Reads the `scnv` value from the URL
2. Saves it to `localStorage` with a 60-day expiry
3. Attaches it as `scan_session_id` to every event sent from that browser

This means if the user navigates away and comes back within 60 days, their subsequent actions are still attributed to the original scan.

## Attribution across pages and sessions

The scan session ID persists across page navigations within the same domain. If a user:

1. Scans a QR Code → lands on `/landing`
2. Clicks through to `/pricing`
3. Signs up on `/signup`

All three page views are attributed to the same QR scan, as long as the SDK is installed on all pages.

## Browser events vs server events

There are two types of events:

| Type               | Sent from              | Auth             | Best for                                           |
| ------------------ | ---------------------- | ---------------- | -------------------------------------------------- |
| **Browser events** | User's browser via SDK | None (public)    | Page views, clicks, scroll, form submissions       |
| **Server events**  | Your backend via API   | API key required | Purchases, sign-ups, leads, any server-side action |

Both event types accept a `scan_session_id`, which links them to the QR scan. For server events, your backend needs to receive the `scan_session_id` from the browser — typically by passing it in a form field, session cookie, or API call.

## How events are processed

Once the Tracking API receives an event, it goes through a processing pipeline:

1. **Validation** — checks required fields, payload size, and site/domain authorization
2. **Deduplication** — marks repeated `event_id` values as duplicates (they are still stored, not dropped)
3. **Device enrichment** — parses user-agent to extract device type, browser, and OS
4. **Location enrichment** — resolves IP address to country and city using GeoIP
5. **Identity linking** — resolves `scan_session_id` to QR Code ID and user ID from the Scanova database
6. **Fraud detection** — heuristic scoring to flag bot-like behaviour
7. **Privacy / GDPR** — strips PII fields if `consent` is `denied` or `pending`

Processed events appear in your dashboard reports with a short ingestion delay (typically under 10 seconds).

## Identity and sessions

Each event the SDK sends carries three separate identity values. Understanding the difference helps when reading reports:

| Identity          | Cookie/Storage key   | Lifetime                 | What it represents                                                                                                                 |
| ----------------- | -------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| `scan_session_id` | `localStorage._scnv` | 60 days                  | The specific QR Code scan that started this user journey. The primary attribution key.                                             |
| `web_session_id`  | Cookie `_scnv_ws`    | 30 minutes of inactivity | One continuous browsing session. Resets after 30 minutes of inactivity, like a standard session.                                   |
| `visitor_id`      | Cookie `_scnv_vid`   | 1 year                   | A persistent anonymous identifier for a browser. Allows returning QR scan visitors to be recognised across multiple scan sessions. |

A single visitor may have many web sessions. A single web session may have many events. All events within 60 days of a scan share the same `scan_session_id`.

## Data availability

* Events are ingested and queued immediately on receipt
* Processed events appear in reports within seconds under normal load
* Short delays (up to a few minutes) can occur during high-traffic spikes