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 ver qual classe de detecção foi acionada (veja Tipos de bot para o vocabulário completo):
| bot.type | Causa comum de falso positivo | Solução |
|---|---|---|
automation | Uma ferramenta de teste deixou o navegador em modo de automação | Desative o modo de automação fora das execuções de teste |
headless | VDI / desktop remoto renderizando sem uma GPU real | Veja "Ambientes corporativos" abaixo |
extension | Há uma extensão de automação, proxy ou VPN ativa | Revise a extensão |
other | Um indicador de automação não específico foi acionado | Consulte reasons (Business+) para a classe |
Nos planos Business e Enterprise, o array reasons do webhook nomeia a classe de
observação por trás do veredito — é o caminho mais rápido para entender um falso
positivo. Veja Códigos de motivo.
2. Ambientes corporativos com renderização por software
Ambientes Citrix, VDI e terminal server renderizam sem uma GPU real, o que se parece com
um runtime 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") { // VDI and remote-desktop users render without a real GPU and can trip the // headless classification — 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() demora perceptivelmente mais para retornar do que nos seus outros
dispositivos e redes de teste.
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 demorando demais
Em dispositivos menos potentes, a coleta demora mais. Toda verificação que possa ser lenta é limitada pelo próprio timeout, então a coleta nunca bloqueia indefinidamente — uma verificação que esgota o tempo é simplesmente reportada como indisponível e a identificação segue sem ela.
A identificação é concluída, mas a confiança fica abaixo do esperado em um navegador ou classe de dispositivo específicos.
Nem toda verificação pode rodar em todo ambiente: CSP estrita, restrições de plataforma e recursos de privacidade do navegador tornam algumas delas indisponíveis. Isso é esperado e tratado de forma controlada — a confiança é calculada a partir do que foi efetivamente coletado, e é por isso que navegadores endurecidos legitimamente se identificam com confiança menor do que um navegador padrão.
Nenhuma ação é necessária do seu lado. Se a confiança for consistentemente baixa em uma
parcela grande do seu tráfego, entre em contato com o suporte informando um requestId
— isso é diagnosticado a partir do registro do lado do servidor, não do navegador.
Se você encontrar um problema não coberto aqui:
debug: true do SDKrequestId de uma identificação afetada