Performing Face Matching

Overview

MobbScan allows you to perform a face biometric matching between the user using the app and the picture on the ID document.

As on the document scan process, this is also a two-step operation compound by detection and validation. Once the document scan is completed you can proceed with the face matching process that will guide the user to capture their face biometrics to be able to match it against the document picture.

These are the different modes to perform the face detection:

• Default: this will look for a face in front of the camera and will take a picture when the face is detected.
• Liveness by head movement via video: this will record a video asking the user to move their head and evaluate the liveness check on the server.
• Passive liveness: this will record a video asking the user not to move and perform the liveness detection on the server side.
• Passive liveness with random movement: in addition to a passive liveness, this will record a video asking the user to perform a random movement.

Swift

ObjectiveC

MobbScanFaceValidationMode.DEFAULT
MobbScanFaceValidationMode.LIVENESS_VIDEO_HEAD_MOVEMENT
MobbScanFaceValidationMode.LIVENESS_VIDEO_PASSIVE
MobbScanFaceValidationMode_LIVENESS_VIDEO_PASSIVE_WITH_RANDOM_MOVEMENT

MobbScanFaceValidationMode_DEFAULT
MobbScanFaceValidationMode_LIVENESS_VIDEO_HEAD_MOVEMENT
MobbScanFaceValidationMode_LIVENESS_VIDEO_PASSIVE
MobbScanFaceValidationMode_LIVENESS_VIDEO_PASSIVE_WITH_RANDOM_MOVEMENT

Besides, all of the modes allow you to customize the user interface as we will see in next sections.

Validate Face

The simplest way of performing this validation is by invoking the validateFace method as it will perform the two steps required to achieve the face validation for you. You only need to set the validation parameters corresponding to the mode of the validation and the camera to be used to capture the user's face.

Swift

ObjectiveC

let faceValidationParams:MobbScanFaceValidationParams = MobbScanFaceValidationParams()
faceValidationParams.faceValidationMode = MobbScanFaceValidationMode.DEFAULT
faceValidationParams.cameraType = MobbScanCameraType.FRONT
MobbScanAPI.getInstance().validateFace(forScanId: scanId, 
                                          params: faceValidationParams,
                        withFaceAcquisitorResult: {(result,data,error) in 
                            // Do something with the captured face image if needed
                        } ,
                                 withCheckResult: {(result, data, error) in
                                    // Check the validation result here
                                 })

MobbScanFaceValidationParams *faceValidationParams = [MobbScanFaceValidationParams new];
faceValidationParams.faceValidationMode = MobbScanFaceValidationMode_DEFAULT;
faceValidationParams.cameraType = MobbScanCameraType_FRONT;
[[MobbScanAPI getInstance] validateFaceForScanId:scanId
                                          params:faceValidationParams
                        withFaceAcquisitorResult:^(MobbScanFaceAcquisitorResult result, MobbScanFaceAcquisitorData * _Nullable resultData, NSError * _Nullable error) {
                            // Do something with the captured face image if needed
                        }
                                withCheckResult:^(MobbScanValidationState result,  MobbScanValidationResultData * _Nullable resultData, NSError * _Nullable error) {
                            // Check the validation result here
                        }];

Note: The third parameter FaceAcquisitorListener can be omitted if you do not need the selfie image as soon as it is captured. Learn more about it below.

Chances are that you have previously got the face cropped from the document, i.e. via NFC scan process, and you want to supply it to the validation process. In that case, you should be using this other variant of validateFace method:

Swift

ObjectiveC

MobbScanAPI.getInstance().validateFace(forScanId: scanId, 
                               withDocumentImage: faceDocumentImage,
                                          params: faceValidationParams,
                        withFaceAcquisitorResult: {(result,data,error) in 
                            // Do something with the captured face image if needed
                        } ,
                                 withCheckResult: {(result, data, error) in
                                    // Check the validation result here
                                 })

[[MobbScanAPI getInstance] validateFaceForScanId:scanId
                               withDocumentImage:faceDocumentImage
                                          params:faceValidationParams
                        withFaceAcquisitorResult:^(MobbScanFaceAcquisitorResult result, MobbScanFaceAcquisitorData * _Nullable resultData, NSError * _Nullable error) {
                            // Do something with the captured face image if needed
                        }
                                withCheckResult:^(MobbScanValidationState result,  MobbScanValidationResultData * _Nullable resultData, NSError * _Nullable error) {
                            // Check the validation result here
                        }];

Process Validation Result

Once the validation process has been completed the MobbScan API will provide you with this information:

