v5.0.0

Major Changes

• Migrated the SDK to Fingerprint API v4. This is a breaking change on every platform.

  Requirements

  • Flutter 3.44.0 and Dart 3.12.0.
  • Android 7.0 (API 24+). Native SDK 4.1.x. The plugin no longer applies the Kotlin Gradle plugin, so it builds under AGP 9. Apps on AGP 8 need Kotlin Gradle plugin 2.2.20 or newer. The plugin no longer adds the jitpack.io repository. If your app uses JitPack dependencies, declare the repository yourself.
  • iOS 15 / tvOS 15, Xcode 16, Swift 6. Native SDK 4.1.x (Fingerprint-iOS).
  • Only native patch releases are picked up automatically.
  • Web uses the bundled @fingerprint/agent v4. There is no extra npm peer dependency.

  Package

  fpjs_pro_plugin is now fingerprint_flutter.

  - fpjs_pro_plugin: ^4.13.1
  + fingerprint_flutter: ^5.0.0
  
  - import 'package:fpjs_pro_plugin/fpjs_pro_plugin.dart';
  + import 'package:fingerprint_flutter/fingerprint_flutter.dart';

  API

  • package:fingerprint_flutter/fingerprint_flutter.dart is the only public import. error.dart, result.dart, and region.dart are gone. pluginVersion is renamed to fingerprintFlutterVersion. Region.stringValue is removed, use Region.name.
  • Static FpjsProPlugin.initFpjs / getVisitorId / getVisitorData are replaced by an instance Fingerprint client with get({tags, linkedId, timeout}).
  • The constructor is synchronous and starts the client. Identification failures surface on get. On Android and iOS:
    • The native client is created and get starts on a background thread, so creating the client at app startup does not block the UI thread.
    • The constructor throws FlutterError if the Flutter binding does not exist yet, so call WidgetsFlutterBinding.ensureInitialized() first, as with initFpjs.
  • Timeouts are Duration. endpoint + endpointFallbacks become one endpoints list. Platform options nest under android, ios, and web.
  • scriptUrlPattern, scriptUrlPatternFallbacks, and extendedResponseFormat are removed.
  • tags must be JSON-compatible (string keys, finite numbers, no typed lists). get throws ArgumentError right away for invalid tags or a timeout under 1 ms, before identifying. The constructor throws ArgumentError for an endpoints entry that is not an http or https URL, or an android.locationTimeout under 1 ms.
  • Custom endpoints still get no automatic fallback on any platform, even though JS agent v4 adds one by default. List the regional default URL last if you want it.
  • On Android and iOS, region still defaults to Region.us. Set it for EU and AP workspaces.

  - await FpjsProPlugin.initFpjs(
  -   '<PUBLIC_API_KEY>',
  -   region: Region.eu,
  -   endpoint: 'https://metrics.example.com',
  -   endpointFallbacks: ['https://metrics2.example.com'],
  -   allowUseOfLocationData: true,
  -   locationTimeoutMillisAndroid: 5000,
  -   scriptUrlPattern:
  -       'https://metrics.example.com/web/v<version>/<apiKey>/loader_v<loaderVersion>.js',
  - );
  - final data = await FpjsProPlugin.getVisitorData(
  -   tags: {'userAction': 'login'},
  -   linkedId: 'user_1234',
  -   timeoutMs: 5000,
  - );
  + final fp = Fingerprint(
  +   apiKey: '<PUBLIC_API_KEY>',
  +   region: Region.eu,
  +   endpoints: [
  +     'https://metrics.example.com',
  +     'https://metrics2.example.com',
  +   ],
  +   android: const AndroidOptions(
  +     allowUseOfLocationData: true,
  +     locationTimeout: Duration(seconds: 5),
  +   ),
  +   ios: const IosOptions(allowUseOfLocationData: true),
  +   web: const WebOptions(
  +     cache: WebCache(
  +       storage: WebCacheStorage.sessionStorage,
  +       duration: WebCacheDuration.optimizeCost,
  +     ),
  +   ),
  + );
  + final result = await fp.get(
  +   tags: {'userAction': 'login'},
  +   linkedId: 'user_1234',
  +   timeout: const Duration(seconds: 5),
  + );
  + print(result.visitorId);
  + print(result.eventId);
  + print(result.suspectScore);

  Result

  • FingerprintResult: eventId, visitorId?, suspectScore?, sealedResult?, cacheHit? (web only).
  • requestId is now eventId. confidence / confidenceScore and the extended types (ipLocation, firstSeenAt, and the rest) are gone.
  • visitorId is null when hidden (Zero Trust).

  Errors

  One FingerprintError (code, message?, eventId?). Discriminate on error.code. Network failures report code: 'network_error'. On web, a failed agent script download reports script_load_fail. FingerprintError does not extend PlatformException; if you catch SDK errors with on PlatformException, switch to FingerprintError.

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

  Web

  Caching is off unless you pass web: WebOptions(cache: ...).

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

  If this tag is missing, get throws script_load_fail. (f680434)

