Added in API level 28

Summary: Nested Classes | Constants | Methods | Inherited Methods

BiometricPrompt

---

Kotlin |Java

public class BiometricPrompt
extends Object

java.lang.Object
↳	android.hardware.biometrics.BiometricPrompt

---

A class that manages a system-provided biometric dialog.

Summary

Nested classes
class	BiometricPrompt.AuthenticationCallback Callback structure provided to BiometricPrompt.authenticate(CancellationSignal, Executor, AuthenticationCallback) or BiometricPrompt.authenticate(CryptoObject, CancellationSignal, Executor, AuthenticationCallback).
class	BiometricPrompt.AuthenticationResult Container for callback data from BiometricPrompt.authenticate(android.os.CancellationSignal, java.util.concurrent.Executor, android.hardware.biometrics.BiometricPrompt.AuthenticationCallback) and BiometricPrompt.authenticate(android.hardware.biometrics.BiometricPrompt.CryptoObject, android.os.CancellationSignal, java.util.concurrent.Executor, android.hardware.biometrics.BiometricPrompt.AuthenticationCallback).
class	BiometricPrompt.Builder A builder that collects arguments to be shown on the system-provided biometric dialog.
class	BiometricPrompt.CryptoObject A wrapper class for the cryptographic operations supported by BiometricPrompt.

Constants
int	AUTHENTICATION_RESULT_TYPE_BIOMETRIC Authentication type reported by AuthenticationResult when the user authenticated by presenting some form of biometric (e.g. fingerprint or face).
int	AUTHENTICATION_RESULT_TYPE_DEVICE_CREDENTIAL Authentication type reported by AuthenticationResult when the user authenticated by entering their device PIN, pattern, or password.
int	BIOMETRIC_ACQUIRED_GOOD The image acquired was good.
int	BIOMETRIC_ACQUIRED_IMAGER_DIRTY The biometric image was too noisy due to suspected or detected dirt on the sensor.
int	BIOMETRIC_ACQUIRED_INSUFFICIENT The biometric image was too noisy to process due to a detected condition or a possibly dirty sensor (See BIOMETRIC_ACQUIRED_IMAGER_DIRTY).
int	BIOMETRIC_ACQUIRED_PARTIAL Only a partial biometric image was detected.
int	BIOMETRIC_ACQUIRED_TOO_FAST The biometric image was incomplete due to quick motion.
int	BIOMETRIC_ACQUIRED_TOO_SLOW The biometric image was unreadable due to lack of motion.
int	BIOMETRIC_ERROR_CANCELED The operation was canceled because the biometric sensor is unavailable.
int	BIOMETRIC_ERROR_HW_NOT_PRESENT The device does not have a biometric sensor.
int	BIOMETRIC_ERROR_HW_UNAVAILABLE The hardware is unavailable.
int	BIOMETRIC_ERROR_LOCKOUT The operation was canceled because the API is locked out due to too many attempts.
int	BIOMETRIC_ERROR_LOCKOUT_PERMANENT The operation was canceled because BIOMETRIC_ERROR_LOCKOUT occurred too many times.
int	BIOMETRIC_ERROR_NO_BIOMETRICS The user does not have any biometrics enrolled.
int	BIOMETRIC_ERROR_NO_DEVICE_CREDENTIAL The device does not have pin, pattern, or password set up.
int	BIOMETRIC_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	BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED A security vulnerability has been discovered and the sensor is unavailable until a security update has addressed this issue.
int	BIOMETRIC_ERROR_TIMEOUT Error state returned when the current request has been running too long.
int	BIOMETRIC_ERROR_UNABLE_TO_PROCESS Error state returned when the sensor was unable to process the current image.
int	BIOMETRIC_ERROR_USER_CANCELED The user canceled the operation.
int	BIOMETRIC_ERROR_VENDOR OEMs should use this constant if there are conditions that do not fit under any of the other publicly defined constants, and must provide appropriate strings for these errors to the BiometricPrompt.AuthenticationCallback.onAuthenticationError(int, CharSequence) callback.
long	BIOMETRIC_NO_AUTHENTICATION Returned from BiometricManager.getLastAuthenticationTime(int) when there has been no successful authentication for the given authenticator since boot.

