MobbScan Cordova: Scannig Documents

Document scanning

As seen in the previous section, a document scan process can be performed after the SDK has been initialized. It can be executed as shown in this example:

let currentScanID;
const documentType = "ESPIDCard";

const onStartSuccess = (scanID) => {
  MobbScanAPI.scanDocumentForSide({ value: MobbScanDocumentSide.FRONT }, scanId, console.log, console.error);
};

const onNewImage = (message) => {
  const result = message.detectionResult;

  if (result === "OK") {
    const documentSide = message.documentSide;
    const image = message.image;
    console.log("Side", documentSide, "detected!");
    console.log("Captured image", image);
  }
};
const onNewData = (validationData) => console.log;

MobbScanAPI.startScanForDocumentType({ value: documentType }, { value: operationMode }, onStartSuccess, console.error);
MobbScanAPI.setScanDocumentImageCallback(onNewImage);
MobbScanAPI.setScanDocumentDataCallback(onNewData);

Let's analyze the workflow:

1. First of all, MobbScanAPI.startScanForDocumentType should be called. If everything goes well, this method will call onStartSuccess with an scanID. This ID will identify the whole scan process.

2. When a scanID has been retrieved, the scan of a document side can be initialized with the method MobbScanAPI.scanDocumentForSide, which will open the camera UI to scan the defined side of the indicated document type. There are two extra callbacks to check if the scan process has been initialized correctly (third and fourth parameters). However, the detected document images and other related data will be sent to the callbacks set with MobbScanAPI.setScanDocumentImageCallback and MobbScanAPI.setScanDocumentDataCallback.

3. In the callback set by MobbScanAPI.setScanDocumentImageCallback, the detection results and captured images will be received.

4. In the callback set by MobbScanAPI.setScanDocumentDataCallback, extracted data from the document will be received.

These methods will be discussed in detail in the following sections.

MobbScanAPI.startScanForDocumentType

This method will start a scanning process for a document, and it will generate an scanID that should be used in all operations related the scan and verification of that document.

This method has the following arguments:

• documentType: The type of document you want to scan. This could be any value listed in our supported documents guide.

• operationMode: There are three supported values:

  • MobbScanOperationMode.SCAN_ONLY_FRONT
  • MobbScanOperationMode.SCAN_ONLY_BACK
  • MobbScanOperationMode.SCAN_BOTH_SIDES

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

• successCallback: A function that will be executed when the method finishes successfully. That method will receive a string argument with the scanID that you provide in methods like scanDocumentForSide().

• failureCallback: A function that will be executed if some error takes place during the scan initialization.

MobbScanAPI.scanDocumentForSide

This method opens the camera UI and starts the scanning of the given document side. It allows the following arguments:

• documentSide : The side of the document that will be scanned. It supports the following values:

  • MobbScanDocumentSide.FRONT
  • MobbScanDocumentSide.BACK

• scanId: Identifier of the scan process provided by MobbScanAPI.startScanForDocumentType.

• successCallback: A function that will be called when the side detection finishes successfully. The method will receive a string with extra info for debugging and logging purposes.

• errorCallback: A function variable that will be executed if the method does not finish successfully. The method will receive a string with extra info for debugging and logging purposes.

MobbScanAPI.setScanDocumentImageCallback

This method sets a callback that will be called when a MobbScanAPI.scanDocumentForSide call detects and captures a document image. The method has only one argument, the callback, and this one will receive an object with the following attributes:

• detectionResult: This could be "OK" (if the document side has been detected) or "PROCESS_CANCELLED" (if the user has cancelled the process).
• documentSide: Detected document side. It could be "BACK" or "FRONT".
• image: Image of the captured document encoded in base64.

MobbScanAPI.setScanDocumentDataCallback

This method sets a callback that will be called when a detection started by MobbScanAPI.scanDocumentForSide finishes the data extraction and validation of a document.

MobbScanAPI.setScanDocumentDataCallback has only one argument, the callback, and this one will receive an object with all the data extracted from the detected side and the result of some validations performed by MobbScan. More details of this object can be found here.

