BiometricPrompt

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 authenticate(CancellationSignal, Executor, AuthenticationCallback) or authenticate(CryptoObject, CancellationSignal, Executor, AuthenticationCallback)

class BiometricPrompt.AuthenticationResult

Container for callback data from authenticate(CancellationSignal, Executor, AuthenticationCallback) and authenticate(CryptoObject, CancellationSignal, Executor, 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 crypto objects supported by BiometricPrompt. 

Constants

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_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_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

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

Public methods

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

This call warms up the fingerprint hardware, displays a system-provided dialog, and starts scanning for a fingerprint.

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

This call warms up the fingerprint hardware, displays a system-provided dialog, and starts scanning for a fingerprint.

Inherited methods

Constants

BIOMETRIC_ACQUIRED_GOOD

int BIOMETRIC_ACQUIRED_GOOD

The image acquired was good.

Constant Value: 0 (0x00000000)

BIOMETRIC_ACQUIRED_IMAGER_DIRTY

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

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

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

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

int BIOMETRIC_ACQUIRED_TOO_SLOW

The biometric image was unreadable due to lack of motion.

Constant Value: 4 (0x00000004)

BIOMETRIC_ERROR_CANCELED

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

int BIOMETRIC_ERROR_HW_NOT_PRESENT

The device does not have a biometric sensor.

Constant Value: 12 (0x0000000c)

BIOMETRIC_ERROR_HW_UNAVAILABLE

int BIOMETRIC_ERROR_HW_UNAVAILABLE

The hardware is unavailable. Try again later.

Constant Value: 1 (0x00000001)

BIOMETRIC_ERROR_LOCKOUT

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

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

int BIOMETRIC_ERROR_NO_BIOMETRICS

The user does not have any biometrics enrolled.

Constant Value: 11 (0x0000000b)

BIOMETRIC_ERROR_NO_SPACE

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_TIMEOUT

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

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

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

int BIOMETRIC_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 methods

authenticate

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

This call warms up the fingerprint hardware, displays a system-provided dialog, and starts scanning for a fingerprint. It terminates when onAuthenticationError(int, CharSequence) is called, when onAuthenticationSucceeded(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 BiometricPrompt.AuthenticationCallback, and button events through the corresponding callback set in setNegativeButton(CharSequence, Executor, DialogInterface.OnClickListener). It is safe to reuse the BiometricPrompt object, and calling 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 onAuthenticationError(int, CharSequence).

Requires the USE_BIOMETRIC permission.

Parameters
cancel CancellationSignal: An object that can be used to cancel authentication

This value must never be null.

executor Executor: An executor to handle callback events

This value must never 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 getMainExecutor(). To dispatch events through a shared thread pool, you can use THREAD_POOL_EXECUTOR.

callback BiometricPrompt.AuthenticationCallback: An object to receive authentication events

This value must never be null.

Throws
IllegalArgumentException If any of the arguments are null

authenticate

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

This call warms up the fingerprint hardware, displays a system-provided dialog, and starts scanning for a fingerprint. It terminates when onAuthenticationError(int, CharSequence) is called, when onAuthenticationSucceeded(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 BiometricPrompt.AuthenticationCallback, and button events through the corresponding callback set in setNegativeButton(CharSequence, Executor, DialogInterface.OnClickListener). It is safe to reuse the BiometricPrompt object, and calling 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 onAuthenticationError(int, CharSequence).

Requires the USE_BIOMETRIC permission.

Parameters
crypto BiometricPrompt.CryptoObject: Object associated with the call

This value must never be null.

cancel CancellationSignal: An object that can be used to cancel authentication

This value must never be null.

executor Executor: An executor to handle callback events

This value must never 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 getMainExecutor(). To dispatch events through a shared thread pool, you can use THREAD_POOL_EXECUTOR.

callback BiometricPrompt.AuthenticationCallback: An object to receive authentication events

This value must never be null.

Throws
IllegalArgumentException If any of the arguments are null