How It Works

A TRACIO é um sistema de identificação cliente-servidor. O cliente coleta sinais do navegador e os envia ao servidor, que calcula um identificador de visitante estável, executa algoritmos de detecção e retorna resultados enriquecidos. Esta seção explica cada estágio do pipeline.

Visão Geral da Arquitetura

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)

Estágio 1: Coleta de Sinais

Quando tracio.getResult() é chamado, o cliente coleta 130+ sinais distintos de navegador organizados em camadas. A coleta usa um pipeline de múltiplas fases com Web Workers e iframes compartilhados para desempenho.

Categorias de Sinais

Pipeline de Coleta

O pipeline de coleta roda em quatro estágios para minimizar o bloqueio da thread principal:

1. Estágio 1 (Imediato): sinais de alta prioridade que são rápidos de coletar (propriedades de navigator, tela, fuso horário). A sonda TURN também começa aqui, pois roda concorrentemente.

2. Estágio 2 (Idle Callback): sinais síncronos que se beneficiam de um período ocioso (media queries de CSS, sondas de armazenamento, testes de cookies).

3. Estágio 3 (Async): sinais que exigem APIs assíncronas ou renderização (canvas, WebGL, impressão digital de áudio, detecção de fontes, renderização de emoji).

4. Web Worker: coleta de sinais isolada em uma thread dedicada (detecção de recursos WASM, doNotTrack).

Um iframe oculto compartilhado é criado uma vez e reutilizado por múltiplos coletores (emoji, MathML, cores do sistema, fontes, frame de tela) para evitar o custo de criar iframes separados por sinal.

Formato do Sinal

Todo sinal segue uma estrutura consistente:

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

Códigos de status:

Estágio 2: Transporte Criptografado

Os sinais coletados são serializados em JSON, depois criptografados e comprimidos antes da transmissão:

1. Serialização JSON: todos os valores de sinais são empacotados em um objeto JSON indexado por sinal, mais campos de metadados (c para chave de API, t para tag, lid para linked ID).

2. Compressão: se o payload exceder 1024 bytes, ele é comprimido usando CompressionStream("deflate-raw").

3. Criptografia XOR: o payload é envolvido em um envelope de criptografia:

   • Um byte de chave XOR aleatório
   • Bytes de cabeçalho (marcadores de validação)
   • Padding aleatório (0-3 bytes)
   • Uma máscara XOR de 9 bytes
   • O payload submetido a XOR com a máscara repetida

4. Codificação Base64: o payload criptografado é codificado em Base64url e enviado como o corpo do POST.

A requisição é enviada ao endpoint de ingress com parâmetros de query para a versão do cliente e a chave de API. As credenciais CORS são incluídas para enviar cookies first-party.

Estágio 3: Processamento no Servidor

O servidor recebe o payload criptografado e o processa através de vários subsistemas:

Extração de Sinais

O servidor decodifica o envelope XOR, descomprime se necessário e faz o parse dos dados JSON dos sinais. O código de status e o valor de cada sinal são extraídos e validados.

Cálculo do ID de Visitante

O ID de visitante é calculado usando uma abordagem de hashing em camadas (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

Cada camada extrai seus sinais designados, constrói uma string canônica e a submete a hash com MurmurHash3-x64-128. Os três hashes das camadas são concatenados e codificados em base62 para produzir o ID de visitante final.

Pontuação de Confiança

A pontuação de confiança (0.0 a 1.0) indica quão certo o sistema está de que este visitante foi corretamente identificado:

• Cookie match (1.0): se o cookie criptografado _vid_t corresponder, a confiança é máxima.
• Primeira visita (0.90): novos visitantes sem registro prévio começam em 0.90.
• Visitante recorrente: a confiança é calculada a partir da ponderação de frequência de sinais (baseada em IDF) e da correspondência fuzzy contra impressões digitais armazenadas usando distância de Hamming em nível de bit.

Bot Detection

O engine de detecção de bots executa múltiplos detectores cujas saídas ponderadas são combinadas em uma pontuação de bot (limiares: bot ≥ 0.70, suspicious ≥ 0.30; um sinal de falha imediata força um veredito de bot). Os detectores contribuintes incluem:

1. Verificação de flag webdriver (prioridade mais alta)
2. Análise composta de sinal de automação
3. Correspondência de UA de bons bots + verificação de IP (DNS reverso)
4. Detecção de navegador headless (11 marcadores, limiar 2+)
5. Detecção de anomalia de eval length
6. Correspondência de padrão de UA de bad bots
7. Classificação de frameworks de automação (Puppeteer, Playwright, Cypress, Selenium)
8. Detecção de VM (VMware, VirtualBox, Parallels, QEMU, Hyper-V)
9. Detecção de emulador (pontuação de emulador mobile)
10. Detecção de Frida/instrumentação
11. Detecção de DevTools
12. Classificação de navegador de privacidade (Tor, Brave, Firefox ETP, Safari ITP)
13. Detecção de app clonado
14. Análise comportamental (taxa/entropia/interação)

Enriquecimento de Smart Signals

Os sinais de enriquecimento no servidor são calculados a partir dos dados brutos dos sinais e da IP intelligence. Eles incluem detecção de VPN/proxy/Tor, geolocalização de IP, análise de adulteração de navegador e suspect scoring.

IP Intelligence

O subsistema de IP intelligence fornece:

• VPN / Proxy / Tor / Datacenter: classificados a partir do IP conectado usando bancos de dados comerciais de IP intelligence (IP2Location)
• Geolocalização: precisão em nível de cidade e ASN via MaxMind GeoIP2

Estágio 4: Resposta

O servidor retorna uma resposta JSON contendo:

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

Este é o resultado para o qual tracio.getResult() resolve no navegador. O evento completo e enriquecido — incluindo o bot_result canônico (human / bot / uncertain), geolocalização e smart signals — é entregue no servidor através de webhooks e exibido no dashboard.

O cliente armazena um token de visitante tanto em um cookie first-party (expiração de 365 dias, SameSite=Lax) quanto no localStorage para persistência entre sessões.

Resumo do Fluxo de Dados

Round-trip total: tipicamente 80-300ms dependendo das condições de rede e das capacidades do navegador.