GBG Developers

Guides   |   Using the Documents Service (Archived Version v1.0)

Using the Documents Service (Archived Version v1.0)

This service allows for a document image (such as a passport or driving license) to either be transferred from an image file or bitmap source, or for an image to be taken with the camera in the mobile device and transferred. The camera method can prompt the user to assist in the document scan, and it is known as Smart Capture.
After the document image has been uploaded the GBG service will analyse it to perform a verification and return the result.
Two examples will be used to demonstrate the feature; the first example uses an image file already on the mobile device, and the second uses Smart Capture.

Here is an example which will launch any gallery application in order to choose 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 when the image selection activity is complete. The image content here is saved to a variable as bitmap content:

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")

The code below shown how the DocumentsService is created and how the bitmap content is sent to the GBG Identity Solution:

val documentsService=DocumentsService(Config(""))
documentsService.uploadDocument(bitmap!!, Tolerance.DEFAULT, resultListener = object: VerifyResultListener<Response<VerifyDocumentResponse>> {
    override fun success(response: Response<VerifyDocumentResponse>) {
        Log.d(TAG,"success: the document was uploaded to the service.")
        VerifyResponseManager.documentId = response.headers()["document-id"]
        VerifyResponseManager.personId = response.headers()["person-id"]
        VerifyResponseManager.verificationId = response.headers()["verification-id"]
        VerifyResponseManager.requestURL = response.raw().request().url().toString()

        Log.d(TAG, response.body().toString())
        Log.d(TAG, response.toString())
    override fun failure(error: ErrorResponse) {
        Log.d(TAG,"Upload failed: ${error.responseBody?.code()} ${error.message}")


When executed, the code will upload the image to the GBG Identity Solution and the returned response if successful will contain the verified detail, logged as debug output.

To use the Smart Capture capability, create an event receiver implementation:

private fun scannerEventReceiver(): VerifyDocumentScannerEventReceiver {
    return object : VerifyDocumentScannerEventReceiver() {

        override fun onProcessingCancelled(context: Context, scannerError: ScannerError) {
            super.onProcessingCancelled(context, scannerError)
            Log.d(TAG,"Processing cancelled.")

        override fun onProcessingFailed(context: Context, errorCode: ScannerError) {
            super.onProcessingFailed(context, errorCode)
            Log.d(TAG,"Processing failed...")

        override fun onProcessingCompleted(context: Context, result: Document) {
                Log.d(TAG,"Processing complete!")
                Log.d(TAG,"isRecognised? : ${result.isRecognised}. doc name ${}")

Create a view model class with a variable that will contain the VerifyDocumentScanner object:

lateinit var docScanner: VerifyDocumentScanner

Configure the document scanner intent to include any alert message as shown here:

private fun buildScannerIntent(): Intent {
    return viewModel.docScanner.getDefaultSmartCaptureIntent()
        .putExtra(ALERT_DIALOG_MESSAGE, "Scan front side of document")

Next, create the Document Scanner service using a context and the event receiver implementation:

var docScanner = VerifyDocumentScanner(context, scannerEventReceiver())

The capture process can now be started by launching the intent:

val captureIntent = docScanner.getDefaultSmartCaptureIntent()

The screenshot below shows an example document scan using the Smart Capture capability. The overlay helps the user frame their document correctly.