Implementation through an iframe

Initial steps

In order to allow the integrator client carry out the onboarding process entirely from their corporate domain, the integration with MobbScan Gateway can be carried out through an <iframe>, for which it is only necessary to add an HTML <iframe> tag to their HTML page.

Example code:

<iframe allow="camera; microphone" src="{{ onboardingUrl }}"></iframe>

The src attribute of the <iframe> contains the onboardingUrl obtained by the integrator client server in the /onboarding/token endpoint response.

Finally, it is necessary to add the allow attribute with the values of camera (mandatory) to request the end user permission to access the camera of their device and microphone (optional, depending on the flow it may be necessary) to request access permission to the microphone of your device.

With this configuration, the user will be able to start the onboarding process in their browser.

During the process, the MobbScan Gateway component will send important event messages to the parent page through the <iframe>, so that the integrator client front can perform certain actions. The parent page can receive the message by registering a listener on the window object and perform some action based on the received event.

The types of events that the parent page can receive have been categorized as informative or error, as detailed below:

Informative events

These events report an event that occurred during the process, and are merely informative.

• OnboardingStarted: The user has started the onboarding process.
• OnboardingFinished: The user has completed the onboarding process, either because he has done all the steps correctly or because an error has occurred during the process.

Example code:

// Allow window to listen for a postMessage
window.addEventListener("message", (event) => {
  // Always verify the sender's identity using the origin and source properties to avoid security leaks
  if (event.origin !== onboardingUrl) return;

  const { onboarding, type, value } = event.data; // onboarding contains onboardingUrl, scanId and token

  const { name } = value; // Info type

  if (type === "Info") {
    switch (name) {
      case "OnboardingStarted":
        // The onboarding process has started
        break;

      case "OnboardingFinished":
        // The onboarding process has finished
        break;

      default:
        break;
    }
  }
});

At the end of the process, the MobbScan Gateway component will perform two actions:

1. Send from the <iframe> to the parent page an event of type info with the value "OnboardingFinished".

2. Make an automatic redirect to the redirectUrl that the integrator client server has indicated in the body of the request to the endpoint /onboarding/token, as long as the value is not empty or null.

Error events

These events report an error that occurred during the process, especially at the beginning, and make it impossible to continue the process.

• ConnectionError: The user's device does not have a stable network connection or is not available.
• HardwareError: The user's device does not have a camera and/or microphone (if necessary), or is not available for use due to a hardware problem.
• OnboardingError: The onboarding process has been canceled because the user has not passed any of the validations.
• PermissionError: The user has not granted access permissions to the camera and/or microphone (if required).
• SupportError: The onboarding process cannot be completed because an unexpected error has occurred (contact us to report it).
• TimeoutError: The onboarding process has been canceled because the user has exceeded the maximum time set.
• TokenError: The onboarding token has expired and is no longer valid.

Example code:

// Allow window to listen for a postMessage
window.addEventListener("message", (event) => {
  // Always verify the sender's identity using the origin and source properties to avoid security leaks
  if (event.origin !== onboardingUrl) return; // onboarding contains onboardingUrl, scanId and token

  const { onboarding, type, value } = event.data;

  const { extraInfo, message, name } = value; // Error type

  if (type === "Error") {
    switch (name) {
      case "ConnectionError":
        // Suggest the user to check the network settings of the device
        break;

      case "HardwareError":
        // Suggest the user to perform the process with another device
        break;

      case "OnboardingError":
        // Some onboarding errors may have additional information, such as a more specific cause or an array of failed validations.
        const { cause, failedValidations } = extraInfo;
        // Example of error object value with name, message and extraInfo property
        /* const extraInfo = {
            cause: {
                message:'The scanning process has not passed all validations',
                name: 'ValidationError'
            },
            message:'There was an error performing the onboarding process.',
            name: 'OnboardingError',
            failedValidations: ['validationDocumentNotExpired']
        } */

        if (failedValidations.includes("validationDocumentNotExpired")) {
          // Inform the user that their document has expired and is invalid
        }
        break;

      case "PermissionError":
        // Ask the user to allow access to the camera and/or microphone
        break;

      case "TimeoutError":
        // Get a new token and reload the iframe
        break;

      case "TokenError":
        // Get a new token and reload the iframe
        break;

      case "SupportError":
        // Contact support
        break;

      default:
        // Get a new token and reload the iframe
        break;
    }
  }
});