tracio.aidocs

Getting Started

  • Overview
  • Quick Start
  • How It Works

SDK & API

  • Device Identification JS Agent
  • Trace API Reference
  • Trace Webhooks

Features

  • Device Identification Engine
  • Bot Detection
  • Trace Signals
  • IP Intelligence

Advanced

  • Cloud Deployment
  • Privacy & GDPR
  • Migration from FPJS

Reference

  • Changelog
  • Troubleshooting
  • Error Handling
  • Testing

How It Works

High-performance signal pipeline: client SDK collection, encrypted transport, proprietary identification, and analytics storage

Architecture Overview

tracio.ai uses a client-server architecture where a lightweight JavaScript SDK runs in the browser, collects hardware and software signals, encrypts the payload, and sends it to our secure cloud for processing. The server decrypts the signals, runs them through a multi-stage identification pipeline, and returns a stable visitor ID, confidence score, bot detection results, 24 smart signals, and IP intelligence in a single JSON response.

This architecture ensures that sensitive signal processing and visitor matching happen exclusively server-side in our secure cloud, where the logic cannot be inspected or tampered with by malicious visitors. The client SDK only collects raw signals and has no knowledge of visitor IDs, matching algorithms, or detection logic.

┌───────────────┐ ┌────────────────────┐
│ Browser │ ── signals ─▶ │ tracio.ai Cloud │
│ (JS SDK) │ │ (identification │
│ │ ◀── result ── │ engine) │
└───────────────┘ └────────────────────┘
1. SDK collects device signals and encrypts them (AES-256-GCM)
2. Server identifies the visitor using proprietary matching
3. Returns: visitorId, confidence, bot detection, smart signals, IP intel

Step 1: Signal Collection

The JavaScript SDK (128KB gzipped) runs in the browser and collects over 1,000 individual signals in under 50ms. Signals are organized into categories that capture different aspects of the device and browser environment. The collection process is designed to be imperceptible to the user -- it does not cause visible page jank, does not trigger consent dialogs, and does not access any personally identifiable information.

Signal Categories

CategoryWhat It CapturesWhy It Matters
CanvasDraws text and shapes on a hidden canvas and hashes the rendered pixelsGPU and rendering engine differences produce unique outputs across devices
WebGLQueries GPU renderer, vendor, extensions, shader precision, texture limitsGPU model is a strong hardware identifier that persists across browsers
AudioProcesses an oscillator tone through an offline AudioContext and hashes the outputAudio processing characteristics vary by OS audio stack and hardware
FontsMeasures rendering width of test strings to detect installed system fontsFont inventory is OS and locale-specific, providing medium-high uniqueness
ScreenResolution, color depth, pixel ratio, available area, taskbar positionScreen configuration is relatively stable and hardware-bound
NavigatorPlatform, languages, hardware concurrency, device memory, touch supportReflects hardware capabilities and user preferences
CSS/MediaMedia query results, CSS feature support, color scheme preferencesBrowser engine and version fingerprint via supported features
MathPrecision of math functions (sin, cos, tan, log) across browser enginesEngine-specific floating point behavior distinguishes Chrome from Firefox from Safari
Client HintsUA-CH brands, platform version, architecture, bitnessModern replacement for User-Agent with structured data
StorageCookie, localStorage, sessionStorage, IndexedDB, FileSystem availabilityPrivacy settings and browser configuration indicators

Collection Timing

Most signals are collected synchronously in under 5ms. A few high-value signals require asynchronous operations: canvas rendering (5-15ms), audio processing (3-10ms), font enumeration (10-30ms), and WebGL probing (5-15ms). The total collection time is typically 30-80ms on modern hardware. The SDK uses requestAnimationFrame scheduling to avoid blocking the main thread.

Step 2: Encryption and Transport

After collection, the signal payload is encrypted using AES-256-GCM with a session key derived from your API key. The encryption serves two purposes: it prevents man-in-the-middle observers from learning what signals are collected, and it prevents clients from tampering with the signal values before they reach the server.

The encrypted payload is sent as a POST request to the tracio.ai API endpoint. The payload size is typically 2-5KB compressed. The SDK handles retries with exponential backoff for transient network failures, and the request times out after the configured timeout (default 10 seconds).

Step 3: Server-Side Processing

The server receives the encrypted payload, decrypts it, and runs the signals through a multi-stage processing pipeline. Each stage adds context and enrichment to the raw signals before producing the final identification result.

Processing Pipeline

