Migration von FingerprintJS Pro

TRACIO entspricht der Browser-Signalerfassung von FingerprintJS Pro v4, stellt dabei sein eigenes SDK (@tracio/sdk) bereit und liefert die Ergebnisse serverseitig per Webhooks aus. Dieser Leitfaden behandelt den Migrationsprozess, Details zur Signalparität sowie die Unterschiede in den SDK- und Antwortformaten, die Sie anpassen müssen.

Kompatibilitätsüberblick

Signalparität

TRACIO entspricht der Browser-Signalerfassung von FingerprintJS Pro v4, verifiziert durch automatisierte Playwright-Vergleichstests, die parallel gegen den produktiven FingerprintJS-Pro-Endpunkt laufen. Zusätzlich zum FingerprintJS-entsprechenden Satz erfasst TRACIO proprietäre Signale (Bot-, Tamper-, Antidetect- und Persistenzsignale), die FingerprintJS nicht bietet.

Migrationsschritte

Schritt 1: TRACIO einrichten

TRACIO ist ein verwalteter Cloud-Dienst. Erstellen Sie Ihr Konto, wählen Sie Ihre Datenregion und kopieren Sie Ihren Public Key aus dem Dashboard. Die vollständige Anleitung finden Sie unter Cloud Deployment. Ihr Public Key kann sicher in clientseitigem Code ausgeliefert werden.

Schritt 2: Mit dem TRACIO-Client testen

Bevor Sie Ihren Produktivtraffic umstellen, testen Sie mit dem Client-SDK von TRACIO. Beachten Sie, dass TRACIO sein eigenes SDK und API verwendet – es ist kein direkter Protokollersatz für den FingerprintJS-Client.

import { Tracio } from "@tracio/sdk"

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

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

Vergleichen Sie das erkannte Gerät mit Ihrer bestehenden FingerprintJS-Pro-Integration, um die Migration zu verifizieren.

Schritt 3: Vergleich parallel ausführen

Führen Sie für kritische Deployments beide Systeme gleichzeitig aus und vergleichen Sie die Ergebnisse:

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

Beachten Sie, dass sich die Besucher-IDs zwischen den Systemen unterscheiden, da sie aus verschiedenen serverseitigen Datenbanken berechnet werden. Die zentrale Kompatibilitätsmetrik ist, dass beide Systeme dasselbe physische Gerät konsistent identifizieren.

Schritt 4: Das Client-SDK ersetzen

TRACIO liefert sein eigenes Client-SDK (@tracio/sdk) aus und verwendet nicht das FingerprintJS-Client-Protokoll erneut, sodass dies eine Codeänderung und kein DNS-Tausch ist. Entfernen Sie den FingerprintJS-Client und initialisieren Sie TRACIO mit Ihrem 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()

Schritt 5: Serverseitigen Event-Abruf ersetzen

FingerprintJS Pro stellt eine Server-API bereit, die Sie per requestId abfragen. TRACIO bietet keinen gleichwertigen kundenseitigen REST-Lese-Endpunkt – stattdessen werden die Ergebnisse in dem Moment, in dem ein Besucher identifiziert wird, als Webhooks an Ihren Server übermittelt. Ersetzen Sie Ihre Polling-Logik durch einen 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")
})

Den vollständigen Payload und die Signaturprüfung finden Sie unter Webhooks.

Schritt 6: Webhook-Konfiguration aktualisieren

Wenn Sie Webhooks verwenden, registrieren Sie diese im TRACIO-Dashboard. Der Webhook-Payload ist ein flaches, camelCase-formatiertes Dokument, signiert mit einem X-Tracio-Signature-Header – er unterscheidet sich vom FingerprintJS-Webhook-Format, aktualisieren Sie Ihren Handler daher entsprechend.

Schritt 7: FingerprintJS Pro außer Betrieb nehmen

Sobald TRACIO in der Produktion verifiziert ist:

1. Entfernen Sie das FingerprintJS-Pro-Client-SDK aus Ihrer Codebasis
2. Kündigen Sie Ihr FingerprintJS-Pro-Abonnement
3. Löschen Sie den CNAME-DNS-Eintrag, der auf fpcdn.io verweist

Vergleich der Antwortformate

TRACIO und FingerprintJS verwenden unterschiedliche Antwortformen – das ist der wichtigste Punkt, den Sie beim Portieren des Codes berücksichtigen müssen.

Client-Antwort

Das Client-SDK von TRACIO löst zu einem kompakten Ergebnis auf:

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

Serverseitiges Ereignis (Webhook)

Anstelle einer per Polling abgerufenen Server-API-Antwort liefert TRACIO pro Identifikation einen flachen, camelCase-formatierten Webhook-Payload – nicht die products-Struktur von 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 }
}

Den vollständigen Payload finden Sie unter Webhooks.

Zentrale Unterschiede

TRACIO ist kein direkter Protokollersatz für FingerprintJS. Neben den unterschiedlichen SDK- und Antwortformen oben ist zu beachten:

Kontinuität der Besucher-ID

Die Besucher-IDs werden zwischen FingerprintJS Pro und TRACIO nicht identisch sein. Die Besucher-ID ist ein Hash von Browser-Signalen, und jedes System verwendet eigene Hashing-Parameter und eine eigene Datenbank. Nach der Migration erscheint jeder Besucher zunächst als „neuer“ Besucher in der Datenbank von TRACIO.

Abhilfe: Verwenden Sie das Feld linkedId, um TRACIO-Besucher-IDs Ihren bestehenden Benutzerkonten oder Sitzungen zuzuordnen. Nach einer Übergangsphase baut sich die Besucherdatenbank von TRACIO auf natürliche Weise auf.

Cookie-Namen

Bestehende FingerprintJS-Pro-Cookies werden nicht übernommen. Besucher erhalten ein neues _vid_t-Cookie von TRACIO.

Zusätzliche Signale

TRACIO erfasst zusätzliche proprietäre Signale, die in FingerprintJS Pro nicht vorhanden sind. Diese bieten zusätzliche Erkennungsmöglichkeiten, beeinträchtigen jedoch nicht die Kompatibilität mit bestehenden Integrationen.

Sealed Results

FingerprintJS Pro liefert sealed_result in der Antwort (ein verschlüsselter Blob für die serverseitige Verifizierung). TRACIO unterstützt derzeit keine Sealed Results. Verwenden Sie stattdessen Webhooks für die serverseitige Verifizierung.

Fehlerbehebung bei der Migration

Konfidenz niedriger als erwartet

Nach der Migration können die Konfidenzwerte für die ersten 24–48 Stunden etwas niedriger ausfallen, während TRACIO seine Besucherdatenbank aufbaut. Das ist zu erwarten und legt sich, sobald Besucher zurückkehren und cookiebasierte Identitäten etablieren.

Client-SDK verbindet sich nicht

Stellen Sie sicher, dass Sie den FingerprintJS-Client durch @tracio/sdk ersetzt haben und dass Tracio.init() mit einem gültigen Public Key für den korrekten Workspace aufgerufen wird.