การย้ายจาก FingerprintJS Pro

TRACIO เทียบเท่ากับการเก็บสัญญาณเบราว์เซอร์ของ FingerprintJS Pro v4 ขณะเดียวกัน ก็เปิดให้ใช้ SDK ของตัวเอง (@tracio/sdk) และส่งมอบผลลัพธ์ฝั่งเซิร์ฟเวอร์ผ่าน webhooks คู่มือนี้ครอบคลุมกระบวนการย้าย รายละเอียดความเทียบเท่าของสัญญาณ และความแตกต่างใน รูปแบบของ SDK และการตอบกลับที่คุณจะต้องปรับเปลี่ยน

ภาพรวมความเข้ากันได้

ความเทียบเท่าของสัญญาณ

TRACIO เทียบเท่ากับการเก็บสัญญาณเบราว์เซอร์ของ FingerprintJS Pro v4 ซึ่งได้รับการยืนยันผ่าน การทดสอบเปรียบเทียบด้วย Playwright แบบอัตโนมัติที่รันเคียงข้างกันกับ endpoint ของ FingerprintJS Pro ในโปรดักชัน นอกเหนือจากชุดที่ตรงกับ FingerprintJS แล้ว TRACIO ยัง เก็บสัญญาณเฉพาะของตัวเอง (สัญญาณ bot, tamper, antidetect และ persistence) ที่ FingerprintJS ไม่มี

ขั้นตอนการย้าย

ขั้นที่ 1: ตั้งค่า TRACIO

TRACIO เป็นบริการคลาวด์แบบจัดการให้ สร้างบัญชีของคุณ เลือกภูมิภาคข้อมูลของคุณ และคัดลอก public key ของคุณจากแดชบอร์ด ดูรายละเอียดทั้งหมดได้ที่ Cloud Deployment public key ของคุณ ปลอดภัยที่จะนำไปใช้ในโค้ดฝั่งไคลเอนต์

ขั้นที่ 2: ทดสอบด้วย TRACIO Client

ก่อนที่จะสลับทราฟฟิกโปรดักชันของคุณ ให้ทดสอบด้วย client SDK ของ TRACIO โปรดทราบ ว่า TRACIO ใช้ SDK และ API ของตัวเอง — ไม่ใช่ตัวแทนโปรโตคอลแบบ drop-in สำหรับไคลเอนต์ของ 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)

โปรดทราบว่า visitor ID จะแตกต่างกันระหว่างระบบ เนื่องจากถูกคำนวณจากฐานข้อมูลฝั่งเซิร์ฟเวอร์ที่ต่างกัน ตัวชี้วัดความเข้ากันได้ที่สำคัญคือทั้งสองระบบระบุอุปกรณ์กายภาพเดียวกันได้อย่างสอดคล้องกัน

ขั้นที่ 4: แทนที่ Client SDK

TRACIO มาพร้อมกับ client SDK ของตัวเอง (@tracio/sdk) และไม่ได้นำโปรโตคอลไคลเอนต์ ของ FingerprintJS มาใช้ซ้ำ ดังนั้นนี่จึงเป็นการแก้ไขโค้ดไม่ใช่การสลับ DNS ลบไคลเอนต์ของ FingerprintJS และเริ่มต้น TRACIO ด้วย public key ของคุณ:

// 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: แทนที่การดึงข้อมูล Event ฝั่งเซิร์ฟเวอร์

FingerprintJS Pro เปิดให้ใช้ Server API ที่คุณ poll ด้วย requestId TRACIO ไม่ได้ มี REST read endpoint ที่ลูกค้าเข้าถึงได้เทียบเท่ากัน — แต่ผลลัพธ์จะถูก ผลักไปยังเซิร์ฟเวอร์ของคุณในรูปแบบ webhooks ทันทีที่ระบุตัวผู้เข้าชมได้ แทนที่ตรรกะ polling ของคุณด้วย webhook handler:

// 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 สำหรับ payload ทั้งหมดและการตรวจสอบลายเซ็น

ขั้นที่ 6: อัปเดตการตั้งค่า Webhook

หากคุณใช้ webhooks ให้ลงทะเบียนไว้ในแดชบอร์ด TRACIO webhook payload เป็นเอกสารแบบ camelCase ราบเรียบที่ลงลายเซ็นด้วย header X-Tracio-Signature — มันแตกต่างจากรูปแบบ webhook ของ FingerprintJS ดังนั้นให้อัปเดต handler ของคุณตามนั้น

