Fingerprint Pro Flutter

Official Flutter plugin for 100% accurate device identification, created for FingerprintJS Pro.

This plugin can be used in a Flutter application to call the native Fingerprint Pro libraries and identify devices.

Fingerprint Pro is a professional visitor identification service that processes all information server-side and transmits it securely to your servers using server-to-server APIs.

Retrieve an accurate, sticky and stable Fingerprint Pro visitor identifier in an Android or an iOS app. This library communicates with the Fingerprint Pro API and requires an API key.

Native libraries used under the hood:

Fingerprint Pro iOS - requires Android 5.0 (API level 21+) or higher
Fingerprint Pro Android - requires iOS/tvOS 12, Swift 5.7 or higher

Quick start

1. Add `fpjs_pro_plugin` to the pubspec.yaml in your Flutter app

dependencies:
  flutter:
    sdk: flutter
  ...
  fpjs_pro_plugin: ^2.0.1

Run pub get to download and install the package.

2. Provide a configuration to the plugin

import 'package:fpjs_pro_plugin/fpjs_pro_plugin.dart';
// ...

// Initialization
class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    doInit();
  }
  
  void doInit() async {
    await FpjsProPlugin.initFpjs(
      '<apiKey>' // insert your actual API key here
    );
  }
  // ...
}

You can also configure region and endpoint in the initFpjs method, like below. For the web platform, you can use an additional scriptUrlPattern property to specify a custom URL for loading the JavaScript agent. This is required for proxy integrations.

void doInit() async {
  await FpjsProPlugin.initFpjs(
    '<apiKey>',
    endpoint: 'https://subdomain.domain.com',
    region: Region.eu, // or Region.ap, Region.us
    scriptUrlPattern: 'https://your.domain/fp_js/script_path?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>'
  );
}

3. Use the plugin in your application code to identify a visitor

3.1 Use the `getVisitorId` method if you need a `visitorId` only:

import 'package:fpjs_pro_plugin/fpjs_pro_plugin.dart';
// ...

// Initialization
class _MyAppState extends State<MyApp> {
  // ...
  // Usage
  void identify() async {
    try {
      visitorId = await FpjsProPlugin.getVisitorId() ?? 'Unknown';
      // use the visitor id
    } on FingerprintProError catch (e) {
      // process an error somehow
      // check lib/error.dart to get more info about error types
    }
  }
}

3.2 Use `getVisitorData` to get extended result

import 'package:fpjs_pro_plugin/fpjs_pro_plugin.dart';
// ...

// Initialization
class _MyAppState extends State<MyApp> {
  // ...
  // Usage
  void identify() async {
    try {
      deviceData = await FpjsProPlugin.getVisitorData();
      // use the visitor id
    } on FingerprintProError catch (e) {
      // process an error somehow
      // check lib/error.dart to get more info about error types
    }
  }
}

By default getVisitorData() will return a short response with the FingerprintJSProResponse type. Provide extendedResponseFormat=true to the initFpjs function to get extended result of FingerprintJSProExtendedResponse type.

void doInit() async {
  await FpjsProPlugin.initFpjs('<apiKey>', extendedResponseFormat: true);
}

3.3 Web platform configuration

Add script tag with js agent loader inside head tag in your html template to use fpjs_pro_plugin on web platform.

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

4. Use `linkedId` and `tags` to label identification event with additional data

void doIdentification() async {
  const tags = {
    'foo': 'bar',
    'numberField': 1234,
    'objectField': {
      'booleanSubfield': true,
      'arraySubfield': [1, 2, 3]
    },
    'booleanField': false
  };
  const linkedId = 'custom_linked_id';

  visitorId = await FpjsProPlugin.getVisitorId(linkedId: linkedId, tags: tags);
  deviceData = await FpjsProPlugin.getVisitorData(linkedId: linkedId, tags: tags);
}

Additional Resources

License

This library is MIT licensed.

Wilson0212tw/fingerprintjs-pro-flutter