Миграция с FingerprintJS Pro

TRACIO повторяет сбор браузерных сигналов FingerprintJS Pro v4, при этом предоставляет собственный SDK (@tracio/sdk) и доставляет результаты на стороне сервера через webhooks. Это руководство охватывает процесс миграции, детали паритета сигналов, а также различия в форматах SDK и ответов, которые вам потребуется учесть.

Обзор совместимости

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

TRACIO повторяет сбор браузерных сигналов FingerprintJS Pro v4, что проверено автоматизированными сравнительными тестами Playwright, работающими параллельно с боевым эндпоинтом FingerprintJS Pro. Помимо набора, соответствующего FingerprintJS, TRACIO собирает проприетарные сигналы (bot, tamper, 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-эндпоинта для чтения — вместо этого результаты отправляются на ваш сервер как webhooks в момент идентификации посетителя. Замените логику опроса обработчиком 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")
})

Полный payload и проверку подписи см. в разделе Webhooks.

Шаг 6. Обновите конфигурацию webhook

Если вы используете webhooks, зарегистрируйте их в панели управления TRACIO. Payload 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 доставляет плоский 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. Вместо этого используйте webhooks для серверной верификации.

Устранение неполадок при миграции

Уверенность ниже ожидаемой

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

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

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