MobbScan Web: Scanning Documents

Introduction

As seen in the previous section, the scan of a document can be performed after the SDK has been initialized by setting a detectionListener and calling the MobbScanAPI.start method:

const onDetection = (result, data, error) => { /* your code */ };
MobbScanAPI.setDetectionListener(onDetection);
MobbScanAPI.start(/*options*/);

Once all the data has been gathered, the document sides should be checked with the server with the following method:

MobbScanAPI.scan(frontImage, backImage, listener);

In the following sections all these methods will be described in detail.

MobbScanAPI.start

This method renders one or two clickable HTML elements which open the webcam to scan a document side. The method takes three arguments:

  • documentType (string): Type of document that will be scanned. Check the supported document types.

  • operationMode: There are three supported values:

    • SCAN_ONLY_FRONT: This mode renders an element to scan the document front side.

    • SCAN_ONLY_BACK: This mode renders an element to scan the document back side.

    • SCAN_BOTH_SIDES: This mode renders two elements to scan both sides of a document in the same page.

    NOTE: If a document with only one side will be scanned (like Passport_TD3), the mode SCAN_ONLY_BACK should be used.

  • scanStartListener: A listener that is triggered when the MobbScan API starts. This listener will receive three arguments:

    • result: This value can take OK or ERROR values.

    • data: If result is OK, this parameter will be an object with a scanId attribute that is a unique identifier for the whole scan process. Also, it can be used to find the current scan data in the Validation Portal.

    • error: If result is ERROR, this parameter will contain a string with a description of the error.

MobbScanAPI.setDetectionListener

This method sets a listener that is going to be called every time that a frame is scanned by MobbScan. This listener will receive three arguments:

  • result: A string which indicates the result of the last detection:

    • STARTED: Nothing has been detected.

    • CAPTURING: A document has been detected, but the server should check the image.

    • DETECTED: The detection has been confirmed by MobbScan server.

    • NOT_DETECTED: The document could not be detected.

    • NOT_FOCUSED: The document has been rejected due to it is too blurry.

    • TIMEOUT : A timeout error has occurred during the document detection process. If you want to know more about this, you can go to Error Handling section.

    • ERROR: An error has ocurred during the process.

  • data: An object which contains data about the current detection process. Relevant attributes:

    • source: Source of the processed image. It can take the following values:

      • WEBCAM
      • FILE
      • MOBILE
      • PDF

    • side: Side of the document that is being processed. It can contain the following values:

      • FRONT
      • BACK

    • image: This attribute will be available when the result is DETECTED. It is a Blob that contains the image of the detected document side. This image should be used with the method MobbScanAPI.scan() to complete the scanning of a document.

    • focusScore: This attribute will be available when the result is NOT_FOCUSED. It's a value that indicates the level of blurry of the image, when it value is near 0 is more focused.

  • error: If an error happens, this paremeter will contain further details about said error. If you want to know more about the information received in this field, you can go to Error Handling section.

MobbScanAPI.scan

This method should be called when both sides have been captured with the listener set to MobbScanAPI.setDetectionListener. This method needs the following arguments:

  • frontImage: Blob which contains the image of the front side of detected document. It can be retrieved in the listener defined in MobbScanAPI.setDetectionListener.

  • backImage: Blob which contains the image of the back side of detected document. It can be retrieved in the listener defined in MobbScanAPI.setDetectionListener.

  • listener: A callback that will be called when the scan process finishes. It receives the following parameters:

    • result: It indicates the scan result. It could take the following values:

      • OK
      • ERROR

    • data: This object contains all the extracted data and validation results in the document attribute.

    • error: In case of an error, this parameter will contain further details about it. If you want to know the most relevant errors, you can go to Error Handling section.

Uploading images from a file browser

It is possible to carry out this process on an uploaded image from the device's file explorer. To enable this feature you only have to call setFileBrowserEnabled method before starting the component, as following:

 MobbScanAPI.setFileBrowserEnabled(true);

Example

    // Sets license
    MobbScanAPI.initAPI('YOUR LICENSE HERE');
    // Sets base url
    MobbScanAPI.setBaseURL("https://yourmobbscaninstance.com");
    // Sets placeholder
    MobbScanAPI.setPlaceholder('mobbscan-placeholder');
    // Enables file browser feature
    MobbScanAPI.setFileBrowserEnabled(true);
    // This listener is called when a frame has been analyzed or detection starts
    MobbScanAPI.setDetectionListener(onDetectionResult);
    // If you want to use the native mode on mobile you have to call this method
    MobbScanAPI.enableVideoMobileCapture();
    // Sets the timeoutListener
    MobbScanAPI.setTimeOutListener(console.error);
    // Sets the timeoutListener on mobile
    MobbScanAPI.setTimeOutListenerVideoMobile(console.error);
    // Sets the error accessing camera
    MobbScanAPI.setErrorAccessingCamera(console.error);
    // Starts scanning
    MobbScanAPI.start(documentType, operationMode, (result, resultData, error) => console.log('API has started with scan id: ', resultData.scanId));


    function onDetectionResult(result, data, error) {
        if (error) {
            console.error(error);
        }

        // If the result is "DETECTED" whe should inspect on which side of the document.
        if (result === MobbScanDetectionResult.DETECTED) {
            const detectedSide = data.side;
            const image = data.image;

            if (detectedSide === MobbScanDocumentSide.FRONT) {
                // Saving the detected image for next step
                documentFrontImage = image;
            } else if (data.side === MobbScanDocumentSide.BACK) {
                // Saving the detected image for next step
                documentBackImage = image;
            }

            // Create some variables to determine if both sides are already scanned
            const documentDetected = !!documentFrontImage && !!documentBackImage;

            if (documentDetected) {
                // When boths sides are ready, call `scan` with both detected images so the server checks that bots sides match
                MobbScanAPI.scan(documentFrontImage, documentBackImage, (result, data, error) => {
                    // Callback called when `scan` request finishes
                    if (result === MobbScanScanResult.ERROR) {
                        // ...
                    }
                    if (result === MobbScanScanResult.OK) {
                        // ...
                    }
                });
            }
        }
    }