GBG Developers

Guides   |   Using the Documents Service

Using the Documents Service

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.

Here is an example which uses Smart Capture.

First, the camera permission needs to be enabled. Go to the info.plist file and in the Information Property List add the property Privacy – Camera Usage Description and set the Value field to any suitable description text.

Create a verifyDocumentScanner variable that you will use later:

private var verifyDocumentScanner: GBGVerifyDocumentScanner!

Next, create a GBGVerifyDocumentScanner object, set to type .document. The smart capture can be launched by calling the present method:


verifyDocumentScanner = GBGVerifyDocumentScanner(scannerType: .document,enableRecaptureDetection: true, delegate: self)


Your code will need a delegate that will be invoked at different stages. The following code can be used:

extension StartVerifyDocumentViewController: GBGVerifyDocumentScannerDelegate {
    func documentScannerController(didFinishScanning model: GBGVerifyDocumentScannerModel?) {
        print("success, doc captured by camera")
    func documentScannerControllerDidCancel() {
        print("Cancelled the model from the document")
    func documentScannerController(didFailWithError error: Error?) {
        print("Failed to get the model from the document")

If the document has been successfully captured by the camera, a success message will be printed in the console. At that point the scanned image can be sent to the GBG service in order to perform the document verification. The code snippet below can be used in the documentScannerController function.

The snippet performs several tasks. Firstly it creates an instance of GBGVerifyDocumentService, and then creates a GBGImage object containing the scanned image, and sets the document processing tolerance to default (this is the usual setting for testing and deployment, unless a stricter policy is required). The verify method is called to send the document image to the GBG cloud service.

If the document is successfully processed, fields from the result can be extracted. The example code here places some of the fields into the GBGVerifyResponseManager object which is a singleton instance that provides storage and access to the fields, so that they can be subsequently used with other services in the SDK.

if let model = model {
    let documentService = GBGVerifyDocumentService()
    let image = GBGImage(image: model.extractedImage, fileName: "sample-ios", mimeType: .png)
    let documentIdRequestHeader = GBGVerifyDocumentRequestHeader().withTolerance(GBGTolerance.default.rawValue)
    documentService.verify( document: image, documentRequestHeader: documentIdRequestHeader, success: { result in
        if let verificationId = result?.response.response?.allHeaderFields["verification-id"] as? String,
            let personId = result?.response.response?.allHeaderFields["person-id"] as? String,
            let documentId = result?.response.response?.allHeaderFields["document-id"] as? String {
            GBGVerifyResponseManager.shared.documentId = documentId
            GBGVerifyResponseManager.shared.personId = personId
            GBGVerifyResponseManager.shared.verificationId = verificationId
            print("success, document verified: \(result)")
    }) { error in
        print("Error when submitting the request to the document service: \(error)")
        if let error = error as? GBGErrorResponse<String> {
            self.showPopup(title: "Status Code: - \(String(describing: error.response?.statusCode))", message: error.body ?? "")
} else {       
    print("Failed to get the model from the document")

When the code is run, after a document capture has been performed, the image will be sent to the GBG service and upon successful return you should see a message in the console.

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

 Custom localisation is possible with this module.  If you wish to change the text that gets displayed to the user and display your own language / phrase then you can make use of the following table:  

verifyDocumentScanner.setCustomLocalization(with: "Localisation-table")