[INTER-2190] Final V4 adjustments

[TheUnderScorer]

• Bumped Android SDK to 4.1.0
• Added tags validation based on flutter implementation
• Added logic to set visitor_id to undefined if it's empty
• Return unknown_error instead of failed for unknown errors on iOS
• Document requirement for single client

[github-actions]

Coverage report

St.❔	Category	Percentage	Covered / Total
🟢	Statements	91.95% (+0.22% 🔼)	240/261
🟢	Branches	89.7% (-0.07% 🔻)	209/233
🟢	Functions	85.71% (+0.53% 🔼)	48/56
🟢	Lines	91.6% (+0.26% 🔼)	229/250

Show new covered files 🐣

St.❔	File	Statements	Branches	Functions	Lines
🟢	tags.ts	94.12%	93.75%	100%	94.12%

Show files with reduced coverage 🔻

St.❔	File	Statements	Branches	Functions	Lines
🟢	FingerprintClient.ts	100%	90% (-2.86% 🔻)	100%	100%

Test suite run success

91 tests passing in 6 suites.

Report generated by 🧪jest coverage report action from 5b2a338

Show full coverage report

St	File	% Stmts	% Branch	% Funcs	% Lines	Uncovered Line #s
🟢	All files	91.95	89.69	85.71	91.6
🟢	src	91.95	89.69	85.71	91.6
🟢	FingerprintClient.ts	100	90	100	100	22,41,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
🟢	tags.ts	94.11	93.75	100	94.11	28
🔴	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
🔴	NativeRNFingerprint.ts	0	0	0	0

[Copilot]

Copilot review overview

🟡 Changes recommended

Address validation error propagation and cross-platform tag and visitor ID contract issues before approval.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 2

Open (2)

• Nested undefined values bypass recursive tag validation · New
• Web normalizer returns empty string instead of undefined visitor ID · New

What changed in this PR

Updates the SDK for Android 4.1.0, recursive tag validation, and empty visitor ID normalization.

Changes:

• Bumps the Android SDK dependency to 4.1.0.
• Adds tag validation and InvalidArgumentError.
• Normalizes empty native visitor_id values to undefined.

File	Summary
sdk/​src/​types.ts	Updates the visitor ID response contract.
sdk/​src/​tags.ts	Adds recursive tag validation.
sdk/​src/​index.ts	Exports validation APIs and errors.
sdk/​src/​FingerprintClient.ts	Applies validation and response normalization.
sdk/​src/​errors.ts	Defines invalid argument errors.
sdk/​android/​fingerprint.gradle	Bumps the Android SDK version.
sdk/​__tests__/​tags.test.ts	Adds tag validation tests.

---

💡 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:

@fingerprint/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 '@fingerprint/react-native'
  + import { FingerprintProvider } from '@fingerprint/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 '@fingerprint/react-native'
  + import { start } from '@fingerprint/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 '@fingerprint/react-native'
  + import { isFingerprintError } from '@fingerprint/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)