Migracja z FingerprintJS Pro

TRACIO odwzorowuje zbieranie sygnałów przeglądarki z FingerprintJS Pro v4, udostępniając przy tym własne SDK (@tracio/sdk) i dostarczając wyniki po stronie serwera za pośrednictwem webhooków. Ten przewodnik omawia proces migracji, szczegóły parytetu sygnałów oraz różnice w SDK i formatach odpowiedzi, które trzeba będzie zaktualizować.

Przegląd zgodności

Parytet sygnałów

TRACIO odwzorowuje zbieranie sygnałów przeglądarki z FingerprintJS Pro v4, zweryfikowane za pomocą zautomatyzowanych testów porównawczych Playwright działających równolegle względem produkcyjnego punktu końcowego FingerprintJS Pro. Poza zestawem zgodnym z FingerprintJS TRACIO zbiera własnościowe sygnały (sygnały botów, manipulacji, antydetekcji i trwałości), których FingerprintJS nie oferuje.

Kroki migracji

Krok 1: Skonfiguruj TRACIO

TRACIO to zarządzana usługa chmurowa. Utwórz konto, wybierz region danych i skopiuj swój klucz publiczny z panelu. Pełny przewodnik znajdziesz w Cloud Deployment. Twój klucz publiczny można bezpiecznie umieścić w kodzie po stronie klienta.

Krok 2: Przetestuj z klientem TRACIO

Zanim przełączysz produkcyjny ruch, przetestuj z klienckim SDK TRACIO. Zwróć uwagę, że TRACIO używa własnego SDK i API — nie jest to bezpośredni zamiennik protokołu dla klienta FingerprintJS.

import { Tracio } from "@tracio/sdk"

const tracio = Tracio.init({
  publicKey: "5ca175fc...",
})

const result = await tracio.getResult()
console.log(result)

Porównaj wykryte urządzenie z istniejącą integracją FingerprintJS Pro, aby zweryfikować migrację.

Krok 3: Uruchom porównanie równoległe

W przypadku krytycznych wdrożeń uruchom oba systemy jednocześnie i porównaj wyniki:

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

Zwróć uwagę, że identyfikatory odwiedzających będą różnić się między systemami, ponieważ są obliczane z różnych baz danych po stronie serwera. Kluczową metryką zgodności jest to, że oba systemy konsekwentnie identyfikują to samo fizyczne urządzenie.

Krok 4: Zamień SDK klienta

TRACIO dostarcza własne klienckie SDK (@tracio/sdk) i nie wykorzystuje ponownie protokołu klienta FingerprintJS, więc jest to zmiana kodu, a nie podmiana DNS. Usuń klienta FingerprintJS i zainicjuj TRACIO swoim kluczem publicznym:

// 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()

Krok 5: Zamień pobieranie zdarzeń po stronie serwera

FingerprintJS Pro udostępnia Server API, które odpytujesz po requestId. TRACIO nie oferuje równoważnego, dostępnego dla klienta punktu końcowego REST do odczytu — zamiast tego wyniki są wypychane na Twój serwer jako webhooki w momencie zidentyfikowania odwiedzającego. Zastąp logikę odpytywania obsługą webhooków:

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

Pełny ładunek i weryfikację podpisu znajdziesz w Webhooks.

Krok 6: Zaktualizuj konfigurację webhooków

Jeśli używasz webhooków, zarejestruj je w panelu TRACIO. Ładunek webhooka to płaski dokument w formacie camelCase podpisany nagłówkiem X-Tracio-Signature — różni się od formatu webhooków FingerprintJS, więc odpowiednio zaktualizuj swoją obsługę.

Krok 7: Wycofaj FingerprintJS Pro z eksploatacji

Gdy TRACIO zostanie zweryfikowane na produkcji:

1. Usuń klienckie SDK FingerprintJS Pro ze swojej bazy kodu
2. Anuluj subskrypcję FingerprintJS Pro
3. Usuń rekord DNS CNAME wskazujący na fpcdn.io

Porównanie formatów odpowiedzi

TRACIO i FingerprintJS używają różnych kształtów odpowiedzi — to główna rzecz, którą trzeba uwzględnić przy przenoszeniu kodu.

Odpowiedź klienta

Klienckie SDK TRACIO rozwiązuje się do zwięzłego wyniku:

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

Zdarzenie po stronie serwera (webhook)

Zamiast odpytywanej odpowiedzi Server API, TRACIO dostarcza płaski ładunek webhooka w formacie camelCase na każdą identyfikację — a nie strukturę products z 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 }
}

Pełny ładunek znajdziesz w Webhooks.

Kluczowe różnice

TRACIO nie jest bezpośrednim zamiennikiem protokołu dla FingerprintJS. Poza różnymi kształtami SDK i odpowiedzi opisanymi powyżej należy zauważyć:

Ciągłość identyfikatora odwiedzającego

Identyfikatory odwiedzających nie będą takie same między FingerprintJS Pro a TRACIO. Identyfikator odwiedzającego to hash sygnałów przeglądarki, a każdy system używa własnych parametrów haszowania i własnej bazy danych. Po migracji każdy odwiedzający pojawi się jako „nowy” odwiedzający w bazie danych TRACIO.

Środek zaradczy: Użyj pola linkedId, aby powiązać identyfikatory odwiedzających TRACIO z istniejącymi kontami użytkowników lub sesjami. Po okresie przejściowym baza danych odwiedzających TRACIO zbuduje się w naturalny sposób.

Nazwy cookie

Istniejące cookie FingerprintJS Pro nie są przenoszone. Odwiedzający otrzymują nowe cookie _vid_t od TRACIO.

Dodatkowe sygnały

TRACIO zbiera dodatkowe własnościowe sygnały, których nie ma w FingerprintJS Pro. Zapewniają one dodatkowe możliwości wykrywania, ale nie wpływają na zgodność z istniejącymi integracjami.

Sealed Results

FingerprintJS Pro dostarcza sealed_result w odpowiedzi (zaszyfrowany blob do weryfikacji po stronie serwera). TRACIO obecnie nie obsługuje sealed results. Zamiast tego użyj webhooków do weryfikacji po stronie serwera.

Rozwiązywanie problemów z migracją

Pewność niższa niż oczekiwana

Po migracji wartości pewności mogą być nieco niższe przez pierwsze 24–48 godzin, gdy TRACIO buduje swoją bazę danych odwiedzających. Jest to oczekiwane i ustępuje, gdy odwiedzający powracają i ustanawiają tożsamości oparte na cookie.

SDK klienta nie łączy się

Upewnij się, że zastąpiłeś klienta FingerprintJS przez @tracio/sdk oraz że Tracio.init() jest wywoływane z prawidłowym kluczem publicznym dla właściwego workspace.