Google is committed to advancing racial equity for Black communities. See how.

BiometricPrompt

public class BiometricPrompt
extends Object

java.lang.Object
   ↳ androidx.biometric.BiometricPrompt

A class that manages a system-provided biometric prompt. On devices running Android 9.0 (API 28) and above, this will show a system-provided authentication prompt, using one of the device's supported biometric modalities (fingerprint, iris, face, etc). Prior to Android 9.0, this will instead show a custom fingerprint authentication dialog. The prompt will persist across configuration changes unless explicitly canceled. For security reasons, the prompt will be dismissed when the client application is no longer in the foreground.

To persist authentication across configuration changes, developers should (re)create the prompt every time the activity/fragment is created. Instantiating the prompt with a new callback early in the fragment/activity lifecycle (e.g. in onCreate()) will allow the ongoing authentication session's callbacks to be received by the new fragment/activity instance. Note that cancelAuthentication() should not be called, and authenticate() does not need to be invoked during activity/fragment creation.

Summary

Nested classes

class BiometricPrompt.AuthenticationCallback

A collection of methods that may be invoked by BiometricPrompt during authentication. 

class BiometricPrompt.AuthenticationResult

A container for data passed to BiometricPrompt.AuthenticationCallback.onAuthenticationSucceeded(AuthenticationResult) when the user has successfully authenticated. 

class BiometricPrompt.CryptoObject

A wrapper class for the crypto objects supported by BiometricPrompt. 

class BiometricPrompt.PromptInfo

A set of configurable options for how the BiometricPrompt should appear and behave. 

Constants

int ERROR_CANCELED

The operation was canceled because the biometric sensor is unavailable.

int ERROR_HW_NOT_PRESENT

The device does not have a biometric sensor.

int ERROR_HW_UNAVAILABLE

The hardware is unavailable.

int ERROR_LOCKOUT

The operation was canceled because the API is locked out due to too many attempts.

int ERROR_LOCKOUT_PERMANENT

The operation was canceled because ERROR_LOCKOUT occurred too many times.

int ERROR_NEGATIVE_BUTTON

The user pressed the negative button.

int ERROR_NO_BIOMETRICS

The user does not have any biometrics enrolled.

int ERROR_NO_DEVICE_CREDENTIAL

The device does not have pin, pattern, or password set up.

int ERROR_NO_SPACE

Error state returned for operations like enrollment; the operation cannot be completed because there's not enough storage remaining to complete the operation.

int ERROR_TIMEOUT

Error state returned when the current request has been running too long.

int ERROR_UNABLE_TO_PROCESS

Error state returned when the sensor was unable to process the current image.

int ERROR_USER_CANCELED

The user canceled the operation.

int ERROR_VENDOR

Hardware vendors may extend this list if there are conditions that do not fall under one of the above categories.

Public constructors

BiometricPrompt(FragmentActivity activity, Executor executor, BiometricPrompt.AuthenticationCallback callback)

Constructs a BiometricPrompt, which can be used to prompt the user to authenticate with a biometric such as fingerprint or face.

BiometricPrompt(Fragment fragment, Executor executor, BiometricPrompt.AuthenticationCallback callback)

Constructs a BiometricPrompt, which can be used to prompt the user to authenticate with a biometric such as fingerprint or face.

Public methods

void authenticate(BiometricPrompt.PromptInfo info, BiometricPrompt.CryptoObject crypto)

Shows the biometric prompt to the user.

void authenticate(BiometricPrompt.PromptInfo info)

Shows the biometric prompt to the user.

void cancelAuthentication()

Cancels the ongoing authentication session and dismisses the prompt.

Inherited methods

Constants

ERROR_CANCELED

public static final int ERROR_CANCELED

The operation was canceled because the biometric sensor is unavailable. For example, this may happen when the user is switched, the device is locked or another pending operation prevents or disables it.

Constant Value: 5 (0x00000005)

ERROR_HW_NOT_PRESENT

public static final int ERROR_HW_NOT_PRESENT

The device does not have a biometric sensor.

Constant Value: 12 (0x0000000c)

ERROR_HW_UNAVAILABLE

public static final int ERROR_HW_UNAVAILABLE

The hardware is unavailable. Try again later.

Constant Value: 1 (0x00000001)

ERROR_LOCKOUT

public static final int ERROR_LOCKOUT

The operation was canceled because the API is locked out due to too many attempts. This occurs after 5 failed attempts, and lasts for 30 seconds.

Constant Value: 7 (0x00000007)

ERROR_LOCKOUT_PERMANENT

public static final int ERROR_LOCKOUT_PERMANENT

The operation was canceled because ERROR_LOCKOUT occurred too many times. Biometric authentication is disabled until the user unlocks with strong authentication (PIN/Pattern/Password)

Constant Value: 9 (0x00000009)

ERROR_NEGATIVE_BUTTON

