How It Works

TRACIO is a client-server identification system. The client collects browser signals and sends them to the server, which computes a stable visitor identifier, runs detection algorithms, and returns enriched results. This section explains each stage of the pipeline.

Architecture Overview

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

Stage 1: Signal Collection

When tracio.getResult() is called, the client collects 130+ distinct browser signals organized into tiers. Collection uses a multi-phase pipeline with Web Workers and shared iframes for performance.

Signal Categories

Collection Pipeline

The collection pipeline runs in four stages to minimize main thread blocking:

1. Stage 1 (Immediate): High-priority signals that are fast to collect (navigator properties, screen, timezone). The TURN probe also starts here as it runs concurrently.

2. Stage 2 (Idle Callback): Synchronous signals that benefit from an idle period (CSS media queries, storage probes, cookie tests).

3. Stage 3 (Async): Signals requiring asynchronous APIs or rendering (canvas, WebGL, audio fingerprint, font detection, emoji rendering).

4. Web Worker: Isolated signal collection in a dedicated thread (WASM feature detection, doNotTrack).

A shared hidden iframe is created once and reused by multiple collectors (emoji, MathML, system colors, fonts, screen frame) to avoid the overhead of creating separate iframes per signal.

Signal Format

Every signal follows a consistent structure:

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

Status codes:

Stage 2: Encrypted Transport

Collected signals are serialized to JSON, then encrypted and compressed before transmission:

1. JSON serialization: All signal values are packed into a JSON object with keys s1 through s212 plus metadata fields (c for API key, t for tag, lid for linked ID).

2. Compression: If the payload exceeds 1024 bytes, it is compressed using CompressionStream("deflate-raw").

3. XOR Encryption: The payload is wrapped in an encryption envelope:

   • A random XOR key byte
   • Header bytes (validation markers)
   • Random padding (0-3 bytes)
   • A 9-byte XOR mask
   • The payload XORed with the repeating mask

4. Base64 encoding: The encrypted payload is Base64url-encoded and sent as the POST body.

The request is sent to the ingress endpoint with query parameters for client version and API key. CORS credentials are included to send first-party cookies.

Stage 3: Server-Side Processing

The server receives the encrypted payload and processes it through several subsystems:

Signal Extraction

The server decodes the XOR envelope, decompresses if needed, and parses the JSON signal data. Each signal's status code and value are extracted and validated.

Visitor ID Computation

The visitor ID is computed using a tiered hashing approach (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

Each tier extracts its designated signals, builds a canonical string, and hashes it with MurmurHash3-x64-128. The three tier hashes are concatenated and encoded in base62 to produce the final visitor ID.

Confidence Scoring

The confidence score (0.0 to 1.0) indicates how certain the system is that this visitor has been correctly identified:

• Cookie match (1.0): If the encrypted _tcid cookie matches, confidence is maximum.
• First visit (0.90): New visitors with no prior record start at 0.90.
• Returning visitor: Confidence is computed from signal frequency weighting (IDF-based) and fuzzy matching against stored fingerprints using bit-level Hamming distance.

Bot Detection

The bot detection engine runs 14 independent detectors in priority order:

1. Webdriver flag check (highest priority)
2. Composite automation signal analysis
3. Good bot UA matching + IP verification (reverse DNS)
4. Headless browser detection (11 markers, threshold 2+)
5. Eval length anomaly detection
6. Bad bot UA pattern matching
7. Automation framework classification (Puppeteer, Playwright, Cypress, Selenium)
8. VM detection (VMware, VirtualBox, Parallels, QEMU, Hyper-V)
9. Emulator detection (mobile emulator scoring)
10. Frida/instrumentation detection
11. DevTools detection
12. Privacy browser classification (Tor, Brave, Firefox ETP, Safari ITP)
13. Cloned app detection
14. Behavioral analysis (rate/entropy/interaction)

Smart Signal Enrichment

24 server-side enrichment signals are computed from the raw signal data, IP intelligence, and behavioral analysis. These include VPN detection, proxy classification, Tor identification, IP geolocation, browser tampering analysis, incognito detection, and suspect scoring.

IP Intelligence

The IP intelligence subsystem provides:

• VPN Detection: Five methods (timezone mismatch, public VPN ASN matching, relay detection via iCloud/WARP, TURN probe IP comparison)
• Proxy Detection: HTTP header analysis, ASN matching, residential proxy identification (cardinality + UA diversity)
• Tor Detection: Exit node matching against Tor bulk exit list
• Geolocation: City-level accuracy via MaxMind GeoIP2
• Velocity Tracking: Per-IP and per-visitor activity across 5-minute, 1-hour, and 24-hour intervals

Stage 4: Response

The server returns a JSON response containing:

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

This is the result tracio.getResult() resolves to in the browser. The full, enriched event — including the canonical bot_result (human / bot / uncertain), geolocation, and smart signals — is available server-side through the Server API and webhooks.

The client stores a visitor token in both a first-party cookie (365-day expiry, SameSite=Lax) and localStorage for persistence across sessions.

Data Flow Summary

Total round-trip: Typically 80-300ms depending on network conditions and browser capabilities.