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 cover three different scenarios. The first scenario use an image from the mobile device gallery. The second directly uses the camera application. The last scenario, known as Smart Capture, uses the camera but with an overlay to guide the user.

Here’s an example where the source image is obtained using any gallery application on the mobile device. Configure an intent in order to obtain the image:

// select an image
var bitmap: Bitmap? = null
val IMAGE_PICK_CODE = 1000
val intent = Intent(Intent.ACTION_GET_CONTENT)
intent.type = "image/*"
startActivityForResult(intent, IMAGE_PICK_CODE)

The following code will execute once the image has been selected:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (resultCode == Activity.RESULT_OK && requestCode == IMAGE_PICK_CODE){
        var imagePath: String? = null
        val uri = data!!.data
        imagePath = uri!!.path
        val input = contentResolver.openInputStream(uri)
        bitmap = BitmapFactory.decodeStream(input, null, null)!!
        Log.d(TAG, "success: got bitmap")

Create the Facematch service:

val facematchService = FacematchService(Config(""))

Ensure that the person identifier and document identifier are available from a previous verification (Facematch cannot be the first verification call; the Facematch service matches the selfie image with a previously scanned document that contains a photo).

val personId = "96a44cc0-1159-417e-b2f0-4dce1aa3a75e"
val documentId = "4022cb7-ae48-2193-c955-118e2da30224"

The following code will result in the image being uploaded to the GBG Identity Solution:

facematchService.uploadSelfie(bitmap!!, personId, documentId, resultListener = object:
        override fun success(response: Response<FacematchResponse>) {
            Log.d( TAG , "success selfie - ${response.message()}${response.code()}" )

        override fun failure(error: ErrorResponse) {
                        Log.e( TAG , "error selfie -- message -->${error.message} | code --> ${error.responseCode}" )

A success or failure message will be generated when the code is executed.

It is also possible to use the camera to capture the image. Create an intent to invoke the camera application:

var bitmap: Bitmap? = null
Intent(MediaStore.ACTION_IMAGE_CAPTURE).also { takePictureIntent ->
    takePictureIntent.resolveActivity(this@MainActivity.packageManager!!)?.also {
        startActivityForResult(takePictureIntent, REQUEST_IMAGE_CAPTURE)

Once the camera snapshot has been taken, the image content can be saved into a bitmap variable as shown here:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    if (requestCode == REQUEST_IMAGE_CAPTURE && resultCode == RESULT_OK) {
        bitmap = data ?.extras?. get ( "data" ) as Bitmap
        Log.d(TAG, "success: got bitmap for facematch")

Next, the Facematch service can be created and the image uploaded to the GBG Identity Solution using the uploadSelfie method as shown earlier in this guide.

To use the Smart Capture capability, follow the Using the Documents Service guide to create an event receiver, but build the intent as shown here, in order to use SCANNER_TYPE_SELFIE instead of SCANNER_TYPE_STANDARD

private fun buildSelfieScannerIntent(): Intent {
    return viewModel.scanner.getDefaultSmartCaptureIntent()
        .putExtra(CAMERA_TRIGGER_DELAY, 0) // 0 will show the trigger immediately.
        .putExtra(ALERT_DIALOG_MESSAGE, “Please take a selfie”)

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