Public methods
void	authenticate(CancellationSignal cancel, Executor executor, BiometricPrompt.AuthenticationCallback callback) This call warms up the biometric hardware, displays a system-provided dialog, and starts scanning for a biometric.
void	authenticate(BiometricPrompt.CryptoObject crypto, CancellationSignal cancel, Executor executor, BiometricPrompt.AuthenticationCallback callback) This call warms up the biometric hardware, displays a system-provided dialog, and starts scanning for a biometric.
int	getAllowedAuthenticators() Gets the type(s) of authenticators that may be invoked by the prompt to authenticate the user, as set by Builder.setAllowedAuthenticators(int).
PromptContentView	getContentView() Gets the content view for the prompt, as set by Builder.setContentView(PromptContentView).
CharSequence	getDescription() Gets the description for the prompt, as set by Builder.setDescription(CharSequence).
Bitmap	getLogoBitmap() Gets the logo bitmap for the prompt, as set by Builder.setLogoBitmap(Bitmap).
String	getLogoDescription() Gets the logo description for the prompt, as set by Builder.setLogoDescription(String).
int	getLogoRes() Gets the drawable resource of the logo for the prompt, as set by Builder.setLogoRes(int).
CharSequence	getNegativeButtonText() Gets the negative button text for the prompt, as set by Builder.setNegativeButton(CharSequence, Executor, DialogInterface.OnClickListener).
CharSequence	getSubtitle() Gets the subtitle for the prompt, as set by Builder.setSubtitle(CharSequence).
CharSequence	getTitle() Gets the title for the prompt, as set by Builder.setTitle(CharSequence).
boolean	isConfirmationRequired() Determines if explicit user confirmation is required by the prompt, as set by Builder.setConfirmationRequired(boolean).

Inherited methods

From class java.lang.Object Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long timeoutMillis, int nanos) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait(long timeoutMillis) Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed. final void wait() Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

AUTHENTICATION_RESULT_TYPE_BIOMETRIC

Added in API level 30

public static final int AUTHENTICATION_RESULT_TYPE_BIOMETRIC

Authentication type reported by AuthenticationResult when the user authenticated by presenting some form of biometric (e.g. fingerprint or face).

Constant Value: 2 (0x00000002)

AUTHENTICATION_RESULT_TYPE_DEVICE_CREDENTIAL

Added in API level 30

public static final int AUTHENTICATION_RESULT_TYPE_DEVICE_CREDENTIAL

Authentication type reported by AuthenticationResult when the user authenticated by entering their device PIN, pattern, or password.

Constant Value: 1 (0x00000001)

BIOMETRIC_ACQUIRED_GOOD

public static final int BIOMETRIC_ACQUIRED_GOOD

The image acquired was good.

Constant Value: 0 (0x00000000)

BIOMETRIC_ACQUIRED_IMAGER_DIRTY

public static final int BIOMETRIC_ACQUIRED_IMAGER_DIRTY

The biometric image was too noisy due to suspected or detected dirt on the sensor. For example, it's reasonable return this after multiple BIOMETRIC_ACQUIRED_INSUFFICIENT or actual detection of dirt on the sensor (stuck pixels, swaths, etc.). The user is expected to take action to clean the sensor when this is returned.

Constant Value: 3 (0x00000003)

BIOMETRIC_ACQUIRED_INSUFFICIENT

public static final int BIOMETRIC_ACQUIRED_INSUFFICIENT

The biometric image was too noisy to process due to a detected condition or a possibly dirty sensor (See BIOMETRIC_ACQUIRED_IMAGER_DIRTY).

Constant Value: 2 (0x00000002)

BIOMETRIC_ACQUIRED_PARTIAL

public static final int BIOMETRIC_ACQUIRED_PARTIAL

Only a partial biometric image was detected. During enrollment, the user should be informed on what needs to happen to resolve this problem, e.g. "press firmly on sensor." (for fingerprint)

Constant Value: 1 (0x00000001)

BIOMETRIC_ACQUIRED_TOO_FAST

public static final int BIOMETRIC_ACQUIRED_TOO_FAST

The biometric image was incomplete due to quick motion. For example, this could also happen if the user moved during acquisition. The user should be asked to repeat the operation more slowly.

Constant Value: 5 (0x00000005)

BIOMETRIC_ACQUIRED_TOO_SLOW

public static final int BIOMETRIC_ACQUIRED_TOO_SLOW

The biometric image was unreadable due to lack of motion.

Constant Value: 4 (0x00000004)

BIOMETRIC_ERROR_CANCELED

public static final int BIOMETRIC_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)

BIOMETRIC_ERROR_HW_NOT_PRESENT

public static final int BIOMETRIC_ERROR_HW_NOT_PRESENT

The device does not have a biometric sensor.

Constant Value: 12 (0x0000000c)

BIOMETRIC_ERROR_HW_UNAVAILABLE

public static final int BIOMETRIC_ERROR_HW_UNAVAILABLE

The hardware is unavailable. Try again later.

Constant Value: 1 (0x00000001)

BIOMETRIC_ERROR_LOCKOUT

public static final int BIOMETRIC_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)

BIOMETRIC_ERROR_LOCKOUT_PERMANENT

public static final int BIOMETRIC_ERROR_LOCKOUT_PERMANENT

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

Constant Value: 9 (0x00000009)

BIOMETRIC_ERROR_NO_BIOMETRICS

