feat: add Proximity Detection init options

ilfa · ilfa · commit d8cc7b304b5d · 2025-09-18T18:55:06.000+02:00
`allowUseOfLocationData` - to allow collect location data
`locationTimeoutMillis` - to configure the location retrieval timeout on Android
diff --git a/README.md b/README.md
@@ -210,6 +210,29 @@ void identify() async {
 }
 ```
 
+### Proximity Detection
+
+Proximity detection is a complementary, location-based signal available only on mobile platforms.
+More info you can find in [Android SDK documentation](https://dev.fingerprint.com/docs/native-android-integration#/proximity-detection-for-android-devices) or in
+[iOS SDK documentation](https://dev.fingerprint.com/docs/ios-sdk#/using-location-data-for-proximity-detection).
+
+The Fingerprint SDK will only collect location data if the `allowUseOfLocationData` option is set to `true`.
+
+```dart
+void doInit() async {
+  await FpjsProPlugin.initFpjs('<PUBLIC_API_KEY>', allowUseOfLocationData: true);
+}
+```
+
+For Android platform it's possible to configure the location retrieval timeout by setting the `locationTimeoutMillis` option to a desired value. By default, it's set to 5 seconds.
+
+```dart
+void doInit() async {
+  await FpjsProPlugin.initFpjs('<PUBLIC_API_KEY>', allowUseOfLocationData: true,
+   locationTimeoutMillis: 10000);
+}
+```
+
 ## Additional Resources
 - [Fingerprint Pro documentation](https://dev.fingerprint.com/docs)
 - [Server API](https://dev.fingerprint.com/reference/server-api)
diff --git a/android/src/main/kotlin/com/fingerprintjs/flutter/fpjs_pro/fpjs_pro_plugin/FpjsProPlugin.kt b/android/src/main/kotlin/com/fingerprintjs/flutter/fpjs_pro/fpjs_pro_plugin/FpjsProPlugin.kt
@@ -68,7 +68,20 @@ class FpjsProPlugin: FlutterPlugin, MethodCallHandler {
           val extendedResponseFormat = call.argument<Boolean>("extendedResponseFormat") ?: false
           val pluginVersion = call.argument<String>("pluginVersion") ?: "unknown"
 
-          initFpjs(token, region, endpoint, endpointFallbacks, extendedResponseFormat, pluginVersion)
+          val allowUseOfLocationData = call.argument<Boolean>("allowUseOfLocationData") ?: false
+
+          val locationTimeoutMillis = call.argument<Int>("locationTimeoutMillis") ?: 5000
+
+          initFpjs(
+              token,
+              region,
+              endpoint,
+              endpointFallbacks,
+              extendedResponseFormat,
+              pluginVersion,
+              allowUseOfLocationData,
+              locationTimeoutMillis.toLong()
+          )
           result.success("Successfully initialized FingerprintJS Pro Client")
         }
       GET_VISITOR_ID -> {
@@ -101,15 +114,26 @@ class FpjsProPlugin: FlutterPlugin, MethodCallHandler {
     channel.setMethodCallHandler(null)
   }
 
-  private fun initFpjs(apiToken: String, region: Configuration.Region?, endpoint: String?, endpointFallbacks:List<String>?, extendedResponseFormat: Boolean, pluginVersion: String) {
+    private fun initFpjs(
+        apiToken: String,
+        region: Configuration.Region?,
+        endpoint: String?,
+        endpointFallbacks: List<String>?,
+        extendedResponseFormat: Boolean,
+        pluginVersion: String,
+        allowUseOfLocationData: Boolean,
+        locationTimeoutMillis: Long
+    ) {
     val factory = FingerprintJSFactory(applicationContext)
     val configuration = Configuration(
       apiToken,
       region ?: Configuration.Region.US,
       endpoint ?: region?.endpointUrl ?: Configuration.Region.US.endpointUrl,
       extendedResponseFormat,
       endpointFallbacks ?: emptyList(),
-      listOf(Pair("fingerprint-pro-flutter", pluginVersion))
+      listOf(Pair("fingerprint-pro-flutter", pluginVersion)),
+      allowUseOfLocationData,
+      locationTimeoutMillis,
     )
 
     fpjsClient = factory.createInstance(configuration)
diff --git a/example/android/app/src/main/AndroidManifest.xml b/example/android/app/src/main/AndroidManifest.xml
@@ -1,5 +1,7 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="com.fingerprintjs.flutter.fpjs_pro.fpjs_pro_plugin_example">
+    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
+    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <application
         android:label="fpjs_pro_plugin_example"
         android:name="${applicationName}"
diff --git a/example/ios/Podfile.lock b/example/ios/Podfile.lock
@@ -4,10 +4,14 @@ PODS:
   - fpjs_pro_plugin (3.3.2):
     - FingerprintPro (< 2.11.0, >= 2.10.0)
     - Flutter
+  - geolocator_apple (1.2.0):
+    - Flutter
+    - FlutterMacOS
 
 DEPENDENCIES:
   - Flutter (from `Flutter`)
   - fpjs_pro_plugin (from `.symlinks/plugins/fpjs_pro_plugin/ios`)
+  - geolocator_apple (from `.symlinks/plugins/geolocator_apple/darwin`)
 
 SPEC REPOS:
   trunk:
@@ -18,11 +22,14 @@ EXTERNAL SOURCES:
     :path: Flutter
   fpjs_pro_plugin:
     :path: ".symlinks/plugins/fpjs_pro_plugin/ios"
+  geolocator_apple:
+    :path: ".symlinks/plugins/geolocator_apple/darwin"
 
 SPEC CHECKSUMS:
   FingerprintPro: f72cfc225731a66d53dd8be3545fbbbd4f4c4777
   Flutter: cabc95a1d2626b1b06e7179b784ebcf0c0cde467
   fpjs_pro_plugin: 17d12dddc60fe3d11011e9e98904bc8b30d48a47
+  geolocator_apple: ab36aa0e8b7d7a2d7639b3b4e48308394e8cef5e
 
 PODFILE CHECKSUM: 2f1a6d2470f392e010cfe7ae5f9f694d8487db82
 
diff --git a/example/ios/Runner/Info.plist b/example/ios/Runner/Info.plist
@@ -2,6 +2,8 @@
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
+	<key>CADisableMinimumFrameDurationOnPhone</key>
+	<true/>
 	<key>CFBundleDevelopmentRegion</key>
 	<string>$(DEVELOPMENT_LANGUAGE)</string>
 	<key>CFBundleDisplayName</key>
@@ -24,6 +26,8 @@
 	<string>$(FLUTTER_BUILD_NUMBER)</string>
 	<key>LSRequiresIPhoneOS</key>
 	<true/>
+	<key>UIApplicationSupportsIndirectInputEvents</key>
+	<true/>
 	<key>UILaunchStoryboardName</key>
 	<string>LaunchScreen</string>
 	<key>UIMainStoryboardFile</key>
@@ -43,9 +47,7 @@
 	</array>
 	<key>UIViewControllerBasedStatusBarAppearance</key>
 	<false/>
-	<key>CADisableMinimumFrameDurationOnPhone</key>
-	<true/>
-	<key>UIApplicationSupportsIndirectInputEvents</key>
-	<true/>
+	<key>NSLocationWhenInUseUsageDescription</key>
+	<string>Activate location for Proximity Detection</string>
 </dict>
 </plist>
diff --git a/example/lib/main.dart b/example/lib/main.dart
@@ -6,6 +6,7 @@ import 'package:flutter/material.dart';
 import 'package:fpjs_pro_plugin/error.dart';
 import 'package:fpjs_pro_plugin/fpjs_pro_plugin.dart';
 import 'package:fpjs_pro_plugin/region.dart';
+import 'package:geolocator/geolocator.dart';
 
 const tags = {
   'a': 'a',
@@ -18,7 +19,7 @@ const tags = {
 };
 
 Future main() async {
-  // Explicitly define which files to load to avoid 
+  // Explicitly define which files to load to avoid
   // console warnings about not finding other possible .env files
   await dotenv.load(fileNames: ['.env', '.env.local']);
   runApp(const MyApp());
@@ -69,6 +70,8 @@ class _MyAppState extends State<MyApp> {
           endpoint: _endpoint,
           scriptUrlPattern: _scriptUrlPattern,
           region: _parseRegion(_region),
+          allowUseOfLocationData: true,
+          locationTimeoutMillis: 6000,
           extendedResponseFormat: true);
     } catch (error) {
       // print('Failed to initialize Fingerprint agent: $error');
@@ -78,10 +81,32 @@ class _MyAppState extends State<MyApp> {
     }
   }
 
+  Future<void> requestPermission() async {
+    LocationPermission permission = await Geolocator.checkPermission();
+    if (permission == LocationPermission.denied) {
+      permission = await Geolocator.requestPermission();
+      if (permission == LocationPermission.denied) {
+        // Permissions are denied, next time you could try
+        // requesting permissions again (this is also where
+        // Android's shouldShowRequestPermissionRationale
+        // returned true. According to Android guidelines
+        // your App should show an explanatory UI now.
+        return Future.error('Location permissions are denied');
+      }
+    }
+
+    if (permission == LocationPermission.deniedForever) {
+      // Permissions are denied forever, handle appropriately.
+      return Future.error(
+          'Location permissions are permanently denied, we cannot request permissions.');
+    }
+  }
+
   /// The native FingerprintJS libraries expose a method called `getVisitorId`
   /// to stay consistent with the original Javascript library used for browser identification.
   /// However in the mobile application context a more accurate name would be something like `getDeviceId`.
   Future<void> _getDeviceId() async {
+    await requestPermission();
     String deviceId;
     try {
       deviceId = await FpjsProPlugin.getVisitorId(
@@ -102,6 +127,7 @@ class _MyAppState extends State<MyApp> {
   }
 
   Future<String> _getDeviceData() async {
+    await requestPermission();
     String identificationInfo;
     try {
       const encoder = JsonEncoder.withIndent('    ');
@@ -121,6 +147,7 @@ class _MyAppState extends State<MyApp> {
   }
 
   Future<void> _runChecks() async {
+    await requestPermission();
     setState(() {
       _checksResult = 'Running';
     });
diff --git a/example/pubspec.lock b/example/pubspec.lock
@@ -41,6 +41,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.19.1"
+  crypto:
+    dependency: transitive
+    description:
+      name: crypto
+      sha256: "1e445881f28f22d6140f181e07737b22f1e099a5e1ff94b0af2f9e4a463f4855"
+      url: "https://pub.dev"
+    source: hosted
+    version: "3.0.6"
   cupertino_icons:
     dependency: "direct main"
     description:
@@ -65,6 +73,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.3.3"
+  fixnum:
+    dependency: transitive
+    description:
+      name: fixnum
+      sha256: b6dc7065e46c974bc7c5f143080a6764ec7a4be6da1285ececdc37be96de53be
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.1.1"
   flutter:
     dependency: "direct main"
     description: flutter
@@ -95,6 +111,54 @@ packages:
       relative: true
     source: path
     version: "4.2.0"
+  geolocator:
+    dependency: "direct main"
+    description:
+      name: geolocator
+      sha256: f62bcd90459e63210bbf9c35deb6a51c521f992a78de19a1fe5c11704f9530e2
+      url: "https://pub.dev"
+    source: hosted
+    version: "13.0.4"
+  geolocator_android:
+    dependency: transitive
+    description:
+      name: geolocator_android
+      sha256: fcb1760a50d7500deca37c9a666785c047139b5f9ee15aa5469fae7dbbe3170d
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.6.2"
+  geolocator_apple:
+    dependency: transitive
+    description:
+      name: geolocator_apple
+      sha256: dbdd8789d5aaf14cf69f74d4925ad1336b4433a6efdf2fce91e8955dc921bf22
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.3.13"
+  geolocator_platform_interface:
+    dependency: transitive
+    description:
+      name: geolocator_platform_interface
+      sha256: "30cb64f0b9adcc0fb36f628b4ebf4f731a2961a0ebd849f4b56200205056fe67"
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.2.6"
+  geolocator_web:
+    dependency: transitive
+    description:
+      name: geolocator_web
+      sha256: b1ae9bdfd90f861fde8fd4f209c37b953d65e92823cb73c7dee1fa021b06f172
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.1.3"
+  geolocator_windows:
+    dependency: transitive
+    description:
+      name: geolocator_windows
+      sha256: "175435404d20278ffd220de83c2ca293b73db95eafbdc8131fe8609be1421eb6"
+      url: "https://pub.dev"
+    source: hosted
+    version: "0.2.5"
   leak_tracker:
     dependency: transitive
     description:
@@ -159,6 +223,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.9.1"
+  plugin_platform_interface:
+    dependency: transitive
+    description:
+      name: plugin_platform_interface
+      sha256: "4820fbfdb9478b1ebae27888254d445073732dae3d6ea81f0b7e06d5dedc3f02"
+      url: "https://pub.dev"
+    source: hosted
+    version: "2.1.8"
   sky_engine:
     dependency: transitive
     description: flutter
@@ -172,6 +244,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.10.0"
+  sprintf:
+    dependency: transitive
+    description:
+      name: sprintf
+      sha256: "1fc9ffe69d4df602376b52949af107d8f5703b77cda567c4d7d86a0693120f23"
+      url: "https://pub.dev"
+    source: hosted
+    version: "7.0.0"
   stack_trace:
     dependency: transitive
     description:
@@ -212,6 +292,22 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "0.7.6"
+  typed_data:
+    dependency: transitive
+    description:
+      name: typed_data
+      sha256: f9049c039ebfeb4cf7a7104a675823cd72dba8297f264b6637062516699fa006
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.4.0"
+  uuid:
+    dependency: transitive
+    description:
+      name: uuid
+      sha256: a5be9ef6618a7ac1e964353ef476418026db906c4facdedaa299b7a2e71690ff
+      url: "https://pub.dev"
+    source: hosted
+    version: "4.5.1"
   vector_math:
     dependency: transitive
     description:
@@ -228,6 +324,14 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "14.3.0"
+  web:
+    dependency: transitive
+    description:
+      name: web
+      sha256: "868d88a33d8a87b18ffc05f9f030ba328ffefba92d6c127917a2ba740f9cfe4a"
+      url: "https://pub.dev"
+    source: hosted
+    version: "1.1.1"
 sdks:
   dart: ">=3.8.0-0 <4.0.0"
   flutter: ">=3.18.0-18.0.pre.54"
diff --git a/example/pubspec.yaml b/example/pubspec.yaml
@@ -19,6 +19,7 @@ dependencies:
   flutter:
     sdk: flutter
   env_flutter: ^0.1.4
+  geolocator: ^13.0.4
 
   fpjs_pro_plugin:
     # When depending on this package from a real application you should use:
diff --git a/ios/Classes/SwiftFpjsProPlugin.swift b/ios/Classes/SwiftFpjsProPlugin.swift
diff --git a/lib/fpjs_pro_plugin.dart b/lib/fpjs_pro_plugin.dart
