Migrate from FingerprintJS Pro

The two products share a shape: a client agent identifies the visitor and returns a request ID, and your server reads the result with a secret key. Most of a migration is renaming. This guide maps each part, then walks through switching over without a gap in protection.

At a glance

Plan the switch

1. 01

   Step 1: Create Fingerly keys

   Create a public key with your site's origins and a secret key, first in development, then in production. Unlike FingerprintJS Pro's optional request filtering, allowed origins are required: a public key with none refuses every browser request. See API keys.

2. 02

   Step 2: Run both agents side by side

   Call Fingerly next to FingerprintJS Pro at the same moments and send both request IDs to your server. Keep deciding with FingerprintJS Pro, and log what Fingerly would have decided.

3. 03

   Step 3: Move server checks

   When the two agree on the sessions you care about, switch your decisions to the Fingerly event. Keep reading FingerprintJS Pro results for a few days as a fallback.

4. 04

   Step 4: Move webhooks

   Register Fingerly endpoints, verify their signatures, and point your consumers at them.

5. 05

   Step 5: Remove the old agent

   Delete the FingerprintJS Pro agent, its proxy routes and its keys.

Replace the JavaScript agent

import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

const fp = await FingerprintJS.load({
  apiKey: '<public api key>',
  region: 'eu',
  endpoint: ['https://metrics.example.com', FingerprintJS.defaultEndpoint],
})

const { requestId, visitorId } = await fp.get({ linkedId: user.id, tag: { action: 'login' } })

Load options

get() options and result

Fingerly also returns the score, the level and the signals in the same response, and local verdicts computed in the browser. Use them to adapt the interface; decide on your server.

Replace the React library

import { FpjsProvider, useVisitorData } from '@fingerprintjs/fingerprintjs-pro-react'

<FpjsProvider loadOptions={{ apiKey: '<public api key>' }}>
  <App />
</FpjsProvider>

const { getData, isLoading } = useVisitorData({ extendedResult: true }, { immediate: false })
const { requestId } = await getData({ ignoreCache: true })

useIdentify({ immediate: true }) replaces immediate: true, and refresh() replaces getData({ ignoreCache: true }). Vue, Svelte, Angular and Next.js have the same shape: see the SDKs.

Mobile

On iOS and Android, replace the FingerprintJS Pro client and its visitor ID calls with Fingerly.load(apiKey:) and identify(tag:). The result has the same fields as on the web. See iOS and Android, or React Native and Flutter.

Replace server reads

import { FingerprintJsServerApiClient, Region } from '@fingerprintjs/fingerprintjs-pro-server-api'

const client = new FingerprintJsServerApiClient({ apiKey: process.env.FP_SECRET_API_KEY!, region: Region.EU })

const event = await client.getEvent(requestId)
const { visitorId, linkedId, timestamp } = event.products.identification.data
const isBot = event.products.botd?.data?.bot.result === 'bad'
const usesVpn = event.products.vpn?.data?.result === true

An event lists only the signal groups that fired. A group that is absent did not fire. Server libraries for Python, Go, Java, .NET, PHP, Ruby and Rust make the same calls.

Smart Signals and signal groups

Every group has a weight you can change, per organization or per key, and the score is their sum. See signals and risk weights.

Replace webhooks

import { isValidWebhookSignature } from '@fingerprintjs/fingerprintjs-pro-server-api'

const valid = isValidWebhookSignature({
  header: req.get('fpjs-event-signature'),
  data: rawBody,
  secret: process.env.FP_WEBHOOK_SECRET!,
})
const visit = JSON.parse(rawBody.toString())

If your consumer needs every signal for every identification, read the event by data.request_id when identification.completed arrives. See webhooks.

Proxy integrations

FingerprintJS Pro's proxy integrations forward both the agent download and its requests. Fingerly's SDK is part of your bundle, so a Fingerly proxy only forwards two API routes. Use the Cloudflare Worker, createProxy for Node.js runtimes, or your own proxy. Choose a new path rather than reusing the old one, so both can run during the switch.

Identities do not carry over

• Store the Fingerly visitor_id next to the FingerprintJS Pro one on your accounts, orders and devices while both run.
• Rules such as "known device for this account" start empty. Loosen new-device friction during the switch, or keep consulting the old IDs until customers have returned once.
• Counters per visitor, such as sign-ups per device, restart from zero. Keep old limits running on the old IDs until the window they cover has passed.

Other differences

• Environments. Keys belong to development, staging or production. Development and staging run the same detection and are free. See environments.
• Pricing. Prepaid, $0.003 per production identification, with no plans or minimums. See billing.
• Retention. Events are readable for 30 days. Keep your own copy for longer. See data retention.
• Regions. The United States region is available; the European Union region is coming soon. See regions.
• Consent. Every SDK takes a consent option and collects nothing until it is granted. See consent tools.