We’ve had access to finger print readers in android for some time now. With Android Marshmallow we saw some API feature that allowed us to perform Fingerprint Authentication within our apps. Whilst this feature allowed us to achieve that authentication process within our applications, but what does this new FingerPrint dialog offer us? Well, one of the core reasons for this is to create a dialog with a authentic look & feel, provided by the system, in order to increase trust between the user and the application they are authenticating with. With the current fingerprint authentication dialog, applications can provide their own styled prompts — so with Android P there is a hope to change this approach to the process.
When using the new Fingerprint Dialog within your application, it will be shown like so:
Looks pretty neat, huh? We can present this dialog to our user when we want to authorise some operation which is being carried out. When presented with the Fingerprint dialog, there are some different situations which the flow can result in:
- The user can press ‘Cancel’ to dismiss the dialog
- The user can carry out a successful fingerprint authentication flow
- The user can carry out an unrecognised fingerprint authentication flow
- The user can attempt fingerprint recognition too many times, resulting in a failure
Now we know what the dialog can do and what it looks like, let’s take a little look at how we can implement it in our apps!
Building a fingerprint dialog instance
We can create a new FingerprintDialog instance by making use of the handy builder that comes with the class:
https://gist.github.com/hitherejoe/05606a6dc3e40522c9b9656f7d870208
Using the builder we can:
- Set a title using setTitle() — A title is required for the fingerprint dialog
- Set a subtitle using setSubtitle() — Providing a subtitle is optional
- Set a description using setDescription() — Providing a description is optional but should be provided to give context to your user
- Set a negative button using setNegativeButton() — This is a required part of the dialog builder. You must provide some text for the button, an Executor instance and a click listener.
Note: You can’t customise the icon or error message that are used within the dialog.
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.
Prompting authentication
Now that we’ve built our dialog and defined a callback to be used for authentication events, we can go ahead and trigger the authentication process. This call can be made like so:
dialog.authenticate(cancellationSignal, executor, callback)
Here we use the authenticate function to display the fingerprint authentication dialog to the user. We pass in three parameters to this function:
- A CancellationSignal instance — This can be used to cancel the authentication process at some point during the lifecycle of the flow
- An Executor instance — Used to handle the execution of events carried out by the fingerprint dialog
- Our Authentication Callback instance — Used to receive events triggered during the authentication process
Once we’ve called authenticate, our user can carry out the authentication flow and we will receive the result through the provided callback. At this point we will handle the result within our user interface.
Conclusion
With Android P coming sometime in the near-future, I hope this post has given you an insight into how the new Fingerprint Dialog works in-order for you to implement it (or switch our the previous implementation) into your applications. If you have any questions or thoughts on this new dialog then I’d love to hear from you!