Fingerprint logo

Build status Discord server

Fingerprint Flutter

Fingerprint is a device intelligence platform offering visitor identification and device intelligence with industry-leading accuracy. Fingerprint Flutter SDK is an easy way to integrate Fingerprint into your Flutter application. The plugin allows you to call the underlying native Fingerprint agents (Android, iOS, and Web) and identify devices.

This package replaces fpjs_pro_plugin. If you are upgrading from 4.x, see the 5.0.0 changelog.

Table of contents

Requirements

  • Flutter 3.44.0 or higher
  • Dart 3.12.0 or higher
  • Android 7.0 (API level 24+) or higher
  • Android apps on AGP 8: Kotlin Gradle plugin 2.2.20 or higher. The Android SDK is built with Kotlin 2.3, and your app's Kotlin version compiles the plugin.
  • iOS 15+/tvOS 15+, Xcode 16+, Swift 6 or higher (stable releases)

We aim to keep the Flutter compatibility policy.

Dependencies

iOS supports Swift Package Manager and CocoaPods. Flutter 3.44+ uses Swift Package Manager by default.

How to install

Add fingerprint_flutter to the pubspec.yaml file in your Flutter app:

dependencies:
  flutter:
    sdk: flutter
  ...
  fingerprint_flutter: ^5.0.0-test.0

Run flutter pub get to download and install the package.

Web platform (Optional)

To use this plugin on the web, add the bundled v4 loader <script> tag to the <head> of your HTML template inside the web/index.html file:

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

Usage

Sign up and copy the public API key from App Settings > API Keys.

1. Create a client

Create one Fingerprint client per API key and configuration. On Android and iOS, region defaults to Region.us when omitted. On web, the agent infers it from the API key. See regions.

import 'package:flutter/widgets.dart';
import 'package:fingerprint_flutter/fingerprint_flutter.dart';

late final Fingerprint client;

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  client = Fingerprint(
    apiKey: '<PUBLIC_API_KEY>',
    region: Region.eu, // or Region.us, Region.ap
  );
  runApp(const MyApp());
}

The constructor returns immediately and starts the client in the background, so create it early and reuse it. Failures surface from get.

On Android and iOS, the constructor throws FlutterError if the Flutter binding does not exist yet. Call WidgetsFlutterBinding.ensureInitialized() first, as above.

Custom endpoints

To avoid ad blockers, proxy identification through a proxy integration. Pass identification URLs as endpoints, first to last.

We recommend including the default API URL for your region as a fallback: https://api.fpjs.io (US), https://eu.api.fpjs.io (EU), https://ap.api.fpjs.io (Asia). There are no fallbacks by default.

final client = Fingerprint(
  apiKey: '<PUBLIC_API_KEY>',
  region: Region.us,
  endpoints: [
    'https://metrics.yourwebsite.com',
    'https://api.fpjs.io',
  ],
);

2. Identify visitors

get returns a FingerprintResult or throws FingerprintError. The constructor starts the client early. get waits for it to be ready and uses it.

try {
  final result = await client.get();
  print(result.visitorId);
  print(result.eventId);
  print(result.suspectScore);
  print(result.sealedResult);
  print(result.cacheHit); // web only, otherwise null
} on FingerprintError catch (error) {
  print(error.code);
  print(error.message);
  print(error.eventId);
}

  • visitorId is null when hidden (Zero Trust).

  • sealedResult is set when Sealed Results are enabled.

  • Look up the event with eventId in the Server API.

  • Known error codes are constants on FingerprintError, such as FingerprintError.clientTimeout.

Linking and tagging information

Pass information about the visitor you already have, such as account or order IDs, as linkedId and tags. See Linking and tagging information.

final result = await client.get(
  linkedId: 'user_1234',
  tags: {
    'userAction': 'login',
    'analyticsId': 'UA-5555-1111-1'
  },
);

tags is a string-keyed map of JSON values. The 16 KB limit applies.

Specifying a custom timeout

Default timeout:

final result = await client.get(timeout: const Duration(seconds: 10));

Must be at least 1 millisecond, otherwise get throws ArgumentError. The same rule applies to android.locationTimeout.

A timeout throws FingerprintError with code client_timeout.

Location data

Location is collected only when allowUseOfLocationData is true on the matching platform options.

final client = Fingerprint(
  apiKey: '<PUBLIC_API_KEY>',
  android: const AndroidOptions(
    allowUseOfLocationData: true,
    locationTimeout: Duration(seconds: 10),
  ),
  ios: const IosOptions(allowUseOfLocationData: true),
);

On Android, identification waits up to locationTimeout for a fix (default 5 seconds), then continues without location. On iOS, collection starts when the client is created, so create it at app startup for the best precision. See Android and iOS proximity detection.

Web options

WebOptions are ignored on Android and iOS. Cache is off unless cache is set.

final client = Fingerprint(
  apiKey: '<PUBLIC_API_KEY>',
  web: const WebOptions(
    storageKeyPrefix: 'fp_',
    urlHashing: WebUrlHashing(path: true, query: true),
    cache: WebCache(
      storage: WebCacheStorage.sessionStorage,
      duration: WebCacheDuration.optimizeCost, // 1 hour. aggressive is 12 hours.
      cachePrefix: 'fp_cache_', // optional
    ),
  ),
);

A custom cache duration must be a whole number of seconds, greater than zero and at most 12 hours: WebCacheDuration.custom(const Duration(hours: 2)). The JS agent checks the maximum. See the JS agent start options.

Additional Resources

Version support

SDK major version Android SDK iOS SDK JS Agent version Status End of support
v5.x (current) v4.x v4.x v4 Supported -
v4.x v2.x v2.x v3 Deprecated (security fixes only) To be decided

Support and feedback

To report problems, ask questions, or provide feedback, please use Issues. If you need private support, please email us at oss-support@fingerprint.com.

License

This project is licensed under the MIT license.

Libraries

fingerprint_flutter