Android SDK unhappy paths
Last updated: October 28, 2024
There are several possible unhappy paths in the iProov claim process. It is essential that you provide user guidance, directions, and education to ensure successful retries and to prevent drop offs.
There are three types of unhappy responses during a claim lifecycle:
See the implementation examples on GitHub: https://github.com/iProov/android/#handling-failures--errors
Select an SDK version
To display exceptions, errors, and failures that are applicable to your environment, select a version of the Android SDK:
Launch exceptions
These are exceptions that should be caught when calling launch() and prevent the SDK from launching.
| Exceptions (launch()) | Description | Suggested resolution action |
|---|---|---|
ListenerNotRegisteredException
|
The iProov listener has not been registered or thelaunch()method is called before callingregisterListener(). |
Verify that the listener is registered. iProov recommends registering in the onCreate() method. |
MultiWindowUnsupportedException
|
The user attempted to use iProov in split-screen/multi-screen mode (not supported). |
Display an appropriate error message and instruction to the user. Try and relaunch. |
CaptureAlreadyActiveException
|
An iProov capture is already in progress. | Wait until the current iProov claim has completed and try again. |
Errors
An error occurs when a user is unable to complete an iProov verification process. For example, the internet connection failed or the user aborted the process.
Corrective measures, user guidance, and retries should be implemented.
| Exceptions (onError) | Description | Suggested resolution action |
|---|---|---|
CameraException
|
An error occurred acquiring or using the camera. Applicable when using the external camera support. | Fatal exception, end the journey. |
CameraPermissionException
|
The user did not allow access to the camera when prompted. | Prompt the user to enable the camera permission (in Settings). |
FaceDetectorException
|
An error occurred with the face detector. |
Fatal error:
|
UnexpectedErrorException
|
An unrecoverable error has occurred during the transaction. |
A fatal error has occurred, attempt a retry. Report clusters of this error type to iProov support. |
ServerException
|
The token was invalidated server-side or some other unrecoverable server error occurred. |
End the journey and display this message: Try again later. |
NetworkException
|
An error occurred with communications to the server. Typically indicates a device connectivity issue, for example, the user's session has timed out or the internet service has been lost. | Prompt the user to reconnect to a suitable cellular or WiFi network and then retry. |
UnsupportedDeviceException
|
The device is not supported, for example, does not have a front-facing camera. |
End the journey and provide steps for the user to restart on a compatible device. Direct the user to an FAQ or support channel detailing the device requirements. |
InvalidOptionsException
|
An error occurred when trying to apply your options. | Log and report device details to iProov. |
Failures
A failure occurs when iProov successfully processes a claim but a user's face cannot be authenticated. For example, the user did not pass the biometric tests and/or machine learning models.
Retry measures are recommended, however, caution should be taken to ensure that potential fraudsters are not given unlimited attempts. For details see API retry mechanism.
| Exceptions (onFailure) | Description | Suggested resolution action | Assurance types |
|---|---|---|---|
unknown
|
The claim failed for an unknown reason. | Try again. | GPA and LA |
too_much_movement
|
The user is moving too much during the claim. | Keep still. | GPA |
too_bright
|
Possible causes:
|
Move somewhere darker. |
GPA Available soon in LA. |
too_dark
|
The user’s environment is too dark. | Move somewhere brighter. |
GPA Available soon in LA. |
misaligned_face
|
User's face is not aligned with the oval. | Keep your face in the oval. | GPA |
eyes_closed
|
One or both of the user's eyes are not open. | Keep your eyes open. |
GPA Available soon in LA. |
face_too_far
|
The user is too far from the device. | Move your face closer to the screen. | GPA |
face_too_close
|
The user is too close to the device. | Move your face farther from the screen. | GPA |
sunglasses
|
The user is wearing glasses with dark lenses. | Remove sunglasses. |
GPA Available soon in LA. |
obscured_face
|
The user's face is not completely visible. | Remove any face coverings. |
GPA Available soon in LA. |
user_timeout
|
Try again. | GPA and LA | |
not_supported
|
Device is not supported. | GPA and LA | |
ambiguous_outcome
|
A claim reject status, either GPA/LA or a face match reject (if applicable).  Warning
Could indicate a fraudulent attempt. |
If in the retry attempt quota, offer a retry. |
|
motion_too_much_movement
|
The user is moving too much during the claim. |
Provide user guidance to remain still during the claim. Retry the claim. |
|
lighting_flash_reflection_too_low
|
The ambient light is too strong or the screen brightness is too low. |
Ask the user to turn their screen brightness up to maximum or move out of the direct sunlight. Retry the claim. See also: Customize the Android user interface |
|
lighting_backlit
|
A strong light source has been detected behind the user. |
Ask the user to adjust their position relative to the light source. Retry the claim. |
|
lighting_too_dark
|
The user’s environment is too dark. |
Ask the user to move to an area with more light. Retry the claim. |
|
lighting_face_too_bright
|
Too much light has been detected on the user’s face. |
Ask the user to adjust their position relative to the light source. Retry the claim. |
|
motion_too_much_mouth_movement
|
The user is talking during the claim. |
Ask the user to refrain from speaking during the claim process. Retry the claim. |
|
failure_user_timeout
|
The session has expired. |
Verify that the user timeoutSecs setting has not been set to a value lower than recommended. If data indicates a poor network, offer a retry with a higher timeout value. |
Next step
