Migrering från FingerprintJS Pro

TRACIO matchar signalinsamlingen i webbläsaren från FingerprintJS Pro v4, samtidigt som det exponerar sitt eget SDK (@tracio/sdk) och levererar resultat på serversidan via webhooks. Den här guiden beskriver migreringsprocessen, detaljer om signalparitet samt skillnaderna i de SDK- och svarsformat som du behöver uppdatera.

Kompatibilitetsöversikt

Signalparitet

TRACIO matchar signalinsamlingen i webbläsaren från FingerprintJS Pro v4, verifierad via automatiserade jämförelsetester i Playwright som körs sida vid sida mot den produktionssatta FingerprintJS Pro-endpunkten. Utöver den FingerprintJS-matchande uppsättningen samlar TRACIO in proprietära signaler (bot-, tamper-, antidetect- och persistenssignaler) som FingerprintJS inte har.

Migreringssteg

Steg 1: Konfigurera TRACIO

TRACIO är en hanterad molntjänst. Skapa ditt konto, välj din dataregion och kopiera din publika nyckel från instrumentpanelen. Se Cloud Deployment för den fullständiga genomgången. Din publika nyckel är säker att skicka ut i klientkod.

Steg 2: Testa med TRACIO-klienten

Innan du växlar över din produktionstrafik, testa med TRACIO:s klient-SDK. Observera att TRACIO använder sitt eget SDK och API – det är ingen direkt protokollersättning för FingerprintJS-klienten.

import { Tracio } from "@tracio/sdk"

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

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

Jämför den identifierade enheten med din befintliga FingerprintJS Pro-integration för att verifiera migreringen.

Steg 3: Kör jämförelse sida vid sida

För kritiska driftsättningar, kör båda systemen samtidigt och jämför resultaten:

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

Observera att besökar-ID:n kommer att skilja sig mellan systemen eftersom de beräknas från olika databaser på serversidan. Den centrala kompatibilitetsmetriken är att båda systemen identifierar samma fysiska enhet konsekvent.

Steg 4: Byt ut klient-SDK:t

TRACIO levererar sitt eget klient-SDK (@tracio/sdk) och återanvänder inte FingerprintJS-klientprotokollet, så detta är en kodändring snarare än ett DNS-byte. Ta bort FingerprintJS-klienten och initiera TRACIO med din publika nyckel:

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

Steg 5: Byt ut hämtning av händelser på serversidan

FingerprintJS Pro exponerar ett Server-API som du pollar med requestId. TRACIO erbjuder ingen motsvarande kundvänd REST-läs-endpunkt – i stället skickas resultaten till din server som webhooks i det ögonblick en besökare identifieras. Ersätt din polling-logik med en webhook-hanterare:

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

Se Webhooks för den fullständiga payloaden och verifiering av signaturen.

Steg 6: Uppdatera webhook-konfigurationen

Om du använder webhooks, registrera dem i TRACIO-instrumentpanelen. Webhook-payloaden är ett platt camelCase-dokument signerat med en X-Tracio-Signature-header – det skiljer sig från FingerprintJS webhook-format, så uppdatera din hanterare därefter.

Steg 7: Avveckla FingerprintJS Pro

När TRACIO är verifierat i produktion:

1. Ta bort FingerprintJS Pro-klient-SDK:t från din kodbas
2. Säg upp din FingerprintJS Pro-prenumeration
3. Ta bort CNAME-DNS-posten som pekar på fpcdn.io

Jämförelse av svarsformat

TRACIO och FingerprintJS använder olika svarsformer – detta är det viktigaste att ta hänsyn till när du porterar kod.

Klientsvar

TRACIO:s klient-SDK löser upp till ett kompakt resultat:

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

Händelse på serversidan (webhook)

I stället för ett pollat Server-API-svar levererar TRACIO en platt camelCase-payload per identifiering – inte FingerprintJS products-struktur:

{
  "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 }
}

Se Webhooks för den fullständiga payloaden.

Viktiga skillnader

TRACIO är inte en direkt protokollersättning för FingerprintJS. Utöver de olika SDK- och svarsformerna ovan bör du notera:

Kontinuitet för besökar-ID

Besökar-ID:n kommer inte att vara desamma mellan FingerprintJS Pro och TRACIO. Besökar-ID:t är en hash av webbläsarsignaler, och varje system använder sina egna hashparametrar och sin egen databas. Efter migreringen kommer varje besökare att framstå som en "ny" besökare i TRACIO:s databas.

Åtgärd: Använd fältet linkedId för att mappa TRACIO-besökar-ID:n till dina befintliga användarkonton eller sessioner. Efter en övergångsperiod byggs TRACIO:s besökardatabas upp på ett naturligt sätt.

Cookie-namn

Befintliga FingerprintJS Pro-cookies förs inte över. Besökare får en ny _vid_t-cookie från TRACIO.

Ytterligare signaler

TRACIO samlar in ytterligare proprietära signaler som inte finns i FingerprintJS Pro. Dessa ger ytterligare detekteringsmöjligheter men påverkar inte kompatibiliteten med befintliga integrationer.

Sealed Results

FingerprintJS Pro tillhandahåller sealed_result i svaret (en krypterad blob för verifiering på serversidan). TRACIO stöder för närvarande inte sealed results. Använd webhooks för verifiering på serversidan i stället.

Felsökning vid migrering

Konfidens lägre än förväntat

Efter migreringen kan konfidensvärdena vara något lägre under de första 24–48 timmarna medan TRACIO bygger upp sin besökardatabas. Detta är förväntat och löser sig i takt med att besökare återvänder och etablerar cookiebaserade identiteter.

Klient-SDK ansluter inte

Bekräfta att du har ersatt FingerprintJS-klienten med @tracio/sdk och att Tracio.init() anropas med en giltig publik nyckel för rätt arbetsyta.