Google is committed to advancing racial equity for Black communities. See how.

BiometricPrompt

open class BiometricPrompt : BiometricConstants
kotlin.Any
   ↳ 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
abstract

A collection of methods that may be invoked by BiometricPrompt during authentication.

open

A container for data passed to AuthenticationCallback#onAuthenticationSucceeded( * AuthenticationResult) when the user has successfully authenticated.

open

A wrapper class for the crypto objects supported by BiometricPrompt.

open

A set of configurable options for how the BiometricPrompt should appear and behave.

Constants
static Int

Authentication type reported by AuthenticationResult when the user authenticated by presenting some form of biometric (e.g. fingerprint or face).

static Int

Authentication type reported by AuthenticationResult when the user authenticated by entering their device PIN, pattern, or password.

static Int

Authentication type reported by AuthenticationResult when the user authenticated via an unknown method.

Public constructors
<init>(@NonNull activity: FragmentActivity, @NonNull callback: BiometricPrompt.AuthenticationCallback)

Constructs a BiometricPrompt, which can be used to prompt the user to authenticate with a biometric such as fingerprint or face.

<init>(@NonNull fragment: Fragment, @NonNull callback: BiometricPrompt.AuthenticationCallback)

Constructs a BiometricPrompt, which can be used to prompt the user to authenticate with a biometric such as fingerprint or face.

<init>(@NonNull activity: FragmentActivity, @NonNull executor: Executor, @NonNull callback: BiometricPrompt.AuthenticationCallback)

Constructs a BiometricPrompt, which can be used to prompt the user to authenticate with a biometric such as fingerprint or face.

<init>(@NonNull fragment: Fragment, @NonNull executor: Executor, @NonNull callback: BiometricPrompt.AuthenticationCallback)

Constructs a BiometricPrompt, which can be used to prompt the user to authenticate with a biometric such as fingerprint or face.

Public methods
open Unit

Shows the biometric prompt to the user.

open Unit

Shows the biometric prompt to the user.

open Unit

Cancels the ongoing authentication session and dismisses the prompt.

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

AUTHENTICATION_RESULT_TYPE_UNKNOWN

static val AUTHENTICATION_RESULT_TYPE_UNKNOWN: Int

Authentication type reported by 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.

Value: -1

Public constructors

<init>

BiometricPrompt(
    @NonNull activity: FragmentActivity,
    @NonNull callback: BiometricPrompt.AuthenticationCallback)

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

<init>

BiometricPrompt(
    @NonNull fragment: Fragment,
    @NonNull callback: BiometricPrompt.AuthenticationCallback)

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

<init>

BiometricPrompt(
    @NonNull activity: FragmentActivity,
    @NonNull executor: Executor,
    @NonNull callback: BiometricPrompt.AuthenticationCallback)

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 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 AuthenticationCallback methods.
callback BiometricPrompt.AuthenticationCallback: The object that will receive and process authentication events.

<init>

BiometricPrompt(
    @NonNull fragment: Fragment,
    @NonNull executor: Executor,
    @NonNull callback: BiometricPrompt.AuthenticationCallback)

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 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 AuthenticationCallback methods.
callback BiometricPrompt.AuthenticationCallback: The object that will receive and process authentication events.

Public methods

authenticate

open fun authenticate(
    @NonNull info: BiometricPrompt.PromptInfo,
    @NonNull crypto: BiometricPrompt.CryptoObject
): Unit

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.
Exceptions
IllegalArgumentException If any of the allowed authenticator types specified by info do not support crypto-based authentication.

authenticate

open fun authenticate(@NonNull info: BiometricPrompt.PromptInfo): Unit

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.

cancelAuthentication

open fun cancelAuthentication(): Unit

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 PromptInfo.Builder#setDeviceCredentialAllowed(boolean) for more details.