Migrating the Fingerprint Flutter SDK from v4 to v5

Fingerprint Flutter SDK 5.0.0 is built on the v4 native SDKs: the Android SDK and the iOS SDK. On web, it uses JavaScript agent v4. All platforms return the v4 event format. It introduces breaking changes, so you must migrate your integration manually. v5 changes the public API and your project’s minimum Flutter, Dart, Android, iOS, Xcode, and build-tool versions. It does not change identification or Smart Signals accuracy.

Flutter SDK v4 (fpjs_pro_plugin) keeps working after v5 is released. You don’t have to upgrade right away.
Flutter SDK v4 uses API v3. Its support ends with the API v3 one-year deprecation period.

What’s new

On Android and iOS, the SDK uses native SDK v4 (4.1.x) instead of v2. Only native patch releases are picked up automatically.
The package is renamed from fpjs_pro_plugin to fingerprint_flutter, and the GitHub repository moved from fingerprintjs/fingerprintjs-pro-flutter to fingerprintjs/flutter.
The static FpjsProPlugin API is replaced by a Fingerprint client instance with a single get() method.
Platform-specific options are grouped under android, ios, and web, and endpoint and endpointFallbacks are replaced by a single endpoints list.
The result is a flat FingerprintResult. requestId is renamed to eventId, and the extended response fields are removed.
All error subclasses are replaced by a single FingerprintError with a code field.
Timeouts use Duration instead of milliseconds.
On web, the SDK uses JavaScript agent v4, bundled in the package.
The constructor and get() validate their arguments and throw ArgumentError for invalid values.
The minimum versions are Flutter 3.44.0, Dart 3.12.0, Android 7.0 (API level 24), and iOS 15 with Xcode 16 and Swift 6.

Migration steps

Update your environment

Make sure your app meets the new minimum versions:

Requirement	v4 minimum	v5 minimum
Flutter	3.19.0	3.44.0
Dart	3.3.0	3.12.0
Android	6.0 (API level 23)	7.0 (API level 24)
iOS	13	15
Swift	5.9	6

v5 also requires Xcode 16 or higher.

On iOS, update the platform :ios line in ios/Podfile if you use CocoaPods, and the iOS deployment target in Xcode.
On Android, set minSdk to 24 or higher in android/app/build.gradle (or build.gradle.kts).
The plugin no longer applies the Kotlin Gradle plugin, so it builds with Android Gradle plugin (AGP) 9. If your app still uses AGP 8, use Kotlin Gradle plugin 2.2.20 or higher.
The plugin no longer adds the jitpack.io Maven repository to your Gradle project. If your app depends on packages from JitPack, add maven { url 'https://jitpack.io' } to your repositories yourself.

Replace the package

In pubspec.yaml, replace fpjs_pro_plugin with fingerprint_flutter:

pubspec.yaml

dependencies:
  flutter:
    sdk: flutter
  fpjs_pro_plugin: ^4.13.1
  fingerprint_flutter: ^5.0.0

Run flutter pub get. Then update your imports. The new package exports all public types from a single library:

Dart

import 'package:fpjs_pro_plugin/fpjs_pro_plugin.dart'; 
import 'package:fpjs_pro_plugin/error.dart'; 
import 'package:fpjs_pro_plugin/region.dart'; 
import 'package:fpjs_pro_plugin/result.dart'; 
import 'package:fingerprint_flutter/fingerprint_flutter.dart'; 

Two top-level APIs are also renamed:

v4	v5
`pluginVersion`	`fingerprintFlutterVersion`
`Region.stringValue`	`Region.name`

If your app targets web, update the loader script in web/index.html:

web/index.html

<script src="assets/packages/fpjs_pro_plugin/web/index.js" defer></script>
<script src="assets/packages/fingerprint_flutter/web/index.js" defer></script>

Create a `Fingerprint` client

FpjsProPlugin.initFpjs() is replaced by the Fingerprint constructor. The constructor is synchronous, so you don’t need to await it. It starts the client in the background, and errors from starting the client surface when you call get(). The constructor itself throws in these cases:

ArgumentError if an endpoints entry is not an http or https URL, or if android.locationTimeout is under 1 millisecond.
FlutterError on Android and iOS if the Flutter binding doesn’t exist yet. Call WidgetsFlutterBinding.ensureInitialized() before you create the client, as you did before initFpjs().

getVisitorId() and getVisitorData() are replaced by a single get() method.

Dart

WidgetsFlutterBinding.ensureInitialized();
await FpjsProPlugin.initFpjs('PUBLIC_API_KEY', region: Region.eu); 
final visitorId = await FpjsProPlugin.getVisitorId(); 
final visitorData = await FpjsProPlugin.getVisitorData(); 
final fingerprint = Fingerprint(apiKey: 'PUBLIC_API_KEY', region: Region.eu); 
final result = await fingerprint.get(); 
print(result.visitorId); 
print(result.eventId); 

Create one client per public API key and configuration, for example when your app starts, and reuse it.

Update identification options

get() accepts tags and linkedId like getVisitorData(). timeoutMs is replaced by timeout, which takes a Duration. get() now validates its arguments and throws ArgumentError before identifying if:

tags is not JSON-compatible. Keys must be strings, and values must be strings, finite numbers, booleans, null, lists, or nested maps. Typed lists such as Uint8List are rejected.
timeout is under 1 millisecond.

