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.AuthenticationCallbackCallback structure provided to  | 
| 
        
        
        
        
        class | BiometricPrompt.AuthenticationResultContainer for callback data from  | 
| 
        
        
        
        
        class | BiometricPrompt.BuilderA builder that collects arguments to be shown on the system-provided biometric dialog. | 
| 
        
        
        
        
        class | BiometricPrompt.CryptoObjectA wrapper class for the cryptographic operations supported by BiometricPrompt. | 
| Constants | |
|---|---|
| int | AUTHENTICATION_RESULT_TYPE_BIOMETRICAuthentication type reported by  | 
| int | AUTHENTICATION_RESULT_TYPE_DEVICE_CREDENTIALAuthentication type reported by  | 
| int | BIOMETRIC_ACQUIRED_GOODThe image acquired was good. | 
| int | BIOMETRIC_ACQUIRED_IMAGER_DIRTYThe biometric image was too noisy due to suspected or detected dirt on the sensor. | 
| int | BIOMETRIC_ACQUIRED_INSUFFICIENTThe biometric image was too noisy to process due to a detected condition or a possibly dirty
 sensor (See  | 
| int | BIOMETRIC_ACQUIRED_PARTIALOnly a partial biometric image was detected. | 
| int | BIOMETRIC_ACQUIRED_TOO_FASTThe biometric image was incomplete due to quick motion. | 
| int | BIOMETRIC_ACQUIRED_TOO_SLOWThe biometric image was unreadable due to lack of motion. | 
| int | BIOMETRIC_ERROR_CANCELEDThe operation was canceled because the biometric sensor is unavailable. | 
| int | BIOMETRIC_ERROR_HW_NOT_PRESENTThe device does not have a biometric sensor. | 
| int | BIOMETRIC_ERROR_HW_UNAVAILABLEThe hardware is unavailable. | 
| int | BIOMETRIC_ERROR_IDENTITY_CHECK_NOT_ACTIVEIdentity Check is currently not active. | 
| int | BIOMETRIC_ERROR_LOCKOUTThe operation was canceled because the API is locked out due to too many attempts. | 
| int | BIOMETRIC_ERROR_LOCKOUT_PERMANENTThe operation was canceled because BIOMETRIC_ERROR_LOCKOUT occurred too many times. | 
| int | BIOMETRIC_ERROR_NOT_ENABLED_FOR_APPSBiometrics is not allowed to verify the user in apps. | 
| int | BIOMETRIC_ERROR_NO_BIOMETRICSThe user does not have any biometrics enrolled. | 
| int | BIOMETRIC_ERROR_NO_DEVICE_CREDENTIALThe device does not have pin, pattern, or password set up. | 
| int | BIOMETRIC_ERROR_NO_SPACEError 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_REQUIREDA security vulnerability has been discovered and the sensor is unavailable until a security update has addressed this issue. | 
| int | BIOMETRIC_ERROR_TIMEOUTError state returned when the current request has been running too long. | 
| int | BIOMETRIC_ERROR_UNABLE_TO_PROCESSError state returned when the sensor was unable to process the current image. | 
| int | BIOMETRIC_ERROR_USER_CANCELEDThe user canceled the operation. | 
| int | BIOMETRIC_ERROR_VENDOROEMs 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  | 
| long | BIOMETRIC_NO_AUTHENTICATIONReturned from  | 
| 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  | 
| 
        
        
        
        
        
        PromptContentView | 
      getContentView()
      Gets the content view for the prompt, as set by
  | 
| 
        
        
        
        
        
        CharSequence | 
      getDescription()
      Gets the description for the prompt, as set by  | 
| 
        
        
        
        
        
        List<FallbackOption> | 
      getFallbackOptions()
      Gets the fallback options for the prompt, as set by
  | 
| 
        
        
        
        
        
        Bitmap | 
      getLogoBitmap()
      Gets the logo bitmap for the prompt, as set by  | 
| 
        
        
        
        
        
        String | 
      getLogoDescription()
      Gets the logo description for the prompt, as set by
  | 
| 
        
        
        
        
        
        int | 
      getLogoRes()
      Gets the drawable resource of the logo for the prompt, as set by
  | 
| 
        
        
        static
        
        
        int | 
      getMaxFallbackOptions()
       | 
| 
        
        
        
        
        
        CharSequence | 
      getNegativeButtonText()
      Gets the negative button text for the prompt, as set by
  | 
| 
        
        
        
        
        
        CharSequence | 
      getSubtitle()
      Gets the subtitle for the prompt, as set by  | 
| 
        
        
        
        
        
        CharSequence | 
      getTitle()
      Gets the title for the prompt, as set by  | 
| 
        
        
        
        
        
        boolean | 
      isConfirmationRequired()
      Determines if explicit user confirmation is required by the prompt, as set by
  | 
| Inherited methods | |
|---|---|
Constants
AUTHENTICATION_RESULT_TYPE_BIOMETRIC
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
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_IDENTITY_CHECK_NOT_ACTIVE
public static final int BIOMETRIC_ERROR_IDENTITY_CHECK_NOT_ACTIVE
Identity Check is currently not active. This device either doesn't have this feature enabled, or it's not considered in a high-risk environment that requires extra security measures for accessing sensitive data.
Constant Value: 20 (0x00000014)
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_NOT_ENABLED_FOR_APPS
public static final int BIOMETRIC_ERROR_NOT_ENABLED_FOR_APPS
Biometrics is not allowed to verify the user in apps.
Constant Value: 21 (0x00000015)
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 
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
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) or
 Builder.addFallbackOption(CharSequence, int, Executor,
 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
 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.
 
 Requires Manifest.permission.USE_BIOMETRIC
| Parameters | |
|---|---|
| cancel | CancellationSignal: An object that can be used to cancel authentication.
 This value cannot benull. | 
| executor | Executor: An executor to handle callback events.
 This value cannot benull.
 Callback and listener events are dispatched through thisExecutor, providing an easy way to control which thread is
 used. To dispatch events through the main thread of your
 application, you can useContext.getMainExecutor().
 Otherwise, provide anExecutorthat dispatches to an appropriate thread. | 
| callback | BiometricPrompt.AuthenticationCallback: An object to receive authentication events.
 This value cannot benull. | 
| Throws | |
|---|---|
| IllegalArgumentException | If any of the arguments are null. | 
authenticate
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) or
 Builder.addFallbackOption(CharSequence, int, 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 benull. | 
| cancel | CancellationSignal: An object that can be used to cancel authentication.
 This value cannot benull. | 
| executor | Executor: An executor to handle callback events.
 This value cannot benull.
 Callback and listener events are dispatched through thisExecutor, providing an easy way to control which thread is
 used. To dispatch events through the main thread of your
 application, you can useContext.getMainExecutor().
 Otherwise, provide anExecutorthat dispatches to an appropriate thread. | 
| callback | BiometricPrompt.AuthenticationCallback: An object to receive authentication events.
 This value cannot benull. | 
| Throws | |
|---|---|
| IllegalArgumentException | If any argument is null, or if the allowed biometric
 authenticator strength is explicitly set to Authenticators.BIOMETRIC_WEAK. Prior toBuild.VERSION_CODES.R, this exception is also thrown ifBuilder.setDeviceCredentialAllowed(boolean)was explicitly set to true. | 
getAllowedAuthenticators
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 benull. | 
getContentView
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
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. | 
getFallbackOptions
public List<FallbackOption> getFallbackOptions ()
Gets the fallback options for the prompt, as set by
 Builder.addFallbackOption(CharSequence, int, Executor, DialogInterface.OnClickListener).
| Returns | |
|---|---|
| List<FallbackOption> | The fallback options for the prompt.
 This value cannot be null. | 
getLogoBitmap
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
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
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. | 
getMaxFallbackOptions
public static int getMaxFallbackOptions ()
| Returns | |
|---|---|
| int | the maximum amount of fallback options that can be added to the prompt | 
getNegativeButtonText
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
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
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
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. | 
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2025-09-17 UTC.