public static final int BIOMETRIC_ERROR_NO_BIOMETRICS

The user does not have any biometrics enrolled.

Constant Value: 11 (0x0000000b)

BIOMETRIC_ERROR_NO_DEVICE_CREDENTIAL

public static final int BIOMETRIC_ERROR_NO_DEVICE_CREDENTIAL

The device does not have pin, pattern, or password set up. See BiometricPrompt.Builder.setAllowedAuthenticators(int), Authenticators.DEVICE_CREDENTIAL, and BiometricManager.canAuthenticate(int).

Constant Value: 14 (0x0000000e)

BIOMETRIC_ERROR_NO_SPACE

public static final int BIOMETRIC_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)

BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED

public static final int BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED

A security vulnerability has been discovered and the sensor is unavailable until a security update has addressed this issue. This error can be received if for example, authentication was requested with Authenticators.BIOMETRIC_STRONG, but the sensor's strength can currently only meet Authenticators.BIOMETRIC_WEAK.

Constant Value: 15 (0x0000000f)

BIOMETRIC_ERROR_TIMEOUT

public static final int BIOMETRIC_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)

BIOMETRIC_ERROR_UNABLE_TO_PROCESS

public static final int BIOMETRIC_ERROR_UNABLE_TO_PROCESS

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

Constant Value: 2 (0x00000002)

BIOMETRIC_ERROR_USER_CANCELED

public static final int BIOMETRIC_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)

BIOMETRIC_ERROR_VENDOR

public static final int BIOMETRIC_ERROR_VENDOR

OEMs should use this constant if there are conditions that do not fit under any of the other publicly defined constants, and must provide appropriate strings for these errors to the BiometricPrompt.AuthenticationCallback.onAuthenticationError(int, CharSequence) callback. OEMs should expect that the error message will be shown to users.

Constant Value: 8 (0x00000008)

BIOMETRIC_NO_AUTHENTICATION

public static final long BIOMETRIC_NO_AUTHENTICATION

Returned from BiometricManager.getLastAuthenticationTime(int) when there has been no successful authentication for the given authenticator since boot.

Constant Value: -1 (0xffffffffffffffff)

Public methods

authenticate

Added in API level 28

public void authenticate (CancellationSignal cancel, 
                Executor executor, 
                BiometricPrompt.AuthenticationCallback callback)

This call warms up the biometric hardware, displays a system-provided dialog, and starts scanning for a biometric. It terminates when BiometricPrompt.AuthenticationCallback.onAuthenticationError(int, java.lang.CharSequence) is called, when BiometricPrompt.AuthenticationCallback.onAuthenticationSucceeded(android.hardware.biometrics.BiometricPrompt.AuthenticationResult) is called, or when the user dismisses the system-provided dialog. This operation can be canceled by using the provided cancel object. The application will receive authentication errors through AuthenticationCallback, and button events through the corresponding callback set in BiometricPrompt.Builder.setNegativeButton(java.lang.CharSequence, java.util.concurrent.Executor, android.content.DialogInterface.OnClickListener). It is safe to reuse the BiometricPrompt object, and calling authenticate(android.os.CancellationSignal, java.util.concurrent.Executor, android.hardware.biometrics.BiometricPrompt.AuthenticationCallback) while an existing authentication attempt is occurring will stop the previous client and start a new authentication. The interrupted client will receive a cancelled notification through BiometricPrompt.AuthenticationCallback.onAuthenticationError(int, java.lang.CharSequence).

Note: Applications generally should not cancel and start authentication in quick succession. For example, to properly handle authentication across configuration changes, it's recommended to use BiometricPrompt in a fragment with setRetainInstance(true). By doing so, the application will not need to cancel/restart authentication during the configuration change.
Requires Manifest.permission.USE_BIOMETRIC

Parameters
cancel	CancellationSignal: An object that can be used to cancel authentication. This value cannot be null.
executor	Executor: An executor to handle callback events. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback	BiometricPrompt.AuthenticationCallback: An object to receive authentication events. This value cannot be null.

Throws
IllegalArgumentException	If any of the arguments are null.

authenticate

Added in API level 28

public void authenticate (BiometricPrompt.CryptoObject crypto, 
                CancellationSignal cancel, 
                Executor executor, 
                BiometricPrompt.AuthenticationCallback callback)

