Migration from FingerprintJS Pro

TRACIO matches FingerprintJS Pro v4's browser signal collection while exposing its own SDK (@tracio/sdk) and Server API. This guide covers the migration process, signal parity details, and the differences in the SDK and response formats you will need to update.

Compatibility Overview

Signal Parity: 132/132 Matched

Every signal collected by FingerprintJS Pro v4 is matched by TRACIO. Verified via automated Playwright comparison tests running side-by-side against the production FingerprintJS Pro endpoint.

Migration Steps

Step 1: Set Up TRACIO

Create your TRACIO account and get API keys. See Cloud Deployment for complete instructions.

# Quick deploy with Docker Compose
git clone https://github.com/anthropic/fp.git
cd fp
cp .env.example .env
# Edit .env with your configuration
docker compose up -d

Verify the server is running:

curl https://app.tracio.ai/health
# { "status": "ok" }

Step 2: Test with the TRACIO Client

Before switching your production traffic, test with TRACIO's client SDK. Note that TRACIO uses its own SDK and API — it is not a drop-in protocol replacement for the FingerprintJS client.

import { Tracio } from "@tracio/sdk"

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

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

Compare the detected device against your existing FingerprintJS Pro integration to verify the migration.

Step 3: Run Side-by-Side Comparison

For critical deployments, run both systems simultaneously and compare results:

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

Note that visitor IDs will be different between systems since they are computed from different server-side databases. The key compatibility metric is that both systems identify the same physical device consistently.

Step 4: Replace the Client SDK

TRACIO ships its own client SDK (@tracio/sdk) and does not reuse the FingerprintJS client protocol, so this is a code change rather than a DNS swap. Remove the FingerprintJS client and initialize TRACIO with your public key:

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

Step 5: Update Server-Side API Calls

If your backend queries the FingerprintJS Pro Server API, switch to the TRACIO Server API. The endpoint, auth model, and response shape are different:

// Before (FingerprintJS Pro)
const response = await fetch(`https://eu.api.fpjs.io/events/${requestId}`, {
  headers: { "Auth-API-Key": "fpjs-api-key" },
})

// After (TRACIO) — workspace-scoped, authenticated with the dashboard session
const response = await fetch(
  `https://app.tracio.ai/api/v1/subscriptions/${workspaceId}/events/${requestId}`,
  { headers: { Authorization: "Bearer <clerk-session-jwt>" } },
)

The TRACIO response is a flat, snake_case event wrapped in an { ok, data } envelope (see the Server API Reference) — it does not use the FingerprintJS products structure.

Step 6: Update Webhook Configuration

If you use webhooks, register them in the TRACIO dashboard. The webhook payload is a flat, camelCase document signed with an X-Tracio-Signature header — it differs from the FingerprintJS webhook format, so update your handler accordingly.

Step 7: Decommission FingerprintJS Pro

Once TRACIO is verified in production:

1. Remove the FingerprintJS Pro client SDK from your codebase
2. Cancel your FingerprintJS Pro subscription
3. Delete the CNAME DNS record pointing to fpcdn.io

Response Format Comparison

TRACIO and FingerprintJS use different response shapes — this is the main thing to account for when porting code.

Client Response

The TRACIO client SDK resolves to a compact result:

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

Server API Response

The TRACIO Server API returns a flat, snake_case event in an { ok, data } envelope — not the FingerprintJS products structure:

{
  "ok": true,
  "data": {
    "request_id": "1710432000_abc123def",
    "visitor_id": "X7fh2Hg9LkMn3pQr",
    "confidence": 0.95,
    "bot_result": "human",
    "bot_type": "",
    "ip": "94.142.239.124",
    "ip_country": "CZ",
    "ip_city": "Prague",
    "decision": "real",
    "risk_score": 4
  }
}

See the Server API Reference for the full field list.

Key Differences

TRACIO is not a drop-in protocol replacement for FingerprintJS. Beyond the different SDK and response shapes above, note:

Visitor ID Continuity

Visitor IDs will not be the same between FingerprintJS Pro and TRACIO. The visitor ID is a hash of browser signals, and each system uses its own hashing parameters and database. After migration, every visitor will appear as a "new" visitor in TRACIO's database.

Mitigation: Use the linkedId field to map TRACIO visitor IDs to your existing user accounts or sessions. After a transition period, TRACIO's visitor database will build up naturally.

Cookie Names

The cookie name difference means existing FingerprintJS Pro cookies will not carry over. Visitors will receive new cookies from TRACIO.

Additional Signals

TRACIO collects additional proprietary signals that are not present in FingerprintJS Pro. These provide additional detection capabilities but do not affect compatibility with existing integrations.

Sealed Results

FingerprintJS Pro provides sealed_result in the response (an encrypted blob for server-side verification). TRACIO does not currently support sealed results. Use the Server API for verification instead.

Troubleshooting Migration

CORS Errors

If you see CORS errors after switching DNS, ensure your Nginx configuration includes:

add_header Access-Control-Allow-Origin $http_origin always;
add_header Access-Control-Allow-Credentials true always;

Confidence Lower Than Expected

After migration, confidence scores may be slightly lower for the first 24-48 hours as TRACIO builds its visitor database. This is expected and resolves as visitors return and establish cookie-based identities.

Missing Smart Signals

Verify that all required external services are configured:

• MaxMind GeoIP databases for geolocation
• Redis for velocity tracking
• TURN server for WebRTC IP probe

Client SDK Not Connecting

Confirm you have replaced the FingerprintJS client with @tracio/sdk and that Tracio.init() is called with a valid public key for the correct workspace.