Interface IBiometricAuthentication
- All Known Implementing Classes:
BiometricAuthentication
What it is. iiziRun's Face ID, Touch ID, Optic ID or fingerprint check through cordova-plugin-fingerprint-aio, asked for just before a sensitive step, a payment or a sign-in, as an extra precaution on top of the other authentication methods (CC-IIZIRUN-BIOMETRIC-API). Got from IClientSessionGyro.getBiometricAuthentication(), never null: a client that is not iiziRun answers "not available".
What the client reports. The server asks an iiziRun client for its report when the client session is created, and the report is cached here: isReported() says whether one arrived, and the getters answer from it; before it arrives, or in a client that is not iiziRun, they answer "not available". The report is asked again with requestReport(Consumer), since a user can enroll a face or a finger at any time. The report is the client's own statement.
The check. authenticate(BiometricPrompt, Consumer) sends the prompt to the client, which shows the platform's biometric prompt and answers; the callback runs on the worker of the application session, where every other answer of the client is delivered, never on the calling thread while it waits. A check that the client does not answer in time, a client session disposed of while it waits, and a second check while one waits are answered with the errors BiometricError.TIMEOUT, BiometricError.SESSION_CLOSED and BiometricError.IN_PROGRESS; the callback is always called exactly once.
Emulation. iiziRun Developer's Settings switch "Emulate Biometric auth" (shown on a device without biometrics) makes the client answer every check with an emulated success, which the client marks as such: isEmulated() reports the switch, and the result's BiometricResult.emulated() marks the answer. An emulated answer counts as success only when the prompt allows it (BiometricPrompt.allowEmulated(boolean)) and the server is a development server; otherwise it is the error BiometricError.EMULATED.
- Author:
- Christopher Mindus
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic enumWhether the device has a credential (passcode, PIN, pattern or password) that a prompt may let stand in for a biometric.Method Summary
Modifier and TypeMethodDescriptionintauthenticate(BiometricPrompt prompt, Consumer<BiometricResult> callback) Asks the user to pass the device's biometric check.Gets whether the device has a credential a prompt may let stand in.getType()Gets the kind of biometric the device offers.Gets the message the plugin answered with the reason.Gets why no biometric check can be made.booleanChecks if the client reported that it is an iPhone or iPad app running on an Apple-silicon Mac (device.isiOSAppOnMac), where the biometric check is the Mac's Touch ID or the user's password.booleanChecks if a check of this client session waits for the client.booleanChecks if a biometric check can be made: the plugin is present and reported a biometric type, or iiziRun Developer's emulation is on and this is a development server.booleanChecks if iiziRun Developer's biometric emulation is on: the client answers every check with an emulated success.booleanChecks if the client carries the plugin (window.Fingerprint).booleanChecks if the client has reported what it can do.booleanisStrong()Checks if the biometric is strong: on Android, class 3 (BIOMETRIC_STRONG, which the plugin'sisAvailablewithrequireStrongBiometricsanswers); on iOS every biometric is.booleanChecks if the client reported that it runs on a simulator or an emulator (Cordova'sdevice.isVirtual).intrequestReport(Consumer<IBiometricAuthentication> callback) Asks the client for its report again.
Method Details
isReported
boolean isReported()Checks if the client has reported what it can do.- Returns:
- true when a report arrived; false before it, after the client failed to answer within the deadline, and in a client that is not iiziRun.
isAvailable
boolean isAvailable()Checks if a biometric check can be made: the plugin is present and reported a biometric type, or iiziRun Developer's emulation is on and this is a development server.- Returns:
- true when
authenticate(BiometricPrompt, Consumer)can be expected to prompt the user.
getType
BiometricType getType()Gets the kind of biometric the device offers.- Returns:
- The type:
BiometricType.NONEbefore the report and when none is available,BiometricType.DEVICE_CREDENTIALwhen only the device credential is.
isStrong
boolean isStrong()Checks if the biometric is strong: on Android, class 3 (BIOMETRIC_STRONG, which the plugin'sisAvailablewithrequireStrongBiometricsanswers); on iOS every biometric is. A device whose only biometric is weak (class 2, face unlock on many Android phones) reports a type andfalsehere: the plugin's prompt accepts it all the same, so a caller that wants a strong one reads this.- Returns:
- true for a strong biometric, false when weak, not available or not reported.
getDeviceCredential
IBiometricAuthentication.DeviceCredential getDeviceCredential()Gets whether the device has a credential a prompt may let stand in.- Returns:
- The answer,
IBiometricAuthentication.DeviceCredential.UNKNOWNbefore the report.
isVirtual
boolean isVirtual()Checks if the client reported that it runs on a simulator or an emulator (Cordova'sdevice.isVirtual). The iOS Simulator and the Android emulator can answer a check (Features > Face ID > Matching Face,adb emu finger touch); the caller decides what that is worth, or refuses it withBiometricPrompt.rejectVirtual(boolean).- Returns:
- true for a virtual device, false otherwise or before the report.
isAppOnMac
boolean isAppOnMac()Checks if the client reported that it is an iPhone or iPad app running on an Apple-silicon Mac (device.isiOSAppOnMac), where the biometric check is the Mac's Touch ID or the user's password.- Returns:
- true on a Mac, false otherwise or before the report.
isEmulated
boolean isEmulated()Checks if iiziRun Developer's biometric emulation is on: the client answers every check with an emulated success.- Returns:
- true when on, false otherwise or before the report.
isPluginPresent
boolean isPluginPresent()Checks if the client carries the plugin (window.Fingerprint).- Returns:
- true when present, false otherwise or before the report.
requestReport
Asks the client for its report again. The callback gets this instance once the report arrived, or once the deadline passed without one (isReported()then says which, and a report that arrived earlier is kept); it runs on the worker of the application session. In a client that is not iiziRun, or when the session is disposed of, the callback is called at once with the state as it is.- Parameters:
callback- The callback, or null for none.- Returns:
- The request ID, or 0 when nothing was sent.
authenticate
Asks the user to pass the device's biometric check. The client shows the platform's prompt with the texts of the prompt and answers; the callback gets the result exactly once, on the worker of the application session. An error the server answers itself is delivered at once:BiometricError.IN_PROGRESSwhile another check of this client session waits,BiometricError.SESSION_CLOSEDwhen the session is disposed of,BiometricError.VIRTUAL_DEVICEwhen the prompt refuses a virtual device the client reported,BiometricError.NOT_IIZIRUNin a client that is not iiziRun. The others come from the client: a success, the plugin's error (BiometricError.BIOMETRIC_DISMISSEDfor a cancelled prompt, ...),BiometricError.PLUGIN_ABSENT; and the server'sBiometricError.TIMEOUTwhen the client does not answer within the prompt's timeout.A success is the client's own statement: see the class comment.
- Parameters:
prompt- What the user is shown and what the check accepts.callback- The callback, called exactly once.- Returns:
- The request ID, or 0 when nothing was sent and the callback was called at once.
- Throws:
NullPointerException- If a parameter is null.
isAuthenticating
boolean isAuthenticating()Checks if a check of this client session waits for the client.- Returns:
- true while one waits.