Міграція з FingerprintJS Pro

TRACIO відповідає збиранню браузерних сигналів FingerprintJS Pro v4, водночас надаючи власний SDK (@tracio/sdk) та доставляючи результати на стороні сервера через вебхуки. Цей посібник охоплює процес міграції, деталі паритету сигналів та відмінності в SDK і форматах відповідей, які вам потрібно буде оновити.

Огляд сумісності

Паритет сигналів

TRACIO відповідає збиранню браузерних сигналів FingerprintJS Pro v4, що підтверджено автоматизованими порівняльними тестами Playwright, які виконуються паралельно з робочим ендпоінтом FingerprintJS Pro. На додачу до набору, що відповідає FingerprintJS, TRACIO збирає власні сигнали (сигнали ботів, підробки, antidetect та персистентності), яких FingerprintJS не пропонує.

Кроки міграції

Крок 1: Налаштування TRACIO

TRACIO — це керований хмарний сервіс. Створіть обліковий запис, оберіть регіон даних і скопіюйте свій публічний ключ з дашборду. Повний покроковий опис див. у Cloud Deployment. Ваш публічний ключ можна безпечно поставляти в клієнтському коді.

Крок 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-ендпоінту для читання — натомість результати надсилаються на ваш сервер як вебхуки в момент ідентифікації відвідувача. Замініть свою логіку опитування обробником вебхуків:

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

Повний payload та перевірку підпису див. у Webhooks.

Крок 6: Оновлення конфігурації вебхуків

Якщо ви використовуєте вебхуки, зареєструйте їх у дашборді TRACIO. Payload вебхука — це плаский документ у форматі camelCase, підписаний заголовком X-Tracio-Signature — він відрізняється від формату вебхука 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": [] }
}

Подія на стороні сервера (вебхук)

Замість відповіді Server API, отриманої опитуванням, 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 }
}

Повний payload див. у Webhooks.

Ключові відмінності

TRACIO не є безшовною протокольною заміною FingerprintJS. Окрім різних SDK та форм відповідей вище, зверніть увагу:

Безперервність Visitor ID

Ідентифікатори відвідувачів не будуть однаковими між FingerprintJS Pro та TRACIO. Ідентифікатор відвідувача — це хеш браузерних сигналів, і кожна система використовує власні параметри хешування та власну базу даних. Після міграції кожен відвідувач з'явиться як «новий» відвідувач у базі даних TRACIO.

Пом'якшення: Використовуйте поле linkedId, щоб зіставити ідентифікатори відвідувачів TRACIO з вашими наявними обліковими записами користувачів або сеансами. Після перехідного періоду база даних відвідувачів TRACIO наповниться природним чином.

Назви cookie

Наявні cookie FingerprintJS Pro не переносяться. Відвідувачі отримують новий cookie _vid_t від TRACIO.

Додаткові сигнали

TRACIO збирає додаткові власні сигнали, яких немає у FingerprintJS Pro. Вони надають додаткові можливості виявлення, але не впливають на сумісність із наявними інтеграціями.

Sealed Results

FingerprintJS Pro надає sealed_result у відповіді (зашифрований blob для перевірки на стороні сервера). TRACIO наразі не підтримує sealed results. Використовуйте вебхуки для перевірки на стороні сервера замість цього.

Усунення проблем міграції

Впевненість нижча за очікувану

Після міграції показники впевненості можуть бути дещо нижчими протягом перших 24–48 годин, поки TRACIO наповнює свою базу даних відвідувачів. Це очікувано й вирішується, щойно відвідувачі повертаються та встановлюють ідентичності на основі cookie.

Клієнтський SDK не підключається

Переконайтеся, що ви замінили клієнт FingerprintJS на @tracio/sdk і що Tracio.init() викликається з дійсним публічним ключем для правильного робочого простору.