Listening for Authentication events

Now that we’ve built our authentication dialog we need to provide a way to listen for authentication events from our users. For this, we can provide an instance of the AuthenticationCallback to our dialog. This callback will return us with one of four states when an authentication flow is carried out:

onAuthenticationError

This will be called when an unrecoverable error has occurred. At this point the authentication flow has finished without success. The callback will be provided with an error code (Int) to identify the cause of the error, along with the error message (CharSequence). We can use these two to let our user know why authentication has failed. The error code returned at this point will be either:

FINGERPRINT_ERROR_CANCELED — The fingerprint sensor is unavailable. This could be due to events such as the device being locked or some other operation has taken place

FINGERPRINT_ERROR_HW_NOT_PRESENT — The device does not have a fingerprint sensor

FINGERPRINT_ERROR_HW_UNAVAILABLE — The device hardware is currently unavailable

FINGERPRINT_ERROR_LOCKOUT — Too many fingerprint attempts have been made, this happens after 5 failed attempts. The user will be able to try again in 30 seconds time

FINGERPRINT_ERROR_LOCKOUT_PERMANENT — Too many FINGERPRINT_ERROR_LOCKOUT errors were thrown, meaning that fingerprint authentication is locked until a strong authentication has been carried out (pin, pattern or password)

FINGERPRINT_ERROR_NO_FINGERPRINTS — This error will be thrown when the user does not have any fingerprints registered on the device

FINGERPRINT_ERROR_NO_SPACE — Thrown when there is not enough storage space on the device to complete the requested operation

FINGERPRINT_ERROR_TIMEOUT — This error occurs when the authentication request has been open for too long. Whilst this is dependant on device / platform, it is generally around 30 seconds

FINGERPRINT_ERROR_UNABLE_TO_PROCESS — The sensor was unable to process the fingerprint image that it received

FINGERPRINT_ERROR_USER_CANCELED — The user cancelled the fingerprint authentication process

FINGERPRINT_ERROR_VENDOR — A vendor specific error that vendors can use to provide specific errors if one of the above is not applicable

onAuthenticationHelp

This will be called when a recoverable error has occurred during the authentication process. The callback will be provided with an help code (Int) to identify the cause, along with a help message (CharSequence). The message is a human readable string, so we can use this to let our user know why the recoverable error has occured.

FINGERPRINT_ACQUIRED_IMAGER_DIRTY — Returned when the retrieved fingerprint was too dirty to read, prompting the user to try cleaning their sensor

FINGERPRINT_ACQUIRED_INSUFFICIENT — The retrieved fingerprint image was too noisy. This could be due to several reasons but is used as a general type for when the image isn’t enough to perform authentication

FINGERPRINT_ACQUIRED_PARTIAL — Only a partial fingerprint was detected, at this point you would prompt the user to try using the sensor again in a different manner

FINGERPRINT_ACQUIRED_TOO_FAST — The user moved their finger away from or around the sensor too quickly, at this point you would prompt the user to try again with less speed

FINGERPRINT_ACQUIRED_TOO_SLOW — The fingerprint was not readable as there was a lack of motion from the user on the fingerprint sensor.

onAuthenticationSucceeded

When the authentication process is successful, this callback will be triggered. At this point we will receive an instance of an AuthenticationResult which we can use to adapt our UI to.

onAuthenticationFailed

If the authentication process fails due to the fingerprint not being recognised, then this callback will be triggered.