Supported Native SDK Version Range

• Fingerprint iOS SDK Version Range: >= 4.1.0 and < 4.2.0
• Fingerprint Android SDK Version Range: >= 4.1.0 and < 4.2.0

v5.0.0-test.1

Patch Changes

• Android: fix R8 release builds failing with "Missing class com.google.android.gms..." and crashing on startup with IllegalAccessError on AGP 9.1. (e656f7a)

Supported Native SDK Version Range

• Fingerprint iOS SDK Version Range: >= 4.1.0 and < 4.2.0
• Fingerprint Android SDK Version Range: >= 4.1.0 and < 4.2.0

• The Fingerprint constructor throws ArgumentError for an endpoints entry that is not an http or https URL. Before, it failed at get, differently on each platform. (e51e064)

v5.0.0-test.0

Major Changes

• Migrated the SDK to Fingerprint API v4. This is a breaking change on every platform.

  Requirements

  • Flutter 3.44.0 and Dart 3.12.0.
  • Android 7.0 (API 24+). Native SDK 4.1.x. The plugin no longer applies the Kotlin Gradle plugin, so it builds under AGP 9. Apps on AGP 8 need Kotlin Gradle plugin 2.2.20 or newer.
  • iOS 15 / tvOS 15, Xcode 16, Swift 6. Native SDK 4.1.x (Fingerprint-iOS).
  • Only native patch releases are picked up automatically.
  • Web uses the bundled @fingerprint/agent v4. There is no extra npm peer dependency.

  Package

  fpjs_pro_plugin is now fingerprint_flutter.

  - fpjs_pro_plugin: ^4.13.1
  + fingerprint_flutter: ^5.0.0
  
  - import 'package:fpjs_pro_plugin/fpjs_pro_plugin.dart';
  + import 'package:fingerprint_flutter/fingerprint_flutter.dart';

  API

  • package:fingerprint_flutter/fingerprint_flutter.dart is the only public import. error.dart, result.dart, and region.dart are gone. pluginVersion is renamed to fingerprintFlutterVersion. Region.stringValue is removed, use Region.name.
  • Static FpjsProPlugin.initFpjs / getVisitorId / getVisitorData are replaced by an instance Fingerprint client with get({tags, linkedId, timeout}).
  • The constructor is synchronous and starts the client. Identification failures surface on get. On Android and iOS, the constructor throws FlutterError if the Flutter binding does not exist yet, so call WidgetsFlutterBinding.ensureInitialized() first, as with initFpjs.
  • Timeouts are Duration. endpoint + endpointFallbacks become one endpoints list. Platform options nest under android, ios, and web.
  • scriptUrlPattern, scriptUrlPatternFallbacks, and extendedResponseFormat are removed.
  • tags must be JSON-compatible (string keys, finite numbers, no typed lists). get throws ArgumentError right away for invalid tags or a timeout under 1 ms, before identifying. The constructor throws ArgumentError for an android.locationTimeout under 1 ms.
  • Custom endpoints still get no automatic fallback on any platform, even though JS agent v4 adds one by default. List the regional default URL last if you want it.
  • On Android and iOS, region still defaults to Region.us. Set it for EU and AP workspaces.

  - await FpjsProPlugin.initFpjs(
  -   '<PUBLIC_API_KEY>',
  -   region: Region.eu,
  -   endpoint: 'https://metrics.example.com',
  -   endpointFallbacks: ['https://metrics2.example.com'],
  -   allowUseOfLocationData: true,
  -   locationTimeoutMillisAndroid: 5000,
  -   scriptUrlPattern:
  -       'https://metrics.example.com/web/v<version>/<apiKey>/loader_v<loaderVersion>.js',
  - );
  - final data = await FpjsProPlugin.getVisitorData(
  -   tags: {'userAction': 'login'},
  -   linkedId: 'user_1234',
  -   timeoutMs: 5000,
  - );
  + final fp = Fingerprint(
  +   apiKey: '<PUBLIC_API_KEY>',
  +   region: Region.eu,
  +   endpoints: [
  +     'https://metrics.example.com',
  +     'https://metrics2.example.com',
  +   ],
  +   android: const AndroidOptions(
  +     allowUseOfLocationData: true,
  +     locationTimeout: Duration(seconds: 5),
  +   ),
  +   ios: const IosOptions(allowUseOfLocationData: true),
  +   web: const WebOptions(
  +     cache: WebCache(
  +       storage: WebCacheStorage.sessionStorage,
  +       duration: WebCacheDuration.optimizeCost,
  +     ),
  +   ),
  + );
  + final result = await fp.get(
  +   tags: {'userAction': 'login'},
  +   linkedId: 'user_1234',
  +   timeout: const Duration(seconds: 5),
  + );
  + print(result.visitorId);
  + print(result.eventId);
  + print(result.suspectScore);

  Result

  • FingerprintResult: eventId, visitorId?, suspectScore?, sealedResult?, cacheHit? (web only).
  • requestId is now eventId. confidence / confidenceScore and the extended types (ipLocation, firstSeenAt, and the rest) are gone.
  • visitorId is null when hidden (Zero Trust).

  Errors

  One FingerprintError (code, message?, eventId?). Discriminate on error.code. Network failures report code: 'network_error' on all platforms. FingerprintError does not extend PlatformException; if you catch SDK errors with on PlatformException, switch to FingerprintError.

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

  Web

  Caching is off unless you pass web: WebOptions(cache: ...).

  - <script src="assets/packages/fpjs_pro_plugin/web/index.js" defer></script>
  + <script src="assets/packages/fingerprint_flutter/web/index.js" defer></script>
  ``` ([f680434](https://github.com/fingerprintjs/flutter/commit/f680434344af66f78c86c3fad94651625097e255))

Patch Changes

• Android: the plugin no longer adds the jitpack.io repository to your Gradle project. If your app uses JitPack dependencies, declare the repository yourself. (f680434)

Supported Native SDK Version Range

• Fingerprint iOS SDK Version Range: >= 4.1.0 and < 4.2.0
• Fingerprint Android SDK Version Range: >= 4.1.0 and < 4.2.0

• Android and iOS: create the native client and start get on a background thread, not the main thread. Creating the client at app startup no longer blocks the UI thread. (f680434)

v4.13.1

Patch Changes

• Fix a Flutter web WASM crash when initializing the agent (List<String> is not a JSArray). Convert Dart string lists with .toJS before passing them to the JS agent. (fc5e475)

Supported Native SDK Version Range

• Fingerprint iOS SDK Version Range: >= 2.17.0 and < 2.18.0
• Fingerprint Android SDK Version Range: >= 2.17.0 and < 2.18.0

v4.13.0

Minor Changes

• Add Swift Package Manager support for iOS. CocoaPods remains supported. FingerprintPro stays >= 2.17.0 < 2.18.0. (c73394c)

Supported Native SDK Version Range

• Fingerprint iOS SDK Version Range: >= 2.17.0 and < 2.18.0
• Fingerprint Android SDK Version Range: >= 2.17.0 and < 2.18.0

v4.13.0-test.0

Minor Changes

• Add Swift Package Manager support for iOS. CocoaPods remains supported. FingerprintPro stays >= 2.17.0 < 2.18.0. (c73394c)

Supported Native SDK Version Range

• Fingerprint iOS SDK Version Range: >= 2.17.0 and < 2.18.0
• Fingerprint Android SDK Version Range: >= 2.17.0 and < 2.18.0

v4.12.0

Minor Changes

• Bump Flutter SDK floor to 3.19.0.
  This is a non-breaking change, as the Dart SDK floor (3.3.0) requires at least Flutter SDK 3.19.0. (9ca1412)

Supported Native SDK Version Range

• Fingerprint iOS SDK Version Range: >= 2.17.0 and < 2.18.0
• Fingerprint Android SDK Version Range: >= 2.17.0 and < 2.18.0

v4.12.0-test.3

Patch Changes

• Restore old tag format (020568c)

Supported Native SDK Version Range

• Fingerprint iOS SDK Version Range: >= 2.17.0 and < 2.18.0
• Fingerprint Android SDK Version Range: >= 2.17.0 and < 2.18.0

fingerprintjs-pro-flutter@4.12.0-test.2

Patch Changes

• Restore tag trigger in publish workflow (c165404)

Supported Native SDK Version Range

• Fingerprint iOS SDK Version Range: >= 2.17.0 and < 2.18.0
• Fingerprint Android SDK Version Range: >= 2.17.0 and < 2.18.0

fingerprintjs-pro-flutter@4.12.0-test.1

Patch Changes

• Update publish workflow to run whenever release is published (6ad50e4)

Supported Native SDK Version Range

• Fingerprint iOS SDK Version Range: >= 2.17.0 and < 2.18.0
• Fingerprint Android SDK Version Range: >= 2.17.0 and < 2.18.0