Announcing the Capacitor Biometrics Plugin¶

Today we are excited to announce our Capacitor Biometrics plugin. It lets you request biometric authentication (Face ID, fingerprint) and device credentials (PIN, pattern, password) on Android and iOS through a single API. The plugin is available to all Capawesome Insiders.

Let's take a quick look at the API and how to use the plugin in your Capacitor app.

Bonus: Video Tutorial and Demo App¶

We created a step-by-step video tutorial that walks through installing the plugin, configuring iOS Face ID permissions, organizing your biometrics logic in a small helper module, triggering authentication from the app UI, and handling success and error states.

Capacitor Biometrics Demo App — A minimal, framework-agnostic demo (vanilla JavaScript and Capacitor) with a complete biometric authentication flow using Face ID or fingerprint.

Installation¶

To install the Capacitor Biometrics plugin, please refer to the Installation section in the plugin documentation.

Usage¶

Let's take a look at the basic usage of the plugin. You can find the complete API reference in the API section of the documentation. The plugin supports both biometric authentication and device credential authentication. Biometric authentication uses the device's biometric capabilities, such as fingerprint or face recognition, while device credential authentication uses the device's lock screen PIN, pattern, or password.

Biometric Authentication¶

The most important method of the plugin is authenticate(), which allows you to request biometric authentication from the user. You can customize the authentication prompt with various options, such as the title, subtitle, and button text:

import { Biometrics, ErrorCode } from '@capawesome-team/capacitor-biometrics';


const authenticate = async () => {
  try {
    await Biometrics.authenticate({
      title: 'Authentication Required',
      subtitle: 'Please authenticate to continue',
      cancelButtonText: 'Cancel',
      iosFallbackButtonText: 'Use Passcode',
    });
  } catch (error) {
    if (error.code === ErrorCode.USER_CANCELED) {
      console.log('User canceled the authentication.');
    } else if (error.code === ErrorCode.NOT_ENROLLED) {
      console.log('No biometric authentication enrolled.');
    } else if (error.code === ErrorCode.NOT_AVAILABLE) {
      console.log('Biometric authentication not available.');
    } else {
      console.log('Another error occurred:', error);
    }
  }
};

The method returns a promise that resolves when the user successfully authenticates or rejects with an error if the user cancels the authentication or if there is an error during the authentication process. You can handle the error using the catch block, where you can check the error code to determine the reason for the failure. The error codes are defined in the ErrorCode enum.

In most cases, you will also want to use the isEnrolled() method to check whether the device supports biometric authentication at all and whether the user has set it up:

import { Biometrics } from '@capawesome-team/capacitor-biometrics';

const isEnrolled = async () => {
  const result = await Biometrics.isEnrolled();
  if (result.isEnrolled) {
    console.log('Biometric authentication is enrolled.');
  } else {
    console.log('No biometric authentication enrolled.');
  }
};

It's recommended to call this method before calling authenticate() to ensure that the user has set up biometric authentication on their device.

Device Credential Authentication¶

In addition to biometric authentication, the plugin also supports device credential authentication using the authenticate() method. For this, you need to set the allowDeviceCredential option to true when calling the method:

import { Biometrics } from '@capawesome-team/capacitor-biometrics';

const authenticate = async () => {
    await Biometrics.authenticate({
      allowDeviceCredential: true,
    });
};

This will show the device's lock screen PIN, pattern, or password prompt if biometric authentication is not available or not enrolled. You can also use the hasDeviceCredential() method to check whether the device supports device credential authentication:

import { Biometrics } from '@capawesome-team/capacitor-biometrics';

const hasDeviceCredential = async () => {
  const { hasDeviceCredential } = await Biometrics.hasDeviceCredential();
  return hasDeviceCredential;
};

Conclusion¶

We hope you find the Capacitor Biometrics plugin useful. Check the API Reference for the full plugin documentation.

Related reading:

Missing a feature?

Create a feature request in our GitHub repository.