Di chuyển từ FingerprintJS Pro

TRACIO tương đương với khả năng thu thập tín hiệu trình duyệt của FingerprintJS Pro v4, đồng thời cung cấp SDK riêng của mình (@tracio/sdk) và gửi kết quả về phía máy chủ qua webhook. Hướng dẫn này bao gồm quy trình di chuyển, chi tiết về sự tương đương tín hiệu, cùng những khác biệt trong SDK và định dạng phản hồi mà bạn sẽ cần cập nhật.

Tổng quan về khả năng tương thích

Sự tương đương tín hiệu

TRACIO tương đương với khả năng thu thập tín hiệu trình duyệt của FingerprintJS Pro v4, được kiểm chứng qua các bài kiểm thử so sánh Playwright tự động chạy song song với endpoint FingerprintJS Pro trên môi trường production. Bên cạnh tập tín hiệu tương đương FingerprintJS, TRACIO còn thu thập các tín hiệu độc quyền (tín hiệu bot, tamper, antidetect và persistence) mà FingerprintJS không có.

Các bước di chuyển

Bước 1: Thiết lập TRACIO

TRACIO là một dịch vụ đám mây được quản lý. Tạo tài khoản của bạn, chọn vùng dữ liệu, và sao chép public key từ dashboard. Xem Cloud Deployment để biết hướng dẫn đầy đủ. Public key của bạn an toàn để đưa vào mã phía client.

Bước 2: Kiểm thử với TRACIO Client

Trước khi chuyển đổi lưu lượng production, hãy kiểm thử với SDK client của TRACIO. Lưu ý rằng TRACIO sử dụng SDK và API riêng của mình — nó không phải là bản thay thế giao thức tương thích trực tiếp cho client FingerprintJS.

import { Tracio } from "@tracio/sdk"

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

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

So sánh thiết bị được phát hiện với tích hợp FingerprintJS Pro hiện có của bạn để xác minh quá trình di chuyển.

Bước 3: Chạy so sánh song song

Đối với các triển khai quan trọng, hãy chạy đồng thời cả hai hệ thống và so sánh kết quả:

// 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)

Lưu ý rằng visitor ID sẽ khác nhau giữa các hệ thống vì chúng được tính toán từ các cơ sở dữ liệu phía máy chủ khác nhau. Chỉ số tương thích quan trọng là cả hai hệ thống đều nhận diện cùng một thiết bị vật lý một cách nhất quán.

Bước 4: Thay thế SDK client

TRACIO cung cấp SDK client riêng của mình (@tracio/sdk) và không tái sử dụng giao thức client FingerprintJS, vì vậy đây là một thay đổi mã chứ không phải là một lần đổi DNS. Xóa client FingerprintJS và khởi tạo TRACIO bằng public key của bạn:

// 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()

Bước 5: Thay thế việc truy xuất sự kiện phía máy chủ

FingerprintJS Pro cung cấp một Server API mà bạn poll theo requestId. TRACIO không cung cấp một endpoint REST read tương đương hướng tới khách hàng — thay vào đó, kết quả được đẩy đến máy chủ của bạn dưới dạng webhook ngay khi một khách truy cập được nhận diện. Thay logic polling của bạn bằng một trình xử lý 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")
})

Xem Webhooks để biết payload đầy đủ và cách xác minh chữ ký.

Bước 6: Cập nhật cấu hình webhook

Nếu bạn dùng webhook, hãy đăng ký chúng trong dashboard TRACIO. Payload webhook là một tài liệu camelCase phẳng được ký bằng header X-Tracio-Signature — nó khác với định dạng webhook của FingerprintJS, vì vậy hãy cập nhật trình xử lý của bạn cho phù hợp.

Bước 7: Ngừng sử dụng FingerprintJS Pro

Sau khi TRACIO đã được xác minh trong môi trường production:

1. Xóa SDK client FingerprintJS Pro khỏi codebase của bạn
2. Hủy đăng ký FingerprintJS Pro của bạn
3. Xóa bản ghi DNS CNAME trỏ tới fpcdn.io

So sánh định dạng phản hồi

TRACIO và FingerprintJS sử dụng các hình dạng phản hồi khác nhau — đây là điều chính cần lưu ý khi chuyển mã.

Phản hồi phía client

SDK client của TRACIO trả về một kết quả gọn:

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

Sự kiện phía máy chủ (webhook)

Thay vì một phản hồi Server API được lấy qua polling, TRACIO gửi một payload webhook camelCase phẳng cho mỗi lần nhận diện — không phải là cấu trúc products của FingerprintJS:

{
  "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 }
}

Xem Webhooks để biết payload đầy đủ.

Những khác biệt chính

TRACIO không phải là bản thay thế giao thức tương thích trực tiếp cho FingerprintJS. Ngoài các hình dạng SDK và phản hồi khác nhau ở trên, hãy lưu ý:

Tính liên tục của Visitor ID

Visitor ID sẽ không giống nhau giữa FingerprintJS Pro và TRACIO. Visitor ID là một hash của các tín hiệu trình duyệt, và mỗi hệ thống sử dụng các tham số hashing và cơ sở dữ liệu riêng. Sau khi di chuyển, mỗi khách truy cập sẽ xuất hiện như một khách "mới" trong cơ sở dữ liệu của TRACIO.

Giải pháp giảm thiểu: Sử dụng trường linkedId để ánh xạ visitor ID của TRACIO với các tài khoản người dùng hoặc phiên hiện có của bạn. Sau một giai đoạn chuyển tiếp, cơ sở dữ liệu khách truy cập của TRACIO sẽ tự nhiên được xây dựng lên.

Tên cookie

Các cookie FingerprintJS Pro hiện có không được chuyển sang. Khách truy cập sẽ nhận một cookie _vid_t mới từ TRACIO.

Tín hiệu bổ sung

TRACIO thu thập các tín hiệu độc quyền bổ sung không có trong FingerprintJS Pro. Chúng cung cấp thêm khả năng phát hiện nhưng không ảnh hưởng đến khả năng tương thích với các tích hợp hiện có.

Sealed Results

FingerprintJS Pro cung cấp sealed_result trong phản hồi (một blob được mã hóa dùng để xác minh phía máy chủ). Hiện tại TRACIO không hỗ trợ sealed results. Thay vào đó, hãy dùng webhooks để xác minh phía máy chủ.

Xử lý sự cố khi di chuyển

Độ tin cậy thấp hơn dự kiến

Sau khi di chuyển, điểm độ tin cậy có thể thấp hơn một chút trong 24-48 giờ đầu tiên khi TRACIO xây dựng cơ sở dữ liệu khách truy cập của mình. Điều này là bình thường và sẽ được giải quyết khi khách truy cập quay lại và thiết lập danh tính dựa trên cookie.

SDK client không kết nối được

Hãy xác nhận rằng bạn đã thay thế client FingerprintJS bằng @tracio/sdk và rằng Tracio.init() được gọi với một public key hợp lệ cho workspace chính xác.