How It Works

TRACIO è un sistema di identificazione client-server. Il client raccoglie i segnali del browser e li invia al server, che calcola un identificatore stabile del visitatore, esegue algoritmi di rilevamento e restituisce risultati arricchiti. Questa sezione spiega ogni fase della pipeline.

Panoramica dell'architettura

Browser                              TRACIO Cloud
  |                                      |
  |-- Tracio.init({ publicKey }) ---------> |  (init, no network)
  |                                      |
  |-- tracio.getResult() ----------------> |
  |   1. Collect 130+ browser signals    |
  |   2. Encrypt (XOR + deflate + B64)   |
  |   3. POST to ingress endpoint        |
  |                                      |
  |                                      |-- Decrypt & extract signals
  |                                      |-- Compute visitor ID (MurmurHash3-128)
  |                                      |-- Run bot detection (weighted scoring)
  |                                      |-- Run smart signals (server-side enrichment)
  |                                      |-- Run IP intelligence (VPN/proxy/Tor)
  |                                      |-- Store visit event
  |                                      |
  |<-- JSON response ------------------- |
  |    visitorId, confidence,            |
  |    bot detection, smart signals      |
  |                                      |
  |-- Store visitor cookie (_vid_t) -----> |  (365-day persistence)

Fase 1: Raccolta dei segnali

Quando viene chiamato tracio.getResult(), il client raccoglie 130+ segnali distinti del browser organizzati in livelli. La raccolta utilizza una pipeline multi-fase con Web Worker e iframe condivisi per le prestazioni.

Categorie di segnali

Pipeline di raccolta

La pipeline di raccolta viene eseguita in quattro fasi per ridurre al minimo il blocco del main thread:

1. Fase 1 (Immediata): segnali ad alta priorità che sono rapidi da raccogliere (proprietà di navigator, schermo, fuso orario). Anche il probe TURN parte qui poiché viene eseguito in modo concorrente.

2. Fase 2 (Idle Callback): segnali sincroni che traggono vantaggio da un periodo di inattività (media query CSS, probe dello storage, test dei cookie).

3. Fase 3 (Async): segnali che richiedono API asincrone o rendering (canvas, WebGL, fingerprint audio, rilevamento dei font, rendering delle emoji).

4. Web Worker: raccolta isolata dei segnali in un thread dedicato (rilevamento delle funzionalità WASM, doNotTrack).

Un iframe nascosto condiviso viene creato una sola volta e riutilizzato da più collector (emoji, MathML, colori di sistema, font, frame dello schermo) per evitare l'overhead della creazione di iframe separati per ogni segnale.

Formato dei segnali

Ogni segnale segue una struttura coerente:

interface Signal<T> {
  s: number // Status code
  v: T // Value (when successful)
}

Codici di stato:

Fase 2: Trasporto crittografato

I segnali raccolti vengono serializzati in JSON, quindi crittografati e compressi prima della trasmissione:

1. Serializzazione JSON: tutti i valori dei segnali vengono impacchettati in un oggetto JSON con chiave per segnale, più campi di metadati (c per la chiave API, t per il tag, lid per il linked ID).

2. Compressione: se il payload supera i 1024 byte, viene compresso usando CompressionStream("deflate-raw").

3. Crittografia XOR: il payload viene racchiuso in un envelope di crittografia:

   • Un byte di chiave XOR casuale
   • Byte di header (marcatori di validazione)
   • Padding casuale (0-3 byte)
   • Una maschera XOR di 9 byte
   • Il payload sottoposto a XOR con la maschera ripetuta

4. Codifica Base64: il payload crittografato viene codificato in Base64url e inviato come corpo del POST.

La richiesta viene inviata all'endpoint di ingress con parametri di query per la versione del client e la chiave API. Le credenziali CORS sono incluse per inviare i cookie di prima parte.

Fase 3: Elaborazione lato server

Il server riceve il payload crittografato e lo elabora attraverso diversi sottosistemi:

Estrazione dei segnali

Il server decodifica l'envelope XOR, decomprime se necessario e analizza i dati JSON dei segnali. Il codice di stato e il valore di ciascun segnale vengono estratti e validati.

Calcolo dell'ID visitatore

