Migrazione da FingerprintJS Pro

TRACIO corrisponde alla raccolta di segnali del browser di FingerprintJS Pro v4 esponendo al contempo il proprio SDK (@tracio/sdk) e consegnando i risultati lato server tramite webhook. Questa guida copre il processo di migrazione, i dettagli sulla parità dei segnali e le differenze nei formati di SDK e risposta che occorrerà aggiornare.

Panoramica sulla compatibilità

Parità dei segnali

TRACIO corrisponde alla raccolta di segnali del browser di FingerprintJS Pro v4, verificata tramite test di confronto Playwright automatizzati eseguiti fianco a fianco contro l'endpoint di produzione di FingerprintJS Pro. Oltre al set FingerprintJS-matching, TRACIO raccoglie segnali proprietari (segnali bot, tamper, antidetect e di persistenza) che FingerprintJS non ha.

Passi della migrazione

Passo 1: configurare TRACIO

TRACIO è un servizio cloud gestito. Creare il proprio account, scegliere la propria regione dati e copiare la propria public key dalla dashboard. Vedi Cloud Deployment per la procedura completa. La propria public key è sicura da distribuire nel codice lato client.

Passo 2: testare con il client TRACIO

Prima di commutare il proprio traffico di produzione, testare con l'SDK client di TRACIO. Si noti che TRACIO usa il proprio SDK e la propria API — non è una sostituzione di protocollo drop-in per il client FingerprintJS.

import { Tracio } from "@tracio/sdk"

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

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

Confrontare il dispositivo rilevato con la propria integrazione FingerprintJS Pro esistente per verificare la migrazione.

Passo 3: eseguire un confronto fianco a fianco

Per i deployment critici, eseguire entrambi i sistemi simultaneamente e confrontare i risultati:

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

Si noti che gli ID visitatore saranno diversi tra i sistemi, poiché sono calcolati da database lato server differenti. La metrica di compatibilità chiave è che entrambi i sistemi identifichino lo stesso dispositivo fisico in modo coerente.

Passo 4: sostituire l'SDK client

TRACIO distribuisce il proprio SDK client (@tracio/sdk) e non riutilizza il protocollo del client FingerprintJS, quindi si tratta di una modifica al codice anziché di uno scambio DNS. Rimuovere il client FingerprintJS e inizializzare TRACIO con la propria public key:

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

Passo 5: sostituire il recupero degli eventi lato server

FingerprintJS Pro espone una Server API che si interroga tramite requestId. TRACIO non offre un endpoint REST di lettura equivalente rivolto al cliente — invece, i risultati sono inviati al proprio server come webhook nel momento in cui un visitatore viene identificato. Sostituire la propria logica di polling con un handler di 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")
})

Vedi Webhooks per il payload completo e la verifica della firma.

Passo 6: aggiornare la configurazione dei webhook

Se si usano i webhook, registrarli nella dashboard di TRACIO. Il payload del webhook è un documento piatto, camelCase, firmato con un header X-Tracio-Signature — differisce dal formato webhook di FingerprintJS, quindi aggiornare il proprio handler di conseguenza.

Passo 7: dismettere FingerprintJS Pro

Una volta verificato TRACIO in produzione:

1. Rimuovere l'SDK client di FingerprintJS Pro dal proprio codebase
2. Annullare il proprio abbonamento a FingerprintJS Pro
3. Eliminare il record DNS CNAME che punta a fpcdn.io

Confronto dei formati di risposta

TRACIO e FingerprintJS usano strutture di risposta diverse — questo è il punto principale di cui tenere conto quando si porta il codice.

Risposta client

L'SDK client di TRACIO si risolve in un risultato compatto:

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

Evento lato server (webhook)

Invece di una risposta della Server API interrogata via polling, TRACIO consegna un payload webhook piatto, camelCase, per ogni identificazione — non la struttura products di 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 }
}

Vedi Webhooks per il payload completo.

Differenze chiave

TRACIO non è una sostituzione di protocollo drop-in per FingerprintJS. Oltre alle diverse strutture di SDK e risposta di cui sopra, si noti:

Continuità dell'ID visitatore

Gli ID visitatore non saranno gli stessi tra FingerprintJS Pro e TRACIO. L'ID visitatore è un hash dei segnali del browser, e ogni sistema usa i propri parametri di hashing e il proprio database. Dopo la migrazione, ogni visitatore apparirà come un «nuovo» visitatore nel database di TRACIO.

Mitigazione: usare il campo linkedId per mappare gli ID visitatore di TRACIO ai propri account utente o sessioni esistenti. Dopo un periodo di transizione, il database dei visitatori di TRACIO si costruirà naturalmente.

Nomi dei cookie

I cookie FingerprintJS Pro esistenti non vengono trasferiti. I visitatori ricevono un nuovo cookie _vid_t da TRACIO.

Segnali aggiuntivi

TRACIO raccoglie ulteriori segnali proprietari che non sono presenti in FingerprintJS Pro. Questi forniscono capacità di rilevamento aggiuntive ma non incidono sulla compatibilità con le integrazioni esistenti.

Risultati sigillati

FingerprintJS Pro fornisce sealed_result nella risposta (un blob cifrato per la verifica lato server). TRACIO al momento non supporta i risultati sigillati. Usare invece i webhook per la verifica lato server.

Risoluzione dei problemi di migrazione

Confidenza inferiore alle attese

Dopo la migrazione, i punteggi di confidenza potrebbero essere leggermente inferiori per le prime 24-48 ore mentre TRACIO costruisce il suo database di visitatori. Questo è previsto e si risolve man mano che i visitatori tornano e stabiliscono identità basate sui cookie.

L'SDK client non si connette

Verificare di aver sostituito il client FingerprintJS con @tracio/sdk e che Tracio.init() sia chiamato con una public key valida per il workspace corretto.