Esta página cobre problemas comuns encontrados durante a integração do TRACIO e suas soluções. O TRACIO é um serviço em nuvem gerenciado, então a maioria dos problemas é do lado do cliente (script bloqueado, cookies, recursos de privacidade do navegador) e não de infraestrutura.
O script do agente ou a requisição de identificação não carrega, ou o console do navegador mostra um erro de CORS contra edge.tracio.ai.
1. Origem não incluída na lista de permissões da sua chave
Cada chave pública pode ser restrita a um conjunto de origens permitidas. Se a origem do seu site não estiver na lista de permissões, o edge rejeita a requisição (403). Adicione sua origem em Request Filtering no painel, ou confirme que a chave que você está usando não está travada por origem em outro site.
2. Ad blocker ou CSP bloqueando a requisição
Extensões de privacidade (uBlock Origin, AdBlock) ou uma Content-Security-Policy estrita podem bloquear o script do agente ou sua requisição de rede. O SDK expõe isso como um erro blocked (veja Tratamento de erros). Para dificultar o bloqueio, sirva o agente a partir de um subdomínio de primeira parte usando as opções scriptUrl / endpoint.
3. Endpoint / região incorretos
Certifique-se de que você está apontando para o endpoint correto. Quando você define region, o SDK fala com edge.us.tracio.ai ou edge.eu.tracio.ai; sem definir, ele usa edge.tracio.ai.
As pontuações de confiança estão consistentemente abaixo de 0.90 para visitantes recorrentes.
1. Cookie não persistindo
O cookie _vid_t pode não estar sendo definido corretamente. Verifique no navegador:
// In browser consoledocument.cookie.split(";").filter((c) => c.includes("_vid_t"))Se o cookie estiver ausente, veja a seção Cookie não persistindo abaixo.
2. Workspace novo
Um workspace recém-criado tem um banco de dados de visitantes vazio, então todos os visitantes aparecem como "novos" com uma confiança em torno de 0.90. Após 24-48 horas, os visitantes recorrentes são reconhecidos com maior confiança.
3. Navegação anônima/privada
No modo anônimo, cookies e localStorage são apagados quando a sessão termina. O TRACIO recorre à correspondência apenas por sinais, que tem menor confiança (tipicamente 0.85-0.95).
4. Navegadores com anti-fingerprinting agressivo
Brave, Firefox (modo estrito) e Safari (ITP) modificam ou bloqueiam alguns sinais do navegador. Isso reduz o conjunto de sinais disponíveis para correspondência. O TRACIO detecta esses navegadores e ajusta a confiança de acordo.
Inspecione a identificação no painel (Visitors / Events), ou aja sobre a
entrega do webhook, que carrega identification.confidence,
identification.incognito e o veredito de bot para cada evento.
Visitantes humanos legítimos são sinalizados como bots.
1. Extensões de navegador modificando propriedades do navigator
Algumas extensões de privacidade modificam navigator.userAgent, navigator.platform ou outras propriedades. Isso pode acionar o detector de adulteração, mas não deveria acionar a detecção de bots sozinho.
Verifique o campo bot.type para identificar qual detector foi acionado:
| bot.type | Causa comum de falso positivo | Solução |
|---|---|---|
webdriver | Ferramenta de teste de navegador deixou navigator.webdriver = true | O usuário deve desativar o modo de teste |
headless | VNC/desktop remoto com renderização de GPU por software | Verifique se SwiftShader/llvmpipe é o renderizador de GPU |
unknown | Anomalia no comprimento de eval por extensão de navegador | Revise a extensão |
rateBot | Atualização automática de página ou polling agressivo | Reduza a frequência de requisições |
2. Ambientes corporativos com renderização por software
Ambientes Citrix, VDI e terminal server frequentemente usam renderização de GPU por software (SwiftShader, llvmpipe), que é um marcador de headless. Se seus usuários operam nesses ambientes, aplique uma política mais branda quando o webhook mostrar um tipo de bot headless:
// `event` is the webhook delivery body (/docs/webhooks)if (event.bot.result === "bot" && event.bot.type === "headless") { // Software-GPU (SwiftShader/llvmpipe) VDI users can trip the headless // detector — consider applying a softer policy for these.}3. Testes automatizados em produção
Se sua equipe de QA roda testes Selenium/Playwright contra a produção, eles serão corretamente detectados como bots. Use uma chave separada para tráfego de teste.
O cookie _vid_t desaparece entre visitas, fazendo com que cada visita apareça como um visitante "novo".
1. Site sem HTTPS
O cookie _vid_t usa a flag Secure e só é definido em HTTPS. Garanta que seu site use HTTPS.
2. Carregamento entre sites (cross-site)
O TRACIO define SameSite=Lax no cookie. Se o agente for carregado em um contexto estritamente cross-site, o cookie pode ser bloqueado. Servir o agente a partir de um subdomínio de primeira parte (via scriptUrl / endpoint) o mantém como same-site.
3. Safari ITP
A Intelligent Tracking Prevention (ITP) do Safari pode limitar o tempo de vida de cookies definidos pelo cliente. O TRACIO também emite o _vid_t no lado do servidor via o cabeçalho Set-Cookie e espelha o UID no localStorage, de modo que a identidade sobrevive mesmo quando o cookie é limitado.
4. Navegador limpando cookies
Alguns navegadores (Brave, Firefox Focus) limpam os cookies ao final da sessão. Usuários com configurações de privacidade agressivas sempre aparecerão como novos visitantes.
tracio.getResult() leva mais de 500ms para retornar.
1. Rede lenta até o edge
Verifique a latência de ida e volta até o seu edge regional:
curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTLS: %{time_appconnect}s\nTotal: %{time_total}s\n" https://edge.tracio.ai/health2. Coleta de sinais demorando demais
Alguns sinais têm timeouts. Em dispositivos lentos, a coleta pode levar 200ms+. Os sinais com maior probabilidade de adicionar latência são a impressão digital de áudio (AudioContext suspenso no iOS), a sondagem WebRTC/TURN, a detecção de fontes e o timing de DRM. Eles são limitados por timeouts e nunca bloqueiam indefinidamente.
Alguns sinais retornam um status de não sucesso (por exemplo, "not available" ou "timeout").
Erros de sinais são esperados e tratados de forma controlada — o sistema ajusta a confiança com base nos sinais que estão disponíveis. Exemplos comuns: canvas bloqueado por CSP, AudioContext expirando no iOS, WebGPU não suportado na maioria dos navegadores, Client Hints indisponíveis fora do Chromium. Nenhuma ação é necessária, a menos que sinais críticos (canvas, WebGL, áudio) falhem consistentemente em muitos visitantes.
Se você encontrar um problema não coberto aqui:
debug: true do SDKrequestId de uma identificação afetada