Migratie van FingerprintJS Pro

TRACIO komt overeen met de browsersignaalverzameling van FingerprintJS Pro v4, maar stelt zijn eigen SDK (@tracio/sdk) beschikbaar en levert de resultaten serverzijdig via webhooks. Deze handleiding behandelt het migratieproces, de details van de signaalpariteit en de verschillen in de SDK- en antwoordformaten die u moet aanpassen.

Compatibiliteitsoverzicht

Signaalpariteit

TRACIO komt overeen met de browsersignaalverzameling van FingerprintJS Pro v4, geverifieerd via geautomatiseerde Playwright-vergelijkingstests die parallel draaien tegen het productie-eindpunt van FingerprintJS Pro. Bovenop de FingerprintJS-overeenkomstige set verzamelt TRACIO proprietaire signalen (bot-, tamper-, antidetect- en persistentiesignalen) die FingerprintJS niet biedt.

Migratiestappen

Stap 1: TRACIO instellen

TRACIO is een beheerde clouddienst. Maak uw account aan, kies uw dataregio en kopieer uw public key uit het dashboard. Zie Cloud Deployment voor de volledige uitleg. Uw public key kan veilig in clientzijdige code worden meegeleverd.

Stap 2: Testen met de TRACIO-client

Voordat u uw productieverkeer omschakelt, test u met de client-SDK van TRACIO. Let op dat TRACIO zijn eigen SDK en API gebruikt — het is geen directe protocolvervanging voor de FingerprintJS-client.

import { Tracio } from "@tracio/sdk"

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

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

Vergelijk het gedetecteerde apparaat met uw bestaande FingerprintJS Pro-integratie om de migratie te verifiëren.

Stap 3: Vergelijking parallel uitvoeren

Voer voor kritieke deployments beide systemen tegelijk uit en vergelijk de 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)

Let op dat de bezoekers-ID's tussen de systemen zullen verschillen, omdat ze worden berekend uit verschillende serverzijdige databases. De belangrijkste compatibiliteitsmetriek is dat beide systemen hetzelfde fysieke apparaat consistent identificeren.

Stap 4: De client-SDK vervangen

TRACIO levert zijn eigen client-SDK (@tracio/sdk) en hergebruikt het FingerprintJS-clientprotocol niet, zodat dit een codewijziging is en geen DNS-omwisseling. Verwijder de FingerprintJS-client en initialiseer TRACIO met uw 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()

Stap 5: Serverzijdig ophalen van events vervangen

FingerprintJS Pro stelt een Server-API beschikbaar die u per requestId opvraagt. TRACIO biedt geen gelijkwaardig klantgericht REST-lees-eindpunt — in plaats daarvan worden de resultaten als webhooks naar uw server gepusht op het moment dat een bezoeker wordt geïdentificeerd. Vervang uw polling-logica door een webhook-handler:

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

Zie Webhooks voor de volledige payload en de handtekeningverificatie.

Stap 6: Webhook-configuratie bijwerken

Als u webhooks gebruikt, registreert u ze in het TRACIO-dashboard. De webhook-payload is een plat camelCase-document, ondertekend met een X-Tracio-Signature-header — het verschilt van het FingerprintJS-webhookformaat, dus werk uw handler dienovereenkomstig bij.

Stap 7: FingerprintJS Pro buiten gebruik stellen

Zodra TRACIO in productie is geverifieerd:

1. Verwijder de FingerprintJS Pro-client-SDK uit uw codebase
2. Zeg uw FingerprintJS Pro-abonnement op
3. Verwijder de CNAME-DNS-record die naar fpcdn.io verwijst

Vergelijking van antwoordformaten

TRACIO en FingerprintJS gebruiken verschillende antwoordvormen — dat is het belangrijkste waar u rekening mee moet houden bij het overzetten van code.

Client-antwoord

De client-SDK van TRACIO lost op naar een compact resultaat:

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

Serverzijdig event (webhook)

In plaats van een per polling opgehaald Server-API-antwoord levert TRACIO per identificatie een platte camelCase-webhook-payload — niet de products-structuur van 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 }
}

Zie Webhooks voor de volledige payload.

Belangrijkste verschillen

TRACIO is geen directe protocolvervanging voor FingerprintJS. Naast de verschillende SDK- en antwoordvormen hierboven geldt het volgende:

Continuïteit van bezoekers-ID

Bezoekers-ID's zullen niet gelijk zijn tussen FingerprintJS Pro en TRACIO. De bezoekers-ID is een hash van browsersignalen, en elk systeem gebruikt zijn eigen hashing-parameters en database. Na de migratie verschijnt elke bezoeker aanvankelijk als een "nieuwe" bezoeker in de database van TRACIO.

Oplossing: Gebruik het veld linkedId om TRACIO-bezoekers-ID's te koppelen aan uw bestaande gebruikersaccounts of sessies. Na een overgangsperiode bouwt de bezoekersdatabase van TRACIO zich op natuurlijke wijze op.

Cookienamen

Bestaande FingerprintJS Pro-cookies worden niet overgenomen. Bezoekers krijgen een nieuw _vid_t-cookie van TRACIO.

Aanvullende signalen

TRACIO verzamelt aanvullende proprietaire signalen die niet aanwezig zijn in FingerprintJS Pro. Deze bieden extra detectiemogelijkheden, maar hebben geen invloed op de compatibiliteit met bestaande integraties.

Sealed Results

FingerprintJS Pro levert sealed_result in het antwoord (een versleutelde blob voor serverzijdige verificatie). TRACIO ondersteunt op dit moment geen sealed results. Gebruik in plaats daarvan webhooks voor serverzijdige verificatie.

Problemen met de migratie oplossen

Confidence lager dan verwacht

Na de migratie kunnen de confidence-scores de eerste 24-48 uur iets lager uitvallen terwijl TRACIO zijn bezoekersdatabase opbouwt. Dit is te verwachten en verdwijnt zodra bezoekers terugkeren en cookiegebaseerde identiteiten vestigen.

Client-SDK maakt geen verbinding

Controleer of u de FingerprintJS-client hebt vervangen door @tracio/sdk en of Tracio.init() wordt aangeroepen met een geldige public key voor de juiste workspace.