Migrace z FingerprintJS Pro

TRACIO odpovídá sběru prohlížečových signálů FingerprintJS Pro v4, přičemž poskytuje vlastní SDK (@tracio/sdk) a doručuje výsledky na straně serveru přes webhooky. Tento návod se zabývá procesem migrace, detaily parity signálů a rozdíly ve formátech SDK a odpovědí, které budete muset upravit.

Přehled kompatibility

Parita signálů

TRACIO odpovídá sběru prohlížečových signálů FingerprintJS Pro v4, ověřeno pomocí automatizovaných porovnávacích testů Playwright běžících souběžně proti produkčnímu endpointu FingerprintJS Pro. Nad rámec sady odpovídající FingerprintJS shromažďuje TRACIO proprietární signály (bot, tamper, antidetect a signály perzistence), které FingerprintJS neposkytuje.

Kroky migrace

Krok 1: Nastavení TRACIO

TRACIO je spravovaná cloudová služba. Vytvořte si účet, zvolte datový region a zkopírujte si veřejný klíč z dashboardu. Kompletní postup najdete v části Cloud Deployment. Váš veřejný klíč lze bezpečně distribuovat v klientském kódu.

Krok 2: Testování s klientem TRACIO

Než přepnete produkční provoz, otestujte klientské SDK TRACIO. Vezměte na vědomí, že TRACIO používá vlastní SDK a API — nejde o přímou náhradu protokolu klienta FingerprintJS.

import { Tracio } from "@tracio/sdk"

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

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

Porovnejte rozpoznané zařízení se svou stávající integrací FingerprintJS Pro a ověřte tak migraci.

Krok 3: Souběžné porovnání

U kritických nasazení spusťte oba systémy současně a porovnejte výsledky:

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

Vezměte na vědomí, že identifikátory návštěvníků se mezi systémy liší, protože jsou počítány z různých databází na straně serveru. Klíčovou metrikou kompatibility je, že oba systémy konzistentně identifikují totéž fyzické zařízení.

Krok 4: Nahrazení klientského SDK

TRACIO dodává vlastní klientské SDK (@tracio/sdk) a nepoužívá znovu protokol klienta FingerprintJS, takže jde o změnu kódu, nikoli o výměnu DNS. Odstraňte klienta FingerprintJS a inicializujte TRACIO svým veřejným klíčem:

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

Krok 5: Nahrazení získávání událostí na straně serveru

FingerprintJS Pro poskytuje Server API, které dotazujete pomocí requestId. TRACIO nenabízí ekvivalentní zákaznický REST čtecí endpoint — místo toho jsou výsledky odesílány na váš server jako webhooky v okamžiku, kdy je návštěvník identifikován. Nahraďte svou pollingovou logiku obslužnou rutinou webhooku:

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

Kompletní payload a ověření podpisu najdete v části Webhooks.

Krok 6: Aktualizace konfigurace webhooků

Pokud používáte webhooky, zaregistrujte je v dashboardu TRACIO. Payload webhooku je plochý dokument ve formátu camelCase podepsaný hlavičkou X-Tracio-Signature — liší se od formátu webhooků FingerprintJS, proto podle toho upravte svou obslužnou rutinu.

Krok 7: Vyřazení FingerprintJS Pro z provozu

Jakmile je TRACIO ověřeno v produkci:

1. Odstraňte klientské SDK FingerprintJS Pro ze své kódové základny
2. Zrušte předplatné FingerprintJS Pro
3. Smažte záznam CNAME DNS odkazující na fpcdn.io

Porovnání formátů odpovědí

TRACIO a FingerprintJS používají odlišné podoby odpovědí — to je hlavní věc, kterou je třeba zohlednit při přenosu kódu.

Odpověď klienta

Klientské SDK TRACIO vrací kompaktní výsledek:

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

Událost na straně serveru (webhook)

Namísto pollingem získané odpovědi Server API doručuje TRACIO na každou identifikaci plochý payload webhooku ve formátu camelCase — nikoli strukturu products 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 }
}

Kompletní payload najdete v části Webhooks.

Klíčové rozdíly

TRACIO není přímá náhrada protokolu FingerprintJS. Kromě odlišných podob SDK a odpovědí výše vezměte na vědomí:

Kontinuita ID návštěvníka

Identifikátory návštěvníků nebudou mezi FingerprintJS Pro a TRACIO shodné. ID návštěvníka je hash prohlížečových signálů a každý systém používá vlastní hashovací parametry a vlastní databázi. Po migraci se každý návštěvník objeví jako „nový“ návštěvník v databázi TRACIO.

Řešení: Použijte pole linkedId k mapování ID návštěvníků TRACIO na vaše stávající uživatelské účty nebo relace. Po přechodném období se databáze návštěvníků TRACIO přirozeně naplní.

Názvy cookies

Stávající cookies FingerprintJS Pro se nepřenášejí. Návštěvníci obdrží od TRACIO nové cookie _vid_t.

Doplňkové signály

TRACIO shromažďuje doplňkové proprietární signály, které ve FingerprintJS Pro nejsou přítomny. Ty poskytují další detekční schopnosti, ale neovlivňují kompatibilitu se stávajícími integracemi.

Sealed Results

FingerprintJS Pro poskytuje v odpovědi sealed_result (šifrovaný blob pro ověření na straně serveru). TRACIO v současnosti sealed results nepodporuje. Pro ověření na straně serveru použijte místo toho webhooky.

Řešení potíží při migraci

Nižší konfidence, než se očekávalo

Po migraci mohou být hodnoty konfidence prvních 24–48 hodin mírně nižší, zatímco TRACIO buduje svou databázi návštěvníků. To je očekávané a vyřeší se, jakmile se návštěvníci vracejí a ustaví identity založené na cookies.

Klientské SDK se nepřipojuje

Ujistěte se, že jste klienta FingerprintJS nahradili balíčkem @tracio/sdk a že Tracio.init() je voláno s platným veřejným klíčem pro správný workspace.