DOCSEARCHbyAlgolia
Submit Docs

cordova-plugin-fingerprint-aio

repository·master·Indexed 43 days ago

https://github.com/niklasmerz/cordova-plugin-fingerprint-aio

Cordova plugin providing a unified interface for biometric authentication (Fingerprint, FaceID) on Android and iOS. Version 6.0.1 supports simple authentication via Fingerprint.show() and advanced security features in version 4.0+ to encrypt and store secrets using Fingerprint.registerBiometricSecret() and Fingerprint.loadBiometricSecret().

Tokens
1.9K
Snippets
6
Records
7
Agent score
6%

What's inside cordova-plugin-fingerprint-aio

  1. Register and load biometric secrets

    master

    Version 4.0+ allows you to encrypt and save a secret behind the biometric prompt. This provides true security by ensuring the secret is only accessible after successful biometric authentication.

    Register a secret

    Use Fingerprint.registerBiometricSecret() to save a string. The secret must match the regex [a-zA-Z0-9\-]+.

    Load a secret

    Use Fingerprint.loadBiometricSecret() to retrieve the previously saved secret after a successful biometric prompt.

    // Registering a secret
Fingerprint.registerBiometricSecret({
      description: "Some biometric description",
      secret: "my-super-secret",
      invalidateOnEnrollment: true,
      disableBackup: true,
    }, successCallback, errorCallback);

// Loading a secret
Fingerprint.loadBiometricSecret({
      description: "Some biometric description",
      disableBackup: true,
    }, successCallback, errorCallback);

  2. Install cordova-plugin-fingerprint-aio

    master

    Install the plugin via NPM using the Cordova CLI. You can also specify a FACEID_USAGE_DESCRIPTION for iOS FaceID prompts during installation.

    To use the latest release candidate for testing, use the @rc tag.

    # Standard installation
cordova plugin add cordova-plugin-fingerprint-aio --save

# Installation with FaceID description for iOS
cordova plugin add cordova-plugin-fingerprint-aio --variable FACEID_USAGE_DESCRIPTION="Login now...."

# Install release candidate
cordova plugin add cordova-plugin-fingerprint-aio@rc

  3. Show authentication dialogue

    master

    Trigger a biometric authentication prompt using Fingerprint.show(). This is used for simple authentication without saving secrets.

    Fingerprint.show({
      description: "Some biometric description"
    }, successCallback, errorCallback);

function successCallback(){
  alert("Authentication successful");
}

function errorCallback(error){
  alert("Authentication invalid " + error.message);
}

  4. Check if fingerprint authentication is available

    master

    Use Fingerprint.isAvailable() to determine if the device supports biometric authentication.

    Return Values:

    • iPhone X: returns 'face'
    • Other iOS devices: returns 'finger'
    • Android P+: returns 'biometric'
    • Other Android devices: returns 'finger'
    Fingerprint.isAvailable(isAvailableSuccess, isAvailableError, optionalParams);

function isAvailableSuccess(result) {
  /* result: 'face', 'finger', or 'biometric' */
  alert("Fingerprint available");
}

function isAvailableError(error) {
  // error is an object with error.message
  alert(error.message);
}

  5. Configure authentication dialogue options

    master

    Both Fingerprint.show(), registerBiometricSecret(), and loadBiometricSecret() accept an options object to customize the UI and behavior.

    Common Options:

    • title: Title in dialogue. Default: <APP_NAME> Biometric Sign On.
    • subtitle: Subtitle in dialogue. Default: null.
    • description: Description in dialogue. iOS requires this (defaults to "Authenticate"). Android defaults to null.
    • disableBackup: If true, removes the fallback option (e.g., PIN/Passcode). Default: false. Note: Always disabled on Android.
    • fallbackButtonTitle: Title of fallback button. Defaults to "Cancel" if disableBackup is true. If false, iOS uses "Use PIN" and Android uses "Use Backup".
    • cancelButtonTitle: Title for the cancel button on Android.
    • confirmationRequired (Android only): If false, user confirmation is NOT required after authentication. Default: true.

  6. Reference: Biometric Error Codes

    master

    The following constants represent the error codes returned by the plugin when authentication fails or is unavailable.

    BIOMETRIC_UNKNOWN_ERROR = -100
BIOMETRIC_UNAVAILABLE = -101
BIOMETRIC_AUTHENTICATION_FAILED = -102
BIOMETRIC_SDK_NOT_SUPPORTED = -103
BIOMETRIC_HARDWARE_NOT_SUPPORTED = -104
BIOMETRIC_PERMISSION_NOT_GRANTED = -105
BIOMETRIC_NOT_ENROLLED = -106
BIOMETRIC_INTERNAL_PLUGIN_ERROR = -107
BIOMETRIC_DISMISSED = -108
BIOMETRIC_PIN_OR_PATTERN_DISMISSED = -109
BIOMETRIC_SCREEN_GUARD_UNSECURED = -110
BIOMETRIC_LOCKED_OUT = -111
BIOMETRIC_LOCKED_OUT_PERMANENT = -112
BIOMETRIC_SECRET_NOT_FOUND = -113

  7. Configure the Android biometric authentication prompt

    master

    When using the plugin on Android, you can customize the appearance and behavior of the biometric authentication dialog by passing an options object. These options are parsed into a PromptInfo object on the native side.

    Available configuration keys:

    • title: The main title of the dialog. If not provided, it defaults to [Application Label] Biometric Sign On.
    • subtitle: A subtitle displayed below the title.
    • description: A detailed description of the authentication request.
    • fallbackButtonTitle: The text for the fallback button (e.g., for device credentials). Defaults to Use backup.
    • cancelButtonTitle: The text for the cancel button. Defaults to Cancel.
    • confirmationRequired: A boolean indicating if a confirmation step is required. Defaults to true.
    • invalidateOnEnrollment: A boolean that, if true, invalidates the biometric credentials if new ones are enrolled on the device. Defaults to false.
    • secret: A string used to associate a secret with the authentication event.
    • disableBackup: A boolean that, if true, disables the use of device credentials as a fallback (Note: this is mapped to isDeviceCredentialAllowed being false).
    {
  "title": "Verify Identity",
  "subtitle": "Please scan your fingerprint",
  "description": "Use your biometric sensor to access your account.",
  "fallbackButtonTitle": "Use PIN",
  "cancelButtonTitle": "Go Back",
  "confirmationRequired": true,
  "invalidateOnEnrollment": true,
  "secret": "my_secure_token"
}