[INTER-2190] Migrate to API V4

[TheUnderScorer]

INTER-2190 Migrate to API v4

Migrates the SDK to Fingerprint API v4 and realigns the public API with @fingerprint/react. This is a breaking change on every platform (web, iOS, Android) and ships as a major release (see .changeset/v4-api-migration.md).

Note

Stacked on top of the new-arch PR (feature/INTER-970-new-arch). Review/merge that one first.

What changed

Renamed / restructured public API

• FingerprintJsProProvider → FingerprintProvider.
• new FingerprintJsProAgent(...) → start(options), returning a client with a single get(options) method. getVisitorId / getVisitorData are removed.
• Added useFingerprint() to read the client from context.
• getData(tags, linkedId, options) collapses into a single options object: getData({ tags, linkedId, timeout }).

useVisitorData behavior

• Now returns a discriminated union (data / isLoading / isFetched / error) similar to React SDK.
• getData always throws on error; the throwOnError option is removed.
• immediate now defaults to false.

Grouped provider / start options

• Platform-only options are nested under android (allowUseOfLocationData, locationTimeoutMillis), ios (allowUseOfLocationData), and web (storageKeyPrefix, urlHashing, remoteControlDetection, cache). locationTimeoutMillisAndroid moves to android.locationTimeoutMillis.
• endpointUrl + fallbackEndpointUrls are replaced by a single endpoints (string or string[]).

snake_case response

• The response is now the flat, snake_case FingerprintResponse (visitor_id, event_id, suspect_score?, sealed_result), matching the Server API v4 and JS agent. requestId → event_id, confidence → suspect_score, sealedResult → sealed_result.
• The nested extended fields (ipLocation, firstSeenAt, etc.) and the extendedResponseFormat option are removed (v4 always returns the flat format).

Single error type

• The ~28 error classes are replaced by a single FingerprintError ({ name, code, event_id }) plus an isFingerprintError type guard. Discriminate on error.code (e.g. too_many_requests).

Web

• The web implementation now uses @fingerprint/agent (v4) instead of @fingerprintjs/fingerprintjs-pro-spa. @fingerprint/agent becomes the web peer dependency.

Native

• iOS and Android modules updated to produce the v4 flat response and the unified error mapping.

Migration highlights

- import { FingerprintJsProProvider, FingerprintJsProAgent, TooManyRequestError } from '...'
+ import { FingerprintProvider, start, isFingerprintError } from '...'

- const client = new FingerprintJsProAgent({ apiKey, region: 'eu' })
- const data = await client.getVisitorData()
+ const fp = start({ apiKey, region: 'eu' })
+ const result = await fp.get()
+ result.visitor_id    // was result.visitorId
+ result.suspect_score // was result.confidence.score

Full before/after guide (provider, hook, imperative client, options, errors, web peer dep) is in .changeset/v4-api-migration.md.

Validation

• Unit tests reworked for the new provider, client, hook, and error model (FingerprintProvider.test.ts, FingerprintClient.test.ts, useVisitorData.test.ts, errors.test.ts).
• E2E app (Detox mobile + Playwright web) and its identification tests updated to the v4 API; e2e server-side switched to @fingerprint/node-sdk.
• README / SDK README updated to v4 usage.

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟢	Statements	91.74% (+40.06% 🔼)	222/242
🟢	Branches	89.77% (+27.81% 🔼)	193/215
🟢	Functions	85.19% (+37.82% 🔼)	46/54
🟢	Lines	91.34% (+41.34% 🔼)	211/231

Show new covered files 🐣

St.❔	File	Statements	Branches	Functions	Lines
🟢	FingerprintClient.ts	100%	92.86%	100%	100%
🟡	FingerprintContext.ts	66.67%	100%	0%	66.67%
🟢	getOptionsCacheKey.ts	84%	83.33%	100%	83.33%
🟢	usePromiseStore.ts	100%	100%	100%	100%
🟢	FingerprintProvider.tsx	100%	100%	100%	100%
🔴	useFingerprint.ts	0%	0%	0%	0%
🔴	FingerprintClient.web.ts	0%	0%	0%	0%

