GBG Developers

Guides   |   Using the Facematch Service

Using the Facematch Service

This guide explains how to use the Facematch service, which allows for a face image (also known as a selfie) to either be transferred from a file or bitmap source, or for an image to be taken with the camera in the mobile device and transferred. The GBG Identity Solution will receive the image and correlate it with photo identification extracted from previously scanned documents.

The examples here shows how to use Facematch with Smart Capture. This feature uses the camera but with an overlay to guide the user.

First, create the Facematch service as shown below. Note that a verifyDocumentScanner variable is used later, because the Facematch service uses components from the Document service.

private lazy var facematchService = GBGFaceMatchService()
private var verifyDocumentScanner: GBGVerifyDocumentScanner!

The service is launched using startSelfieCapture.


Delegate functions are used to handle the events. Use the startSelfieCapture delegate function to present the camera view. This is done by creating a GBGVerifyDocumentScanner object and setting a type value to .selfie to enable it for Facematch mode instead of Document scanning mode. The camera is launched using the present method.

extension StartFaceMatchViewController: GBGVerifyDocumentScannerDelegate {
    func documentScannerController(didFinishScanning model: GBGVerifyDocumentScannerModel?) {
        print(“facematch, camera capture complete”)
    func documentScannerControllerDidCancel() {
        print(“facematch, cancelled”)
    func documentScannerController(didFailWithError error: Error?) {
        print(“facematch, error”)
    func startSelfieCapture() {
        print(“facematch, launching camera service in selfie mode”)
        verifyDocumentScanner = GBGVerifyDocumentScanner(scannerType: .selfie, options: nil, delegate: self)

When run, the camera will launch and the user will be prompted through the Smart Capture process.

The captured image is sent to the GBG service from within the documentScanController delegate function. The code example below shows how to do this.

A request header is built containing a person identifier and document verification identifier. These values are obtained from other SDK services (Facematch cannot be the first verification call; the Facematch service matches the selfie image with a previously scanned document that contains a photo).

The request header and the image are sent to the GBG Facematch service for verification, using the match method. The returned result can be examined to verify pass or failure; the example below prints the output to the console.

if let image = model?.extractedImage {
    let selfieRequestHeader = GBGSelfieRequestHeader()
        .withPersonId(GBGVerifyResponseManager.shared.personId ?? "")
        .withDocumentVerificationId(GBGVerifyResponseManager.shared.verificationId ?? "")
    self.facematchService.match(GBGImage(image: image, fileName: "selfie", mimeType: .jpg), selfieRequestHeader: selfieRequestHeader, success: { result in
        print("facematch complete, result \(result?.body)")
    }, failure: { error in
        print("facematch error \(error)")

The screenshot here shows a Smart Capture selfie being taken. The overlay is presented to help the user frame themselves correctly.