MobbScan Web: Liveness

WARNING: Liveness validation feature is only available from version 2.8.0 and above

Introduction

Mobbscan Web offers liveness validation to check if the detected face comes from a real user. This method is an extra step in the face matching validation process.

Please follow the steps described below to enable liveness validation.

Installation

To enable the face matching step, an additional script should be added in the head HTML element, replacing {version} with your current MobbScan version, and specifying the correct path to your mobbscan-api folder:

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

After starting the scan, a listener should be added, which will be called when a face frame has been analyzed, similar to how it has been done with MobbScanAPI.setDetectionListener during the scan of a document:

MobbScanAPI.setFaceDetectionListener(onFaceDetectionResult);

After that call, MobbScanAPI.start will render an additional hidden HTML element that will start a face scan when clicked.

Adding head movement liveness validation

After receiving an OK result in the MobbScanAPI.scan listener, the liveness checking step can be started. First of all, the HTML elements related to the face scan should be visible (and optionally, the document HTML elements could be hidden):

MobbScanAPI.hideDocumentsAndShowFace();

When the face UI is clicked, the scan of the face will start and onFaceDetectionResult will be triggered for each captured frame.

In order to pass this validation, a video will be recorded for 5 seconds where the user has to move the head side by side.

To enable this feature you only have to call enableLivenessHeadMovement method before starting the component.

MobbScanAPI.enableLivenessHeadMovement();

It can be configured the duration of the identify verification process (once the liveness recording is finished) using the setLivenessTimeOut method:

MobbScanAPI.setLivenessTimeOut(Xseconds);

If this parameter is not specified, the default value will be 1 minute for iOS devices and 30 seconds for all other devices.

MobbScanAPI.setFaceDetectionListener

As specified above, a listener that will be called every time a frame is analyzed should be defined, and it can be done using this method. The listener that is set will receive three arguments:

  • result: String which indicates the result of the last detection:

    • STARTED: Nothing has been detected.

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

    • STARTING_LIVENESS: The liveness process has begun.

    • LIVENESS_CHECKING: The liveness video has been carried out, but the server should check the process.

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

    • NOT_DETECTED: Liveness data could not be processed because an error has occurred, which information will be returned in the error field.

    • TIMEOUT : A timeout error has occurred during the face liveness validation. 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. This argument will be available when the result is equal to DETECTED. Relevant attributes:

    • image: It contains the image of the detected face on liveness validation process.

    • scores: An object which contains data about the scores (over 1) obtained from liveness checking. There are three different scores:

      • faceMatching
      • identityVerification
      • liveness

    • video: Blob which contains the video of the liveness process.

  • 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.

Example of a face detection listener

NOTE: Error handling omitted for educational purposes.

const onFaceDetectionResult = (result, data, error) => {
    if (result === "DETECTED") {
        console.log("Face matched with score", data.scores);
    }
}

Perform liveness head movement with new instance of the component

If you want to scan the document and perform the liveness validation in two separate files you should destroy the instance of MobbScanAPI at face liveness step. To recreate the interface and finish the process you have to follow these steps:

  • Initialize the api as usual, if the api is initialized you can omit this step.
  • Set face detection listener with setFaceDetectionListener method.
  • Enabled head movement liveness process with enableLivenessHeadMovement method.
  • Call detectFace with the scanId of the process to match face and the placeholder if you didn't call setPlaceHolder before. Note that to indicate the scanId, a previous document scan must have been performed.

Example

    // Sets license
    MobbScanAPI.initAPI('YOUR LICENSE HERE');
    // Sets base url
    MobbScanAPI.setBaseURL("https://yourmobbscaninstance.com");
    // This listener is called when a face frame has been analyzed
    MobbScanAPI.setFaceDetectionListener(onFaceDetectionResult);
    // If you want to use the native mode on mobile you have to call this method
    MobbScanAPI.enableVideoMobileCapture();
    //Enable liveness head movement
    MobbScanAPI.enableLivenessHeadMovement();
    MobbScanAPI.setLivenessText("Please move the head side by side in:");
    // Sets liveness timeout
    MobbScanAPI.setLivenessTimeOut(60);
    // 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 face detection
    MobbScanAPI.detectFace("YOUR SCAN ID", "mobbscan-placeholder")

    function onFaceDetectionResult(result, data, error) {
        if (error) {
            console.error(error);
        }
        // If is a DETECTED result...
        if ((result === MobbScanFaceDetectionResult.DETECTED)) {
            // The results obtained from the liveness validation can be displayed
            document.getElementById("resultFace").textContent = JSON.stringify(data, undefined, 2);
            console.log("Face matched with score", data.scores);
        }
    }