Migrarea de la FingerprintJS Pro

TRACIO reproduce colectarea de semnale din browser a FingerprintJS Pro v4, expunând totodată propriul SDK (@tracio/sdk) și livrând rezultatele pe partea de server prin webhook-uri. Acest ghid acoperă procesul de migrare, detaliile privind paritatea semnalelor și diferențele la nivelul SDK-ului și al formatelor de răspuns pe care va trebui să le actualizezi.

Prezentare generală a compatibilității

Paritatea semnalelor

TRACIO reproduce colectarea de semnale din browser a FingerprintJS Pro v4, verificată prin teste automate de comparație Playwright care rulează în paralel cu endpoint-ul de producție FingerprintJS Pro. Pe lângă setul echivalent cu FingerprintJS, TRACIO colectează semnale proprietare (semnale de bot, tamper, antidetect și persistență) pe care FingerprintJS nu le oferă.

Pași de migrare

Pasul 1: Configurează TRACIO

TRACIO este un serviciu cloud gestionat. Creează-ți contul, alege regiunea de date și copiază-ți cheia publică din dashboard. Consultă Cloud Deployment pentru parcurgerea completă. Cheia ta publică poate fi inclusă în siguranță în codul client.

Pasul 2: Testează cu clientul TRACIO

Înainte de a comuta traficul de producție, testează cu SDK-ul client al TRACIO. Reține că TRACIO folosește propriul SDK și API — nu este un înlocuitor de protocol interschimbabil pentru clientul FingerprintJS.

import { Tracio } from "@tracio/sdk"

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

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

Compară dispozitivul detectat cu integrarea ta existentă FingerprintJS Pro pentru a verifica migrarea.

Pasul 3: Rulează o comparație în paralel

Pentru deployment-uri critice, rulează ambele sisteme simultan și compară rezultatele:

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

Reține că ID-urile de vizitator vor diferi între sisteme, întrucât sunt calculate din baze de date diferite pe partea de server. Metrica de compatibilitate esențială este că ambele sisteme identifică în mod consecvent același dispozitiv fizic.

Pasul 4: Înlocuiește SDK-ul client

TRACIO livrează propriul SDK client (@tracio/sdk) și nu reutilizează protocolul clientului FingerprintJS, așa că aceasta este o modificare de cod, nu o schimbare de DNS. Elimină clientul FingerprintJS și inițializează TRACIO cu cheia ta publică:

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

Pasul 5: Înlocuiește preluarea evenimentelor pe partea de server

FingerprintJS Pro expune un Server API pe care îl interoghezi după requestId. TRACIO nu oferă un endpoint REST de citire echivalent, orientat spre client — în schimb, rezultatele sunt trimise pe serverul tău sub formă de webhook-uri în momentul în care un vizitator este identificat. Înlocuiește logica de polling cu un handler de 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")
})

Consultă Webhooks pentru payload-ul complet și verificarea semnăturii.

Pasul 6: Actualizează configurația webhook-urilor

Dacă folosești webhook-uri, înregistrează-le în dashboard-ul TRACIO. Payload-ul webhook este un document plat, în format camelCase, semnat cu un header X-Tracio-Signature — diferă de formatul de webhook FingerprintJS, așa că actualizează-ți handler-ul în consecință.

Pasul 7: Scoate din uz FingerprintJS Pro

După ce TRACIO este verificat în producție:

1. Elimină SDK-ul client FingerprintJS Pro din baza ta de cod
2. Anulează abonamentul FingerprintJS Pro
3. Șterge înregistrarea DNS CNAME care indică spre fpcdn.io

Compararea formatelor de răspuns

TRACIO și FingerprintJS folosesc forme de răspuns diferite — acesta este principalul aspect de luat în calcul atunci când portezi codul.

Răspunsul pe client

SDK-ul client al TRACIO se rezolvă la un rezultat compact:

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

Eveniment pe partea de server (webhook)

În loc de un răspuns de Server API preluat prin polling, TRACIO livrează un payload webhook plat, în format camelCase, pentru fiecare identificare — nu structura products a 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 }
}

Consultă Webhooks pentru payload-ul complet.

Diferențe esențiale

TRACIO nu este un înlocuitor de protocol interschimbabil pentru FingerprintJS. Pe lângă formele diferite de SDK și de răspuns de mai sus, reține:

Continuitatea ID-ului de vizitator

ID-urile de vizitator nu vor fi identice între FingerprintJS Pro și TRACIO. ID-ul de vizitator este un hash al semnalelor din browser, iar fiecare sistem folosește propriii parametri de hashing și propria bază de date. După migrare, fiecare vizitator va apărea drept vizitator „nou” în baza de date a TRACIO.

Măsură de atenuare: Folosește câmpul linkedId pentru a mapa ID-urile de vizitator TRACIO la conturile sau sesiunile tale de utilizator existente. După o perioadă de tranziție, baza de date de vizitatori a TRACIO se va construi în mod natural.

Numele cookie-urilor

Cookie-urile FingerprintJS Pro existente nu sunt preluate. Vizitatorii primesc un nou cookie _vid_t de la TRACIO.

Semnale suplimentare

TRACIO colectează semnale proprietare suplimentare care nu sunt prezente în FingerprintJS Pro. Acestea oferă capabilități de detecție suplimentare, dar nu afectează compatibilitatea cu integrările existente.

Sealed Results

FingerprintJS Pro furnizează sealed_result în răspuns (un blob criptat pentru verificarea pe partea de server). TRACIO nu acceptă în prezent sealed results. Folosește în schimb webhook-urile pentru verificarea pe partea de server.

Depanarea migrării

Nivel de încredere mai mic decât cel așteptat

După migrare, scorurile de încredere pot fi ușor mai mici în primele 24–48 de ore, în timp ce TRACIO își construiește baza de date de vizitatori. Acest lucru este de așteptat și se rezolvă pe măsură ce vizitatorii revin și își stabilesc identități bazate pe cookie-uri.

SDK-ul client nu se conectează

Verifică dacă ai înlocuit clientul FingerprintJS cu @tracio/sdk și dacă Tracio.init() este apelat cu o cheie publică validă pentru workspace-ul corect.