本页介绍 TRACIO 集成过程中遇到的常见问题及其解决方案。TRACIO 是一项托管式云服务，因此大多数问题都出在客户端（脚本被拦截、Cookie、浏览器隐私功能），而非基础设施。
代理脚本或识别请求加载失败，或者浏览器控制台针对 edge.tracio.ai 显示 CORS 错误。
1. Origin 未加入你的密钥的允许列表
每个公钥都可以被限制在一组允许的 origin 内。如果你的站点的 origin 不在允许列表中，边缘节点会拒绝该请求（403）。在仪表盘的 Request Filtering 下添加你的 origin，或确认你所使用的密钥没有被 origin 绑定到另一个站点。
2. 广告拦截器或 CSP 拦截了请求
隐私扩展（uBlock Origin、AdBlock）或严格的 Content-Security-Policy 可能会拦截代理脚本或其网络请求。SDK 会将其表现为 blocked 错误（参见错误处理）。若要提高拦截的难度，可通过 scriptUrl / endpoint 选项从第一方子域提供代理脚本。
3. 错误的端点 / 区域
请确认你指向的是正确的端点。当你设置 region 时，SDK 会与 edge.us.tracio.ai 或 edge.eu.tracio.ai 通信；不设置时，则使用 edge.tracio.ai。
回访访客的置信度分数持续低于 0.90。
1. Cookie 未持久化
_vid_t Cookie 可能未被正确设置。在浏览器中检查：
// In browser consoledocument.cookie.split(";").filter((c) => c.includes("_vid_t"))如果 Cookie 缺失，请参见下方的 Cookie 未持久化 一节。
2. 全新的工作区
全新的工作区拥有一个空的访客数据库，因此所有访客都会显示为“新”访客，置信度约为 0.90。经过 24–48 小时后，回访访客会以更高的置信度被识别。
3. 无痕/隐私浏览
在无痕模式下，Cookie 和 localStorage 会在会话结束时被清除。TRACIO 会回退到纯信号匹配，其置信度较低（通常为 0.85–0.95）。
4. 具有激进反指纹机制的浏览器
Brave、Firefox（严格模式）和 Safari（ITP）会修改或拦截某些浏览器信号。这会减少可用于匹配的信号集。TRACIO 会检测这些浏览器并相应地调整置信度。
在仪表盘（Visitors / Events）中检查识别结果，或者根据 Webhook 投递进行处理，该投递会为每个事件携带 identification.confidence、identification.incognito 以及 bot 判定结果。
合法的人类访客被标记为机器人。
1. 浏览器扩展修改了 navigator 属性
某些隐私扩展会修改 navigator.userAgent、navigator.platform 或其他属性。这可能触发篡改检测器，但不应仅凭此触发机器人检测。
检查 bot.type 字段以识别是哪个检测器触发的：
| bot.type | 常见的误报原因 | 解决方案 |
|---|---|---|
webdriver | 浏览器测试工具遗留了 navigator.webdriver = true | 用户应关闭测试模式 |
headless | 使用软件 GPU 渲染的 VNC/远程桌面 | 检查 SwiftShader/llvmpipe 是否为 GPU 渲染器 |
unknown | 浏览器扩展导致的 Eval 长度异常 | 检查该扩展 |
rateBot | 自动化页面刷新或激进的轮询 | 降低请求频率 |
2. 使用软件渲染的企业环境
Citrix、VDI 和终端服务器环境常常使用软件 GPU 渲染（SwiftShader、llvmpipe），这是一种 headless 标志。如果你的用户在此类环境中操作，当 Webhook 显示 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. 在生产环境中进行自动化测试
如果你的 QA 团队针对生产环境运行 Selenium/Playwright 测试，这些测试会被正确地识别为机器人。请为测试流量使用单独的密钥。
_vid_t Cookie 在两次访问之间消失，导致每次访问都显示为“新”访客。
1. 非 HTTPS 站点
_vid_t Cookie 使用 Secure 标志，仅在 HTTPS 下设置。请确保你的站点使用 HTTPS。
2. 跨站加载
TRACIO 在 Cookie 上设置了 SameSite=Lax。如果代理在严格的跨站上下文中加载，Cookie 可能会被拦截。从第一方子域提供代理（通过 scriptUrl / endpoint）可使其保持同站。
3. Safari ITP
Safari 的智能防跟踪（Intelligent Tracking Prevention，ITP）可能会限制客户端设置的 Cookie 的存续时间。TRACIO 还会通过 Set-Cookie 头在服务端下发 _vid_t，并将 UID 镜像到 localStorage，因此即使 Cookie 被限制，身份标识仍能保留。
4. 浏览器清除 Cookie
某些浏览器（Brave、Firefox Focus）会在会话结束时清除 Cookie。具有激进隐私设置的用户将始终显示为新访客。
tracio.getResult() 返回耗时超过 500ms。
1. 到边缘节点的网络缓慢
检查到你所在区域边缘节点的往返延迟：
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. 信号采集耗时过长
某些信号设有超时。在慢速设备上，采集可能耗时 200ms 以上。最有可能增加延迟的信号是音频指纹（AudioContext 在 iOS 上被挂起）、WebRTC/TURN 探测、字体检测以及 DRM 计时。这些都受超时限制，绝不会无限期地阻塞。
某些信号返回非成功状态（例如“not available”或“timeout”）。
信号错误是预期之内的，并会被优雅地处理——系统会根据可用的信号调整置信度。常见示例：Canvas 被 CSP 拦截、AudioContext 在 iOS 上超时、WebGPU 在大多数浏览器上不受支持、Client Hints 在 Chromium 之外不可用。除非关键信号（Canvas、WebGL、音频）在大量访客中持续失败，否则无需采取任何操作。
如果你遇到本页未涵盖的问题：