MobbScan Web: Scan & Record Video with custom interface

Introduction

MobbScan includes an agent to get more information about how users behave during the scan of their documents and faces. It is a separate portal to the Validation portal and it is not mandatory for document and face matching. However, if video recording of the scan process is needed, your server installation must have the agent installed.

Configuration

To enable video recording, you should add in your head HTML element an additional script, replacing {version} with your current MobbScan Video version (which could differ with the MobbScan Web version, but they are bundled together in the same distribution file), and specifying the correct path to your mobbscan-api folder:

<script type="text/javascript" src="../mobbscan-api/mobbscan-videoapi-{version}.min.js"></script>

Obviously, to enable the functions common to the rest of the processes, the main script must be included, replacing {version} with your current MobbScan SDK version:

<script type="text/javascript" src="../mobbscan-api/mobbscan-api-{version}.min.js"></script>

As well as the script corresponding to face detection:

<script type="text/javascript" src="../mobbscan-api/mobbscan-api-face-{version}.min.js"></script>

The process to integrate this feature is similar as described on previous docs. You have to initialize the SDK following these steps:

MobbScanAPI.initAPI('YOUR_LICENSE_HERE');
MobbScanAPI.setTimeOutListener(timeOutListener);

The location of MobbScan recording UI should be defined in a separate method (remove the MobbScanAPI.setPlaceholder call if it exists):

MobbScanAPI.setPlaceholderRecord('mobbscan-placeholder');

In order to configure the URL of your MobbScan Agent instance, you should call setBaseURL:

MobbScanAPI.setBaseURL("https://your-mobbscan.com/mobbscan-agent");

To enable the face detector you should call setFaceDetectionEnabled to show on unattended video:

MobbScanAPI.setFaceDetectionEnabled('true');

Start process

After that, you can call the startUnattendedVideoCustom method to start the process:

MobbScanAPI.startUnattendedVideoCustom(DOCUMENT_TYPE, OPERATION_MODE, recordListener, recordTimeout*);

function recordListener(result, data, error) {

}

*recordTimeout is an opcional parameter to limit the video record total duration.

Please note that when the MobbScanAPI.startUnattendedVideoCustom is called it will render a video DOM on provided placeholder, so you should manage everything in recordListener, which is described below.

Detect document

To start the detect document process you must call detectDocument to start the process.

Usually we fire this method when WAITING event is triggered to start the detect process for front or back side in case of the document to scan would be a Passport.

Furthermore, we call this method after DETECTED event with data.side equals to MobbScanDocumentSide.FRONT if the document is not a passport.

MobbScanAPI.detectDocument();

Detect Face

After scanning the both sides of the document you can end the process or launch the facial matching with the provided face detector. To launch the face matching you must call detectFace.

We usually call this method once the DETECTED event is triggered with data.side equals to MobbScanDocumentSide.BACK.

MobbScanAPI.detectFace();

In addition, we call addFaceOverlay before detectFace to append to the interface the default overlay with progress bar provided on the SDK. This step is optional and if you have a custom interface to detect face it can be omitted.

MobbScanAPI.addFaceOverlay();
MobbScanAPI.detectFace();

Stop record

You must call this method to complete the process and save the video on MobbScan Agent:

MobbScanAPI.stopRecord();

How to use

As stated above, there is a new listener to be specified using MobbScanAPI.setRecordListener. This listener will be triggered during the recording process (that automatically starts when the users click the "Start" button) and will receive the following three arguments:

  • result: Type of event. The supported results are the following:

    • START_VIDEO_SUCCESS: It is triggered when the overall process starts. In this case, data will be an object with the current scanID.

    • VIDEO_ATTACHED: It is triggered when has been attached

    • MINUTES_LEFT: Represents the remaining time to connect with the video.

    • WAITING: It is triggered when video is attached to DOM and all elements are ready to detect and scan document.

    • STARTED: It is triggered when a document scan or face detection starts. In the first case, data will contain a source attribute describing the source of the images (typically WEBCAM or MOBILE) and the side of the document (FRONT or BACK).

    • SCAN_STARTED: Same as STARTED but without the side attribute in data.

    • CAPTURING: It is triggered when a document or a face has been detected, but the server should check the image.

    • NOT_DETECTED: It is triggered when the document could not be detected.

    • NOT_FOCUSED: It is triggered when the document has been rejected due to it is too blurry.

    • DETECTED: It is triggered when a document or a face is detected.

    • OK: This event can be received in two separate occasions:

      • When the scan document process or the overall process ends. In this case, data will be an object that contains the results obtained from the process.

    • FINISHED: It is triggered when the process finishes. The data will contain an attribute named finishedByClient which indicates who has finished the process.

    • FINISHED_WITH_ERRORS: It is triggered when the video record finishes with error during the process.

    • PROCESS_CANCELLED: It is triggered when the process has been cancelled.

    • TIMEOUT: It is triggered when a timeout error has ocurred during video record. If you want to know more about this, you can go to Error Handling section.

    • WRONG_PARAMETERS_ERROR: It is triggered when the timeout specified on start method is out of bound.

    • ERROR: It is triggered when an error has ocurred during the process.

  • data: It contains an object with the data of process. This information changes according to the point of the process:

    • When the scan document process ends. In this case, data will be an object with the following attributes:

      • code: If everything is fine, it will be OK.

      • description: SCAN_DOCUMENT_SUCCESS.

      • scanId: The scan id of the process.

      • document: The ID document data extracted from the image.

    • When a face is detected. In this case, data will be an object with the following attributes:

      • side: On this step it always will be FACE.

      • image: Blob with the image of the cropped face.

    • When the overall process ends. In this case, data contains another data object with the following attributes:

      • code: If everything is fine, it will be OK.

      • description: Readable description of the result. If everything is fine, it will be VALIDATE_SUCCESS.

      • type: Type of scan (typically FACE).

      • state: It could be VALID if the document is scanned successfully and the face matches, or INVALID otherwise.

      • score: Score of the scan over 100. It is a score over 100 that represents the similiraty between the face which appears in the document and the face detected by MobbScan. It can be used to establish your own threshold instead of relying on the state field.

  • error: In case of an error, this parameter will contain further details about it. If you want to know more about the information received in this field, you can go to Error Handling section.

Video styles

When you use this component the SDK appends a video element tag to the DOM of the specified placeholder. This video is attached with an empty class name that changes depending of type of detection. These classes are:

  • videoDetect: This class is active while document detector is running.
  • videoDetectFace: This class is active when face detector is running.

The suggested values for these classes are the following:

/*
*If the device is a desktop device you must set camera rotation to 180 degrees.
*/
.videoDetect {
    width: 100%;
    transform: rotateY(180deg);
    -webkit-transform: rotateY(180deg);
    -moz-transform: rotateY(180deg);
}

.videoDetectFace {
    width: 100%;
    transform: rotateY(180deg);
    -webkit-transform: rotateY(180deg);
    -moz-transform: rotateY(180deg);
}

/*
*If the device is a tablet or mobile device you must set camera rotation to 0 degrees.
*/
@media ( max-width :758px) {        
    .videoDetect {
        width: 100%;
        transform: rotateY(0deg);
        -webkit-transform: rotateY(0deg);
        -moz-transform: rotateY(0deg);
        }   
}