Migration depuis FingerprintJS Pro

TRACIO correspond à la collecte de signaux navigateur de FingerprintJS Pro v4 tout en exposant son propre SDK (@tracio/sdk) et en livrant les résultats côté serveur via des webhooks. Ce guide couvre le processus de migration, les détails de parité des signaux et les différences dans les formats de SDK et de réponse que vous devrez mettre à jour.

Vue d'ensemble de la compatibilité

Parité des signaux

TRACIO correspond à la collecte de signaux navigateur de FingerprintJS Pro v4, vérifiée via des tests de comparaison Playwright automatisés exécutés en parallèle sur l'endpoint de production FingerprintJS Pro. Au-delà de l'ensemble correspondant à FingerprintJS, TRACIO collecte des signaux propriétaires (signaux de bot, de falsification, d'anti-détection et de persistance) que FingerprintJS ne collecte pas.

Étapes de migration

Étape 1 : configurer TRACIO

TRACIO est un service cloud managé. Créez votre compte, choisissez votre région de données, et copiez votre clé publique depuis le dashboard. Consultez Cloud Deployment pour la procédure complète. Votre clé publique peut être livrée en toute sécurité dans le code côté client.

Étape 2 : tester avec le client TRACIO

Avant de basculer votre trafic de production, testez avec le SDK client de TRACIO. Notez que TRACIO utilise son propre SDK et sa propre API — ce n'est pas un remplacement de protocole clé en main pour le client FingerprintJS.

import { Tracio } from "@tracio/sdk"

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

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

Comparez l'appareil détecté à votre intégration FingerprintJS Pro existante pour vérifier la migration.

Étape 3 : exécuter une comparaison en parallèle

Pour les déploiements critiques, exécutez les deux systèmes simultanément et comparez les résultats :

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

Notez que les visitor ID différeront entre les systèmes puisqu'ils sont calculés à partir de bases de données côté serveur distinctes. La métrique de compatibilité clé est que les deux systèmes identifient le même appareil physique de manière cohérente.

Étape 4 : remplacer le SDK client

TRACIO fournit son propre SDK client (@tracio/sdk) et ne réutilise pas le protocole client FingerprintJS, il s'agit donc d'un changement de code plutôt que d'un simple échange DNS. Retirez le client FingerprintJS et initialisez TRACIO avec votre clé publique :

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

Étape 5 : remplacer la récupération d'événements côté serveur

FingerprintJS Pro expose une Server API que vous interrogez par requestId. TRACIO n'offre pas d'endpoint REST de lecture équivalent côté client — à la place, les résultats sont poussés vers votre serveur sous forme de webhooks dès qu'un visiteur est identifié. Remplacez votre logique de polling par 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")
})

Consultez Webhooks pour le payload complet et la vérification de signature.

Étape 6 : mettre à jour la configuration des webhooks

Si vous utilisez des webhooks, enregistrez-les dans le dashboard TRACIO. Le payload de webhook est un document plat en camelCase signé avec un en-tête X-Tracio-Signature — il diffère du format webhook de FingerprintJS, mettez donc votre handler à jour en conséquence.

Étape 7 : mettre hors service FingerprintJS Pro

Une fois TRACIO vérifié en production :

1. Retirez le SDK client FingerprintJS Pro de votre base de code
2. Annulez votre abonnement FingerprintJS Pro
3. Supprimez l'enregistrement DNS CNAME pointant vers fpcdn.io

Comparaison des formats de réponse

TRACIO et FingerprintJS utilisent des formes de réponse différentes — c'est le principal point à prendre en compte lors du portage du code.

Réponse client

Le SDK client TRACIO se résout en un résultat compact :

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

Événement côté serveur (webhook)

Au lieu d'une réponse Server API interrogée, TRACIO livre un payload webhook plat en camelCase par identification — et non la structure products de 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 }
}

Consultez Webhooks pour le payload complet.

Différences clés

TRACIO n'est pas un remplacement de protocole clé en main pour FingerprintJS. Au-delà des différences de SDK et de forme de réponse ci-dessus, notez :

Continuité du visitor ID

Les visitor ID ne seront pas identiques entre FingerprintJS Pro et TRACIO. Le visitor ID est un hash des signaux du navigateur, et chaque système utilise ses propres paramètres de hachage et sa propre base de données. Après la migration, chaque visiteur apparaîtra comme un « nouveau » visiteur dans la base de données de TRACIO.

Atténuation : utilisez le champ linkedId pour mapper les visitor ID de TRACIO à vos comptes utilisateur ou sessions existants. Après une période de transition, la base de données visiteurs de TRACIO se construira naturellement.

Noms de cookies

Les cookies FingerprintJS Pro existants ne sont pas transférés. Les visiteurs reçoivent un nouveau cookie _vid_t de TRACIO.

Signaux supplémentaires

TRACIO collecte des signaux propriétaires supplémentaires qui ne sont pas présents dans FingerprintJS Pro. Ils offrent des capacités de détection supplémentaires mais n'affectent pas la compatibilité avec les intégrations existantes.

Résultats scellés

FingerprintJS Pro fournit sealed_result dans la réponse (un blob chiffré pour la vérification côté serveur). TRACIO ne prend pas en charge les résultats scellés pour le moment. Utilisez les webhooks pour la vérification côté serveur à la place.

Dépannage de la migration

Confiance plus basse que prévu

Après la migration, les scores de confiance peuvent être légèrement plus bas pendant les 24 à 48 premières heures, le temps que TRACIO construise sa base de données visiteurs. C'est attendu et cela se résout à mesure que les visiteurs reviennent et établissent des identités basées sur les cookies.

Le SDK client ne se connecte pas

Vérifiez que vous avez remplacé le client FingerprintJS par @tracio/sdk et que Tracio.init() est appelé avec une clé publique valide pour le workspace approprié.