Show files with reduced coverage 🔻

St.❔	File	Statements	Branches	Functions	Lines
🟡	errors.ts	75% (+64.29% 🔼)	50% (-50% 🔻)	50% (+39.29% 🔼)	75% (+64.29% 🔼)
🟢	useVisitorData.ts	95.92% (-4.08% 🔻)	85.71% (-14.29% 🔻)	90% (-10% 🔻)	95.74% (-4.26% 🔻)

Test suite run success

85 tests passing in 5 suites.

Report generated by 🧪jest coverage report action from 294c0cd

Show full coverage report

St	File	% Stmts	% Branch	% Funcs	% Lines	Uncovered Line #s
🟢	All files	91.73	89.76	85.18	91.34
🟢	src	91.73	89.76	85.18	91.34
🟢	FingerprintClient.ts	100	92.85	100	100	22,54
🔴	FingerprintClient.web.ts	0	0	0	0	5-58
🟡	FingerprintContext.ts	66.66	100	0	66.66	6
🟢	FingerprintProvider.tsx	100	100	100	100
🟡	errors.ts	75	50	50	75	3,121
🟢	getOptionsCacheKey.ts	84	83.33	100	83.33	10,33,43,52
🔴	index.ts	0	0	0	0
🔴	types.ts	0	0	0	0
🟢	unwrapError.ts	100	88.46	100	100	18-19,40
🟢	unwrapError.web.ts	100	100	100	100
🔴	useFingerprint.ts	0	0	0	0	24-28
🟢	usePromiseStore.ts	100	100	100	100
🟢	useVisitorData.ts	95.91	85.71	90	95.74	166-167
🟢	utils.ts	100	100	100	100
🔴	src/specs	0	0	0	0
🔴	NativeRNFingerprintjsPro.ts	0	0	0	0

[Copilot]

🟡 Changes recommended

Request-option handling, stale responses, native tag consistency, error metadata, and migration documentation remain incorrect.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Migrates the SDK and its native/web integrations to Fingerprint API v4.

Changes:

• Replaces legacy providers and agents with FingerprintProvider, start(), and useFingerprint().
• Introduces snake_case responses and unified FingerprintError handling.
• Upgrades native, web, and E2E dependencies and tests.

File summaries

