Migración desde FingerprintJS Pro

TRACIO iguala la recopilación de señales de navegador de FingerprintJS Pro v4 a la vez que expone su propio SDK (@tracio/sdk) y entrega los resultados del lado del servidor mediante webhooks. Esta guía cubre el proceso de migración, los detalles de la paridad de señales y las diferencias en el SDK y los formatos de respuesta que tendrá que actualizar.

Resumen de compatibilidad

Paridad de señales

TRACIO iguala la recopilación de señales de navegador de FingerprintJS Pro v4, verificada mediante pruebas de comparación automatizadas con Playwright que se ejecutan en paralelo frente al endpoint de producción de FingerprintJS Pro. Además del conjunto equivalente a FingerprintJS, TRACIO recopila señales propietarias (señales de bot, manipulación, antidetección y persistencia) que FingerprintJS no tiene.

Pasos de migración

Paso 1: Configure TRACIO

TRACIO es un servicio de nube gestionada. Cree su cuenta, elija su región de datos y copie su clave pública desde el panel. Consulte Despliegue en la nube para el recorrido completo. Su clave pública es segura para incluirla en el código del lado del cliente.

Paso 2: Pruebe con el cliente de TRACIO

Antes de cambiar su tráfico de producción, pruebe con el SDK de cliente de TRACIO. Tenga en cuenta que TRACIO usa su propio SDK y API: no es un reemplazo de protocolo directo (drop-in) del cliente de FingerprintJS.

import { Tracio } from "@tracio/sdk"

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

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

Compare el dispositivo detectado con su integración existente de FingerprintJS Pro para verificar la migración.

Paso 3: Ejecute una comparación en paralelo

Para despliegues críticos, ejecute ambos sistemas simultáneamente y compare los resultados:

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

Tenga en cuenta que los visitor IDs serán distintos entre sistemas, ya que se calculan a partir de bases de datos del lado del servidor diferentes. La métrica de compatibilidad clave es que ambos sistemas identifiquen el mismo dispositivo físico de forma consistente.

Paso 4: Reemplace el SDK de cliente

TRACIO incluye su propio SDK de cliente (@tracio/sdk) y no reutiliza el protocolo del cliente de FingerprintJS, así que este es un cambio de código en lugar de un cambio de DNS. Elimine el cliente de FingerprintJS e inicialice TRACIO con su clave pública:

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

Paso 5: Reemplace la recuperación de eventos del lado del servidor

FingerprintJS Pro expone una API de servidor que consulta por requestId. TRACIO no ofrece un endpoint REST de lectura equivalente orientado al cliente: en su lugar, los resultados se envían (push) a su servidor como webhooks en el momento en que se identifica a un visitante. Reemplace su lógica de polling por un manejador de webhooks:

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

Consulte Webhooks para el payload completo y la verificación de firma.

Paso 6: Actualice la configuración de webhooks

Si usa webhooks, regístrelos en el panel de TRACIO. El payload del webhook es un documento plano en camelCase firmado con una cabecera X-Tracio-Signature: difiere del formato de webhook de FingerprintJS, así que actualice su manejador en consecuencia.

Paso 7: Dé de baja FingerprintJS Pro

Una vez que TRACIO esté verificado en producción:

1. Elimine el SDK de cliente de FingerprintJS Pro de su base de código
2. Cancele su suscripción a FingerprintJS Pro
3. Elimine el registro DNS CNAME que apunta a fpcdn.io

Comparación del formato de respuesta

TRACIO y FingerprintJS usan formas de respuesta diferentes: esto es lo principal que hay que tener en cuenta al portar el código.

Respuesta del cliente

El SDK de cliente de TRACIO se resuelve en un resultado compacto:

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

Evento del lado del servidor (webhook)

En lugar de una respuesta de API de servidor consultada por polling, TRACIO entrega un payload de webhook plano en camelCase por cada identificación, no la estructura 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 }
}

Consulte Webhooks para el payload completo.

Diferencias clave

TRACIO no es un reemplazo de protocolo directo (drop-in) de FingerprintJS. Más allá de las diferencias de SDK y de forma de respuesta anteriores, tenga en cuenta:

Continuidad del visitor ID

Los visitor IDs no serán los mismos entre FingerprintJS Pro y TRACIO. El visitor ID es un hash de las señales del navegador, y cada sistema usa sus propios parámetros de hashing y su propia base de datos. Tras la migración, cada visitante aparecerá como un visitante «nuevo» en la base de datos de TRACIO.

Mitigación: use el campo linkedId para mapear los visitor IDs de TRACIO a sus cuentas de usuario o sesiones existentes. Tras un periodo de transición, la base de datos de visitantes de TRACIO se irá construyendo de forma natural.

Nombres de cookies

Las cookies existentes de FingerprintJS Pro no se transfieren. Los visitantes reciben una nueva cookie _vid_t de TRACIO.

Señales adicionales

TRACIO recopila señales propietarias adicionales que no están presentes en FingerprintJS Pro. Estas proporcionan capacidades de detección adicionales, pero no afectan a la compatibilidad con las integraciones existentes.

Resultados sellados (sealed results)

FingerprintJS Pro proporciona sealed_result en la respuesta (un blob cifrado para la verificación del lado del servidor). TRACIO no admite actualmente los resultados sellados. Use los webhooks para la verificación del lado del servidor en su lugar.

Resolución de problemas de migración

Confianza más baja de lo esperado

Tras la migración, las puntuaciones de confianza pueden ser ligeramente más bajas durante las primeras 24-48 horas mientras TRACIO construye su base de datos de visitantes. Esto es esperado y se resuelve a medida que los visitantes regresan y establecen identidades basadas en cookies.

El SDK de cliente no conecta

Confirme que ha reemplazado el cliente de FingerprintJS por @tracio/sdk y que Tracio.init() se llama con una clave pública válida para el workspace correcto.