מעבר מ-FingerprintJS Pro

TRACIO תואם לאיסוף אותות הדפדפן של FingerprintJS Pro v4, ובה בעת חושף SDK משלו (@tracio/sdk) ומספק את התוצאות בצד השרת באמצעות webhooks. מדריך זה מכסה את תהליך המעבר, פרטי התאמת האותות, וההבדלים בפורמטים של ה-SDK והתגובה שתצטרכו לעדכן.

סקירת תאימות

התאמת אותות

TRACIO תואם לאיסוף אותות הדפדפן של FingerprintJS Pro v4, מאומת באמצעות בדיקות השוואה אוטומטיות ב-Playwright הרצות זו לצד זו מול נקודת הקצה של FingerprintJS Pro בסביבת הייצור. מעבר לקבוצה התואמת ל-FingerprintJS, TRACIO אוסף אותות ייחודיים (אותות bot, tamper, antidetect ו-persistence) שאין ב-FingerprintJS.

שלבי המעבר

שלב 1: הגדרת TRACIO

TRACIO הוא שירות ענן מנוהל. צרו את החשבון שלכם, בחרו את אזור הנתונים, והעתיקו את ה-public key שלכם מלוח הבקרה. ראו Cloud Deployment להדרכה המלאה. את ה-public key שלכם בטוח לשלוח בקוד צד-לקוח.

שלב 2: בדיקה עם לקוח TRACIO

לפני החלפת תעבורת הייצור, בדקו עם ה-SDK של לקוח TRACIO. שימו לב ש-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)

שימו לב שמזהי המבקרים יהיו שונים בין המערכות, מאחר שהם מחושבים ממסדי נתונים שונים בצד השרת. מדד התאימות המרכזי הוא ששתי המערכות מזהות את אותו מכשיר פיזי באופן עקבי.

שלב 4: החלפת ה-SDK של הלקוח

TRACIO מספק 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: החלפת אחזור האירועים בצד השרת

FingerprintJS Pro חושף Server API שאתם מבצעים אליו polling לפי requestId. TRACIO אינו מציע נקודת קצה מקבילה לקריאת REST הפונה ללקוח — במקום זאת, התוצאות נדחפות לשרת שלכם כ-webhooks ברגע שמבקר מזוהה. החליפו את לוגיקת ה-polling שלכם ב-handler של 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 עבור ה-payload המלא ואימות החתימה.

שלב 6: עדכון תצורת ה-Webhook

אם אתם משתמשים ב-webhooks, רשמו אותם בלוח הבקרה של TRACIO. ה- webhook payload הוא מסמך שטוח בפורמט camelCase החתום עם כותרת X-Tracio-Signature — הוא שונה מפורמט ה-webhook של FingerprintJS, לכן עדכנו את ה-handler שלכם בהתאם.

שלב 7: הוצאת FingerprintJS Pro משירות

לאחר ש-TRACIO אומת בסביבת הייצור:

1. הסירו את ה-SDK של לקוח FingerprintJS Pro מבסיס הקוד שלכם
2. בטלו את המנוי שלכם ל-FingerprintJS Pro
3. מחקו את רשומת ה-CNAME DNS המפנה ל-fpcdn.io

השוואת פורמטי התגובה

TRACIO ו-FingerprintJS משתמשים בצורות תגובה שונות — זהו הדבר המרכזי שיש להביא בחשבון בעת העברת הקוד.

תגובת הלקוח

ה-SDK של לקוח TRACIO מתפענח לתוצאה קומפקטית:

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

אירוע בצד השרת (webhook)

במקום תגובת Server API המתקבלת ב-polling, 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 אינו תחליף פרוטוקול ישיר ל-FingerprintJS. מעבר לצורות ה-SDK והתגובה השונות שלמעלה, שימו לב:

רציפות מזהה המבקר

מזהי המבקרים לא יהיו זהים בין FingerprintJS Pro ל-TRACIO. מזהה המבקר הוא hash של אותות דפדפן, וכל מערכת משתמשת בפרמטרי hashing ובמסד נתונים משלה. לאחר המעבר, כל מבקר יופיע כמבקר "חדש" במסד הנתונים של TRACIO.

הקלה: השתמשו בשדה linkedId כדי למפות מזהי מבקרים של TRACIO לחשבונות המשתמשים או ההפעלות (sessions) הקיימים שלכם. לאחר תקופת מעבר, מסד הנתונים של המבקרים ב-TRACIO ייבנה באופן טבעי.

שמות Cookie

קובצי ה-cookie הקיימים של FingerprintJS Pro אינם מועברים. מבקרים מקבלים cookie חדש _vid_t מ-TRACIO.

אותות נוספים

TRACIO אוסף אותות ייחודיים נוספים שאינם קיימים ב-FingerprintJS Pro. אלה מספקים יכולות זיהוי נוספות אך אינם משפיעים על התאימות עם אינטגרציות קיימות.

תוצאות חתומות (Sealed Results)

FingerprintJS Pro מספק sealed_result בתגובה (blob מוצפן לאימות בצד השרת). TRACIO אינו תומך כרגע בתוצאות חתומות. השתמשו במקום זאת ב-webhooks לאימות בצד השרת.

פתרון תקלות במעבר

רמת ביטחון נמוכה מהצפוי

לאחר המעבר, ציוני רמת הביטחון עשויים להיות מעט נמוכים יותר במשך 24-48 השעות הראשונות, בזמן ש-TRACIO בונה את מסד נתוני המבקרים שלו. זהו מצב צפוי שנפתר ככל שמבקרים חוזרים ומבססים זהויות מבוססות-cookie.

ה-SDK של הלקוח אינו מתחבר

ודאו שהחלפתם את לקוח FingerprintJS ב-@tracio/sdk ושה- Tracio.init() נקרא עם public key תקף עבור ה-workspace הנכון.