File	Description
.changeset/v4-api-migration.md	Documents breaking migration.
README.md	Updates public usage guide.
pnpm-lock.yaml	Locks the v4 web agent.
sdk/README.md	Updates SDK documentation.
sdk/RNFingerprintjsPro.podspec	Upgrades iOS dependency.
sdk/package.json	Replaces web peer dependency.
sdk/src/useVisitorData.ts	Redesigns query hook.
sdk/src/useFingerprint.ts	Adds client hook.
sdk/src/unwrapError.web.ts	Normalizes web errors.
sdk/src/unwrapError.ts	Normalizes native errors.
sdk/src/types.ts	Defines v4 public types.
sdk/src/specs/NativeRNFingerprintjsPro.ts	Updates native contract.
sdk/src/index.ts	Exports new API.
sdk/src/FingerprintProvider.tsx	Adds redesigned provider.
sdk/src/FingerprintJsProProvider.tsx	Removes legacy provider.
sdk/src/FingerprintJsProContext.ts	Removes legacy context.
sdk/src/FingerprintJsProAgent.web.ts	Removes legacy web agent.
sdk/src/FingerprintJsProAgent.ts	Removes legacy native agent.
sdk/src/FingerprintContext.ts	Adds new context.
sdk/src/FingerprintClient.web.ts	Implements web client.
sdk/src/FingerprintClient.ts	Implements native client.
sdk/src/errors.ts	Introduces unified errors.
sdk/ios/RNFingerprintjsPro.xcodeproj/project.pbxproj	Links iOS v4 package.
sdk/ios/RNFingerprintjsPro.swift	Migrates Swift bridge.
sdk/ios/RNFingerprintjsPro.mm	Updates Objective-C bridge.
sdk/ios/JSONTypeConvertor.swift	Updates SDK import.
sdk/ios/FPJSError+React.swift	Maps v4 error codes.
sdk/android/src/main/java/com/fingerprintjs/reactnative/RNFingerprintjsProModule.kt	Migrates Android bridge.
sdk/android/settings.gradle	Updates Kotlin plugin.
sdk/android/fingerprint.gradle	Selects Android SDK v4.
sdk/android/build.gradle	Updates Android dependency.
sdk/__tests__/useVisitorData.test.ts	Tests redesigned hook.
sdk/__tests__/setup.ts	Updates native mocks.
sdk/__tests__/helpers.tsx	Uses new provider.
sdk/__tests__/FingerprintProvider.test.ts	Tests new provider.
sdk/__tests__/FingerprintJsProProvider.test.ts	Removes legacy tests.
sdk/__tests__/FingerprintClient.test.ts	Tests native client.
sdk/__tests__/errors.test.ts	Tests unified errors.
e2e-app/pnpm-workspace.yaml	Normalizes workspace configuration.
e2e-app/pnpm-lock.yaml	Locks migrated dependencies.
e2e-app/package.json	Updates agent and server SDK.
e2e-app/e2e/ids.ts	Adds error-code identifier.
e2e-app/e2e/identify.ts	Handles v4 results.
e2e-app/e2e/identification.test.ts	Migrates native E2E tests.
e2e-app/e2e-web/identification.test.ts	Migrates web E2E tests.
e2e-app/App.tsx	Uses the new SDK API.

Review details

Files not reviewed (2)

• e2e-app/pnpm-lock.yaml: Generated file
• pnpm-lock.yaml: Generated file

• Files reviewed: 43/46 changed files
• Comments generated: 6
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

🚀 Following releases will be created using changesets from this PR:

@fingerprintjs/fingerprintjs-pro-react-native@4.0.0-rc.1

Major Changes