L'ID visitatore viene calcolato usando un approccio di hashing a livelli (V3):

Tier 1 (Frozen): 20 base62 characters
  - Stable hardware signals that rarely change
  - Canvas, WebGL renderer, audio fingerprint, fonts
  - Provides long-term visitor identity

Tier 2 (Semi-stable): 10 base62 characters
  - Signals that change with browser updates
  - User-Agent data, Client Hints, plugins
  - Extensible without breaking Tier 1

Tier 3 (Volatile): 10 base62 characters
  - Signals that change frequently
  - Screen resolution, timezone, language
  - Used for confidence scoring, not identity

Ogni livello estrae i segnali a esso designati, costruisce una stringa canonica e la sottopone ad hashing con MurmurHash3-x64-128. I tre hash dei livelli vengono concatenati e codificati in base62 per produrre l'ID visitatore finale.

Punteggio di confidenza

Il punteggio di confidenza (da 0.0 a 1.0) indica quanto il sistema è certo che questo visitatore sia stato identificato correttamente:

• Corrispondenza dei cookie (1.0): se il cookie crittografato _vid_t corrisponde, la confidenza è massima.
• Prima visita (0.90): i nuovi visitatori senza record precedenti partono da 0.90.
• Visitatore di ritorno: la confidenza viene calcolata dalla ponderazione della frequenza dei segnali (basata su IDF) e dal fuzzy matching rispetto ai fingerprint memorizzati usando la distanza di Hamming a livello di bit.

Bot Detection

Il motore di rilevamento dei bot esegue più rilevatori i cui output ponderati vengono combinati in un punteggio bot (soglie: bot ≥ 0.70, suspicious ≥ 0.30; un segnale hard-fail forza un verdetto bot). I rilevatori che contribuiscono includono:

1. Controllo del flag webdriver (massima priorità)
2. Analisi composita dei segnali di automazione
3. Corrispondenza UA dei good bot + verifica dell'IP (reverse DNS)
4. Rilevamento dei browser headless (11 marker, soglia 2+)
5. Rilevamento dell'anomalia della lunghezza di eval
6. Corrispondenza dei pattern UA dei bad bot
7. Classificazione dei framework di automazione (Puppeteer, Playwright, Cypress, Selenium)
8. Rilevamento VM (VMware, VirtualBox, Parallels, QEMU, Hyper-V)
9. Rilevamento emulatori (punteggio per emulatori mobile)
10. Rilevamento Frida/strumentazione
11. Rilevamento dei DevTools
12. Classificazione dei privacy browser (Tor, Brave, Firefox ETP, Safari ITP)
13. Rilevamento di app clonate
14. Analisi comportamentale (frequenza/entropia/interazione)

Arricchimento con Smart Signal

I segnali di arricchimento lato server vengono calcolati dai dati grezzi dei segnali e dall'IP intelligence. Questi includono il rilevamento di VPN/proxy/Tor, la geolocalizzazione dell'IP, l'analisi della manomissione del browser e il suspect scoring.

IP Intelligence

Il sottosistema di IP intelligence fornisce:

• VPN / Proxy / Tor / Datacenter: classificati a partire dall'IP di connessione usando database commerciali di IP intelligence (IP2Location)
• Geolocalizzazione: accuratezza a livello di città e ASN tramite MaxMind GeoIP2

Fase 4: Risposta

Il server restituisce una risposta JSON contenente:

{
  "visitorId": "X7fh2Hg9LkMn3pQr",
  "bot": {
    "detected": false,
    "confidence": 2,
    "reasons": []
  }
}

Questo è il risultato a cui tracio.getResult() si risolve nel browser. L'evento completo e arricchito — incluso il canonico bot_result (human / bot / uncertain), la geolocalizzazione e gli smart signal — viene consegnato lato server tramite webhooks ed è visibile nella dashboard.

Il client memorizza un token del visitatore sia in un cookie di prima parte (scadenza a 365 giorni, SameSite=Lax) sia in localStorage per la persistenza tra le sessioni.

Riepilogo del flusso dei dati

Round-trip totale: tipicamente 80-300ms a seconda delle condizioni di rete e delle capacità del browser.