MobbScan React Native SDK: API Reference

MobbScanAPI

This is the object which contains all the methods of the SDK.

msInitAPI(licenseId)

This method initializes the MobbScan API instance. It should be called before any other method.

Parameters

  • licenseId (string): The license code provided by Mobbeel.
    MobbScanAPI.msInitAPI(licenseID);

Warning!

This method is only supported from v2.20.0. For prior versions, please use this method:

initAPI(licenseId, success, error)

Parameters

  • licenseId (string): The license code provided by Mobbeel.

  • success (function): A callback that will be called if the initialization finishes correctly.

  • error (function): A callback that will be called if some problem occurs during the initialization. The error is passed as first parameter of the callback.

    MobbScanAPI.initAPI(licenseID, successCallback, error => console.error(error));

setBaseUrl(baseUrl)

This method sets the Mobbscan API base URL.

Parameters

  • baseUrl (string): Base URL of the MobbScan API.

setFixedMode(orientation)

This method fixes the screen orientation when the camera is capturing.

Parameters

  • orientation (string): Orientation that will be fixed. Allowed values:

    • "NONE"
    • "PORTRAIT"
    • "LANDSCAPE"

startScan(document Type, operationMode)

This method starts a scan process for a document. If several document scans should be done for the same MobbScanAPI instance, this method should be called once per scan.

Parameters

  • documentType (string): Type of document to be scanned. Check the supported values.

  • operationMode (string): Type of operation to be performed. Supported values:

    • SCAN_BOTH_SIDES
    • SCAN_ONLY_FRONT
    • SCAN_ONLY_BACK

Warning!

This method is only supported from v2.20.0. For prior versions, please use this method:

startScan(document Type, operationMode, successCallback, errorCallback)

Parameters

  • documentType (string): Type of document to be scanned. Check the supported values.

  • operationMode (string): Type of operation to be performed. Supported values:

    • SCAN_BOTH_SIDES
    • SCAN_ONLY_FRONT
    • SCAN_ONLY_BACK

  • sucessCallback (function): A callback that will be called if the scan initializes correctly. It takes as paremeters the result and the scanId:

    MobbScanAPI.startScan(docType, opMode, (result, scanId) => console.log(scanId), errorCallback);

  • errorCallback (function): A callback that will be called if the scan initialization fails. It takes as paremeters the error:

    MobbScanAPI.startScan(docType, opMode, sucessCallback, error => console.log(error));

To check the results of the overall scan process, read about the SUCCESS_SCAN_EVENT and ERROR_SCAN_EVENT events.

Document scan

scanDocumentSide(side)

This method opens the phone camera and starts the scan of a document side. startScan method should be called previously.

Parameters

  • side (string): The side of the document that will be scanned. Supported values:

    • FRONT
    • BACK

The results of this method can be checked on SUCCESS_DETECTED_EVENT, ERROR_DETECTED_EVENT , SUCCESS_SCAN_EVENT, and ERROR_SCAN_EVENT sections.

Document detection + scan

From version v2.25.0 the plugin allows the developer to split both processess, detection and scan in different methods.

Document detection

If you just need to detect the document and save the image, you can do this by invoking the detection method:

MobbScanAPI.detectDocumentSide(side)

Thei side parameter values are the same for the scanDocumentSide() method, described in previous paragraph.

The results of this method can be checked on SUCCESS_DETECTED_EVENT, and ERROR_DETECTED_EVENT sections.

Document scan

Once that you have acquired the document cropped images, you can performe anytime a scanning process, in order to extract the OCR information of the document. To do so, you have to invoke a scanning method, providing the images that you previously received from the detection method:

MobbScanAPI.scanDocumentFrontSide(front_image, back_image, scanid)

Parameters

  • front_image (string): The front side image of your document, in base64 format. If you are scanning a passport, this parameter should be null;
  • back_image (string): The back side image of your document, in base64 format.
  • scanId (string): The process identifier that was returned by the startScan method

The results of this method can be checked on SUCCESS_SCAN_EVENT, and ERROR_SCAN_EVENT sections.

Face Detection

detectFace(validationMode)

This method opens the phone camera and start the face detection. startScan method should be called previously.

Parameters

  • validationMode (string): Validation mode. Supported values:

    • DEFAULT: In this method just the face is scanned, without liveness checks.

    • LIVENESS_SMILE: Face detection with a liveness check that ask the user to smile to check that they is an actual person.

    • LIVENESS_HEAD_MOVEMENT: Face detection with a liveness check that ask the user to move their head to check that they is an actual person.

    • LIVENESS_VIDEO_HEAD_MOVEMENT: Face detection with a liveness check that asks the user to move the head from side to side. While the user is moving the face, a video is recorded that will be used for check the liveness and match the face with the document extracted face.

