BiometricPrompt.Builder
public
static
class
BiometricPrompt.Builder
extends Object
| java.lang.Object | |
| ↳ | android.hardware.biometrics.BiometricPrompt.Builder |
A builder that collects arguments to be shown on the system-provided biometric dialog.
Summary
Public constructors | |
|---|---|
Builder(Context context)
Creates a builder for a |
|
Public methods | |
|---|---|
BiometricPrompt.Builder
|
addFallbackOption(CharSequence text, int iconType, Executor executor, DialogInterface.OnClickListener listener)
Optional: Sets the text, icon, executor, and click listener for a fallback option in biometric prompt. |
BiometricPrompt
|
build()
Creates a |
BiometricPrompt.Builder
|
setAllowedAuthenticators(int authenticators)
Optional: Specifies the type(s) of authenticators that may be invoked by
|
BiometricPrompt.Builder
|
setConfirmationRequired(boolean requireConfirmation)
Optional: Sets a hint to the system for whether to require user confirmation after authentication. |
BiometricPrompt.Builder
|
setContentView(PromptContentView view)
Optional: Sets application customized content view that will be shown on the prompt. |
BiometricPrompt.Builder
|
setDescription(CharSequence description)
Optional: Sets a description that will be shown on the prompt. |
BiometricPrompt.Builder
|
setDeviceCredentialAllowed(boolean allowed)
This method was deprecated
in API level 30.
Replaced by |
BiometricPrompt.Builder
|
setLogoBitmap(Bitmap logoBitmap)
Optional: Sets the bitmap drawable of the logo that will be shown on the prompt. |
BiometricPrompt.Builder
|
setLogoDescription(String logoDescription)
Optional: Sets logo description text that will be shown on the prompt. |
BiometricPrompt.Builder
|
setLogoRes(int logoRes)
Optional: Sets the drawable resource of the logo that will be shown on the prompt. |
BiometricPrompt.Builder
|
setNegativeButton(CharSequence text, Executor executor, DialogInterface.OnClickListener listener)
Optional: Sets the text, executor, and click listener for the negative button on the prompt. |
BiometricPrompt.Builder
|
setSubtitle(CharSequence subtitle)
Optional: Sets a subtitle that will be shown on the prompt. |
BiometricPrompt.Builder
|
setTitle(CharSequence title)
Required: Sets the title that will be shown on the prompt. |
Inherited methods | |
|---|---|
Public constructors
Builder
public Builder (Context context)
Creates a builder for a BiometricPrompt dialog.
| Parameters | |
|---|---|
context |
Context: The Context that will be used to build the prompt. |
Public methods
addFallbackOption
public BiometricPrompt.Builder addFallbackOption (CharSequence text, int iconType, Executor executor, DialogInterface.OnClickListener listener)
Optional: Sets the text, icon, executor, and click listener for a fallback option in biometric prompt.
Fallback option is displayed as the negative button in prompt
authentication screen if it is the only option and will display in a list in the
fallback
options page if there are more than one. If device credential authentication is allowed
through setAllowedAuthenticators(int), it will
count as a fallback option.
If a fallback option is not provided and
setNegativeButton(java.lang.CharSequence, java.util.concurrent.Executor, android.content.DialogInterface.OnClickListener) is
not set, the option to use device credential will be
shown as the negative button if allowed in setAllowedAuthenticators(int). If
credential is not allowed, "Cancel" will be shown as the negative button.
A maximum of BiometricPrompt.getMaxFallbackOptions() fallback options can be added. This
number does not include device credential authentication.
Note: These fallback options will not be displayed if
setNegativeButton(java.lang.CharSequence, java.util.concurrent.Executor, android.content.DialogInterface.OnClickListener) is
set
| Parameters | |
|---|---|
text |
CharSequence: Text to be shown on the fallback option for the prompt.
This value cannot be null. |
iconType |
int: Icon to be shown for the fallback option
Value is BiometricManager.ICON_TYPE_PASSWORD, BiometricManager.ICON_TYPE_QR_CODE, BiometricManager.ICON_TYPE_ACCOUNT, BiometricManager.ICON_TYPE_GENERIC, or BiometricManager.ICON_TYPE_SETTING |
executor |
Executor: Executor that will be used to run the on click callback.
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. |
listener |
DialogInterface.OnClickListener: Listener containing a callback to be run when the button is pressed.
This value cannot be null. |
| Returns | |
|---|---|
BiometricPrompt.Builder |
This builder.
This value cannot be null. |
build
public BiometricPrompt build ()
Creates a BiometricPrompt.
| Returns | |
|---|---|
BiometricPrompt |
An instance of BiometricPrompt.
This value cannot be null. |
| Throws | |
|---|---|
IllegalArgumentException |
If any required fields are unset, or if given any invalid combination of field values. |
setAllowedAuthenticators
public BiometricPrompt.Builder setAllowedAuthenticators (int authenticators)
Optional: Specifies the type(s) of authenticators that may be invoked by
BiometricPrompt to authenticate the user. Available authenticator types are
defined in Authenticators and can be combined via bitwise OR. Defaults to:
Authenticators.BIOMETRIC_WEAKfor non-crypto authentication, orAuthenticators.BIOMETRIC_STRONGfor crypto-based authentication.
If this method is used and no authenticator of any of the specified types is available
at the time BiometricPrompt#authenticate(...) is called, authentication will
be canceled and AuthenticationCallback.onAuthenticationError(int, CharSequence)
will be invoked with an appropriate error code.
This method should be preferred over setDeviceCredentialAllowed(boolean) and
overrides the latter if both are used. Using this method to enable device credential
authentication (with Authenticators.DEVICE_CREDENTIAL) will replace the negative
button on the prompt, making it an error to also call
setNegativeButton(java.lang.CharSequence, java.util.concurrent.Executor, android.content.DialogInterface.OnClickListener).
If unlocking cryptographic operation(s), it is the application's responsibility to request authentication with the proper set of authenticators (e.g. match the authenticators specified during key generation).
| Parameters | |
|---|---|
authenticators |
int: A bit field representing all valid authenticator types that may be
invoked by the prompt.
Value is either 0 or a combination of BiometricManager.Authenticators.BIOMETRIC_STRONG, BiometricManager.Authenticators.BIOMETRIC_WEAK, android.hardware.biometrics.BiometricManager.Authenticators.BIOMETRIC_CONVENIENCE, BiometricManager.Authenticators.DEVICE_CREDENTIAL, and BiometricManager.Authenticators.IDENTITY_CHECK |
| Returns | |
|---|---|
BiometricPrompt.Builder |
This builder.
This value cannot be null. |
setConfirmationRequired
public BiometricPrompt.Builder setConfirmationRequired (boolean requireConfirmation)
Optional: Sets a hint to the system for whether to require user confirmation after
authentication. For example, implicit modalities like face and iris are passive, meaning
they don't require an explicit user action to complete authentication. If set to true,
these modalities should require the user to take some action (e.g. press a button)
before AuthenticationCallback.onAuthenticationSucceeded(AuthenticationResult) is
called. Defaults to true.
A typical use case for not requiring confirmation would be for low-risk transactions, such as re-authenticating a recently authenticated application. A typical use case for requiring confirmation would be for authorizing a purchase.
Note that this just passes a hint to the system, which the system may then ignore. For example, a value of false may be ignored if the user has disabled implicit authentication in Settings, or if it does not apply to a particular modality (e.g. fingerprint).
| Parameters | |
|---|---|
requireConfirmation |
boolean: true if explicit user confirmation should be required, or
false otherwise. |
| Returns | |
|---|---|
BiometricPrompt.Builder |
This builder.
This value cannot be null. |
setContentView
public BiometricPrompt.Builder setContentView (PromptContentView view)
Optional: Sets application customized content view that will be shown on the prompt.
Note that the description set by Builder.setDescription(CharSequence) will be
overridden by Builder.setContentView(PromptContentView). The view provided to
Builder.setContentView(PromptContentView) will be used if both methods are
called.
| Parameters | |
|---|---|
view |
PromptContentView: The customized view information.
This value cannot be null. |
| Returns | |
|---|---|
BiometricPrompt.Builder |
This builder.
This value cannot be null. |
setDescription
public BiometricPrompt.Builder setDescription (CharSequence description)
Optional: Sets a description that will be shown on the prompt.
Note that the description set by Builder.setDescription(CharSequence) will be
overridden by Builder.setContentView(PromptContentView). The view provided to
Builder.setContentView(PromptContentView) will be used if both methods are
called.
| Parameters | |
|---|---|
description |
CharSequence: The description to display.
This value cannot be null. |
| Returns | |
|---|---|
BiometricPrompt.Builder |
This builder.
This value cannot be null. |
setDeviceCredentialAllowed
public BiometricPrompt.Builder setDeviceCredentialAllowed (boolean allowed)
This method was deprecated
in API level 30.
Replaced by setAllowedAuthenticators(int).
Optional: If enabled, the user will be given the option to authenticate with their device
PIN, pattern, or password. Developers should first check BiometricManager.canAuthenticate(int) for Authenticators.DEVICE_CREDENTIAL
before enabling. If the device is not secured with a credential,
AuthenticationCallback.onAuthenticationError(int, CharSequence) will be invoked
with BiometricPrompt.BIOMETRIC_ERROR_NO_DEVICE_CREDENTIAL. Defaults to false.
Note that enabling this option replaces the negative button on the prompt with one
that allows the user to authenticate with their device credential, making it an error to
call setNegativeButton(java.lang.CharSequence, java.util.concurrent.Executor, android.content.DialogInterface.OnClickListener).
| Parameters | |
|---|---|
allowed |
boolean: true if the prompt should fall back to asking for the user's device
credential (PIN/pattern/password), or false otherwise. |
| Returns | |
|---|---|
BiometricPrompt.Builder |
This builder.
This value cannot be null. |
setLogoBitmap
public BiometricPrompt.Builder setLogoBitmap (Bitmap logoBitmap)
Optional: Sets the bitmap drawable of the logo that will be shown on the prompt.
Note that using this method is not recommended in most scenarios because the calling
application's icon will be used by default. Setting the logo is intended for large
bundled applications that perform a wide range of functions and need to show distinct
icons for each function.
Requires Manifest.permission.SET_BIOMETRIC_DIALOG_ADVANCED
| Parameters | |
|---|---|
logoBitmap |
Bitmap: A bitmap drawable of the logo that will be shown on the prompt.
This value cannot be null. |
| Returns | |
|---|---|
BiometricPrompt.Builder |
This builder.
This value cannot be null. |
setLogoDescription
public BiometricPrompt.Builder setLogoDescription (String logoDescription)
Optional: Sets logo description text that will be shown on the prompt.
Note that using this method is not recommended in most scenarios because the calling
application's name will be used by default. Setting the logo description is intended for
large bundled applications that perform a wide range of functions and need to show
distinct description for each function.
Requires Manifest.permission.SET_BIOMETRIC_DIALOG_ADVANCED
| Parameters | |
|---|---|
logoDescription |
String: The logo description text that will be shown on the prompt.
This value cannot be null. |
| Returns | |
|---|---|
BiometricPrompt.Builder |
This builder.
This value cannot be null. |
| Throws | |
|---|---|
IllegalArgumentException |
If logo description is null. |
setLogoRes
public BiometricPrompt.Builder setLogoRes (int logoRes)
Optional: Sets the drawable resource of the logo that will be shown on the prompt.
Note that using this method is not recommended in most scenarios because the calling
application's icon will be used by default. Setting the logo is intended for large
bundled applications that perform a wide range of functions and need to show distinct
icons for each function.
Requires Manifest.permission.SET_BIOMETRIC_DIALOG_ADVANCED
| Parameters | |
|---|---|
logoRes |
int: A drawable resource of the logo that will be shown on the prompt. |
| Returns | |
|---|---|
BiometricPrompt.Builder |
This builder.
This value cannot be null. |
setNegativeButton
public BiometricPrompt.Builder setNegativeButton (CharSequence text, Executor executor, DialogInterface.OnClickListener listener)
Optional: Sets the text, executor, and click listener for the negative button on the prompt. This is typically a cancel button, but may be also used to show an alternative method for authentication, such as a screen that asks for a backup password.
If not provided and no fallback is added through
addFallbackOption(java.lang.CharSequence, int, java.util.concurrent.Executor, android.content.DialogInterface.OnClickListener)
(API 36.1 and later),
the option to use device credential will be
shown as the negative button if allowed in setAllowedAuthenticators(int). If
credential is not allowed, "Cancel" will be shown as the negative button.
In API 36 and earlier, this setting is required. Note that this setting is not
required, and in fact is explicitly disallowed, if
device credential authentication is enabled via setAllowedAuthenticators(int)
or
setDeviceCredentialAllowed(boolean). To use credential authentication and
provide custom behavior, use
addFallbackOption(java.lang.CharSequence, int, java.util.concurrent.Executor, android.content.DialogInterface.OnClickListener)
| Parameters | |
|---|---|
text |
CharSequence: Text to be shown on the negative button for the prompt.
This value cannot be null. |
executor |
Executor: Executor that will be used to run the on click callback.
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. |
listener |
DialogInterface.OnClickListener: Listener containing a callback to be run when the button is pressed.
This value cannot be null. |
| Returns | |
|---|---|
BiometricPrompt.Builder |
This builder.
This value cannot be null. |
setSubtitle
public BiometricPrompt.Builder setSubtitle (CharSequence subtitle)
Optional: Sets a subtitle that will be shown on the prompt.
| Parameters | |
|---|---|
subtitle |
CharSequence: The subtitle to display.
This value cannot be null. |
| Returns | |
|---|---|
BiometricPrompt.Builder |
This builder.
This value cannot be null. |
setTitle
public BiometricPrompt.Builder setTitle (CharSequence title)
Required: Sets the title that will be shown on the prompt.
| Parameters | |
|---|---|
title |
CharSequence: The title to display.
This value cannot be null. |
| Returns | |
|---|---|
BiometricPrompt.Builder |
This builder.
This value cannot be null. |