[TheUnderScorer]

This PR includes the BareRNSPMTest app that is used to test the SPM support in CI. It can also be run locally; you only need to remember to run npx react-native spm --deintegrate in the place where you would normally run pod install.

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟢	Statements	91.74%	222/242
🟢	Branches	89.77%	193/215
🟢	Functions	85.19%	46/54
🟢	Lines	91.34%	211/231

Test suite run success

85 tests passing in 5 suites.

Report generated by 🧪jest coverage report action from 4089572

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	21,53
🔴	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

[kevinmia]

Overall looks good to me! Just left some non-blocking comments.

On thing to note: I tried running this locally with Xcode 27, and the app crashed repeatedly on launch. Think we only need to address this if we ever plan on bumping the version to 27 for the CI workflow. But if this is a temporary testing app, can ignore. Especially since CI has been passing with version 26.3

Here's info from Claude:

Crash: EXC_BREAKPOINT (SIGTRAP) — UIApplicationEvaluateRuntimeIssueForNoSceneLifecycleAdoption

"Application failed to launch: UIScene life cycle is required for apps built with this SDK. See 'Transitioning to the UIKit scene-based life cycle' in the UIKit documentation for more information on migration."

Root cause: AppDelegate.swift doesn't adopt scene lifecycle (no SceneDelegate, no UIApplicationSceneManifest in Info.plist) — it creates a UIWindow directly in didFinishLaunchingWithOptions, which Xcode 27's iOS SDK no longer allows.

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

Minor Changes

• Added experimental support for Swift Package Manager. The library now ships with its own Package.swift.

  If you are on React Native >= 0.87, you can run:

  cd ios
  # deintegrate will remove CocoaPods from your project
  npx react-native spm --deintegrate

  to consume the library via Swift Package Manager. (7af274f)