• Migrated the SDK to Fingerprint API v4 and realigned the public API with @fingerprint/react. This is a breaking change on every platform (web, iOS, Android).

  Renamed API

  • FingerprintJsProProvider → FingerprintProvider.
  • FingerprintJsProAgent (constructed with new) → start(options), returning a client with a single get(options) method (getVisitorId/getVisitorData are removed).
  • Added useFingerprint() to read the client from context.

  Single options object

  • getData(tags, linkedId, options) → getData({ tags, linkedId, timeout }).
  • useVisitorData now returns a discriminated union (data/isLoading/isFetched/error), and getData always throws on error. The throwOnError option is removed. immediate defaults to false.

  Grouped provider/start options

  • Platform-only options are nested: android (allowUseOfLocationData, locationTimeoutMillis), ios (allowUseOfLocationData), web (storageKeyPrefix, urlHashing, cache). locationTimeoutMillisAndroid moves to android.locationTimeoutMillis.
  • endpointUrl + fallbackEndpointUrls are replaced by a single endpoints (string or string[]).

  snake_case response

  • The response is now the flat, snake_case FingerprintResponse (visitor_id, event_id, suspect_score?, sealed_result), matching the Server API v4 and JS agent. requestId is replaced by event_id, confidence is removed, and suspect_score is a new optional Smart Signals value; sealedResult is renamed to sealed_result. The nested extended fields (ipLocation, firstSeenAt, etc.) and the extendedResponseFormat option are removed (v4 always returns the flat format).

  Single error type

  • The ~28 error classes are replaced by a single FingerprintError ({ name, code, event_id }) plus an isFingerprintError type guard. Discriminate on error.code (e.g. too_many_requests).
  • Every network failure reports code: 'network_error' on all platforms. The platform-specific network_unavailable (Android), network_connection and network_abort (web) codes are not emitted.

  Web

  • The web implementation now uses @fingerprint/agent (v4) instead of @fingerprintjs/fingerprintjs-pro-spa. Install @fingerprint/agent as the web peer dependency.
  • ️Caching is available only on web and is disabled by default. To enable caching on web, pass the JavaScript agent cache option:

    <FingerprintProvider
      apiKey={'your-fpjs-public-api-key'}
      region={'eu'}
      web={{cache: {storage: 'sessionStorage', duration: 'optimize-cost'}}}
    >
      <App />
    </FingerprintProvider>

  iOS:

  • The new version floor for iOS is 15.1.

  Android:

  • The new version floor for Android is Android 7.0 (API level 24+).

  Migration

  Provider

  - import { FingerprintJsProProvider } from '@fingerprintjs/fingerprintjs-pro-react-native'
  + import { FingerprintProvider } from '@fingerprintjs/fingerprintjs-pro-react-native'
  
  - <FingerprintJsProProvider apiKey="PUBLIC_API_KEY" region="eu">
  + <FingerprintProvider apiKey="PUBLIC_API_KEY" region="eu">
      <App />
  - </FingerprintJsProProvider>
  + </FingerprintProvider>

  Hook (useVisitorData)

  - const { isLoading, error, data, getData } = useVisitorData()
  + const { isLoading, isFetched, error, data, getData } = useVisitorData()
  
    // positional args + opt-in throwing → single options object, always throws
  - await getData({ userAction: 'login' }, 'user_1234', { timeout: 5000, throwOnError: true })
  + await getData({ tags: { userAction: 'login' }, linkedId: 'user_1234', timeout: 5000 })
  
  - data?.visitorId
  - data?.confidence.score
  + data?.visitor_id
  + data?.suspect_score

  Imperative client

  - import { FingerprintJsProAgent } from '@fingerprintjs/fingerprintjs-pro-react-native'
  + import { start } from '@fingerprintjs/fingerprintjs-pro-react-native'
  
  - const client = new FingerprintJsProAgent({ apiKey: 'PUBLIC_API_KEY', region: 'eu' })
  - const visitorId = await client.getVisitorId()
  - const data = await client.getVisitorData()
  + const fp = start({ apiKey: 'PUBLIC_API_KEY', region: 'eu' })
  + const result = await fp.get()
  + result.visitor_id

  Provider / start options

    {
      apiKey: 'PUBLIC_API_KEY',
      region: 'eu',
  -   endpointUrl: 'https://metrics.example.com',
  -   fallbackEndpointUrls: ['https://metrics2.example.com'],
  +   endpoints: ['https://metrics.example.com', 'https://metrics2.example.com'],
  -   extendedResponseFormat: true,
  -   allowUseOfLocationData: true,
  -   locationTimeoutMillisAndroid: 5000,
  +   android: { allowUseOfLocationData: true, locationTimeoutMillis: 5000 },
  +   ios: { allowUseOfLocationData: true },
    }

  Errors

  - import { TooManyRequestError } from '@fingerprintjs/fingerprintjs-pro-react-native'
  + import { isFingerprintError } from '@fingerprintjs/fingerprintjs-pro-react-native'
  
    try {
      await fp.get()
    } catch (error) {
  -   if (error instanceof TooManyRequestError) {
  +   if (isFingerprintError(error) && error.code === 'too_many_requests') {
        // handle rate limiting
      }
    }

  Web peer dependency

  - npm install @fingerprintjs/fingerprintjs-pro-spa
  + npm install @fingerprint/agent

  --- (64f1dfb)

[kevinmia]

Did a did a scan for any leftover references and verified that both comments from Juraj's review are addressed. Unit tests and manual testing passed