To check the results of this call, read about the SUCCESS_DETECT_FACE_EVENT, ERROR_DETECT_FACE_EVENT, SUCCESS_MATCH_EVENT and ERROR_MATCH_EVENT events.

validateFace(validationMode)

This method performs a facial detection, just like the previuos one. However, once the detection has finished, a facial validation is done, matching the user detected face with the extracted face image from the scanned document on a previous step.

Parameters

  • validationMode (string): Validation mode. The suported values are the same as the previous method.

To check the results of this call, read about the SUCCESS_DETECT_FACE_EVENT, ERROR_DETECT_FACE_EVENT, SUCCESS_MATCH_EVENT and ERROR_MATCH_EVENT events.

validateFaceUsingScanId(scanId, validationMode)

This method performs a face detection and validation like the previous one. In this case, you can specify the scanId you want to use. By doing so, you can perform a facial validation with the document face image extracted in a prevoius document scan process. You just need to provide the scanId of this process.

Parameters

  • validationMode (string): Validation mode. The suported values are the same as the previous method.
  • scanId (string): The scanId of the document scan process you want to match the face with.

To check the results of this call, read about the SUCCESS_DETECT_FACE_EVENT, ERROR_DETECT_FACE_EVENT, SUCCESS_MATCH_EVENT and ERROR_MATCH_EVENT events.

Events

Several events can be listened to using the React Native DeviceEventEmitter.addListener. For example:

import DeviceEventEmitter from "react-native";

DeviceEventEmitter.addListener("SUCCESS_DETECTED_EVENT", event => console.log(event));

These are the events that MobbScan emits:

SUCCESS_INIT_EVENT

This event is triggered once the plugin has checked the license and it's a valid one.

ERROR_INIT_EVENT

This event is triggered once the plugin has checked the license and it's not a valid one. Please take a look to the error handling section for more information.

SUCCESS_START_SCAN_EVENT

This event is triggered once the plugin has started a new scanning process. An event object is passed as first paramenter of the callback which contains the following attributes:

  • RESULTcontains the code of the operation result.
  • SCAN_IDcontains the identifier of the scanning process.

ERROR_START_SCAN_EVENT

This event is triggered if an error happens during the starting scan process. Please take a look to the error handling section for more information.

SUCCESS_DETECTED_EVENT

This event is triggered when a document side has been detected after the call of the scanDocumentSide method. An event object is passed as first paramenter of the callback which contains the following attributes:

  • IMAGE_DETECTED contains a picture of the detected document side during the process.
  • DOCUMENT_SIDE contains the side of the document that has been detected.

ERROR_DETECTED_EVENT

This event is triggered when an error occurs during the detection of a document side after the call of the scanDocumentSide method. Please take a look to the error handling section for more information.

SUCCESS_SCAN_EVENT

This event is triggered when a scan process has finished correctly. An event object is passed as first parameter of the callback which contains the following attributes:

  • RESULT is the result of the scanning process.
  • ID_DOCUMENTcontains a JSON object with the scanning document data.
  • DOCUMENT_IMAGE_FACE contains an image of the extracted user face from the document.

ERROR_SCAN_EVENT

This event is triggered when an error occurs during the document scan. Please take a look to the error handling section for more information.

SUCCESS_DETECT_FACE_EVENT

This event is triggered when a face has been detected after the call of the detectFace method. An event object is passed as first parameter of the callback which contains the following atributes:

  • USER_IMAGE_FACE contains a picture of the user extracted during the detection process.

ERROR_DETECT_FACE_EVENT

This event is triggered when an error occurs during the scanning of a face after the call of the detectFace method. Please take a look to the error handling section for more information.

SUCESS_MATCH_EVENT

This event is triggered when the scanned face and the document face are matched. An event object is passed as first parameter of the callback which contains the following attributes:

  • SCORE contains the confindence value of the matching between the extracted face from the document and the user selfie captured during the process.

If you are using the liveness validation, you will also get these values:

  • LIVENESS_SCORE contains the confidence of the liveness process.
  • FACE_MATCHING_SCORE contais a score that indicates the confidence of the facial matching between the ID card headshot and the face image obtained from the video.
  • IDENTITY_VERIFICATION_SCORE contains an overall indentity verification process confidence.
  • LIVENESS_VALIDATION is a MobbScanValidationState that indicates if the liveness score is considered valid or not according to MobbScan standards.
  • FACE_MATCHING_VALIDATION is a MobbScanValidationState that indicates if the face matching score is considered valid or not according to MobbScan standards.
  • IDENTITY_VERIFICATION_VALIDATION is a MobbScanValidationState that indicates if the overall confidence of the process is valid or not according to MobbScan standards.

ERROR_MATCH_EVENT

This event is triggered when the scanned face and the document face do not match. Please take a look to the error handling section for more information.

← ExamplesError Handling →