This call warms up the biometric hardware, displays a system-provided dialog, and starts scanning for a biometric. It terminates when BiometricPrompt.AuthenticationCallback.onAuthenticationError(int, java.lang.CharSequence) is called, when BiometricPrompt.AuthenticationCallback.onAuthenticationSucceeded(android.hardware.biometrics.BiometricPrompt.AuthenticationResult), or when the user dismisses the system-provided dialog, at which point the crypto object becomes invalid. This operation can be canceled by using the provided cancel object. The application will receive authentication errors through AuthenticationCallback, and button events through the corresponding callback set in Builder.setNegativeButton(CharSequence, Executor, DialogInterface.OnClickListener). It is safe to reuse the BiometricPrompt object, and calling BiometricPrompt.authenticate(CancellationSignal, Executor, AuthenticationCallback) while an existing authentication attempt is occurring will stop the previous client and start a new authentication. The interrupted client will receive a cancelled notification through AuthenticationCallback.onAuthenticationError(int, CharSequence).

Note: Applications generally should not cancel and start authentication in quick succession. For example, to properly handle authentication across configuration changes, it's recommended to use BiometricPrompt in a fragment with setRetainInstance(true). By doing so, the application will not need to cancel/restart authentication during the configuration change.

Per the Android CDD, only biometric authenticators that meet or exceed the requirements for Strong are permitted to integrate with Keystore to perform related cryptographic operations. Therefore, it is an error to call this method after explicitly calling Builder.setAllowedAuthenticators(int) with any biometric strength other than Authenticators.BIOMETRIC_STRONG.
Requires Manifest.permission.USE_BIOMETRIC

Parameters
crypto	BiometricPrompt.CryptoObject: A cryptographic operation to be unlocked after successful authentication. This value cannot be null.
cancel	CancellationSignal: An object that can be used to cancel authentication. This value cannot be null.
executor	Executor: An executor to handle callback events. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback	BiometricPrompt.AuthenticationCallback: An object to receive authentication events. This value cannot be null.

Throws
IllegalArgumentException	If any argument is null, or if the allowed biometric authenticator strength is explicitly set to Authenticators.BIOMETRIC_WEAK. Prior to Build.VERSION_CODES.R, this exception is also thrown if Builder.setDeviceCredentialAllowed(boolean) was explicitly set to true.

getAllowedAuthenticators

Added in API level 30

public int getAllowedAuthenticators ()

Gets the type(s) of authenticators that may be invoked by the prompt to authenticate the user, as set by Builder.setAllowedAuthenticators(int).

Returns
int	A bit field representing the type(s) of authenticators that may be invoked by the prompt (as defined by Authenticators), or 0 if this field was not set. This value may be null.

getContentView

Added in API level 35

public PromptContentView getContentView ()

Gets the content view for the prompt, as set by Builder.setContentView(PromptContentView).

Returns
PromptContentView	The content view for the prompt, or null if the prompt has no content view.

getDescription

Added in API level 30

public CharSequence getDescription ()

Gets the description for the prompt, as set by Builder.setDescription(CharSequence).

Returns
CharSequence	The description for the prompt, or null if the prompt has no description.

getLogoBitmap

Added in API level 35

public Bitmap getLogoBitmap ()

Gets the logo bitmap for the prompt, as set by Builder.setLogoBitmap(Bitmap). Currently for system applications use only.
Requires Manifest.permission.SET_BIOMETRIC_DIALOG_ADVANCED

Returns
Bitmap	The logo bitmap of the prompt, or null if the prompt has no logo bitmap set.

getLogoDescription

Added in API level 35

public String getLogoDescription ()

Gets the logo description for the prompt, as set by Builder.setLogoDescription(String). Currently for system applications use only.
Requires Manifest.permission.SET_BIOMETRIC_DIALOG_ADVANCED

Returns
String	The logo description of the prompt, or null if the prompt has no logo description set.

getLogoRes

Added in API level 35

public int getLogoRes ()

Gets the drawable resource of the logo for the prompt, as set by Builder.setLogoRes(int). Currently for system applications use only.
Requires Manifest.permission.SET_BIOMETRIC_DIALOG_ADVANCED

Returns
int	The drawable resource of the logo, or 0 if the prompt has no logo resource set.

getNegativeButtonText

Added in API level 30

public CharSequence getNegativeButtonText ()

Gets the negative button text for the prompt, as set by Builder.setNegativeButton(CharSequence, Executor, DialogInterface.OnClickListener).

Returns
CharSequence	The negative button text for the prompt, or null if no negative button text was set.

getSubtitle

Added in API level 30

public CharSequence getSubtitle ()

Gets the subtitle for the prompt, as set by Builder.setSubtitle(CharSequence).

Returns
CharSequence	The subtitle for the prompt, or null if the prompt has no subtitle.

getTitle

Added in API level 30

public CharSequence getTitle ()

Gets the title for the prompt, as set by Builder.setTitle(CharSequence).

Returns
CharSequence	The title of the prompt, which is guaranteed to be non-null.

isConfirmationRequired

Added in API level 30

public boolean isConfirmationRequired ()

Determines if explicit user confirmation is required by the prompt, as set by Builder.setConfirmationRequired(boolean).

Returns
boolean	true if explicit user confirmation is required, or false otherwise.