react-native-fingerprint-scanner

Depending on your React Native version, use the following commands to configure the project:

For RN >= 0.60:

$ cd ios && pod install

For RN < 0.60:

$ react-native link react-native-fingerprint-scanner

You must add the following permissions to your project files to enable biometric authentication.

Android

In AndroidManifest.xml:

• API level 28+ (BiometricPrompt): <uses-permission android:name="android.permission.USE_BIOMETRIC" />
• API level 23-28 (FingerprintCompat): <uses-permission android:name="android.permission.USE_FINGERPRINT" />
• API level < 23 (Legacy Samsung/MeiZu - Deprecated in 4.0.0): <uses-permission android:name="android.permission.USE_FINGERPRINT" />

iOS

In Info.plist: Add a description for FaceID usage:

<key>NSFaceIDUsageDescription</key>
<string>$(PRODUCT_NAME) requires FaceID access to allows you quick and secure access.</string>

Install the library using npm or yarn:

$ npm install react-native-fingerprint-scanner --save

OR

$ yarn add react-native-fingerprint-scanner

For full functionality (including FaceID on Android), ensure your android/app/build.gradle uses appropriate SDK versions:

android {
    compileSdkVersion 29
    buildToolsVersion "29.0.2"
    defaultConfig {
        targetSdkVersion 29
    }
}

If using Proguard, add these rules to android/app/proguard-rules.pro (Note: Samsung and MeiZu rules are deprecated in 4.0.0):

# MeiZu Fingerprint (Deprecated in 4.0.0)
-keep class com.fingerprints.service.** { *; }
-dontwarn com.fingerprints.service.**

# Samsung Fingerprint (Deprecated in 4.0.0)
-keep class com.samsung.android.sdk.** { *; }
-dontwarn com.samsung.android.sdk.**

On Android, use authenticate() to trigger the native biometric prompt.

Options:

• title (String): Title text for the native popup.
• subTitle (String): Subtitle text for the native popup.
• description (String): Description text for the native popup.
• cancelButton (String): Text for the cancel button.
• onAttempt (Function): A callback triggered when a user attempts a scan but fails.

Returns: A Promise that resolves upon successful authentication or rejects on failure.

FingerprintScanner
  .authenticate({ title: 'Log in with Biometrics' })
  .then(() => {
    this.props.onAuthenticate();
  });

Use isSensorAvailable() to determine if the device supports biometric authentication and what type is currently available.

• Returns: A Promise<string> resolving to the biometryType.
• iOS values: 'Touch ID' or 'Face ID'.
• Android values: 'Biometrics'.
• Errors: If the check fails, the promise rejects with a FingerprintScannerError containing name, message, and biometric.

FingerprintScanner
  .isSensorAvailable()
  .then(biometryType => this.setState({ biometryType }))
  .catch(error => this.setState({ errorMessage: error.message }));

On iOS, use authenticate() to trigger the native biometric prompt.

Options:

• description (String): A message explaining to the user why authentication is being requested.
• fallbackEnabled (Boolean): If true (default), allows the user to use a fallback method like entering their device passcode.

Returns: A Promise that resolves upon successful authentication or rejects on failure.

FingerprintScanner
  .authenticate({ description: 'Scan your fingerprint on the device scanner to continue' })
  .then(() => {
    this.props.handlePopupDismissed();
    AlertIOS.alert('Authenticated successfully');
  })
  .catch((error) => {
    this.props.handlePopupDismissed();
    AlertIOS.alert(error.message);
  });

Call release() to stop the fingerprint scanner listener, clear the internal state cache in native code, and cancel any visible native prompts. It is recommended to call this during the component unmount lifecycle to prevent memory leaks or hanging prompts.

componentWillUnmount() {
  FingerprintScanner.release();
}

Ensure your library version matches your environment:

• Gradle < 3: Use version <= 2.5.0.
• RN >= 0.57 and/or Gradle >= 3: Use version >= 2.6.0.
• RN >= 0.60: Use version >= 3.0.0.
• Android native Face Unlock: Must use version >= 4.0.0.