Step 6: GlobalGateway image capture SDK

GlobalGateway Image Capture SDK

Overview:

The Image Capture SDK enables users to capture and upload high-quality ID document images and selfies for identity verification. It further allows for data extraction from the submitted ID document images. It also supports document authentication and facial recognition to verify and authenticate the identity. The SDK leverages a device’s native camera application to acquire images for automatic analysis.

This document contains an overview of the Image Capture SDK, its features, and its minimum system requirements required for implementation. It also provides a detailed description of all functions that developers need to integrate with.

What is Image Capture SDK?
The SDK provides developers with the options needed to integrate their application seamlessly and maintain a customized user experience. The freedom to create any UI with any framework is possible with our pure JavaScript API. This approach allows you to simply call methods in our JavaScript API to capture identity documents (driver’s licenses, ID cards, passports, residence permit), additionally allowing for auto-capture of selfies. This approach also allows complete control over the front end or look and feel of your site. We have also included a sample HTML template to demonstrate how to develop various workflows to get you up and running quickly. Once the image of an ID document is captured, the image is reduced in size, compressed, and passed in RAM to the native application. Images are never stored on the camera roll or any persistent device storage. All image analysis and enhancement takes place in RAM.

NOTE: The SDK may have problems capturing images on desktop or laptop computers due to the lower quality of web cameras.

System Requirements:
The Image Capture SDK is supported on the following platforms:

BrowserSupported version
Safari/iOS*11.2+
Chrome67.0+ && Android OS version 4.1+ or iOS 13+
Firefox63+ or iOS 13+
Samsung Internet Browser7.2 - 8.2 / 9.2+ Android

Other Requirements:

  • Devices must have a camera that supports a minimum of 720p resolution.
  • Chrome requires the use of HTTPS / SSL when accessing the video for AUTO_CAPTURE mode.
  • Browser needs to support getUserMedia
  • Browser needs to support Web Assembly
  • Browser needs to support WebGL

Unsupported Browsers:
For browsers that do not meet the minimum general requirements listed above, the SDK will return an error and integrators should handle these errors in their application.
Note: The HTML page must run over Https to work / Chrome requires this to access the device's video camera.

Pre-requisite

Place GlobalGatewayCapturePublic folder in public folder as it contains helper js files which would be loaded on demand during runtime to reduce footprint.

GlobalGatewayImageCapture.js in your html

Request Web SDK credentials from [email protected]

<script>
    const username = 'USERNAME_TO_REPLACE';
    const password = 'PASSWORD_TO_REPLACE';

Initialize Step

To initialize GlobalGatewayImageCaptureSDK

//include javaScript in the BODY of html file.
//The SDK will automatically run initialization onload.

<script type='text/javascript' src="path/to/GlobalGatewayCapturePublic/GlobalGatewayImageCapture.js">

Capture Step

13071307

This section covers the front end JavaScript code needed to take 2-3 photos.

There are 4 capture functions**

  • StartAcuantFrontDocumentCapture
  • StartAcuantBackDocumentCapture
  • StartAcuantPassportCapture
  • StartAcuantSelfieCapture

To start capture, call any start function with the following parameters:

NameTypeDescription
isAutoBooleanToggle for Auto Capture mode and Manual Capture mode. When set to manual capture, there will be no timeout triggered.
startProcessfunctionCallback function that will be called when a picture is captured by the sdk and the picture is currently going through processing (quality metrics, cropping, get liveness data, etc).
showImagefunctionCallback function returns the image in base 64 with classification data, liveness assessment and quality metrics.
showErrorfunctionCallback function returns an error object with code and type.
tokenStringSDK token.
shouldCollectGeoBooleanToggle for location data collection.

When capturing an image, depending on your ID type, you’ll want to choose the correct capture method. We offer 4 versions in automatic mode which auto snaps the images as well as a manual mode which opens the camera app on your phone.

For the front image, you can initiate the capture as follows:

// Capture Driver Licence and ID Cards.
      StartAcuantFrontDocumentCapture(getIsAutoDropDown(), shouldCollectGeo, startProcess, showImage, showError, token);

At this point the user will be guided to take a photo in automatic mode. If there's too much glare this process will advise the customer about this as well.

If the capture is successful the showImage will be called, if it fails the showError will be called. We recommend handling both scenarios as a part of your workflow.

A response with classification result will be available with the image, if the images is successfully classified you should proceed with the back image.

Sample of good Classification data (in a new field called IDClassification):

{
    "image": "result-Image-string",
    "quality": {
        "glare": 99.99948740005493,
        "dpi": 551,
        "sharpness": 68.20454001426697
    },
    "classification": {
        "ClassName": "Drivers License",
        "CountryCode": "CA",
        "Name": "British Columbia (BC) Driver's Licence",
        "Side": "Front",
        "InstanceID": "52814eeb-1805-43f2-8935-116094464612",
        "DocumentID": "24c90581-5518-4644-94ec-7d16c3eaa3a1"
    }
}

If its unknown as below, please allow the users 2 more tries before proceeding with the back capture.

Sample of unknown Classification data (in a new field called IDClassification):

{
    "image": "result-Image-string",
    "quality": {
        "glare": 20.99948740005493,
        "dpi": 551,
        "sharpness": 68.20454001426697
    },
    "classification": {
       "ClassName":"Unknown",
       "CountryCode":"",
       "Name":"Unknown",
       "Side":"Front",
       "InstanceID":"698e8878-137b-44df-af99-483e1260b54d",
       "DocumentID":"00000000-0000-0000-0000-000000000000"
    }
}