Detect and scan in different calls

From v2.19.4 you can perform the detection and scanning operations in different calls, in case you need to split these behaviours:

MobbScanAPI.detectDocument

This method throw the MobbScan detection interface and performs the document detection process. The detected image will be returned in the callback that you setted in the method setScanDocumentImageCallback.It allows the following arguments:

• documentSide : The side of the document that will be scanned. It supports the following values:

  • MobbScanDocumentSide.FRONT
  • MobbScanDocumentSide.BACK

• successCallback: A function that will be called when the side detection finishes successfully.

• errorCallback: A function variable that will be executed if the method does not finish successfully.

MobbScanAPI. scanDocument

This method performs an scanning process using a detected image provided by the previous method. The scanning data will be returned in the callback that you setted in the method setScanDocumentDataCallback.

It allows the following arguments:

• documentSide : The side of the document that will be scanned. It supports the following values:

  • MobbScanDocumentSide.FRONT
  • MobbScanDocumentSide.BACK

• image: A base64 image. This must be a detected document image. Otherwise, the scanning process will not be able to get the ocr data.

• scanId: Identifier of the scan process provided by MobbScanAPI.startScanForDocumentType.

• successCallback: A function that will be called when the side detection finishes successfully.

• errorCallback: A function variable that will be executed if the method does not finish successfully.

QA Control

Since version v2.18.5, the MobbScan Plugin allows the developers to enable or disable the detection QA controls.

These controls are a set of checks that ensure that the detected image have the necessary quality to scan the document or validate the face later.

In order to do this, you must create an instance of the object MobbScanConfiguration and initialize the MobbScan API using it:

var msConfiguration = new MobbScanConfiguration();
msConfiguration.checkDocumentPosition = true;
msConfiguration.checkFacialPosition = true;

. . .

MobbScanAPI.initAPIWithLicenseAndConfiguration("YOUR_LICENSE_HERE",msConfiguration, success, failure);

All of these parameters are boolean which are set true by default. The QA parameters that you can enable or disable are those:

Document Detection QA Checks

Parameter	Comment
checkDocumentLightness	Check the ambient light is neither too dark nor too shiny.
checkDocumentPosition	Check the document is placed within the detection box, and it is neither too far nor too near.
checkDocumentSparkles	Check there are no sparkles on the document image.
falsePositive	Check the document side is the one we are looking for.

Facial Detection QA Checks

Parameter	Comment
checkFacialLightness	Check the ambient light is neither too dark nor too shiny.
checkFacialPosition	Check the face of the user is placed within the frame, and it is neither too far nor too near.
checkFacialMask	Check the face is not covered by a mask.
checkFacialFocus	Check the image of the face is focused.

MRZ Scanning

MobbScan also supports the scan of the MRZ part of a document, ignoring the rest of the data. The process is very similar to the "Document scanning" process, but you should change the MobbScanAPI.startScanForDocumentType call for this one:

MobbScanAPI.startScanForDocumentMrz(documentType, operationMode, mrzMode, successCallback, failureCallback);

The parameters are the following:

• documentType: It should be MobbScanDocumentType.IDDocumentMrz.

• operationMode: It should be MobbScanOperationMode.SCAN_ONLY_BACK.

• mrzMode: This argument accepts the following three values:

  • "DEFAULT": In this mode, when the MRZ is detected, the full image will be sent to the client.

  • "WITH_CROPPED_DOCUMENT": In this mode, when the MRZ is detected, MobbScan will try to crop the MRZ in the captured image.

  • "FORCE_CROPPED_DOCUMENT": In this mode, the process will not be considered finished until MobbScan could crop the MRZ in the document.

• successCallback: A function that will be executed when the method finish successfully. That method will receive a string argument with the scanID that you will provide in methods like scanDocumentForSide().

• failureCallback: A function that will be executed if some error happens during the scan initialization.

The results of the MRZ scan process will be notified to the callbacks set by MobbScanAPI.setScanDocumentImageCallback and MobbScanAPI.setScanDocumentDataCallback.