Esta página cubre los problemas comunes que se encuentran durante la integración de TRACIO y sus soluciones. TRACIO es un servicio de nube gestionada, así que la mayoría de los problemas son del lado del cliente (script bloqueado, cookies, funciones de privacidad del navegador) y no de infraestructura.
El script del agente o la solicitud de identificación no se carga, o la consola del navegador muestra un error de CORS contra edge.tracio.ai.
1. El origen no está en la lista de permitidos de su clave
Cada clave pública puede restringirse a un conjunto de orígenes permitidos. Si el origen de su sitio no está en la lista de permitidos, el edge rechaza la solicitud (403). Añada su origen en Request Filtering en el panel, o confirme que la clave que está usando no está restringida por origen a un sitio diferente.
2. Un bloqueador de anuncios o CSP bloquea la solicitud
Las extensiones de privacidad (uBlock Origin, AdBlock) o un Content-Security-Policy estricto pueden bloquear el script del agente o su solicitud de red. El SDK expone esto como un error blocked (consulte Manejo de errores). Para dificultar el bloqueo, sirva el agente desde un subdominio de origen (first-party) usando las opciones scriptUrl / endpoint.
3. Endpoint / región incorrectos
Asegúrese de estar apuntando al endpoint correcto. Cuando establece region, el SDK se comunica con edge.us.tracio.ai o edge.eu.tracio.ai; sin establecer, usa edge.tracio.ai.
Las puntuaciones de confianza están de forma consistente por debajo de 0.90 para los visitantes recurrentes.
1. La cookie no persiste
Puede que la cookie _vid_t no se esté estableciendo correctamente. Compruébelo en el navegador:
// In browser consoledocument.cookie.split(";").filter((c) => c.includes("_vid_t"))Si la cookie falta, consulte la sección La cookie no persiste más abajo.
2. Workspace nuevo
Un workspace completamente nuevo tiene una base de datos de visitantes vacía, así que todos los visitantes aparecen como «nuevos» con una confianza en torno a 0.90. Tras 24-48 horas, los visitantes recurrentes se reconocen con mayor confianza.
3. Navegación de incógnito/privada
En modo incógnito, las cookies y localStorage se borran cuando termina la sesión. TRACIO recurre a la coincidencia basada solo en señales, que tiene menor confianza (normalmente 0.85-0.95).
4. Navegadores con antifingerprinting agresivo
Brave, Firefox (modo estricto) y Safari (ITP) modifican o bloquean algunas señales del navegador. Esto reduce el conjunto de señales disponible para la coincidencia. TRACIO detecta estos navegadores y ajusta la confianza en consecuencia.
Inspeccione la identificación en el panel (Visitors / Events), o actúe sobre la
entrega del webhook, que lleva identification.confidence,
identification.incognito y el veredicto bot de cada evento.
Visitantes humanos legítimos se marcan como bots.
1. Extensiones del navegador que modifican propiedades de navigator
Algunas extensiones de privacidad modifican navigator.userAgent, navigator.platform u otras propiedades. Esto puede activar el detector de manipulación, pero no debería activar la detección de bots por sí solo.
Revise el campo bot.type para identificar qué detector se activó:
| bot.type | Causa común de falso positivo | Solución |
|---|---|---|
webdriver | Una herramienta de pruebas dejó navigator.webdriver = true | El usuario debería desactivar el modo de pruebas |
headless | Escritorio VNC/remoto con renderizado de GPU por software | Compruebe si SwiftShader/llvmpipe es el renderer de GPU |
unknown | Anomalía en la longitud de eval por una extensión del navegador | Revise la extensión |
rateBot | Recarga automatizada de páginas o polling agresivo | Reduzca la frecuencia de solicitudes |
2. Entornos corporativos con renderizado por software
Los entornos Citrix, VDI y de terminal server a menudo usan renderizado de GPU por software (SwiftShader, llvmpipe), que es un marcador de headless. Si sus usuarios operan en estos entornos, aplique una política más blanda cuando el webhook muestre un 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. Pruebas automatizadas en producción
Si su equipo de QA ejecuta pruebas con Selenium/Playwright contra producción, esas se detectarán correctamente como bots. Use una clave separada para el tráfico de pruebas.
La cookie _vid_t desaparece entre visitas, lo que hace que cada visita aparezca como un visitante «nuevo».
1. Sitio sin HTTPS
La cookie _vid_t usa el flag Secure y solo se establece sobre HTTPS. Asegúrese de que su sitio use HTTPS.
2. Carga entre sitios (cross-site)
TRACIO establece SameSite=Lax en la cookie. Si el agente se carga en un contexto estrictamente entre sitios, la cookie puede bloquearse. Servir el agente desde un subdominio de origen (first-party) (vía scriptUrl / endpoint) la mantiene en el mismo sitio (same-site).
3. Safari ITP
La Prevención de Rastreo Inteligente (ITP) de Safari puede limitar la vida útil de las cookies establecidas por el cliente. TRACIO también emite _vid_t del lado del servidor mediante la cabecera Set-Cookie y refleja el UID en localStorage, así que la identidad sobrevive incluso cuando la cookie queda limitada.
4. El navegador borra las cookies
Algunos navegadores (Brave, Firefox Focus) borran las cookies al terminar la sesión. Los usuarios con ajustes de privacidad agresivos siempre aparecerán como visitantes nuevos.
tracio.getResult() tarda más de 500ms en devolver un resultado.
1. Red lenta hacia el edge
Compruebe la latencia de ida y vuelta hacia su 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. La recopilación de señales tarda demasiado
Algunas señales tienen timeouts. En dispositivos lentos, la recopilación puede tardar 200ms o más. Las señales con mayor probabilidad de añadir latencia son la huella de audio (AudioContext suspendido en iOS), la sonda WebRTC/TURN, la detección de fuentes y los tiempos de DRM. Estas están acotadas por timeouts y nunca bloquean de forma indefinida.
Algunas señales devuelven un estado que no es de éxito (por ejemplo «not available» o «timeout»).
Los errores de señales son esperados y se manejan con elegancia: el sistema ajusta la confianza en función de las señales que están disponibles. Ejemplos comunes: canvas bloqueado por CSP, AudioContext con timeout en iOS, WebGPU no soportado en la mayoría de los navegadores, Client Hints no disponibles fuera de Chromium. No se requiere ninguna acción a menos que señales críticas (canvas, WebGL, audio) fallen de forma consistente en muchos visitantes.
Si se encuentra con un problema que no se cubre aquí:
debug: true del SDKrequestId de una identificación afectada