Migrate from another provider

Most device identification 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. Allowed origins are required, not optional: 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 your current agent at the same moments and send both request IDs to your server. Keep deciding with your current provider, 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 your current provider's 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 old agent, its proxy routes and its keys.

Replace the JavaScript agent

import { load } from '@fingerly/web-js'

const fingerly = await load({
  apiKey: 'fly_pk_production_…',
  endpoints: '/k7x2qm4a',
  fallbackToDefaultEndpoint: true,
  consent: 'granted', // only once you have consent (or another lawful basis)
})

const { requestId, visitorId } = await fingerly.identify({ tag: 'login' })

Load options

Identify 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 a React library

import { FingerlyProvider, useIdentify } from '@fingerly/react'

<FingerlyProvider apiKey="fly_pk_production_…" consent="granted">
  <App />
</FingerlyProvider>

const { identify, isLoading } = useIdentify({ tag: 'login' })
const { requestId } = await identify({ force: true })

useIdentify({ immediate: true }) identifies on mount, and refresh() identifies again, bypassing any cached result. Vue, Svelte, Angular and Next.js have the same shape: see the SDKs.

Mobile

On iOS and Android, replace your current client and its visitor ID calls with Fingerly.load(apiKey:consent:) and identify(tag:), passing a granted consent state once you have consent. The result has the same fields as on the web. See iOS and Android, or React Native and Flutter. The mobile SDKs are coming soon and not yet available to install.

Replace server reads

import { load } from '@fingerly/node'

const fingerly = load({ secretKey: process.env.FINGERLY_SECRET_KEY! })
const fired = (event: { triggers: Array<{ signal: string }> }, group: string) =>
  event.triggers.some((trigger) => trigger.signal === group)

const event = await fingerly.events.get(requestId)
const { visitor_id, tag, occurred_at } = event
const isBot = fired(event, 'bot')
const usesVpn = fired(event, 'vpn')

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.

Risk 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 { verifyWebhook } from '@fingerly/node'

const valid = verifyWebhook({
  secret: process.env.FINGERLY_WEBHOOK_SECRET!,
  payload: rawBody,
  timestamp: req.get('x-fingerly-timestamp'),
  signature: req.get('x-fingerly-signature'),
})
const { type, data } = 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

Many providers' proxy integrations forward both an agent download and its requests. Fingerly's SDK is part of your bundle, so a Fingerly proxy forwards one path, the random one the dashboard issues, to one API URL. Use the Cloudflare Worker, a server SDK's proxy, a ready-made template for Vercel, Netlify, AWS CloudFront, Google Cloud Run, nginx, Caddy, Traefik or a container, or your own proxy. A custom subdomain maps to a hosted subdomain, with the same weakness against DNS-level blockers. The new path is different from the old one, so both can run during the switch.

Identities do not carry over

• Store the Fingerly visitor_id next to your current provider's 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, from $0.0025 per production identification, falling with monthly volume, with no plans or minimums. See billing.
• Retention. Events are readable for 30 days. Keep your own copy for longer. See data retention.
• Consent. Every SDK takes a consent option, defaults it to pending, and collects nothing until it is granted. If your current agent collects as soon as it is called, pass granted or wire up your consent tool when you switch. See consent tools.