从 FingerprintJS Pro 迁移

TRACIO 在浏览器信号采集上与 FingerprintJS Pro v4 保持一致，同时提供自己的 SDK（@tracio/sdk），并通过 webhook 在服务端交付结果。本 指南涵盖迁移流程、信号对等的细节，以及你需要更新的 SDK 与响应格式方面的差异。

兼容性概览

信号对等

TRACIO 在浏览器信号采集上与 FingerprintJS Pro v4 保持一致，并通过 自动化的 Playwright 对比测试进行验证——这些测试与生产环境的 FingerprintJS Pro 端点并行运行。在与 FingerprintJS 一致的信号集之上，TRACIO 还采集 FingerprintJS 所不具备的专有信号（bot、篡改、反检测以及持久化信号）。

迁移步骤

第 1 步：设置 TRACIO

TRACIO 是一项托管式云服务。创建你的账户，选择数据区域， 并从控制台复制你的 公钥。完整操作说明见 Cloud Deployment。你的公钥可安全地随客户端代码一起发布。

第 2 步：使用 TRACIO 客户端测试

在切换生产流量之前，先用 TRACIO 的客户端 SDK 进行测试。请注意， TRACIO 使用自己的 SDK 和 API——它不是 FingerprintJS 客户端的 即插即用协议替代品。

import { Tracio } from "@tracio/sdk"

const tracio = Tracio.init({
  publicKey: "5ca175fc...",
})

const result = await tracio.getResult()
console.log(result)

将检测到的设备与你现有的 FingerprintJS Pro 集成进行比较，以验证迁移结果。

第 3 步：并行运行对比

对于关键部署，可同时运行两套系统并比较结果：

// Temporary: run both systems and compare
const fpjsResult = await fpjsAgent.get() // FingerprintJS Pro agent
const tracioResult = await tracio.getResult() // TRACIO instance

// Compare visitor IDs (they will differ — different servers)
// But bot detection should be equivalent for the same device
console.log("FPJS visitorId:", fpjsResult.visitorId)
console.log("TRACIO visitorId:", tracioResult.visitorId)
console.log("FPJS bot:", fpjsResult.bot)
console.log("TRACIO bot:", tracioResult.bot)

请注意，两套系统的访客 ID 会不同，因为它们由不同的服务端数据库计算得出。关键的兼容性指标在于：两套系统都能一致地识别出同一台物理设备。

第 4 步：替换客户端 SDK

TRACIO 提供自己的客户端 SDK（@tracio/sdk），并不复用 FingerprintJS 客户端协议，因此这是一次代码改动，而非 DNS 切换。 移除 FingerprintJS 客户端，并用你的公钥初始化 TRACIO：

// Before (FingerprintJS Pro)
import * as FingerprintJS from "@fingerprintjs/fingerprintjs-pro"
const fpAgent = await FingerprintJS.load({ apiKey: "fpjs-public-key" })
const fpResult = await fpAgent.get()

// After (TRACIO)
import { Tracio } from "@tracio/sdk"
const tracio = Tracio.init({ publicKey: "5ca175fc..." })
const result = await tracio.getResult()

第 5 步：替换服务端事件获取

FingerprintJS Pro 提供一个服务端 API，你通过 requestId 轮询它。TRACIO 不 提供等效的面向客户的 REST 读取端点——相反，结果会在访客被识别的 那一刻以 webhook 的形式推送到你的服务器。 用一个 webhook 处理程序替换你的轮询逻辑：

// Before (FingerprintJS Pro) — pull by requestId
const response = await fetch(`https://eu.api.fpjs.io/events/${requestId}`, {
  headers: { "Auth-API-Key": "fpjs-api-key" },
})

// After (TRACIO) — receive a signed webhook per identification
app.post("/webhook/tracio", (req, res) => {
  // verify req.headers["x-tracio-signature"], then act on req.body
  const event = req.body // { requestId, visitorId, bot, geo, network, decision, ... }
  res.status(200).send("OK")
})

完整的载荷和签名验证方法见 Webhooks。

第 6 步：更新 webhook 配置

如果你使用 webhook，请在 TRACIO 控制台中注册它们。 webhook 载荷 是一份扁平的 camelCase 文档，使用 X-Tracio-Signature 头签名——它与 FingerprintJS webhook 格式不同， 因此请相应地更新你的处理程序。

第 7 步：停用 FingerprintJS Pro

一旦 TRACIO 在生产环境中通过验证：

1. 从你的代码库中移除 FingerprintJS Pro 客户端 SDK
2. 取消你的 FingerprintJS Pro 订阅
3. 删除指向 fpcdn.io 的 CNAME DNS 记录

响应格式对比

TRACIO 和 FingerprintJS 使用不同的响应结构——这是移植代码时 最需要注意的一点。

客户端响应

TRACIO 客户端 SDK 解析为一个紧凑的结果：

{
  "visitorId": "X7fh2Hg9LkMn3pQr",
  "bot": { "detected": false, "confidence": 2, "reasons": [] }
}

服务端事件（webhook）

TRACIO 不返回经轮询获取的服务端 API 响应，而是为每次识别交付一份扁平的 camelCase webhook 载荷——不是 FingerprintJS 的 products 结构：

{
  "requestId": "1710432000_abc123def",
  "visitorId": "X7fh2Hg9LkMn3pQr",
  "identification": { "confidence": 0.95 },
  "bot": { "result": "human", "type": "", "score": 0.02 },
  "geo": { "country": "CZ", "city": "Prague" },
  "network": { "vpn": false, "proxy": false, "tor": false, "datacenter": false },
  "decision": { "action": "allow", "riskScore": 4 }
}

完整的载荷见 Webhooks。

关键差异

TRACIO 不是 FingerprintJS 的即插即用协议替代品。除了上面 不同的 SDK 和响应结构外，还需注意：

访客 ID 的连续性

FingerprintJS Pro 与 TRACIO 之间的访客 ID 不会相同。访客 ID 是浏览器信号的哈希值，而每套系统都使用各自的哈希参数和数据库。迁移之后，每一位访客在 TRACIO 的数据库中都会显示为「新」访客。

缓解办法：使用 linkedId 字段将 TRACIO 访客 ID 映射到你现有的用户账户或会话。经过一段过渡期后，TRACIO 的访客数据库会自然地积累起来。

Cookie 名称

现有的 FingerprintJS Pro cookie 不会保留。访客会从 TRACIO 收到一个新的 _vid_t cookie。

额外信号

TRACIO 采集 FingerprintJS Pro 中不存在的额外专有信号。这些信号提供了额外的检测能力，但不会影响与现有集成的兼容性。

Sealed Results

FingerprintJS Pro 在响应中提供 sealed_result（一个用于服务端验证的加密块）。TRACIO 目前不支持 sealed result。请改用 webhooks 进行服务端验证。

迁移故障排查

置信度低于预期

迁移之后，在最初的 24–48 小时内，置信度分数可能会略低，因为 TRACIO 正在构建其访客数据库。这属于预期情况，随着访客回访并建立基于 cookie 的身份，问题会自行解决。

客户端 SDK 无法连接

请确认你已将 FingerprintJS 客户端替换为 @tracio/sdk，并且 Tracio.init() 是用一个对应正确工作区的有效公钥调用的。