Class BiometricPrompt

java.lang.Object
com.iizix.gyro.BiometricPrompt

public final class BiometricPrompt extends Object
What the user is shown by a biometric check of IBiometricAuthentication.authenticate(BiometricPrompt, Consumer), and what the check accepts (CC-IIZIRUN-BIOMETRIC-API). The texts are the caller's, in the user's language: nothing here is translated.

What each platform shows: Android's BiometricPrompt shows the title, the subtitle, the description and its negative button; iOS shows the description as the reason of its system sheet (its title is the app's own), and the fallback button when the device credential is allowed. By default a check accepts biometrics only (disableBackup:true is sent to the plugin); allowDeviceCredential(boolean) lets the device's passcode, PIN, pattern or password stand in, which is the weaker option.

Every setter returns this prompt, so a prompt is built in one expression: new BiometricPrompt("Confirm the payment").description("Place your finger on the sensor").cancelText("Cancel"). A prompt is not thread safe while it is built; once handed to authenticate it is read only.

Author:
Christopher Mindus
  • Field Details

    • DEFAULT_TIMEOUT_MS

      public static final long DEFAULT_TIMEOUT_MS
      The default time the client has to answer a check: two minutes, more than the platforms give a prompt (Android's times out after about 30 seconds, with the platform's own code).
      See Also:
  • Constructor Details

    • BiometricPrompt

      public BiometricPrompt(String title)
      Creates a prompt.
      Parameters:
      title - The title: Android shows it as the prompt's title; iOS shows the description instead.
      Throws:
      NullPointerException - If title is null.
  • Method Details

    • subtitle

      public BiometricPrompt subtitle(String subtitle)
      Sets the subtitle, shown by Android under the title.
      Parameters:
      subtitle - The subtitle, or null for none.
      Returns:
      This prompt.
    • description

      public BiometricPrompt description(String description)
      Sets the description: Android shows it under the subtitle, iOS as the reason of its sheet ("Authentication" without one).
      Parameters:
      description - The description, or null for none.
      Returns:
      This prompt.
    • cancelText

      public BiometricPrompt cancelText(String cancelText)
      Sets the text of the cancel button: Android's negative button. iOS shows its own.
      Parameters:
      cancelText - The text, or null for the plugin's ("Cancel").
      Returns:
      This prompt.
    • fallbackText

      public BiometricPrompt fallbackText(String fallbackText)
      Sets the text of the fallback button, shown when the device credential is allowed: on iOS the button under the biometric sheet ("Use Passcode"), on Android the negative button of the prompt, which then leads to the device credential screen (the plugin's Android side labels that button with the cancel text; IIZI's client bridge gives it this text instead, so that the button says what it does).
      Parameters:
      fallbackText - The text, or null for the plugin's.
      Returns:
      This prompt.
    • allowDeviceCredential

      public BiometricPrompt allowDeviceCredential(boolean allow)
      Lets the device credential (passcode, PIN, pattern or password) stand in for a biometric: disableBackup:false is sent to the plugin. Off by default, so that a check accepts biometrics only. A caller that allows it cannot assume a biometric passed: the result's method is then BiometricResult.Method.UNKNOWN, since the plugin does not tell which one the user used.
      Parameters:
      allow - true to allow the device credential.
      Returns:
      This prompt.
    • allowEmulated

      public BiometricPrompt allowEmulated(boolean allow)
      Lets an answer of iiziRun Developer's biometric emulation (its Settings switch "Emulate Biometric auth", on a device without biometrics) count as success. Off by default: an emulated answer is then the error BiometricError.EMULATED. Even when allowed, an emulated answer counts only on a development server (the Designer's debug launch); on any other server it is BiometricError.EMULATED.
      Parameters:
      allow - true to accept an emulated answer on a development server.
      Returns:
      This prompt.
    • rejectVirtual

      public BiometricPrompt rejectVirtual(boolean reject)
      Refuses a client that reported that it runs on a simulator or an emulator (IBiometricAuthentication.isVirtual()): the check is not sent and the result is BiometricError.VIRTUAL_DEVICE. Off by default: the iOS Simulator and the Android emulator can answer a check (Features > Face ID > Matching Face, adb emu finger touch), which is what a developer wants, and the caller reads isVirtual() itself.
      Parameters:
      reject - true to refuse a virtual device.
      Returns:
      This prompt.
    • timeout

      public BiometricPrompt timeout(long timeoutMs)
      Sets the time the client has to answer, after which the result is BiometricError.TIMEOUT. The platforms end a prompt of their own before the default (DEFAULT_TIMEOUT_MS); a shorter time is for a caller that cannot wait that long.
      Parameters:
      timeoutMs - The time in milliseconds, positive.
      Returns:
      This prompt.
      Throws:
      IllegalArgumentException - If timeoutMs is not positive.
    • getTitle

      public String getTitle()
      Gets the title.
      Returns:
      The title, never null.
    • getSubtitle

      public String getSubtitle()
      Gets the subtitle.
      Returns:
      The subtitle, or null for none.
    • getDescription

      public String getDescription()
      Gets the description.
      Returns:
      The description, or null for none.
    • getCancelText

      public String getCancelText()
      Gets the text of the cancel button.
      Returns:
      The text, or null for the plugin's.
    • getFallbackText

      public String getFallbackText()
      Gets the text of the fallback button.
      Returns:
      The text, or null for the plugin's.
    • isDeviceCredentialAllowed

      public boolean isDeviceCredentialAllowed()
      Checks if the device credential may stand in for a biometric.
      Returns:
      true when allowed, false by default.
    • isEmulatedAllowed

      public boolean isEmulatedAllowed()
      Checks if an emulated answer counts as success on a development server.
      Returns:
      true when allowed, false by default.
    • isVirtualRejected

      public boolean isVirtualRejected()
      Checks if a virtual device is refused.
      Returns:
      true when refused, false by default.
    • getTimeout

      public long getTimeout()
      Gets the time the client has to answer.
      Returns:
      The time in milliseconds, DEFAULT_TIMEOUT_MS by default.
    • toString

      public String toString()
      Gets a text for debugging: the title and the options, never the other texts.
      Overrides:
      toString in class Object
      Returns:
      The text.