GlobalGateway Image Capture SDK V2

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:

Browser

Supported version

Safari/iOS

*11.2+

Chrome

67.0+ && Android OS version 4.1+ or iOS 13+

Firefox

63+ or iOS 13+

Samsung Internet Browser

7.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

Step 1

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

Step 2

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

There are 4 capture functions**

  • StartFrontDocumentCapture
  • StartBackDocumentCapture
  • StartPassportCapture
  • StartSelfieCapture

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

  • isAuto (boolean): Toggle for Auto Capture mode and Manual Capture mode. When set to manual capture, there will be no timeout triggered.
  • startProcess (function): The callback
  • showImage (function): Returns the image in base 64 with classification data, liveness assessment and quality metrics
  • showError (function): Returns an error object with code and type
  • token (string): SDK token
  • shouldCollectGeo (boolean) : Toggle for location data

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.
      StartFrontDocumentCapture(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 StartBackDocumentCapture if your document requires a full picture of the back

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

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

// Capture Photo Page of Passport
      StartPassportCapture(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.

You can initiate the selfie capture as follows:

// Capture Selfie
      StartSelfieCapture(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:

The section below shows the workflows with the different capture mechanisms.
Please note, for passport there's no back image required.

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 https://api.globaldatacompany.com/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"
    }
  }
}

More information regarding GlobalGateway ID Document Verification step can be found here
https://developer.trulioo.com/docs/document-verification-step-5-verify

Error Code

Error message

Description

111

CONSTRAINT_NOT_SATISFIED

The 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.

9001

FACE_TOO_CLOSE

The Face was too close during selfie capture

9002

FACE_NOT_FOUND

The Face was not found during selfie capture

9003

FACE_TOO_SMALL

The Face was too small during selfie capture

9004

FACE_ANGLE_TOO_LARGE

The Face angle was too large during selfie capture

9005

FACE_CROPPED

The Face was cropped during selfie capture

9006

FAILED_TO_READ_IMAGE

The selfie image wasn't able to be read

9012

TOO_MANY_FACES

Too many faces detected during selfie capture

1008

MISSING_TOKEN

Missing SDK token

1009

INVALID_TOKEN

Token is expired or unknown

1011

INVALID_ORIGIN_URL

Liveness 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.

1012

MISSING_IMAGE

Missing image for liveness or classification


Did this page help you?