Encrypted Payload
|
v
+-----------------+
| 1. Decrypt | AES-256-GCM decryption, payload validation
+--------+--------+
|
v
+-----------------+
| 2. Parse | Extract 1,000+ individual signals from the payload
| Signals | Validate types, ranges, and consistency
+--------+--------+
|
v
+-----------------+
| 3. Signal | Group signals into hardware, browser, session tiers
| Processing | Compute proprietary hash per tier
+--------+--------+
|
v
+-----------------+
| 4. Candidate | Search for visitors with matching hardware hash
| Lookup | Narrows billions of possibilities to dozens of candidates
+--------+--------+
|
v
+-----------------+
| 5. AI | Compare each candidate against full signal set
| Matching | Weighted scoring with drift tolerance
+--------+--------+
|
v
+-----------------+
| 6. Confidence | Compute confidence score (0.0 - 1.0)
| Scoring | Threshold check for match vs. new visitor
+--------+--------+
|
v
+-----------------+
| 7. Smart | Run 24 server-side detectors in parallel:
| Signals | Bot, VPN, proxy, Tor, tampering, incognito, VM, etc.
+--------+--------+
|
v
+-----------------+
| 8. IP Intel | GeoIP lookup, VPN ASN check, blocklist, reputation
+--------+--------+
|
v
JSON Response

Multi-Tier Signal Processing

Signals are separated into three tiers based on stability. Hardware-tier signals (canvas, WebGL, audio, screen) change only when the physical device changes. Browser-tier signals (fonts, User-Agent, math precision) change with browser updates. Session-tier signals (timezone, color scheme, connection type) change frequently with user behavior. Each tier is processed independently using proprietary algorithms, producing a composite fingerprint used for visitor lookup and matching.

TierStabilityWeightExamples
HardwareVery High60%Canvas, WebGL renderer/vendor, audio hash, screen resolution, color depth
BrowserMedium30%Fonts, User-Agent, platform, math precision, CSS features
SessionLow10%Timezone, color scheme, cookie support, connection type

Cross-Session Matching

Real-world browsers change over time. Fonts get installed, browser versions update, users switch between light and dark mode. The AI-powered matching engine handles these expected changes by comparing signals individually rather than relying on a single monolithic approach. Each signal comparison produces a match score between 0.0 and 1.0, weighted by the signal's uniqueness and stability. The weighted sum produces the final confidence score.

Smart Signals

After identification, the server runs 24 smart signal detectors in parallel. These detectors analyze the browser signals, IP address, and behavioral history to produce enrichment data including bot detection, VPN/proxy detection, tampering analysis, incognito mode detection, virtual machine detection, and an aggregated suspect score.

  • Bot Detection (multiple methods) -- Webdriver flag, automation framework scanning, headless browser markers, good bot verification, eval length analysis, and behavioral rate analysis
  • IP Intelligence -- VPN detection (4 methods), proxy detection, Tor exit node matching, IP blocklist, IP reputation scoring
  • Browser Analysis -- Incognito detection, tampering detection, privacy browser identification, developer tools detection
  • Device Analysis -- Virtual machine detection, emulator detection, factory reset detection, cloned app detection
  • Behavioral -- Velocity tracking (5m/1h/24h windows), high-activity flagging, suspect score computation

Step 4: Response

The API returns a comprehensive JSON response containing the visitor ID, confidence score, bot detection results, all smart signals, and IP intelligence. The entire server-side processing pipeline completes in under 50ms, including database queries and GeoIP lookups.

{
"visitorId": "X7fh2Hg9LkMn3pQr",
"confidence": { "score": 0.995, "revision": "v3.0" },
"requestId": "1710432000_abc123def",
"bot": { "result": "notDetected", "probability": 0.0 },
"ipLocation": {
"city": { "name": "Prague" },
"country": { "code": "CZ", "name": "Czechia" },
"latitude": 50.05,
"longitude": 14.4,
"timezone": "Europe/Prague"
},
"incognito": false,
"tampering": { "result": false, "anomalyScore": 0.12 },
"vpn": { "result": false, "confidence": "high" },
"suspectScore": { "result": 3 },
"velocity": {
"distinctIp": { "intervals": { "5m": 1, "1h": 1, "24h": 2 } },
"events": { "intervals": { "5m": 1, "1h": 3, "24h": 12 } }
}
}

Performance Characteristics

MetricValue
SDK size128KB gzipped
Signal collection30-80ms
Server processing< 50ms (P95 < 30ms)
Total end-to-end50-200ms

Security

  • End-to-end encryption -- Signal payloads are encrypted with AES-256-GCM before leaving the browser. Even if the network is compromised, signal data cannot be read or modified.
  • Server-side identification -- Visitor ID computation happens exclusively server-side. The client SDK has no knowledge of matching algorithms, visitor histories, or detection logic.
  • No PII collection -- The SDK collects browser configuration and hardware signals only. No names, emails, passwords, browsing history, or form input is ever accessed.
  • Tamper resistance -- The server cross-validates signals against each other to detect tampering. For example, a Chrome User-Agent with Safari-specific math precision triggers the tampering detector.
  • Data sovereignty -- All data is processed and stored in your chosen region (EU or US). No third-party data sharing, full encryption at rest and in transit.