الترحيل من FingerprintJS Pro

يطابق TRACIO جمع إشارات المتصفح في FingerprintJS Pro v4 مع توفير حزمة SDK الخاصة به (@tracio/sdk) وتسليم النتائج من جانب الخادم عبر webhooks. يغطي هذا الدليل عملية الترحيل، وتفاصيل تكافؤ الإشارات، والاختلافات في صيغ SDK والاستجابة التي ستحتاج إلى تحديثها.

نظرة عامة على التوافق

تكافؤ الإشارات

يطابق TRACIO جمع إشارات المتصفح في FingerprintJS Pro v4، وهو ما تم التحقق منه عبر اختبارات مقارنة آلية باستخدام Playwright تعمل جنبًا إلى جنب مقابل نقطة نهاية FingerprintJS Pro الإنتاجية. وبالإضافة إلى المجموعة المطابقة لـ FingerprintJS، يجمع TRACIO إشارات مملوكة (إشارات البوت، والعبث، ومكافحة الكشف، والاستمرارية) التي لا يوفرها FingerprintJS.

خطوات الترحيل

الخطوة 1: إعداد TRACIO

‏TRACIO هو خدمة سحابية مُدارة. أنشئ حسابك، واختر منطقة بياناتك، وانسخ المفتاح العام الخاص بك من لوحة التحكم. راجع نشر السحابة للحصول على الشرح الكامل. من الآمن شحن مفتاحك العام في الكود من جانب العميل.

الخطوة 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 باستخدام مفتاحك العام:

// 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 تستعلم عنها عبر requestId. لا يوفر TRACIO نقطة نهاية REST للقراءة موجّهة للعميل مكافئة — بدلًا من ذلك، تُدفع النتائج إلى خادمك على شكل webhooks في اللحظة التي يُتعرَّف فيها على الزائر. استبدل منطق الاستطلاع (polling) لديك بمعالِج 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

إذا كنت تستخدم webhooks، فسجّلها في لوحة تحكم TRACIO. إن حمولة webhook هي مستند مسطح بصيغة camelCase موقّع بترويسة X-Tracio-Signature — وهي تختلف عن صيغة webhook الخاصة بـ FingerprintJS، لذا حدّث معالِجك وفقًا لذلك.

الخطوة 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 المُسترجَعة عبر الاستطلاع، يسلّم TRACIO حمولة webhook مسطحة بصيغة 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 للاطلاع على الحمولة الكاملة.

الاختلافات الرئيسية

‏TRACIO ليس بديلًا مباشرًا للبروتوكول عن FingerprintJS. إلى جانب اختلاف أشكال SDK والاستجابة أعلاه، لاحظ ما يلي:

استمرارية معرّف الزائر

لن تكون معرّفات الزوّار متطابقة بين FingerprintJS Pro وTRACIO. معرّف الزائر هو تجزئة (hash) لإشارات المتصفح، ويستخدم كل نظام معلمات التجزئة وقاعدة البيانات الخاصة به. بعد الترحيل، سيظهر كل زائر بوصفه زائرًا "جديدًا" في قاعدة بيانات TRACIO.

التخفيف: استخدم حقل linkedId لربط معرّفات زوّار TRACIO بحسابات المستخدمين أو الجلسات الحالية لديك. بعد فترة انتقالية، ستُبنى قاعدة بيانات الزوّار في TRACIO بشكل طبيعي.

أسماء Cookie

لا تُنقل ملفات cookie الحالية الخاصة بـ FingerprintJS Pro. يتلقى الزوّار ملف cookie جديدًا باسم _vid_t من TRACIO.

إشارات إضافية

يجمع TRACIO إشارات مملوكة إضافية غير موجودة في FingerprintJS Pro. توفر هذه الإشارات قدرات كشف إضافية لكنها لا تؤثر على التوافق مع التكاملات الحالية.

النتائج المختومة (Sealed Results)

يوفر FingerprintJS Pro sealed_result في الاستجابة (كتلة مشفّرة للتحقق من جانب الخادم). لا يدعم TRACIO حاليًا النتائج المختومة. استخدم webhooks للتحقق من جانب الخادم بدلًا من ذلك.

استكشاف أخطاء الترحيل وإصلاحها

الثقة أقل من المتوقع

بعد الترحيل، قد تكون درجات الثقة أقل قليلًا خلال أول 24–48 ساعة بينما يبني TRACIO قاعدة بيانات الزوّار الخاصة به. هذا أمر متوقع ويزول مع عودة الزوّار وترسيخ هويات قائمة على ملفات cookie.

حزمة SDK للعميل لا تتصل

تأكد من أنك قد استبدلت عميل FingerprintJS بـ @tracio/sdk وأن Tracio.init() يُستدعى بمفتاح عام صالح لمساحة العمل الصحيحة.