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 |
class |
BiometricPrompt.AuthenticationResult
A container for data passed to |
class |
BiometricPrompt.CryptoObject
A wrapper class for the crypto objects supported by |
class |
BiometricPrompt.PromptInfo
A set of configurable options for how the |
Constants | |
---|---|
int |
AUTHENTICATION_RESULT_TYPE_BIOMETRIC
Authentication type reported by |
int |
AUTHENTICATION_RESULT_TYPE_DEVICE_CREDENTIAL
Authentication type reported by |
int |
AUTHENTICATION_RESULT_TYPE_UNKNOWN
Authentication type reported by |
int |
ERROR_CANCELED
The operation was canceled because the biometric sensor is unavailable. |
int |
ERROR_HW_NOT_PRESENT
The device does not have the required authentication hardware. |
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 |
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
The operation can't be completed because there is not enough device storage remaining. |
int |
ERROR_SECURITY_UPDATE_REQUIRED
A security vulnerability has been discovered with one or more hardware sensors. |
int |
ERROR_TIMEOUT
The current operation has been running too long and has timed out. |
int |
ERROR_UNABLE_TO_PROCESS
The sensor was unable to process the current image. |
int |
ERROR_USER_CANCELED
The user canceled the operation. |
int |
ERROR_VENDOR
The operation failed due to a vendor-specific error. |
Public constructors | |
---|---|
BiometricPrompt(FragmentActivity activity, BiometricPrompt.AuthenticationCallback callback)
Constructs a |
|
BiometricPrompt(Fragment fragment, BiometricPrompt.AuthenticationCallback callback)
Constructs a |
|
BiometricPrompt(FragmentActivity activity, Executor executor, BiometricPrompt.AuthenticationCallback callback)
Constructs a |
|
BiometricPrompt(Fragment fragment, Executor executor, BiometricPrompt.AuthenticationCallback callback)
Constructs a |
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
AUTHENTICATION_RESULT_TYPE_BIOMETRIC
public static final int AUTHENTICATION_RESULT_TYPE_BIOMETRIC
Authentication type reported by BiometricPrompt.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
public static final int AUTHENTICATION_RESULT_TYPE_DEVICE_CREDENTIAL
Authentication type reported by BiometricPrompt.AuthenticationResult
when the user authenticated by
entering their device PIN, pattern, or password.
Constant Value: 1 (0x00000001)
AUTHENTICATION_RESULT_TYPE_UNKNOWN
public static final int AUTHENTICATION_RESULT_TYPE_UNKNOWN
Authentication type reported by BiometricPrompt.AuthenticationResult
when the user authenticated via
an unknown method.
This value may be returned on older Android versions due to partial incompatibility
with a newer API. It does NOT necessarily imply that the user authenticated with a method
other than those represented by AUTHENTICATION_RESULT_TYPE_DEVICE_CREDENTIAL
and
AUTHENTICATION_RESULT_TYPE_BIOMETRIC
.
Constant Value: -1 (0xffffffff)
ERROR_CANCELED
public static final int ERROR_CANCELED
The operation was canceled because the biometric sensor is unavailable. This may happen when the user is switched, the device is locked, or another pending operation prevents it.
Constant Value: 5 (0x00000005)
ERROR_HW_NOT_PRESENT
public static final int ERROR_HW_NOT_PRESENT
The device does not have the required authentication hardware.
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 their device credential (i.e. PIN,
pattern, or 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
The operation can't be completed because there is not enough device storage remaining.
Constant Value: 4 (0x00000004)
ERROR_SECURITY_UPDATE_REQUIRED
public static final int ERROR_SECURITY_UPDATE_REQUIRED
A security vulnerability has been discovered with one or more hardware sensors. The affected sensor(s) are unavailable until a security update has addressed the issue.
Constant Value: 15 (0x0000000f)
ERROR_TIMEOUT
public static final int ERROR_TIMEOUT
The current operation has been running too long and has timed out.
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
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, such as a password. The application should also provide the user a way of returning to biometric authentication, such as a button.
Constant Value: 10 (0x0000000a)
ERROR_VENDOR
public static final int ERROR_VENDOR
The operation failed due to a vendor-specific error.
This error code may be used by hardware vendors to extend this list to cover errors that don't fall under one of the other predefined categories. Vendors are responsible for providing the strings for these errors.
These messages are typically reserved for internal operations such as enrollment but may be used to express any error that is not otherwise covered. In this case, applications are expected to show the error message, but they are advised not to rely on the message ID, since this may vary by vendor and device.
Constant Value: 8 (0x00000008)
Public constructors
BiometricPrompt
public BiometricPrompt (FragmentActivity activity, 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 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. |
callback |
BiometricPrompt.AuthenticationCallback : The object that will receive and process authentication events. |
BiometricPrompt
public BiometricPrompt (Fragment fragment, 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 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. |
callback |
BiometricPrompt.AuthenticationCallback : The object that will receive and process authentication events. |
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()
.
Calling this method invokes crypto-based authentication, which is incompatible with
Class 2 (formerly Weak) biometrics and (prior to Android
11) device credential. Therefore, it is an error for info
to explicitly allow any
of these authenticator types on an incompatible Android version.
Parameters | |
---|---|
info |
BiometricPrompt.PromptInfo : An object describing the appearance and behavior of the prompt. |
crypto |
BiometricPrompt.CryptoObject : A crypto object to be associated with this authentication. |
Throws | |
---|---|
IllegalArgumentException |
If any of the allowed authenticator types specified by
info do not support crypto-based 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 : An object describing the appearance and behavior of the prompt. |
See also:
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.
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2020-10-01 UTC.