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 ver qué clase de detección se activó (consulte Tipos de bot para el vocabulario completo):
| bot.type | Causa común de falso positivo | Solución |
|---|---|---|
automation | Una herramienta de pruebas dejó el navegador en modo de automatización | Desactive el modo de automatización fuera de las pruebas |
headless | VDI / escritorio remoto que renderiza sin una GPU real | Vea «Entornos corporativos» más abajo |
extension | Hay activa una extensión de automatización, proxy o VPN | Revise la extensión |
other | Se activó un indicador de automatización no específico | Consulte reasons (Business+) para la clase |
En los planes Business y Enterprise, el array reasons del webhook nombra la clase de
observación que hay detrás del veredicto: es la vía más rápida para entender un falso
positivo. Consulte Códigos de motivo.
2. Entornos corporativos con renderizado por software
Los entornos Citrix, VDI y de terminal server renderizan sin una GPU real, lo que se
parece a un runtime 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") { // VDI and remote-desktop users render without a real GPU and can trip the // headless classification — 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 notablemente más en resolverse que en sus otros
dispositivos y redes de prueba.
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 tarda demasiado
En dispositivos de bajo rendimiento la recopilación tarda más. Toda comprobación que pueda ser lenta está acotada por su propio timeout, así que la recopilación nunca bloquea de forma indefinida: una comprobación que agota su tiempo simplemente se reporta como no disponible y la identificación continúa sin ella.
La identificación se completa, pero la confianza es menor de lo esperado en un navegador o una clase de dispositivo concretos.
No todas las comprobaciones pueden ejecutarse en todos los entornos: una CSP estricta, las restricciones de la plataforma y las funciones de privacidad del navegador hacen que algunas no estén disponibles. Esto es esperable y se maneja con elegancia: la confianza se calcula a partir de lo que realmente se recopiló, y por eso los navegadores endurecidos se identifican legítimamente con menos confianza que uno estándar.
No se requiere ninguna acción por su parte. Si la confianza es sistemáticamente baja en
una parte grande de su tráfico, contacte con soporte indicando un requestId: eso se
diagnostica desde el registro del lado del servidor, no desde el navegador.
Si se encuentra con un problema que no se cubre aquí:
debug: true del SDKrequestId de una identificación afectada