Migrasi dari FingerprintJS Pro

TRACIO menyamai pengumpulan sinyal browser FingerprintJS Pro v4 sekaligus menyediakan SDK-nya sendiri (@tracio/sdk) dan mengirimkan hasil di sisi server melalui webhook. Panduan ini membahas proses migrasi, detail paritas sinyal, serta perbedaan pada format SDK dan respons yang perlu Anda perbarui.

Ikhtisar Kompatibilitas

Paritas Sinyal

TRACIO menyamai pengumpulan sinyal browser FingerprintJS Pro v4, diverifikasi melalui uji perbandingan Playwright otomatis yang berjalan berdampingan terhadap endpoint FingerprintJS Pro produksi. Di atas set yang menyamai FingerprintJS, TRACIO mengumpulkan sinyal proprieter (sinyal bot, tamper, antidetect, dan persistensi) yang tidak dimiliki FingerprintJS.

Langkah Migrasi

Langkah 1: Siapkan TRACIO

TRACIO adalah layanan cloud terkelola. Buat akun Anda, pilih region data, dan salin public key Anda dari dashboard. Lihat Cloud Deployment untuk panduan lengkap. Public key Anda aman untuk disertakan dalam kode sisi klien.

Langkah 2: Uji dengan Klien TRACIO

Sebelum mengalihkan trafik produksi Anda, uji dengan SDK klien TRACIO. Perhatikan bahwa TRACIO menggunakan SDK dan API-nya sendiri — ini bukan pengganti protokol drop-in untuk klien FingerprintJS.

import { Tracio } from "@tracio/sdk"

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

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

Bandingkan perangkat yang terdeteksi dengan integrasi FingerprintJS Pro Anda yang ada untuk memverifikasi migrasi.

Langkah 3: Jalankan Perbandingan Berdampingan

Untuk deployment kritis, jalankan kedua sistem secara bersamaan dan bandingkan hasilnya:

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

Perhatikan bahwa visitor ID akan berbeda antar sistem karena dihitung dari basis data sisi server yang berbeda. Metrik kompatibilitas utama adalah bahwa kedua sistem mengidentifikasi perangkat fisik yang sama secara konsisten.

Langkah 4: Ganti SDK Klien

TRACIO menyediakan SDK kliennya sendiri (@tracio/sdk) dan tidak menggunakan kembali protokol klien FingerprintJS, sehingga ini adalah perubahan kode, bukan pertukaran DNS. Hapus klien FingerprintJS dan inisialisasi TRACIO dengan public key Anda:

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

Langkah 5: Ganti Pengambilan Event Sisi Server

FingerprintJS Pro menyediakan Server API yang Anda polling berdasarkan requestId. TRACIO tidak menawarkan endpoint REST read yang setara untuk pelanggan — sebagai gantinya, hasil dikirim ke server Anda sebagai webhook pada saat seorang pengunjung teridentifikasi. Ganti logika polling Anda dengan handler 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")
})

Lihat Webhooks untuk payload lengkap dan verifikasi tanda tangan.

Langkah 6: Perbarui Konfigurasi Webhook

Jika Anda menggunakan webhook, daftarkan di dashboard TRACIO. Payload webhook adalah dokumen camelCase datar yang ditandatangani dengan header X-Tracio-Signature — ini berbeda dari format webhook FingerprintJS, jadi perbarui handler Anda sesuai kebutuhan.

Langkah 7: Nonaktifkan FingerprintJS Pro

Setelah TRACIO terverifikasi di produksi:

1. Hapus SDK klien FingerprintJS Pro dari basis kode Anda
2. Batalkan langganan FingerprintJS Pro Anda
3. Hapus record DNS CNAME yang menunjuk ke fpcdn.io

Perbandingan Format Respons

TRACIO dan FingerprintJS menggunakan bentuk respons yang berbeda — inilah hal utama yang perlu diperhitungkan saat memindahkan kode.

Respons Klien

SDK klien TRACIO menghasilkan hasil yang ringkas:

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

Event Sisi Server (webhook)

Alih-alih respons Server API yang diambil melalui polling, TRACIO mengirimkan payload webhook camelCase datar per identifikasi — bukan struktur 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 }
}

Lihat Webhooks untuk payload lengkap.

Perbedaan Utama

TRACIO bukan pengganti protokol drop-in untuk FingerprintJS. Selain perbedaan SDK dan bentuk respons di atas, perhatikan:

Kontinuitas Visitor ID

Visitor ID tidak akan sama antara FingerprintJS Pro dan TRACIO. Visitor ID adalah hash dari sinyal browser, dan setiap sistem menggunakan parameter hashing serta basis data sendiri. Setelah migrasi, setiap pengunjung akan tampak sebagai pengunjung "baru" di basis data TRACIO.

Mitigasi: Gunakan field linkedId untuk memetakan visitor ID TRACIO ke akun pengguna atau sesi Anda yang ada. Setelah masa transisi, basis data pengunjung TRACIO akan terbangun secara alami.

Nama Cookie

Cookie FingerprintJS Pro yang ada tidak dibawa serta. Pengunjung menerima cookie _vid_t baru dari TRACIO.

Sinyal Tambahan

TRACIO mengumpulkan sinyal proprieter tambahan yang tidak ada di FingerprintJS Pro. Sinyal ini menyediakan kemampuan deteksi tambahan tetapi tidak memengaruhi kompatibilitas dengan integrasi yang ada.

Sealed Results

FingerprintJS Pro menyediakan sealed_result dalam respons (blob terenkripsi untuk verifikasi sisi server). TRACIO saat ini tidak mendukung sealed results. Gunakan webhooks untuk verifikasi sisi server sebagai gantinya.

Pemecahan Masalah Migrasi

Confidence Lebih Rendah dari Perkiraan

Setelah migrasi, skor confidence mungkin sedikit lebih rendah selama 24-48 jam pertama saat TRACIO membangun basis data pengunjungnya. Ini wajar dan akan teratasi ketika pengunjung kembali dan membentuk identitas berbasis cookie.

SDK Klien Tidak Terhubung

Pastikan Anda telah mengganti klien FingerprintJS dengan @tracio/sdk dan bahwa Tracio.init() dipanggil dengan public key yang valid untuk workspace yang benar.