Announcing the Capacitor Biometrics Plugin

Today we are excited to announce our brand new Capacitor Biometrics plugin. This plugin allows you to request biometric authentication, such as using face recognition or fingerprint recognition, on the device. The plugin provides cross-platform support for Android and iOS and is now available to all Capawesome Insiders.

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

Installation

See Getting started with Insiders and follow the instructions to install the plugin. After that, follow the platform-specific instructions in the sections Android and iOS.

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 are as excited as we are about the new Capacitor Biometrics plugin. Be sure to check out the API Reference to see what else you can do with this plugin. If you are missing any features, just create a feature request in the GitHub repository. Make sure you follow us on X so you don't miss any future updates.