v1 - Step 6: 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:

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

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:

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:

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:

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