FingerprintJS Pro'dan Geçiş

TRACIO, FingerprintJS Pro v4'ün tarayıcı sinyali toplama işlevini karşılar; bunu kendi SDK'sını (@tracio/sdk) sunarak ve sonuçları sunucu tarafında webhook'lar aracılığıyla teslim ederek yapar. Bu kılavuz, geçiş sürecini, sinyal paritesi ayrıntılarını ve güncellemeniz gereken SDK ile yanıt formatlarındaki farklılıkları kapsar.

Uyumluluk Genel Bakışı

Sinyal Paritesi

TRACIO, FingerprintJS Pro v4'ün tarayıcı sinyali toplama işlevini karşılar; bu, üretim FingerprintJS Pro uç noktasına karşı yan yana çalışan otomatik Playwright karşılaştırma testleriyle doğrulanmıştır. FingerprintJS ile eşleşen kümenin üzerine TRACIO, FingerprintJS'in toplamadığı tescilli sinyaller (bot, tamper, antidetect ve persistence sinyalleri) toplar.

Geçiş Adımları

Adım 1: TRACIO'yu Kurun

TRACIO, yönetilen bir bulut hizmetidir. Hesabınızı oluşturun, veri bölgenizi seçin ve public key'inizi panodan kopyalayın. Tam yönergeler için bkz. Cloud Deployment. Public key'iniz istemci tarafı kodda güvenle gönderilebilir.

Adım 2: TRACIO İstemcisiyle Test Edin

Üretim trafiğinizi değiştirmeden önce TRACIO'nun istemci SDK'sıyla test edin. TRACIO'nun kendi SDK'sını ve API'sini kullandığını unutmayın — bu, FingerprintJS istemcisi için doğrudan bir protokol yerine geçme değildir.

import { Tracio } from "@tracio/sdk"

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

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

Geçişi doğrulamak için tespit edilen cihazı mevcut FingerprintJS Pro entegrasyonunuzla karşılaştırın.

Adım 3: Yan Yana Karşılaştırma Çalıştırın

Kritik dağıtımlar için her iki sistemi aynı anda çalıştırın ve sonuçları karşılaştırın:

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

Ziyaretçi kimliklerinin sistemler arasında farklı olacağını unutmayın; bunlar farklı sunucu tarafı veritabanlarından hesaplanır. Temel uyumluluk metriği, her iki sistemin de aynı fiziksel cihazı tutarlı biçimde tanımlamasıdır.

Adım 4: İstemci SDK'sını Değiştirin

TRACIO kendi istemci SDK'sını (@tracio/sdk) sunar ve FingerprintJS istemci protokolünü yeniden kullanmaz; dolayısıyla bu bir DNS değişimi değil, bir kod değişikliğidir. FingerprintJS istemcisini kaldırın ve TRACIO'yu public key'inizle başlatın:

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

Adım 5: Sunucu Tarafı Olay Alımını Değiştirin

FingerprintJS Pro, requestId ile sorguladığınız bir Server API sunar. TRACIO, eşdeğer bir müşteriye açık REST okuma uç noktası sunmaz — bunun yerine sonuçlar, bir ziyaretçi tanımlandığı anda webhook'lar olarak sunucunuza gönderilir. Yoklama (polling) mantığınızı bir webhook işleyicisiyle değiştirin:

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

Tam yük ve imza doğrulaması için bkz. Webhooks.

Adım 6: Webhook Yapılandırmasını Güncelleyin

Webhook kullanıyorsanız bunları TRACIO panosunda kaydedin. Webhook yükü, X-Tracio-Signature başlığıyla imzalanan düz, camelCase bir belgedir — FingerprintJS webhook formatından farklıdır, bu nedenle işleyicinizi buna göre güncelleyin.

Adım 7: FingerprintJS Pro'yu Devre Dışı Bırakın

TRACIO üretimde doğrulandıktan sonra:

1. FingerprintJS Pro istemci SDK'sını kod tabanınızdan kaldırın
2. FingerprintJS Pro aboneliğinizi iptal edin
3. fpcdn.io'yu işaret eden CNAME DNS kaydını silin

Yanıt Formatı Karşılaştırması

TRACIO ve FingerprintJS farklı yanıt şekilleri kullanır — kodu taşırken hesaba katmanız gereken temel nokta budur.

İstemci Yanıtı

TRACIO istemci SDK'sı kompakt bir sonuca çözümlenir:

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

Sunucu Tarafı Olay (webhook)

Yoklanan bir Server API yanıtı yerine TRACIO, her tanımlama için düz, camelCase bir webhook yükü teslim eder — FingerprintJS'in products yapısı değildir:

{
  "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 }
}

Tam yük için bkz. Webhooks.

Temel Farklılıklar

TRACIO, FingerprintJS için doğrudan bir protokol yerine geçme değildir. Yukarıdaki farklı SDK ve yanıt şekillerinin yanı sıra şunları unutmayın:

Ziyaretçi Kimliği Sürekliliği

Ziyaretçi kimlikleri FingerprintJS Pro ve TRACIO arasında aynı olmayacaktır. Ziyaretçi kimliği, tarayıcı sinyallerinin bir hash'idir ve her sistem kendi hashing parametrelerini ve veritabanını kullanır. Geçişten sonra her ziyaretçi TRACIO'nun veritabanında "yeni" bir ziyaretçi olarak görünecektir.

Azaltma: TRACIO ziyaretçi kimliklerini mevcut kullanıcı hesaplarınıza veya oturumlarınıza eşlemek için linkedId alanını kullanın. Bir geçiş döneminden sonra TRACIO'nun ziyaretçi veritabanı doğal olarak oluşacaktır.

Çerez Adları

Mevcut FingerprintJS Pro çerezleri devralınmaz. Ziyaretçiler TRACIO'dan yeni bir _vid_t çerezi alır.

Ek Sinyaller

TRACIO, FingerprintJS Pro'da bulunmayan ek tescilli sinyaller toplar. Bunlar ek tespit yetenekleri sağlar ancak mevcut entegrasyonlarla uyumluluğu etkilemez.

Sealed Results

FingerprintJS Pro, yanıtta sealed_result sağlar (sunucu tarafı doğrulama için şifreli bir blob). TRACIO şu anda sealed results'ı desteklemez. Sunucu tarafı doğrulama için bunun yerine webhook'ları kullanın.

Geçiş Sorun Giderme

Güven Beklenenden Düşük

Geçişten sonra, TRACIO ziyaretçi veritabanını oluştururken ilk 24-48 saat boyunca güven puanları biraz daha düşük olabilir. Bu beklenen bir durumdur ve ziyaretçiler geri dönüp çerez tabanlı kimlikler oluşturdukça çözülür.

İstemci SDK'sı Bağlanmıyor

FingerprintJS istemcisini @tracio/sdk ile değiştirdiğinizden ve Tracio.init() çağrısının doğru workspace için geçerli bir public key ile yapıldığından emin olun.