uonick/capacitor-native-biometric

Capacitor Native Biometric

Use biometrics confirm device owner presence or authenticate users. A couple of methods are provided to handle user credentials. These are securely stored using Keychain (iOS) and Keystore (Android).

Installation (Only supports Capacitor 5)

• npm i @capgo/capacitor-native-biometric

Usage

import { NativeBiometric } from "@capgo/capacitor-native-biometric";

async performBiometricVerificatin(){
  const result = await NativeBiometric.isAvailable();

  if(!result.isAvailable) return;

  const isFaceID = result.biometryType == BiometryType.FACE_ID;

  const verified = await NativeBiometric.verifyIdentity({
    reason: "For easy log in",
    title: "Log in",
    subtitle: "Maybe add subtitle here?",
    description: "Maybe a description too?",
  })
    .then(() => true)
    .catch(() => false);

  if(!verified) return;

  const credentials = await NativeBiometric.getCredentials({
    server: "www.example.com",
  });
}

// Save user's credentials
NativeBiometric.setCredentials({
  username: "username",
  password: "password",
  server: "www.example.com",
}).then();

// Delete user's credentials
NativeBiometric.deleteCredentials({
  server: "www.example.com",
}).then();

Biometric Auth Errors

This is a plugin specific list of error codes that can be thrown on verifyIdentity failure, or set as a part of isAvailable. It consolidates Android and iOS specific Authentication Error codes into one combined error list.

Code	Description	Platform
0	Unknown Error	Android, iOS
1	Biometrics Unavailable	Android, iOS
2	User Lockout	Android, iOS
3	Biometrics Not Enrolled	Android, iOS
4	User Temporary Lockout	Android (Lockout for 30sec)
10	Authentication Failed	Android, iOS
11	App Cancel	iOS
12	Invalid Context	iOS
13	Not Interactive	iOS
14	Passcode Not Set	Android, iOS
15	System Cancel	Android, iOS
16	User Cancel	Android, iOS
17	User Fallback	Android, iOS

• isAvailable(...)
• verifyIdentity(...)
• getCredentials(...)
• setCredentials(...)
• deleteCredentials(...)
• Interfaces
• Enums

isAvailable(...)

isAvailable(options?: IsAvailableOptions | undefined) => any

Checks if biometric authentication hardware is available.

Param	Type
options	IsAvailableOptions

Returns: any

Since: 1.0.0

---

verifyIdentity(...)

verifyIdentity(options?: BiometricOptions | undefined) => any

Prompts the user to authenticate with biometrics.

Param	Type
options	BiometricOptions

Returns: any

Since: 1.0.0

---

getCredentials(...)

getCredentials(options: GetCredentialOptions) => any

Gets the stored credentials for a given server.

Param	Type
options	GetCredentialOptions

Returns: any

Since: 1.0.0

---

setCredentials(...)

setCredentials(options: SetCredentialOptions) => any

Stores the given credentials for a given server.

Param	Type
options	SetCredentialOptions

Returns: any

Since: 1.0.0

---

deleteCredentials(...)

deleteCredentials(options: DeleteCredentialOptions) => any

Deletes the stored credentials for a given server.

Param	Type
options	DeleteCredentialOptions

Returns: any

Since: 1.0.0

---

Interfaces

IsAvailableOptions

Prop	Type	Description
useFallback	boolean	Specifies if should fallback to passcode authentication if biometric authentication is not available.

AvailableResult

Prop	Type
isAvailable	boolean
biometryType	BiometryType
errorCode	number

BiometricOptions

Prop	Type	Description	Default
reason	string
title	string
subtitle	string
description	string
negativeButtonText	string
useFallback	boolean	Specifies if should fallback to passcode authentication if biometric authentication fails.
fallbackTitle	string	Only for iOS. Set the text for the fallback button in the authentication dialog. If this property is not specified, the default text is set by the system.
maxAttempts	number	Only for Android. Set a maximum number of attempts for biometric authentication. The maximum allowed by android is 5.	1

GetCredentialOptions

Prop	Type
server	string

Credentials

Prop	Type
username	string
password	string

SetCredentialOptions

Prop	Type
username	string
password	string
server	string

DeleteCredentialOptions

Prop	Type
server	string

Enums

BiometryType

Members	Value
NONE	0
TOUCH_ID	1
FACE_ID	2
FINGERPRINT	3
FACE_AUTHENTICATION	4
IRIS_AUTHENTICATION	5
MULTIPLE	6

## Face ID (iOS)

To use FaceID Make sure to provide a value for NSFaceIDUsageDescription, otherwise your app may crash on iOS devices with FaceID.

This value is just the reason for using FaceID. You can add something like the following example to App/info.plist:

<key>NSFaceIDUsageDescription</key>
<string>For an easier and faster log in.</string>

Biometric (Android)

To use android's BiometricPrompt api you must add the following permission to your AndroidManifest.xml:

<uses-permission android:name="android.permission.USE_BIOMETRIC">

And register the plugin by adding it to you MainActivity's onCreate (Not needed for Capacitor 3):

import ee.forgr.biometric.NativeBiometric;

public class MainActivity extends BridgeActivity {
  @Override
  public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // Initializes the Bridge
    this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{
      // Additional plugins you've installed go here
      // Ex: add(TotallyAwesomePlugin.class);
      add(NativeBiometric.class);
    }});
  }
}

Contributors

Jonthia One Click Web Studio Brian Weasner Mohamed Diarra

Want to Contribute?

Learn about contributing HERE

Notes

Hasn't been tested on Android API level 22 or lower.