Implement Android event listeners

Last updated: October 28, 2024

To implement a streamlined and successful user journey you must:

  • Implement the iProov event listener interface.

  • Register the listener with the activity.

Examples

See the implementation examples: https://github.com/iProov/android#register-a-listener

SDK claim lifecycle

The diagram below maps the possible events during an iProov Android SDK claim transaction. .

Events

Event Description Implementation guidance Suggested user experience
onConnecting

The SDK is connecting to the iProov server.

 Recommended debug logging. Depending on the journey, display a loading or progress indicator.
onConnected The SDK is connected and the iProov UI launches. Recommended debug logging. Hide the progress indicators. The iProov UI displays automatically.
onProcessing The claim is being processed and video streamed to complete the user authentication.

  • This callback event may be called multiple times.

  • iProov recommends adding the calls to the debug logs.

 Display a progress indicator. Descriptive messages are provided by iProov.
onSuccess The iProov claim was completed successfully. You must call the validate endpoint to validate this token. See the Verify enrolled users API.

  • Display a user success message. The user can proceed to the next step in the happy path.

  • Consider waiting for a response from the validate endpoint before the journey completes.
onFailure The claim was processed resulting in a failure code. May indicate a fraudulent attempt. Review the failure codes. Some codes will indicate a valid retry attempt with appropriate user guidance. Others will indicate that the GPA or LA claim has been rejected.

Depending on the failure code:

  • Offer a retry and provide guidance for completing a claim.

  • End the journey.
onError

iProov was unable to process the claim. There was a system failure establishing a connection or capture, or during the processing. The error reason is provided by iProov.

Log as an error. If the error occurred in the allowed number of retry attempts:

  • Start a retry flow.

  • Map the error reason to the appropriate user guidance messaging.

  • Offer a retry journey with guidance for resolving the error, for example, Give permission to access the camera.

  • For severe errors this may be the end of the journey , for example, unsupported devices.
onCancelled The user canceled the process by tapping Back. Log the incomplete user journey including the retry attempt number.

Offer a retry attempt and provide guidance for completing a claim.

See: Unhappy path

Android lifecycle events

Event Description Implementation guidance
onCreate

Activity onCreate override.

 You must register this activity as the iProov listener.
onDestroy Activity onDestroy override.

iProov strongly recommends unregistering the listener.

See: Android cleanup

Register the listener

Before launching the iProov SDK you must implement the interface and register the event listener. See this example: https://github.com/iProov/android#register-a-listener

Recommendation

Register the listener in the onCreate() method.

Important

If you do not register the listener before launching the SDK, an exception will be thrown.

Next step

Launch the Android SDK