The below image is for reference on how it will look on a mobile device during the capture:

295295

For the Back image, you can use StartAcuantBackDocumentCapture if your document requires a full picture of the back

// Capture Driver Licence and ID Cards.
      StartAcuantBackDocumentCapture(getIsAutoDropDown(), shouldCollectGeo, startProcess, showImage, showError, token);

If a Passport photo is needed, please use the function below

// Capture Photo Page of Passport
      StartAcuantPassportCapture(getIsAutoDropDown(), shouldCollectGeo, startProcess, showImage, showError, token)

After you've captured the back image and handled both callbacks (Success and Error), now comes time for the selfie with Liveness check.

Selfie Capture Step

You can initiate the selfie capture as follows:

// Capture Selfie
      StartAcuantSelfieCapture(getIsAutoDropDown(), shouldCollectGeo, startProcess, showImage, showError, token);

Once you've initiated the auto selfie and the capture is successful, you will receive one of the responses below.

Sample of Pass/Live (in a new field called Liveness):

{
    "image": "result-image-string",
    "liveness": {
        "LivenessResult": {
            "LivenessAssessment": "Pass"
        },
        "ErrorCode": null,
        "ErrorMessage": null
    }
}

Sample of Fail/Not Live (in a new field called Liveness):

{
    "image": "result-image-string",
    "liveness": {
        "LivenessResult": {
            "LivenessAssessment": "Fail"
        },
        "ErrorCode": null,
        "ErrorMessage": null
    }
}

Sample of an Error (in a new field called Liveness):

{
    "image": "result-image-string",
    "liveness": {
        "LivenessResult": {
            "LivenessAssessment": "null"
        },
        "ErrorCode": 9003,
        "ErrorMessage": “Face is too small. Move the camera closer to the face and retake the picture.”
    }
}

A Pass or Fail won't have any error codes, please see error table for the complete list.

The image below is for reference on how it will look on a mobile device:

295295

Using The Captured Image
The result of capture will be in base64 image format:
Image = data:image/jpeg;base64,/9j/4QAYRXhpZgAASUkqAAgAAAAA ....

To verify, set your request body with the byte data after “data:image/jpeg;base64,” prefix:

POST <<endpoint>>/verifications/v1/verify
Authorization: Basic ACCESS_TOKEN
Content-Type: application/json
body:
{
  "AcceptTruliooTermsAndConditions": true,
  "CleansedAddress": false,
  "VerboseMode": true,
  "ConfigurationName": "Identity Verification",
  "CallBackUrl": "www.example.com",
  "CountryCode": "US",
  "DataFields": {
    "PersonInfo": {
      "FirstGivenName": "Mary",
      "FirstSurName": "Sample"
    },
    "Document": {
      "DocumentFrontImage":"/9j/4QAYRXhpZgAASUkqAAgAAAAA .....IQCEIQCEIQCEIQP/9k=",
      "DocumentBackImage": "/9j/4QAYRXhpZgAASUkqAAgAAAAA......LKICIiAiIgIiICIiAiIg//Z",
      "LivePhoto": "/9/9j/4QAYRXhpZgAASUkqAAgAAAAA .....JGHGTDKYFRFS/9k=",
      "DocumentType": "DrivingLicence"
    }
  }
}

Error Code

Error CodeError messageDescription
111CONSTRAINT_NOT_SATISFIEDThe video camera must run at 1280x720, but this device does not support this required resolution. The user is likely using a very old device. You may also see this returned during development because the web app is not being served over TLS.
9001FACE_TOO_CLOSEThe Face was too close during selfie capture
9002FACE_NOT_FOUNDThe Face was not found during selfie capture
9003FACE_TOO_SMALLThe Face was too small during selfie capture
9004FACE_ANGLE_TOO_LARGEThe Face angle was too large during selfie capture
9005FACE_CROPPEDThe Face was cropped during selfie capture
9006FAILED_TO_READ_IMAGEThe selfie image wasn't able to be read
9012TOO_MANY_FACESToo many faces detected during selfie capture
1000FAIL_TO_INITIALIZESDK credential error
1001IMAGE_SMALLER_THAN_MIN_SIZEImage is too small
1002CORRUPT_IMAGEImage is unreadable
1003FILE_TYPE_INVALIDInvalid image file type
1004PDF_FILE_SIZE_OVER_4_MBPDF File is over 4MB
1005AUTO_CAPTURE_NOT_SUPPORTAuto Capture is not supported on this device
1006FAIL_TO_AUTO_CAPTUREError during auto capture
1007FAIL_TO_MANUAL_CAPTUREError during manual capture
1008MISSING_TOKENMissing SDK token
1009INVALID_TOKENToken is expired or unknown
1010NO_MORE_TOKEN_ATTEMPTSToken has been used already
1011INVALID_ORIGIN_URLLiveness and Classification is from a different origin domain name from the ones they specified in the request body when calling the get sdk token endpoint.
1012MISSING_IMAGEMissing image for liveness or classification
1013FAIL_TO_GET_LIVENESS_DATAError retrieving liveness data
1014FAIL_TO_GET_CLASSIFICATION_DATAError retrieving classification data
1015FAIL_TO_CAPTUREFail to capture image
1016FAIL_TO_PROCESSFail to process captured image.
1017AUTO_CAPTURE_REPEAT_ERRORAuto capture has previously failed and was called again
1018AUTO_CAPTURE_SEQUENCE_BREAK_ERRORCamera capture failed due to unexpected sequence break