FingerprintJS Pro에서 마이그레이션

TRACIO는 FingerprintJS Pro v4의 브라우저 신호 수집을 그대로 재현하면서도 자체 SDK(@tracio/sdk)를 제공하고 결과를 웹훅을 통해 서버 측에서 전달합니다. 이 가이드는 마이그레이션 절차, 신호 패리티 세부 사항, 그리고 업데이트해야 할 SDK 및 응답 형식의 차이점을 다룹니다.

호환성 개요

신호 패리티

TRACIO는 FingerprintJS Pro v4의 브라우저 신호 수집을 그대로 재현하며, 이는 프로덕션 FingerprintJS Pro 엔드포인트와 나란히 실행되는 자동화된 Playwright 비교 테스트로 검증됩니다. FingerprintJS 일치 세트에 더해, TRACIO는 FingerprintJS가 제공하지 않는 독자 신호(봇, 변조, 안티디텍트, 지속성 신호)를 수집합니다.

마이그레이션 단계

1단계: TRACIO 설정

TRACIO는 매니지드 클라우드 서비스입니다. 계정을 만들고, 데이터 리전을 선택한 뒤, 대시보드에서 공개 키(public key) 를 복사하세요. 전체 안내는 Cloud Deployment를 참고하세요. 공개 키는 클라이언트 측 코드에 포함해 배포해도 안전합니다.

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로 폴링하는 서버 API를 제공합니다. TRACIO는 동등한 고객용 REST 조회 엔드포인트를 제공하지 않으며 — 대신 방문자가 식별되는 순간 결과가 웹훅으로 서버에 푸시됩니다. 폴링 로직을 웹훅 핸들러로 교체하세요:

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

전체 페이로드와 서명 검증은 Webhooks를 참고하세요.

6단계: 웹훅 구성 업데이트

웹훅을 사용한다면 TRACIO 대시보드에 등록하세요. 웹훅 페이로드는 X-Tracio-Signature 헤더로 서명된 플랫한 camelCase 문서입니다 — FingerprintJS 웹훅 형식과 다르므로, 그에 맞게 핸들러를 업데이트하세요.

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": [] }
}

서버 측 이벤트 (웹훅)

폴링으로 조회하는 서버 API 응답 대신, TRACIO는 식별마다 플랫한 camelCase 웹훅 페이로드를 전달합니다 — 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 }
}

전체 페이로드는 Webhooks를 참고하세요.

주요 차이점

TRACIO는 FingerprintJS의 드롭인 프로토콜 대체가 아닙니다. 위의 서로 다른 SDK 및 응답 형태 외에도 다음에 유의하세요:

방문자 ID 연속성

방문자 ID는 FingerprintJS Pro와 TRACIO 간에 동일하지 않습니다. 방문자 ID는 브라우저 신호의 해시이며, 각 시스템은 고유한 해싱 파라미터와 데이터베이스를 사용합니다. 마이그레이션 후에는 모든 방문자가 TRACIO 데이터베이스에서 "새" 방문자로 나타납니다.

완화 방법: linkedId 필드를 사용해 TRACIO 방문자 ID를 기존 사용자 계정 또는 세션에 매핑하세요. 전환 기간이 지나면 TRACIO의 방문자 데이터베이스가 자연스럽게 축적됩니다.

쿠키 이름

기존 FingerprintJS Pro 쿠키는 이전되지 않습니다. 방문자는 TRACIO로부터 새로운 _vid_t 쿠키를 받습니다.

추가 신호

TRACIO는 FingerprintJS Pro에는 없는 추가 독자 신호를 수집합니다. 이는 추가적인 탐지 기능을 제공하지만 기존 통합과의 호환성에는 영향을 주지 않습니다.

Sealed Results

FingerprintJS Pro는 응답에 sealed_result(서버 측 검증을 위한 암호화된 블롭)를 제공합니다. TRACIO는 현재 sealed result를 지원하지 않습니다. 대신 서버 측 검증에는 웹훅을 사용하세요.

마이그레이션 문제 해결

신뢰도가 예상보다 낮음

마이그레이션 후 처음 24~48시간 동안은 TRACIO가 방문자 데이터베이스를 구축하는 동안 신뢰도 점수가 다소 낮을 수 있습니다. 이는 예상된 현상이며, 방문자가 재방문하여 쿠키 기반 신원을 확립하면 해소됩니다.

클라이언트 SDK가 연결되지 않음

FingerprintJS 클라이언트를 @tracio/sdk로 교체했는지, 그리고 Tracio.init()이 올바른 워크스페이스의 유효한 공개 키로 호출되는지 확인하세요.