BiometricPrompt
open class BiometricPrompt
| kotlin.Any | |
| ↳ | android.hardware.biometrics.BiometricPrompt |
A class that manages a system-provided biometric dialog.
Summary
| Nested classes | |
|---|---|
| abstract |
Callback structure provided to |
| open |
Container for callback data from |
| open |
A builder that collects arguments to be shown on the system-provided biometric dialog. |
|
A wrapper class for the cryptographic operations supported by BiometricPrompt. |
|
| Constants | |
|---|---|
| static Int |
Authentication type reported by |
| static Int |
Authentication type reported by |
| static Int |
The image acquired was good. |
| static Int |
The biometric image was too noisy due to suspected or detected dirt on the sensor. |
| static Int |
The biometric image was too noisy to process due to a detected condition or a possibly dirty sensor (See |
| static Int |
Only a partial biometric image was detected. |
| static Int |
The biometric image was incomplete due to quick motion. |
| static Int |
The biometric image was unreadable due to lack of motion. |
| static Int |
The operation was canceled because the biometric sensor is unavailable. |
| static Int |
The device does not have a biometric sensor. |
| static Int |
The hardware is unavailable. |
| static Int |
The operation was canceled because the API is locked out due to too many attempts. |
| static Int |
The operation was canceled because BIOMETRIC_ERROR_LOCKOUT occurred too many times. |
| static Int |
The user does not have any biometrics enrolled. |
| static Int |
The device does not have pin, pattern, or password set up. |
| static Int |
Error state returned for operations like enrollment; the operation cannot be completed because there's not enough storage remaining to complete the operation. |
| static Int |
A security vulnerability has been discovered and the sensor is unavailable until a security update has addressed this issue. |
| static Int |
Error state returned when the current request has been running too long. |
| static Int |
Error state returned when the sensor was unable to process the current image. |
| static Int |
The user canceled the operation. |
| static Int |
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 |
| static Long |
Returned from |
| Public methods | |
|---|---|
| open Unit |
authenticate(crypto: BiometricPrompt.CryptoObject, cancel: CancellationSignal, executor: Executor, callback: BiometricPrompt.AuthenticationCallback)This call warms up the biometric hardware, displays a system-provided dialog, and starts scanning for a biometric. |
| open Unit |
authenticate(cancel: CancellationSignal, executor: Executor, callback: BiometricPrompt.AuthenticationCallback)This call warms up the biometric hardware, displays a system-provided dialog, and starts scanning for a biometric. |
| open Int |
Gets the type(s) of authenticators that may be invoked by the prompt to authenticate the user, as set by |
| open PromptContentView? |
Gets the content view for the prompt, as set by |
| open CharSequence? |
Gets the description for the prompt, as set by |
| open Bitmap? |
Gets the logo bitmap for the prompt, as set by |
| open String? |
Gets the logo description for the prompt, as set by |
| open Int |
Gets the drawable resource of the logo for the prompt, as set by |
| open CharSequence? |
Gets the negative button text for the prompt, as set by |
| open CharSequence? |
Gets the subtitle for the prompt, as set by |
| open CharSequence |
getTitle()Gets the title for the prompt, as set by |
| open Boolean |
Determines if explicit user confirmation is required by the prompt, as set by |
Constants
AUTHENTICATION_RESULT_TYPE_BIOMETRIC
static val AUTHENTICATION_RESULT_TYPE_BIOMETRIC: Int
Authentication type reported by AuthenticationResult when the user authenticated by presenting some form of biometric (e.g. fingerprint or face).
Value: 2
AUTHENTICATION_RESULT_TYPE_DEVICE_CREDENTIAL
static val AUTHENTICATION_RESULT_TYPE_DEVICE_CREDENTIAL: Int
Authentication type reported by AuthenticationResult when the user authenticated by entering their device PIN, pattern, or password.
Value: 1
BIOMETRIC_ACQUIRED_GOOD
static val BIOMETRIC_ACQUIRED_GOOD: Int
The image acquired was good.
Value: 0
BIOMETRIC_ACQUIRED_IMAGER_DIRTY
static val BIOMETRIC_ACQUIRED_IMAGER_DIRTY: Int
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.
Value: 3
BIOMETRIC_ACQUIRED_INSUFFICIENT
static val BIOMETRIC_ACQUIRED_INSUFFICIENT: Int
The biometric image was too noisy to process due to a detected condition or a possibly dirty sensor (See BIOMETRIC_ACQUIRED_IMAGER_DIRTY).
Value: 2
BIOMETRIC_ACQUIRED_PARTIAL
static val BIOMETRIC_ACQUIRED_PARTIAL: Int
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)
Value: 1
BIOMETRIC_ACQUIRED_TOO_FAST
static val BIOMETRIC_ACQUIRED_TOO_FAST: Int
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.
Value: 5
BIOMETRIC_ACQUIRED_TOO_SLOW
static val BIOMETRIC_ACQUIRED_TOO_SLOW: Int
The biometric image was unreadable due to lack of motion.
Value: 4
BIOMETRIC_ERROR_CANCELED
static val BIOMETRIC_ERROR_CANCELED: Int
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.
Value: 5
BIOMETRIC_ERROR_HW_NOT_PRESENT
static val BIOMETRIC_ERROR_HW_NOT_PRESENT: Int
The device does not have a biometric sensor.
Value: 12
BIOMETRIC_ERROR_HW_UNAVAILABLE
static val BIOMETRIC_ERROR_HW_UNAVAILABLE: Int
The hardware is unavailable. Try again later.
Value: 1
BIOMETRIC_ERROR_LOCKOUT
static val BIOMETRIC_ERROR_LOCKOUT: Int
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.
Value: 7
BIOMETRIC_ERROR_LOCKOUT_PERMANENT
static val BIOMETRIC_ERROR_LOCKOUT_PERMANENT: Int
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)
Value: 9
BIOMETRIC_ERROR_NO_BIOMETRICS
static val BIOMETRIC_ERROR_NO_BIOMETRICS: Int
The user does not have any biometrics enrolled.
Value: 11
BIOMETRIC_ERROR_NO_DEVICE_CREDENTIAL
static val BIOMETRIC_ERROR_NO_DEVICE_CREDENTIAL: Int
The device does not have pin, pattern, or password set up. See BiometricPrompt.Builder#setAllowedAuthenticators(int), Authenticators#DEVICE_CREDENTIAL, and BiometricManager#canAuthenticate(int).
Value: 14
BIOMETRIC_ERROR_NO_SPACE
static val BIOMETRIC_ERROR_NO_SPACE: Int
Error state returned for operations like enrollment; the operation cannot be completed because there's not enough storage remaining to complete the operation.
Value: 4
BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED
static val BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED: Int
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.
Value: 15
BIOMETRIC_ERROR_TIMEOUT
static val BIOMETRIC_ERROR_TIMEOUT: Int
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.
Value: 3
BIOMETRIC_ERROR_UNABLE_TO_PROCESS
static val BIOMETRIC_ERROR_UNABLE_TO_PROCESS: Int
Error state returned when the sensor was unable to process the current image.
Value: 2
BIOMETRIC_ERROR_USER_CANCELED
static val BIOMETRIC_ERROR_USER_CANCELED: Int
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.
Value: 10
BIOMETRIC_ERROR_VENDOR
static val BIOMETRIC_ERROR_VENDOR: Int
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, callback. OEMs should expect that the error message will be shown to users.
Value: 8
BIOMETRIC_NO_AUTHENTICATION
static val BIOMETRIC_NO_AUTHENTICATION: Long
Returned from BiometricManager#getLastAuthenticationTime(int) when there has been no successful authentication for the given authenticator since boot.
Value: -1L
Public methods
authenticate
open fun authenticate(
crypto: BiometricPrompt.CryptoObject,
cancel: CancellationSignal,
executor: Executor,
callback: BiometricPrompt.AuthenticationCallback
): Unit
This call warms up the biometric hardware, displays a system-provided dialog, and starts scanning for a biometric. It terminates when android.hardware.biometrics.BiometricPrompt.AuthenticationCallback#onAuthenticationError(int,java.lang.CharSequence) is called, when android.hardware.biometrics.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,. It is safe to reuse the BiometricPrompt object, and calling BiometricPrompt#authenticate(CancellationSignal, Executor, 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,.
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 android.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. |
| Exceptions | |
|---|---|
java.lang.IllegalArgumentException |
If any argument is null, or if the allowed biometric authenticator strength is explicitly set to Authenticators#BIOMETRIC_WEAK. Prior to android.os.Build.VERSION_CODES#R, this exception is also thrown if Builder#setDeviceCredentialAllowed(boolean) was explicitly set to true. |
authenticate
open fun authenticate(
cancel: CancellationSignal,
executor: Executor,
callback: BiometricPrompt.AuthenticationCallback
): Unit
This call warms up the biometric hardware, displays a system-provided dialog, and starts scanning for a biometric. It terminates when android.hardware.biometrics.BiometricPrompt.AuthenticationCallback#onAuthenticationError(int,java.lang.CharSequence) is called, when android.hardware.biometrics.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 android.hardware.biometrics.BiometricPrompt.Builder#setNegativeButton(java.lang.CharSequence,java.util.concurrent.Executor,android.content.DialogInterface.OnClickListener). It is safe to reuse the BiometricPrompt object, and calling android.hardware.biometrics.BiometricPrompt#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 android.hardware.biometrics.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 android.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. |
| Exceptions | |
|---|---|
java.lang.IllegalArgumentException |
If any of the arguments are null. |
getAllowedAuthenticators
open fun getAllowedAuthenticators(): Int
Gets the type(s) of authenticators that may be invoked by the prompt to authenticate the user, as set by Builder#setAllowedAuthenticators(int).
| Return | |
|---|---|
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
open fun getContentView(): PromptContentView?
Gets the content view for the prompt, as set by Builder#setContentView(PromptContentView).
| Return | |
|---|---|
PromptContentView? |
The content view for the prompt, or null if the prompt has no content view. |
getDescription
open fun getDescription(): CharSequence?
Gets the description for the prompt, as set by Builder#setDescription(CharSequence).
| Return | |
|---|---|
CharSequence? |
The description for the prompt, or null if the prompt has no description. |
getLogoBitmap
open fun getLogoBitmap(): Bitmap?
Gets the logo bitmap for the prompt, as set by Builder#setLogoBitmap(Bitmap). Currently for system applications use only.
Requires android.Manifest.permission#SET_BIOMETRIC_DIALOG_ADVANCED
| Return | |
|---|---|
Bitmap? |
The logo bitmap of the prompt, or null if the prompt has no logo bitmap set. |
getLogoDescription
open fun getLogoDescription(): String?
Gets the logo description for the prompt, as set by Builder#setLogoDescription(String). Currently for system applications use only.
Requires android.Manifest.permission#SET_BIOMETRIC_DIALOG_ADVANCED
| Return | |
|---|---|
String? |
The logo description of the prompt, or null if the prompt has no logo description set. |
getLogoRes
open fun getLogoRes(): Int
Gets the drawable resource of the logo for the prompt, as set by Builder#setLogoRes(int). Currently for system applications use only.
Requires android.Manifest.permission#SET_BIOMETRIC_DIALOG_ADVANCED
| Return | |
|---|---|
Int |
The drawable resource of the logo, or 0 if the prompt has no logo resource set. |
getNegativeButtonText
open fun getNegativeButtonText(): CharSequence?
Gets the negative button text for the prompt, as set by Builder#setNegativeButton(CharSequence, Executor, DialogInterface.OnClickListener).
| Return | |
|---|---|
CharSequence? |
The negative button text for the prompt, or null if no negative button text was set. |
getSubtitle
open fun getSubtitle(): CharSequence?
Gets the subtitle for the prompt, as set by Builder#setSubtitle(CharSequence).
| Return | |
|---|---|
CharSequence? |
The subtitle for the prompt, or null if the prompt has no subtitle. |
getTitle
open fun getTitle(): CharSequence
Gets the title for the prompt, as set by Builder#setTitle(CharSequence).
| Return | |
|---|---|
CharSequence |
The title of the prompt, which is guaranteed to be non-null. |
isConfirmationRequired
open fun isConfirmationRequired(): Boolean
Determines if explicit user confirmation is required by the prompt, as set by Builder#setConfirmationRequired(boolean).
| Return | |
|---|---|
Boolean |
true if explicit user confirmation is required, or false otherwise. |