How It Works

TRACIO est un système d'identification client-serveur. Le client collecte des signaux du navigateur et les envoie au serveur, qui calcule un identifiant de visiteur stable, exécute des algorithmes de détection et renvoie des résultats enrichis. Cette section explique chaque étape du pipeline.

Vue d'ensemble de l'architecture

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)

Étape 1 : Collecte des signaux

Lorsque tracio.getResult() est appelé, le client collecte 130+ signaux de navigateur distincts, organisés en tiers. La collecte utilise un pipeline multi-phases avec des Web Workers et des iframes partagées pour la performance.

Catégories de signaux

Pipeline de collecte

Le pipeline de collecte s'exécute en quatre étapes afin de minimiser le blocage du thread principal :

1. Étape 1 (Immédiate) : signaux haute priorité rapides à collecter (propriétés navigator, écran, fuseau horaire). La sonde TURN démarre également ici car elle s'exécute en parallèle.

2. Étape 2 (Idle Callback) : signaux synchrones qui bénéficient d'une période d'inactivité (media queries CSS, sondes de stockage, tests de cookies).

3. Étape 3 (Async) : signaux nécessitant des API asynchrones ou du rendu (canvas, WebGL, empreinte audio, détection de polices, rendu des emoji).

4. Web Worker : collecte de signaux isolée dans un thread dédié (détection des fonctionnalités WASM, doNotTrack).

Une iframe cachée partagée est créée une seule fois et réutilisée par plusieurs collecteurs (emoji, MathML, couleurs système, polices, cadre d'écran) afin d'éviter le surcoût lié à la création d'iframes séparées par signal.

Format des signaux

Chaque signal suit une structure cohérente :

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

Codes de statut :

Étape 2 : Transport chiffré

Les signaux collectés sont sérialisés en JSON, puis chiffrés et compressés avant transmission :

1. Sérialisation JSON : toutes les valeurs de signaux sont regroupées dans un objet JSON indexé par signal, plus des champs de métadonnées (c pour la clé API, t pour le tag, lid pour le linked ID).

2. Compression : si le payload dépasse 1024 octets, il est compressé avec CompressionStream("deflate-raw").

3. Chiffrement XOR : le payload est enveloppé dans une enveloppe de chiffrement :

   • Un octet de clé XOR aléatoire
   • Des octets d'en-tête (marqueurs de validation)
   • Du padding aléatoire (0-3 octets)
   • Un masque XOR de 9 octets
   • Le payload XORé avec le masque répété

4. Encodage Base64 : le payload chiffré est encodé en Base64url et envoyé comme corps du POST.

La requête est envoyée à l'endpoint d'ingress avec des paramètres de requête pour la version du client et la clé API. Les credentials CORS sont inclus pour envoyer les cookies first-party.

Étape 3 : Traitement côté serveur

Le serveur reçoit le payload chiffré et le traite à travers plusieurs sous-systèmes :

Extraction des signaux

Le serveur décode l'enveloppe XOR, décompresse si nécessaire et parse les données de signaux JSON. Le code de statut et la valeur de chaque signal sont extraits et validés.

Calcul du visitor ID

Le visitor ID est calculé selon une approche de hachage hiérarchisé (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

Chaque tier extrait ses signaux désignés, construit une chaîne canonique et la hache avec MurmurHash3-x64-128. Les trois hashes de tiers sont concaténés et encodés en base62 pour produire le visitor ID final.

Scoring de confiance

Le score de confiance (0.0 à 1.0) indique à quel point le système est certain que ce visiteur a été correctement identifié :

• Correspondance de cookie (1.0) : si le cookie chiffré _vid_t correspond, la confiance est maximale.
• Première visite (0.90) : les nouveaux visiteurs sans enregistrement antérieur démarrent à 0.90.
• Visiteur de retour : la confiance est calculée à partir de la pondération de fréquence des signaux (basée sur l'IDF) et d'une correspondance floue face aux empreintes stockées, en utilisant la distance de Hamming au niveau du bit.

Bot Detection

Le moteur de détection des bots exécute plusieurs détecteurs dont les sorties pondérées se combinent en un score de bot (seuils : bot ≥ 0.70, suspicious ≥ 0.30 ; un signal à échec forcé impose un verdict de bot). Les détecteurs contributeurs incluent :

1. Vérification du flag webdriver (priorité la plus haute)
2. Analyse composite des signaux d'automatisation
3. Correspondance d'UA de bon bot + vérification d'IP (DNS inverse)
4. Détection des navigateurs headless (11 marqueurs, seuil 2+)
5. Détection d'anomalie d'eval length
6. Correspondance de motifs d'UA de bots malveillants
7. Classification des frameworks d'automatisation (Puppeteer, Playwright, Cypress, Selenium)
8. Détection de VM (VMware, VirtualBox, Parallels, QEMU, Hyper-V)
9. Détection d'émulateur (scoring des émulateurs mobiles)
10. Détection Frida/instrumentation
11. Détection des DevTools
12. Classification des navigateurs de confidentialité (Tor, Brave, Firefox ETP, Safari ITP)
13. Détection d'app clonée
14. Analyse comportementale (débit/entropie/interaction)

Enrichissement Smart Signal

Les signaux d'enrichissement côté serveur sont calculés à partir des données de signaux brutes et de l'IP intelligence. Ils incluent la détection VPN/proxy/Tor, la géolocalisation IP, l'analyse d'altération du navigateur et le suspect scoring.

IP Intelligence

Le sous-système d'IP intelligence fournit :

• VPN / Proxy / Tor / Datacenter : classés à partir de l'IP de connexion à l'aide de bases de données commerciales d'IP intelligence (IP2Location)
• Géolocalisation : précision au niveau ville et ASN via MaxMind GeoIP2

Étape 4 : Réponse

Le serveur renvoie une réponse JSON contenant :

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

C'est le résultat auquel tracio.getResult() se résout dans le navigateur. L'événement complet et enrichi — incluant le bot_result canonique (human / bot / uncertain), la géolocalisation et les smart signals — est livré côté serveur via les webhooks et affiché dans le tableau de bord.

Le client stocke un token de visiteur à la fois dans un cookie first-party (expiration 365 jours, SameSite=Lax) et dans localStorage pour la persistance entre les sessions.

Résumé du flux de données

Aller-retour total : généralement 80-300ms selon les conditions réseau et les capacités du navigateur.