public static final int ERROR_NEGATIVE_BUTTON

The user pressed the negative button.

Constant Value: 13 (0x0000000d)

ERROR_NO_BIOMETRICS

public static final int ERROR_NO_BIOMETRICS

The user does not have any biometrics enrolled.

Constant Value: 11 (0x0000000b)

ERROR_NO_DEVICE_CREDENTIAL

public static final int ERROR_NO_DEVICE_CREDENTIAL

The device does not have pin, pattern, or password set up.

Constant Value: 14 (0x0000000e)

ERROR_NO_SPACE

public static final int ERROR_NO_SPACE

Error state returned for operations like enrollment; the operation cannot be completed because there's not enough storage remaining to complete the operation.

Constant Value: 4 (0x00000004)

ERROR_TIMEOUT

public static final int ERROR_TIMEOUT

Error state returned when the current request has been running too long. This is intended to prevent programs from waiting for the biometric sensor indefinitely. The timeout is platform and sensor-specific, but is generally on the order of 30 seconds.

Constant Value: 3 (0x00000003)

ERROR_UNABLE_TO_PROCESS

public static final int ERROR_UNABLE_TO_PROCESS

Error state returned when the sensor was unable to process the current image.

Constant Value: 2 (0x00000002)

ERROR_USER_CANCELED

public static final int ERROR_USER_CANCELED

The user canceled the operation. Upon receiving this, applications should use alternate authentication (e.g. a password). The application should also provide the means to return to biometric authentication, such as a "use " button.

Constant Value: 10 (0x0000000a)

ERROR_VENDOR

public static final int ERROR_VENDOR

Hardware vendors may extend this list if there are conditions that do not fall under one of the above categories. Vendors are responsible for providing error strings for these errors. These messages are typically reserved for internal operations such as enrollment, but may be used to express vendor errors not otherwise covered. Applications are expected to show the error message string if they happen, but are advised not to rely on the message id since they will be device and vendor-specific

Constant Value: 8 (0x00000008)

Public constructors

BiometricPrompt

public BiometricPrompt (FragmentActivity activity, 
                Executor executor, 
                BiometricPrompt.AuthenticationCallback callback)

Constructs a BiometricPrompt, which can be used to prompt the user to authenticate with a biometric such as fingerprint or face. The prompt can be shown to the user by calling authenticate() and persists across device configuration changes by default.

If authentication is in progress, calling this constructor to recreate the prompt will also update the Executor and BiometricPrompt.AuthenticationCallback for the current session. Thus, this method should be called by the client activity each time the configuration changes (e.g. in onCreate()).

Parameters
activity FragmentActivity: The activity of the client application that will host the prompt.
executor Executor: The executor that will be used to run BiometricPrompt.AuthenticationCallback methods.
callback BiometricPrompt.AuthenticationCallback: The object that will receive and process authentication events.

BiometricPrompt

public BiometricPrompt (Fragment fragment, 
                Executor executor, 
                BiometricPrompt.AuthenticationCallback callback)

Constructs a BiometricPrompt, which can be used to prompt the user to authenticate with a biometric such as fingerprint or face. The prompt can be shown to the user by calling authenticate() and persists across device configuration changes by default.

If authentication is in progress, calling this constructor to recreate the prompt will also update the Executor and BiometricPrompt.AuthenticationCallback for the current session. Thus, this method should be called by the client fragment each time the configuration changes (e.g. in onCreate()).

Parameters
fragment Fragment: The fragment of the client application that will host the prompt.
executor Executor: The executor that will be used to run BiometricPrompt.AuthenticationCallback methods.
callback BiometricPrompt.AuthenticationCallback: The object that will receive and process authentication events.

Public methods

authenticate

public void authenticate (BiometricPrompt.PromptInfo info, 
                BiometricPrompt.CryptoObject crypto)

Shows the biometric prompt to the user. The prompt survives lifecycle changes by default. To cancel authentication and dismiss the prompt, use cancelAuthentication().

Parameters
info BiometricPrompt.PromptInfo: A BiometricPrompt.PromptInfo object describing the appearance and behavior of the prompt.
crypto BiometricPrompt.CryptoObject: A crypto object to be associated with this authentication.

authenticate

public void authenticate (BiometricPrompt.PromptInfo info)

Shows the biometric prompt to the user. The prompt survives lifecycle changes by default. To cancel authentication and dismiss the prompt, use cancelAuthentication().

Parameters
info BiometricPrompt.PromptInfo: A BiometricPrompt.PromptInfo object describing the appearance and behavior of the prompt.

cancelAuthentication

public void cancelAuthentication ()

Cancels the ongoing authentication session and dismisses the prompt.

On versions prior to Android 10 (API 29), calling this method while the user is authenticating with their device credential will NOT work as expected. See BiometricPrompt.PromptInfo.Builder.setDeviceCredentialAllowed(boolean) for more details.