ขั้นที่ 7: ปลดระวาง FingerprintJS Pro

เมื่อ TRACIO ได้รับการยืนยันในโปรดักชันแล้ว:

1. ลบ FingerprintJS Pro client SDK ออกจาก codebase ของคุณ
2. ยกเลิกการสมัครสมาชิก FingerprintJS Pro ของคุณ
3. ลบ CNAME DNS record ที่ชี้ไปยัง fpcdn.io

การเปรียบเทียบรูปแบบการตอบกลับ

TRACIO และ FingerprintJS ใช้รูปแบบการตอบกลับที่ต่างกัน — นี่คือสิ่งหลักที่ ต้องคำนึงถึงเมื่อพอร์ตโค้ด

การตอบกลับฝั่งไคลเอนต์

Client SDK ของ TRACIO คืนค่าเป็นผลลัพธ์ที่กระชับ:

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

Event ฝั่งเซิร์ฟเวอร์ (webhook)

แทนที่จะเป็นการตอบกลับ Server API ที่ได้จากการ poll TRACIO จะส่งมอบ payload แบบ camelCase ราบเรียบต่อการระบุตัวแต่ละครั้ง — ไม่ใช่โครงสร้าง products ของ 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 }
}

ดู Webhooks สำหรับ payload ทั้งหมด

ความแตกต่างหลัก

TRACIO ไม่ใช่ ตัวแทนโปรโตคอลแบบ drop-in สำหรับ FingerprintJS นอกเหนือจาก SDK และรูปแบบการตอบกลับที่ต่างกันข้างต้นแล้ว โปรดทราบว่า:

ความต่อเนื่องของ Visitor ID

Visitor ID จะ ไม่ เหมือนกันระหว่าง FingerprintJS Pro กับ TRACIO visitor ID เป็นแฮชของสัญญาณเบราว์เซอร์ และแต่ละระบบใช้พารามิเตอร์การแฮชและฐานข้อมูลของตัวเอง หลังจากการย้าย ผู้เข้าชมทุกคนจะปรากฏเป็นผู้เข้าชม "ใหม่" ในฐานข้อมูลของ TRACIO

การบรรเทา: ใช้ฟิลด์ linkedId เพื่อจับคู่ visitor ID ของ TRACIO กับบัญชีผู้ใช้หรือเซสชันที่มีอยู่ของคุณ หลังจากช่วงเปลี่ยนผ่าน ฐานข้อมูลผู้เข้าชมของ TRACIO จะก่อตัวขึ้นตามธรรมชาติ

ชื่อ Cookie

Cookie ของ FingerprintJS Pro ที่มีอยู่จะไม่ถูกนำมาใช้ต่อ ผู้เข้าชมจะได้รับ cookie _vid_t ใหม่จาก TRACIO

สัญญาณเพิ่มเติม

TRACIO เก็บสัญญาณเฉพาะเพิ่มเติมที่ไม่มีใน FingerprintJS Pro สัญญาณเหล่านี้ให้ความสามารถในการตรวจจับเพิ่มเติม แต่ไม่กระทบต่อความเข้ากันได้กับการผสานรวมที่มีอยู่

Sealed Results

FingerprintJS Pro ให้ sealed_result ในการตอบกลับ (blob ที่เข้ารหัสสำหรับการตรวจสอบฝั่งเซิร์ฟเวอร์) ปัจจุบัน TRACIO ยังไม่รองรับ sealed results ให้ใช้ webhooks สำหรับการตรวจสอบฝั่งเซิร์ฟเวอร์แทน

การแก้ปัญหาการย้าย

Confidence ต่ำกว่าที่คาดไว้

หลังจากการย้าย คะแนน confidence อาจต่ำลงเล็กน้อยในช่วง 24-48 ชั่วโมงแรกขณะที่ TRACIO สร้างฐานข้อมูลผู้เข้าชม นี่เป็นเรื่องที่คาดไว้และจะคลี่คลายเมื่อผู้เข้าชมกลับมาและสร้างอัตลักษณ์ที่อิงกับ cookie

Client SDK เชื่อมต่อไม่ได้

ยืนยันว่าคุณได้แทนที่ไคลเอนต์ของ FingerprintJS ด้วย @tracio/sdk แล้ว และ Tracio.init() ถูกเรียกด้วย public key ที่ถูกต้องสำหรับ workspace ที่ถูกต้อง