Implement Web event listeners

Last updated: October 28, 2024

To create a streamlined and successful user journey, implement the iProov event listeners.

Implementation details and examples: https://github.com/iProov/web#listeners

SDK claim lifecycle

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

Events

Event Description Implementation guidance Suggested user experience
ready A token has been provided to the SDK, iProov has initialized successfully, and has permission to access the camera.

  • Information log.

  • The start button is displayed.

 Customize the start button where appropriate.
connecting The SDK is connecting to the iProov server. Recommended debug logging. n/a
connected The SDK is connected. The iProov UI launches in full screen. Recommended debug logging. The SDK launches in full screen.
started The iProov SDK has launched in full screen mode and the user has started the claim process.

  • Information log.

  • If implemented via an iFrame, verify that full screen permission is allowed.

The SDK launches in full screen mode.
progress Authentication progress update.

  • This event may be called several times.

  • iProov recommends adding this to the debug logs.

 Display a progress indicator, messages are provided by the iProov system.
streaming Video is streaming to the iProov platform, full screen is still active. Recommended debug logging. n/a
streamed Streaming has completed and full screen has exited. Recommended debug logging. Display a progress indicator, messages are provided by the iProov system.
passed The iProov claim was completed successfully. You must call the validate endpoint to validate this token. See Verify enrolled users API.

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

  • Consider waiting for a response from the validate endpoint before the journey completes.
failed 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.
error

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.

 
mutiple_cameras

An array of camera devices is returned if:

  • The option enable_camera_selector is true.

  • More than one camera is detected.

 n/a The camera selection slot is displayed.
permission (LA only) Camera or motion permissions are unknown. Use the iProov support checker.

  • Display guidance.

  • Request the appropriate permissions.
permission_denied Permissions have been explicitly blocked by the user.

  • Log the event.

  • Display guidance about enabling permissions.

  • Show the user how to enable the required permissions.

  • By default, some browsers deny the required permissions, for example, Brave.
interrupted

  • The browser exits full screen mode. Can be caused by other software interrupting, for example, anti-virus software.

  • A retry is possible.

  • Can also occur if the user clicks ESC during full screen mode.

  • The same token can be used with a retry.

  • If a page reloads, a new token is required.

  • Offer a retry.

  • Include guidance to help the user perform a successful claim.

  • Add a message that the solution will launch in full screen.
cancelled The user clicked Exit during the full screen process. If a retry is offered, a new token is required.

  • Offer a retry.

  • Include guidance to help the user perform a successful claim.
unsupported The device or browser are not supported.

Log the following:

  • Device

  • Browser version

  • OS details

  • Display guidance.

  • Include information about supported browsers and devices.

 

Next step

Launch the Web SDK