In v4, some of these values were silently dropped or failed with a timeout error. Check that your tags are JSON-compatible before you upgrade.

Dart

await FpjsProPlugin.getVisitorData( 
await fingerprint.get( 
  tags: {'action': 'login'},
  linkedId: 'user_1234',
  timeoutMs: 5000, 
  timeout: const Duration(seconds: 5), 
);

Update client options

Options that apply to one platform only are grouped in AndroidOptions, IosOptions, and WebOptions. endpoint and endpointFallbacks are replaced by a single endpoints list.

v4 option	v5 option
`apiKey` (positional argument)	`apiKey` (named argument)
`region`	`region`
`endpoint` and `endpointFallbacks`	`endpoints`
`allowUseOfLocationData`	`android.allowUseOfLocationData` and `ios.allowUseOfLocationData`
`locationTimeoutMillisAndroid`	`android.locationTimeout` (`Duration`)
`scriptUrlPattern` and `scriptUrlPatternFallbacks`	Removed, use `endpoints` instead.
`extendedResponseFormat`	Removed. v5 only has one response format.

Dart

await FpjsProPlugin.initFpjs( 
  'PUBLIC_API_KEY', 
  region: Region.eu, 
  endpoint: 'https://metrics.yourwebsite.com', 
  endpointFallbacks: ['https://eu.api.fpjs.io'], 
  allowUseOfLocationData: true, 
  locationTimeoutMillisAndroid: 5000, 
); 
final fingerprint = Fingerprint( 
  apiKey: 'PUBLIC_API_KEY', 
  region: Region.eu, 
  endpoints: ['https://metrics.yourwebsite.com', 'https://eu.api.fpjs.io'], 
  android: const AndroidOptions( 
    allowUseOfLocationData: true, 
    locationTimeout: Duration(seconds: 5), 
  ), 
  ios: const IosOptions(allowUseOfLocationData: true), 
); 

With a custom endpoints list, the SDK tries only the endpoints you pass. It does not fall back to the default Fingerprint endpoint. Add the default endpoint for your region as the last item.

On web, you can also enable caching of identification results with WebOptions. Caching is off by default. See Web options in the Flutter SDK README and the JavaScript agent cache option.

Update result fields

The result is now a flat FingerprintResult:

v4 field	v5 field
`requestId`	`eventId`
`visitorId` (`String`)	`visitorId` (`String?`)
`sealedResult`	`sealedResult`
`confidenceScore`	Removed
Extended fields, such as `ipLocation` and `firstSeenAt`	Removed

visitorId is null when the visitor ID is hidden, for example in Zero Trust Mode. v5 also adds these fields:

suspectScore: the Suspect Score, if available. It is not a replacement for the confidence score. A higher value means a more suspicious request.
cacheHit: true when the result came from the web cache. null on web unless WebOptions.cache is set, and always null on Android and iOS.

The FingerprintJSProResponse and FingerprintJSProExtendedResponse types are removed. To get the data from the removed fields, send eventId to your backend and get the full event with the Server API.

Dart

final requestId = visitorData.requestId; 
final score = visitorData.confidenceScore.score; 
final eventId = result.eventId; 
final suspectScore = result.suspectScore; 

Update error handling

The FingerprintProError subclasses, such as TooManyRequestError and ClientTimeoutError, are replaced by a single FingerprintError class. Compare error.code with the constants on FingerprintError instead of checking the error type. FingerprintError does not extend PlatformException. If your code catches SDK errors with on PlatformException, it still compiles but no longer catches them. Catch FingerprintError instead.

Dart

try {
  await FpjsProPlugin.getVisitorData(); 
  await fingerprint.get(); 
} on FingerprintProError catch (error) { 
  if (error is TooManyRequestError) { 
} on FingerprintError catch (error) { 
  if (error.code == FingerprintError.tooManyRequests) { 
    // Handle rate limiting
  }
}

Common v4 error classes map to these codes:

v4 error class	v5 `error.code`
`ClientTimeoutError`	`client_timeout` (`FingerprintError.clientTimeout`)
`NetworkError`	`network_error` (`FingerprintError.networkError`)
`TooManyRequestError`	`too_many_requests` (`FingerprintError.tooManyRequests`)
`ApiKeyNotFoundError`	`public_api_key_not_found` (`FingerprintError.publicApiKeyNotFound`)
`WrongRegionError`	`wrong_region` (`FingerprintError.wrongRegion`)

Error codes are the same on Android, iOS, and web where the platforms share the error. Network failures report the network_error code on all platforms. The list of codes can grow in future versions, so add a generic fallback for codes you don’t handle. For the full list, see the FingerprintError constants.

Understanding Fingerprint

Identify browsers

Identify mobile devices

AI

Rules Engine and Flow (Beta)

Protect your implementation

Integrate with your server

Integrate Smart Signals

Tips and advanced guides

Platform updates

Resources

Legal

Migrating the Fingerprint Flutter SDK from v4 to v5

What’s new

Migration steps

Update your environment

Replace the package

Create a `Fingerprint` client

Update identification options

Update client options

Update result fields

Update error handling

​What’s new

​Migration steps

​Update your environment

​Replace the package

​Create a Fingerprint client

​Update identification options

​Update client options

​Update result fields

​Update error handling

​Related resources

What’s new

Migration steps

Update your environment

Replace the package

Create a `Fingerprint` client

Update identification options

Update client options

Update result fields

Update error handling

Related resources