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).
npm i @capgo/capacitor-native-biometric
import { NativeBiometric, BiometryType } from "@capgo/capacitor-native-biometric";
async performBiometricVerification(){
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();
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(options?: IsAvailableOptions | undefined) => any
Checks if biometric authentication hardware is available.
Param | Type |
---|---|
options |
IsAvailableOptions |
Returns: any
Since: 1.0.0
verifyIdentity(options?: BiometricOptions | undefined) => any
Prompts the user to authenticate with biometrics.
Param | Type |
---|---|
options |
BiometricOptions |
Returns: any
Since: 1.0.0
getCredentials(options: GetCredentialOptions) => any
Gets the stored credentials for a given server.
Param | Type |
---|---|
options |
GetCredentialOptions |
Returns: any
Since: 1.0.0
setCredentials(options: SetCredentialOptions) => any
Stores the given credentials for a given server.
Param | Type |
---|---|
options |
SetCredentialOptions |
Returns: any
Since: 1.0.0
deleteCredentials(options: DeleteCredentialOptions) => any
Deletes the stored credentials for a given server.
Param | Type |
---|---|
options |
DeleteCredentialOptions |
Returns: any
Since: 1.0.0
Prop | Type | Description |
---|---|---|
useFallback |
boolean |
Specifies if should fallback to passcode authentication if biometric authentication is not available. |
Prop | Type |
---|---|
isAvailable |
boolean |
biometryType |
BiometryType |
errorCode |
number |
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 |
Prop | Type |
---|---|
server |
string |
Prop | Type |
---|---|
username |
string |
password |
string |
Prop | Type |
---|---|
username |
string |
password |
string |
server |
string |
Prop | Type |
---|---|
server |
string |
Members | Value |
---|---|
NONE |
0 |
TOUCH_ID |
1 |
FACE_ID |
2 |
FINGERPRINT |
3 |
FACE_AUTHENTICATION |
4 |
IRIS_AUTHENTICATION |
5 |
MULTIPLE |
6 |
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>
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);
}});
}
}
Jonthia QliQ.dev Brian Weasner Mohamed Diarra
Learn about contributing HERE
Hasn't been tested on Android API level 22 or lower.
| -------------------------- | ------------------------- | | 0 | Erreur inconnue | Android, iOS | | 1 | Biométrie indisponible | Android, iOS | | 2 | Verrouillage de l'utilisateur | Android, iOS | | 3 | Biométrie non enregistrée | Android, iOS | | 4 | Verrouillage temporaire de l'utilisateur | Android (Verrouillage pour 30sec) | | 10 | Échec de l'authentification| Android, iOS | | 11 | Annulation de l'application | iOS | | 12 | Contexte invalide | iOS | | 13 | Non interactif | iOS | | 14 | Code d'accès non défini | Android, iOS | | 15 | Annulation système | Android, iOS | | 16 | Annulation de l'utilisateur | Android, iOS | | 17 | Récupération de l'utilisateur | Android, iOS |
Vous pouvez gérer ces codes d'erreur en fonction des exigences de votre application.
C'est tout ! Vous avez appris avec succès comment utiliser le package @capgo/capacitor-native-biometric
pour intégrer l'authentification biométrique dans vos applications Capacitor.