• MobbScanValidationState: the result of the validation. Possible values are:

  Value	Description
  VALID	Operation finished successfully and the validation has been checked as correct
  NOT_VALID	Operation finished successfully and the validation has been checked as not correct
  NOT_CHECKED	The validation process has not been checked or it is not applicable to the document

• MobbScanValidationResultData: the result data extracted from the process. For a friendlier data handling, we encourage you to downcast this object to FaceRecognitionValidationResultData type. This way you will be able to access data like this:

  Property	Description
  currentFace	The user selfie just captured in the detection phase
  documentImage	The face image extracted from the document
  score	The score value of the validation process

• NSError: in case it happens, this contains the error code and extra information about it.

If no error happened, within the result data you will be able to get the confidence score of the face matching and also the face picture captured in the process.

Besides, in case of having performed a validation with liveness check (LIVENESS_VIDEO_HEAD_MOVEMENT, LIVENESS_VIDEO_PASSIVE and LIVENESS_VIDEO_PASSIVE_WITH_RANDOM_MOVEMENT modes), a more detailed information is provided. This information is equivalent to the detailed in this section corresponding to the server service. In order to get this data, you will need to perform a class cast of the given MobbScanValidationResultData to MSIdentityVerificationValidationResultData. The latter will contain the following data:

Property	Description
livenessValidation	Validation result for the liveness check
faceMatchingValidation	Validation result for the face macthing process
identityVerificationValidation	Overall validation result for the identity validation process
livenessScore	Confidence value estimated in the liveness check process
faceMatchingScore	Confidence value estimated for the face match
identityVerificationScore	Overall confidence value of the identity validation process
faceDocument	Face cropped from the document used to match with the one extracted from the video
faceSelfie	Face extracted from the video used to match with the one cropped from the document

Two-Step Validation Process

You might want to perform the face capture and validation at two different moments. This would mean doing separately the two steps that MobbScan hides from you in the method detailed at the beginning of this page. Or maybe you just want to use MobbScan SDK to capture the face and send it directly to the server, or the other way around, you may want to use your own means to capture the user's selfie and use MobbScan SDK to validate their identity. In any case, we will see how to do both single steps in the current section.

Perform Face Detection

The detectFace method allows you to detect the user's face and take a shot of it that will be given to you as a result when the process completes. It also will provide you with a video in case the validation includes liveness detection:

Swift

ObjectiveC

let params:MobbScanFaceValidationParams = MobbScanFaceValidationParams();
params.faceValidationMode = MobbScanFaceValidationMode.DEFAULT;
params.cameraType = MobbScanCameraType.FRONT;
MobbScanAPI.getInstance().detectFace(params) { (result, data, error) in
    // process face detection result
}

MobbScanFaceValidationParams *faceValidationParams = [MobbScanFaceValidationParams new];
faceValidationParams.faceValidationMode = MobbScanFaceValidationMode_DEFAULT;
faceValidationParams.cameraType = MobbScanCameraType_FRONT;
[[MobbScanAPI getInstance] detectFace:faceValidationParams completion:^(MobbScanFaceAcquisitorResult result, MobbScanFaceAcquisitorData * _Nullable resultData, NSError * _Nullable error) {
    // process face detection result
}];

As you can see above, the completion of this method provides you with three parameters:

• MobbScanFaceAcquisitorResult is the result of the face capture. Possible values are:

  Value	Description
  FACE_ACQUIRED	The user face was detected and captured
  ERROR	The process failed

• MobbScanFaceAcquisitorData will contain the data generated in the process:

  Property	Description
  faces	The face pictures captured (regularly one item)
  faceVideo	The video recorded with the user face (for video modes)

Tip: likewise validateFace method allows UI customization, you can customize the user interface displayed in this method by meeting its same requirements.

Perform Face Validation

Last but not least, when you want to perform a face validation providing your own captured selfie to MobbScan you will invoke the following method:

Swift

ObjectiveC

MobbScanAPI.getInstance().validateFace(forScanId: scanId, withFace: faceImage) { (state, data, error) in
    // process result
}

[[MobbScanAPI getInstance] validateFaceForScanId:scanId
                                        withFace:faceImage
                                 withCheckResult:^(MobbScanValidationState result, MobbScanValidationResultData * _Nullable resultData, NSError * _Nullable error) {
    // process validation result
}];

The completion of this method will provide you with the same output as the validateFace method detailed at the beginning of this page.

Customizing the UI

If you are interested in giving your personal touch to the face detection view, please check out this section.