FingerprintJS Pro からの移行

TRACIO は FingerprintJS Pro v4 のブラウザシグナル収集に対応しつつ、独自のSDK （@tracio/sdk）を公開し、結果をWebhook経由でサーバー側に配信します。この ガイドでは、移行のプロセス、シグナルパリティの詳細、そして更新が必要となるSDKと レスポンス形式の違いを取り上げます。

互換性の概要

シグナルパリティ

TRACIO は FingerprintJS Pro v4 のブラウザシグナル収集に対応しており、本番の FingerprintJS Pro エンドポイントに対して並行して実行される自動化された Playwright 比較テストによって検証されています。FingerprintJS対応のセットに加えて、TRACIO は FingerprintJS には存在しない独自のシグナル（ボット、改ざん、アンチディテクト、 永続性のシグナル）を収集します。

移行の手順

ステップ1: TRACIO のセットアップ

TRACIO はマネージドなクラウドサービスです。アカウントを作成し、データリージョンを選択して、 ダッシュボードから 公開鍵 をコピーしてください。完全な手順については クラウドデプロイ を参照してください。公開鍵は クライアント側のコードに含めて出荷しても安全です。

ステップ2: TRACIO クライアントでのテスト

本番トラフィックを切り替える前に、TRACIO のクライアントSDKでテストしてください。 TRACIO は独自のSDKとAPIを使用しており、FingerprintJS クライアントのプロトコルを そのまま差し替えるものではない点に注意してください。

import { Tracio } from "@tracio/sdk"

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

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

検出されたデバイスを既存の FingerprintJS Pro 統合と比較して、移行を検証してください。

ステップ3: 並行比較の実施

重要なデプロイでは、両方のシステムを同時に実行して結果を比較してください。

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

訪問者IDは、異なるサーバー側のデータベースから計算されるため、システム間で異なる点に 注意してください。重要な互換性の指標は、両方のシステムが同じ物理デバイスを一貫して 識別することです。

ステップ4: クライアントSDKの置き換え

TRACIO は独自のクライアントSDK（@tracio/sdk）を出荷しており、FingerprintJS クライアントのプロトコルを再利用しません。そのため、これはDNSの差し替えではなく コード変更となります。FingerprintJS クライアントを削除し、あなたの公開鍵で TRACIO を初期化してください。

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

ステップ5: サーバー側イベント取得の置き換え

FingerprintJS Pro は、requestId でポーリングする Server API を公開しています。TRACIO は 同等の顧客向けREST読み取りエンドポイントを提供していません — 代わりに、結果は訪問者が 識別された瞬間に Webhookとしてあなたのサーバーへプッシュされます。 ポーリングロジックを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")
})

完全なペイロードと署名検証については Webhook を参照してください。

ステップ6: Webhook構成の更新

Webhookを使用する場合は、TRACIO ダッシュボードで登録してください。 Webhookペイロード は X-Tracio-Signature ヘッダーで署名された フラットな camelCase ドキュメントです — FingerprintJS の Webhook形式とは異なるため、 それに合わせてハンドラーを更新してください。

ステップ7: FingerprintJS Pro の廃止

TRACIO が本番で検証されたら、次を行います。

1. コードベースから FingerprintJS Pro クライアントSDKを削除する
2. FingerprintJS Pro のサブスクリプションを解約する
3. fpcdn.io を指す CNAME DNS レコードを削除する

レスポンス形式の比較

TRACIO と FingerprintJS は異なるレスポンス形状を使用します — これはコードを移植する際に 考慮すべき主要な点です。

クライアントレスポンス

TRACIO のクライアントSDKは、コンパクトな結果に解決します。

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

サーバー側イベント（Webhook）

ポーリングされる Server API のレスポンスの代わりに、TRACIO は識別ごとにフラットな camelCase の Webhookペイロードを配信します — FingerprintJS の products 構造では ありません。

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

完全なペイロードについては Webhook を参照してください。

主な相違点

TRACIO は FingerprintJS のプロトコルをそのまま差し替えるものでは ありません。上記の 異なるSDKとレスポンス形状に加えて、次に注意してください。

訪問者IDの継続性

訪問者IDは、FingerprintJS Pro と TRACIO の間で同じには なりません。訪問者IDは ブラウザシグナルのハッシュであり、各システムは独自のハッシュパラメータとデータベースを 使用します。移行後、すべての訪問者は TRACIO のデータベースでは「新規」訪問者として 表れます。

緩和策: linkedId フィールドを使用して、TRACIO の訪問者IDを既存のユーザー アカウントやセッションに対応付けてください。移行期間の後、TRACIO の訪問者データベースは 自然に蓄積されていきます。

Cookie名

既存の FingerprintJS Pro Cookieは引き継がれません。訪問者は TRACIO から新しい _vid_t Cookieを受け取ります。

追加のシグナル

TRACIO は、FingerprintJS Pro には存在しない追加の独自シグナルを収集します。これらは 追加の検知能力を提供しますが、既存の統合との互換性には影響しません。

Sealed Results

FingerprintJS Pro は、レスポンスに sealed_result（サーバー側検証用の暗号化ブロブ）を 提供します。TRACIO は現在 sealed results をサポートしていません。代わりにサーバー側の 検証には Webhook を使用してください。

移行のトラブルシューティング

信頼度が予想より低い

移行後、TRACIO が訪問者データベースを構築する最初の24〜48時間は、信頼度スコアが わずかに低くなる場合があります。これは想定内であり、訪問者が再訪してCookieベースの アイデンティティを確立するにつれて解消されます。

クライアントSDKが接続しない

FingerprintJS クライアントを @tracio/sdk に置き換えたこと、そして正しいワークスペースの 有効な公開鍵で Tracio.init() が呼び出されていることを確認してください。