Migração do FingerprintJS Pro

A TRACIO corresponde à coleta de sinais de navegador do FingerprintJS Pro v4 ao mesmo tempo em que expõe seu próprio SDK (@tracio/sdk) e entrega os resultados no servidor via webhooks. Este guia cobre o processo de migração, os detalhes de paridade de sinais e as diferenças nos formatos de SDK e resposta que você precisará atualizar.

Visão geral de compatibilidade

Paridade de sinais

A TRACIO corresponde à coleta de sinais de navegador do FingerprintJS Pro v4, verificada por testes automatizados de comparação com Playwright rodando lado a lado contra o endpoint de produção do FingerprintJS Pro. Além do conjunto correspondente ao FingerprintJS, a TRACIO coleta sinais proprietários (sinais de bot, adulteração, antidetecção e persistência) que o FingerprintJS não possui.

Passos da migração

Passo 1: Configurar a TRACIO

A TRACIO é um serviço de nuvem gerenciado. Crie sua conta, escolha sua região de dados e copie sua chave pública do dashboard. Consulte Cloud Deployment para o passo a passo completo. Sua chave pública é segura para incluir em código do lado do cliente.

Passo 2: Testar com o cliente TRACIO

Antes de mudar seu tráfego de produção, teste com o SDK do cliente da TRACIO. Observe que a TRACIO usa seu próprio SDK e API — não é uma substituição de protocolo drop-in para o cliente do FingerprintJS.

import { Tracio } from "@tracio/sdk"

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

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

Compare o dispositivo detectado com sua integração existente do FingerprintJS Pro para verificar a migração.

Passo 3: Executar comparação lado a lado

Para deployments críticos, execute os dois sistemas simultaneamente e compare os 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)

Observe que os IDs de visitante serão diferentes entre os sistemas, já que são computados a partir de bancos de dados distintos no servidor. A métrica-chave de compatibilidade é que ambos os sistemas identifiquem o mesmo dispositivo físico de forma consistente.

Passo 4: Substituir o SDK do cliente

A TRACIO fornece seu próprio SDK de cliente (@tracio/sdk) e não reutiliza o protocolo do cliente do FingerprintJS, portanto esta é uma mudança de código, e não uma troca de DNS. Remova o cliente do FingerprintJS e inicialize a TRACIO com sua chave 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()

Passo 5: Substituir a recuperação de eventos no servidor

O FingerprintJS Pro expõe uma Server API que você consulta por requestId. A TRACIO não oferece um endpoint REST de leitura equivalente voltado ao cliente — em vez disso, os resultados são enviados ao seu servidor como webhooks no momento em que um visitante é identificado. Substitua sua lógica de polling por um 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")
})

Consulte Webhooks para o payload completo e a verificação de assinatura.

Passo 6: Atualizar a configuração de webhook

Se você usa webhooks, registre-os no dashboard da TRACIO. O payload do webhook é um documento plano em camelCase assinado com um cabeçalho X-Tracio-Signature — ele difere do formato de webhook do FingerprintJS, então atualize seu handler adequadamente.

Passo 7: Desativar o FingerprintJS Pro

Depois que a TRACIO estiver verificada em produção:

1. Remova o SDK do cliente do FingerprintJS Pro do seu código
2. Cancele sua assinatura do FingerprintJS Pro
3. Exclua o registro DNS CNAME que aponta para fpcdn.io

Comparação de formato de resposta

A TRACIO e o FingerprintJS usam formas de resposta diferentes — esta é a principal coisa a considerar ao portar código.

Resposta do cliente

O SDK do cliente da TRACIO resolve para um resultado compacto:

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

Evento no servidor (webhook)

Em vez de uma resposta de Server API consultada por polling, a TRACIO entrega um payload de webhook plano em camelCase por identificação — não a estrutura products do 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 o payload completo.

Principais diferenças

A TRACIO não é uma substituição de protocolo drop-in para o FingerprintJS. Além do SDK e das formas de resposta diferentes acima, observe:

Continuidade do ID de visitante

Os IDs de visitante não serão os mesmos entre o FingerprintJS Pro e a TRACIO. O ID de visitante é um hash de sinais de navegador, e cada sistema usa seus próprios parâmetros de hashing e banco de dados. Após a migração, cada visitante aparecerá como um visitante "novo" no banco de dados da TRACIO.

Mitigação: use o campo linkedId para mapear os IDs de visitante da TRACIO para suas contas de usuário ou sessões existentes. Após um período de transição, o banco de dados de visitantes da TRACIO se acumulará naturalmente.

Nomes de cookie

Os cookies existentes do FingerprintJS Pro não são transferidos. Os visitantes recebem um novo cookie _vid_t da TRACIO.

Sinais adicionais

A TRACIO coleta sinais proprietários adicionais que não estão presentes no FingerprintJS Pro. Eles fornecem capacidades de detecção adicionais, mas não afetam a compatibilidade com integrações existentes.

Resultados selados (sealed results)

O FingerprintJS Pro fornece sealed_result na resposta (um blob criptografado para verificação no servidor). A TRACIO atualmente não oferece suporte a resultados selados. Use webhooks para verificação no servidor em vez disso.

Solução de problemas de migração

Confiança menor do que o esperado

Após a migração, as pontuações de confiança podem ficar ligeiramente mais baixas nas primeiras 24-48 horas enquanto a TRACIO constrói seu banco de dados de visitantes. Isso é esperado e se resolve à medida que os visitantes retornam e estabelecem identidades baseadas em cookie.

SDK do cliente não conecta

Confirme que você substituiu o cliente do FingerprintJS por @tracio/sdk e que Tracio.init() é chamado com uma chave pública válida para o workspace correto.