Document WebCapture SDK – IdDoc Autocapture (Passport/Identity Card/DL) 

Overview 

Document WebCapture SDK is a JavaScript SDK that autocaptures any identity document, including passports, identity cards, driver's licenses, and resident identity permits in ID1, ID2, or ID3 format.

Document WebCapture SDK selects the best image within a video stream using artificial intelligence and machine learning algorithms based on the following standards:

• There is no web browser extension required.

• The computation is done within the back end, and minimal resources from the user's smartphone are required.

• The autocaptured image must be suitable for document authentication (verification that the document is a genuine document) using DocAuth Services as part of IDEMIA's solutions.

Document WebCapture SDK provides dynamic and post capture guidance to the user to help autocapture a good quality image by alerting on the following issues:

• Correct camera distance for the smartphone/document (subject is not too far or too close)
• Glare detection
• Too much angle during the capture (trapezoid form)
• Too dark/insufficient lighting
• Document is blurry

Document WebCapture SDK has MRZ capability via PDF417 barcode extraction.

A demo app is available to showcase the integration of IDEMIA Web CaptureSDK for IDEMIA Identity offer in the following repository:

Github repository: https://github.com/idemia/WebCaptureSDK
Section: ID Document Autocapture

Requirements 

Minimal connectivity upload/download: 1.5 Mbps (means Wifi, 4G, regular 3G)

Maximal connectivity latency: 500ms

Minimal supported resolution: Video resolution FullHD (1080 pixels * 1920 pixels)

Supported browsers:

• Android: Chrome 57+, FireFox 68+, Opera 47+, Samsung Internet 9+, HuaweiBrowser 12+, Brave 110+
• iOS: Safari 14+

Note: If the device has several back cameras, HuaweiBrowser and Opera are not supported on Android.

• Desktop (Windows, Mac OS, Linux): not supported

WebView:

WebCapture SDK supports:

• Chrome WebView (v57+) on Android
• WKWebView on iOS (v14+)

In order to integrate properly the SDK in a WebView it is mandatory to follow the recommendations. See the FAQ section for integration details.

WebCam: not supported

Document WebCapture SDK 

Document WebCapture SDK is a JavaScript SDK hosted within a back end. This SDK brings in live identity document detection from video streams. This SDK allows an integrator to acquire a best-image from a video stream of an identity document (ID), such as a passport, identity card, or driver's license.

. It supports two kinds of readings:

• PDF417: Stacked linear barcode format
• MRZ: Machine readable zone

As an integrator, you can follow the three steps below (approximately 15 minutes) to test and use Document WebCapture SDK.

Getting started 

The sample source code provided requires access to the IDEMIA Global Digital Identity offer. The purpose of the sample application is to provide a good practice example for integration.

Sample application 

Steps for downloading and installing the Document WebCapture SDK sample application are described below.

Step 1: Install prerequisites

Required systems

• OS: Linux or Windows
• Memory: At least 8GB of RAM (recommended minimum)
• CPU: 2.5 GHz (recommended minimum)

Required services

To facilitate integration with Document WebCapture SDK, we provide a web application in source code as an integration good practice example. This sample application is developed in Node.js.

Install Node.js for your operating system:

• Linux: Download & install https://nodejs.org/dist/v16.17.1/node-v16.17.1-linux-x64.tar.gz
• Windows: Download & install https://nodejs.org/dist/v16.17.1/

To start the integration, you'll need an API key and a sandbox environment. To obtain this, you'll need to register yourself through https://experience.idemia.com/auth/signup/.

Step 2: Sample application setup

1. Download the latest sample web application from the GitHub repository.

• Github Repository: https://github.com/idemia/WebCaptureSDK
• Section: ID Document Autocapture

2. Unzip the archive and navigate to the root folder.
3. Edit the /server/config/default.js file with the following:

• Add your API key by filling in the WEB_SDK_LIVENESS_ID_DOC value.
• Modify document services with your url (see Environment value in 'Dashboard'):
• DOCSERVER_VIDEO_URL or Document SDK

4. Create a TLS keypair and certificate. You can also convert an existing key/certificate in PEM format into PKCS#12 file format, or use an existing one. Then fill the values in the server/config/defaults.js file with the corresponding location.

   An example snippet is shown:

   Shell
   1TLS_KEYSTORE_PATH: path.join(__dirname, 'certs/demo-doc.p12'),
   2TLS_KEYSTORE_PASSWORD: loadSecretFromFile(path.join(__dirname, 'secrets/tls_keystore_password.txt')),

   The password of this keystore should be filled inside the default file at 'secrets/tls_keystore_password.txt'

Step 3: Run and test the sample application

1. Open a terminal to the root folder.

2. Launch the following command to load the dependencies as shown in the snippet:

Shell
1npm install --verbose

3. Launch the following command to run the sample application as shown in the snippet:

Shell
1npm run start

4. Open a browser and run the demo at: https://localhost:9943/demo-server/. To use a smartphone connected through the same network without the firewall, go to https://IP_ADDRESS:9943/demo-doc/.

Note: For testing the sample source code from GitHub with an Android phone, consult the FAQ section.

Warning: Since the front-end sources and the back-end sources are located under this same package, everything should be protected behind an authentication tool (except for local test purposes). The defaults.js source file should not be exposed at any time to the world (it contains the API key used to communicate with the Document WebCapture SDK). A good practice is to use an external tool to retrieve the API key and any sensitive information, such as KMS or VAULT.

Use case 1: Only identity document autocapture required

The provided sample is ready to be used. No further modifications are required.

Use case 2: Integration with ID&V Global

1. If you want to link Biometric Services with ID&V/GIPS, edit the file /server/config/default.js and update the variables as follows:

• set IDPROOFING to true

• set GIPS_URL to the URL you received

• set GIPS_RS_API_Key with the API key header to use

2. Open a terminal to the root folder

3. Run this command to load the dependencies

Shell
1npm install --verbose

4. Run this command to start the sample application

Shell
1npm run start

5. Now you can open a browser and go to:

https://localhost:9943/demo-server/

For testing sample source code from GitHub with an Android phone please consult FAQ section.

Configuration parameters 

All configuration variables from the demonstration code are described below.

Descriptions of the files from the source code are shown below.

Use cases 

Capture both sides of an identity card from a known issuing country (web SDK workflow) 

This use case applies when the issuing country of the document, the type of document, and the sides to capture are known.

Requirements

The SP must write its application to facilitate integration within the Document WebCapture SDK. A web application must be developed to allow the user to reach and use the Document WebCapture server.

Note: Refer to the provided sample web application described in Getting Started for more details.

To enable identity document (ID) detection via WebCapture SDK, the client application must be configured with:

• API keys provided by portal administrator(s) to access the Rest API services

• The URL to access the WebCapture Server and SDK

UML diagram for identity document autocapture

This use case consists of using the Document WebCapture SDK to autocapture a high quality identity document.

Process steps for identity document autocapture

Step 1: Load the web application with the WebCapture JavaScript SDK

• A user is asked for an identity document (ID) authentication via a web application developed by the Service Provider.

• The user launches the web application with a compatible browser (detection API) and a compatible connectivity (connectivityMeasure API)

• The web application loads and displays the supported countries and load type.

Step 2: Initiate the session

• The user selects the issuing country of the document and the type of document to capture. Note that in ID&V integration, these data may come directly from GIPS backend without asking user's needs.

• The web application of the Service Provider handles the request and initiation of a document session.

• This request returns the new session identifier.

Step 3: Initiate the DocCaptureClient

The web browser uses the Web Capture SDK JavaScript initDocCaptureClient function to retrieve the device's camera device. This is executed in the browser.

• Initialize a doc capture client with the given configuration.

• The returned client lets you start and stop the doc capture on a given video stream, to catch doc tracking info and manage any errors.

Step 4: Get the device stream

The web browser uses the SDK JavaScript function getDeviceStream to retrieve the video stream of the selected device. This is executed in the browser.

• This function both requests and returns the associated media stream.
• When opening a media stream, a specific configuration can be applied to define the capture conditions such as camera resolution and frame rate.

Step 5: Start the capture

The web browser uses the start SDK JavaScript function to initialize a doc capture client. This is executed in the browser and starts a capture client and a document capture for a specific capture identifier in the given session.

• The user video is streamed to the server and exchanges live tracking info of the document with the server.

• Front side is captured

• The document server finds the best image (front side) from the video stream.

• The server asks the user to flip the document

• Back side is captured

• The document server finds the best image (back side) from the video stream.

• The document server extracts the identity information depending on requested rules.

• The document status is updated at the end of the process.

• The document server stops the capture via websocket, and returns document data (status, identity, images).

• Once the document capture is validated by the user, the web browser uses the SDK JavaScript function finishSession.

Step 6: Poll for results

• The document server asynchronously notifies GIPS.

• The document status is retrieved from GIPS by the Service Provider.

• The web browser display the result to the user.

Document autocapture using a native SDK (native SDK workflow) 

This use case applies when document capture is performed by the native SDK.

UML diagram for identity document autocapture

Process steps for identity document autocapture

Step 1: Initiate the session

• The user selects the issuing country of the document and the type of document to capture. Note that in ID&V integration, these data may come directly from GIPS backend without asking user's needs.

• The web application of the Service Provider handles the request and initiation of a document session.

• This request returns the new document session identifier.

Step 2: Autocapture the document

• The native SDK requests the document session identifier generated.

• The native SDK preforms the front side auto capture.

• The native SDK asks the user to flip the document to capture the other side of the document. Auto capture is paused during a specific time.

• The native SDK preforms the back side auto capture.

• The native SDK asks the user to validate the auto capture of the document.

• The native SDK sends the front and back best images to the back end.

Step 3: Finish the capture

• The native SDK notifies the document server of the end of the document capture.

Step 4: Poll for results

• The document server asynchronously notifies GIPS.

• The document status is retrieved from GIPS by the Service Provider.

• The web browser display the result to the user.

Definitions 

Some definitions used in this documentation are described below.

Document Session 

The document session is an in-memory session stored within the back end that is accessed by the service provider using APIs:

• It is related to one document type; for example, a US driver's license
• It is used to store all user captures of their identity document
• The user cannot modify or retrieve the document session content

WebSDK 

The WebSDK includes the following:

• All extracted data from the document is stored in the same document session
• Attempts to retry can be made within the same session until either the end-user or the integrator initiates the finishSession API call.

Document Capture 

The document capture represents one video capture of a user identity document using JavaScript.

Document Capture status 

A document capture goes through different statuses during its life cycle in the session as described in the table.

Best image 

The best image represents the best detected frame of the document among all video frames during the document capture.

Capture rules 

A capture rule is a data extraction feature used by webDocServer to extract identity information from the user document capture.

Rules supported by webDocServer are shown in the table.

Rest APIs 

APIs documentation not available.

JavaScript APIs 

The JavaScript APIs are comprised of a JavaScript library that provides a rich set of client-side functionalities to perform the following:

• Manage the user's camera to send the video stream of the document capture to the Document WebCapture SDK
• Guide the user during a document capture via an exchange of live feedback

EnvironmentDetection 

detection

The DocserverEnvironment.detection() function detects if the current environment (OS and browser) is supported.

The code is shown in the snippet:

JavaScript
1DocserverEnvironment.detection(detectMultipleCamera, callback);

If the environment is not supported, the response contains a list of supported browsers according to the current OS (the parameter supportedBrowser is returned).

DocserverEnvironment.detection() is asynchronous when parameter detectMultipleCamera is true and takes a callback parameter that is executed once the check is done.

Parameters

The parameters for the detection function are shown in the table.

Example code usage

An example of the DocserverEnvironment.detection() function that detects the current environment (OS and browser) is shown in the snippet:

JavaScript
1function envCheckCb(env) {
2  if (!env.envDetected) { 
3      console.log("env detection failed with error:" + env.message);
4      return 
5  }
6  var envOS = env.envDetected.os;
7  if (!envOs.isSupported) {
8      console.log("env detection error: ", env.message , "Supported OS list", envOs.supportedList);
9      return 
10  }
11  var envBrowser = env.envDetected.browser;
12  if (!envBrowser.isSupported) {
13      console.log("env detection error: ", env.message , "Supported Browsers", envBrowser.supportedList);
14      return 
15  }
16}
17
18DocserverEnvironment.detection(true, envCheckCb); // << async check with new callback param

Success response example

Result: OS and browser supported

An example success response for DocserverEnvironment.detection() that detects the OS and browser are supported is shown in the snippet:

JSON
1{
2  "envDetected": {
3    "os": {
4      "isSupported": true,
5      "supportedList": [],
6      "isMobile": false
7    },
8    "browser": {
9      "isSupported": true,
10      "supportedList": []
11    }
12  },
13  "message": ""
14}

Error response example

Result: Browser not supported

An example success response for DocserverEnvironment.detection() that detects that the browser is not supported is shown in the snippet:

JSON
1{
2  "envDetected": {
3    "os": {
4      "isSupported": true,
5      "supportedList": []
6    },
7    "browser": {
8      "isSupported": false,
9      "supportedList": [
10        {
11          "name": "Chrome",
12          "minimumVersion": "56"
13        },
14        {
15          "name": "Firefox",
16          "minimumVersion": "50"
17        },
18        {
19          "name": "Opera",
20          "minimumVersion": "47"
21        },
22        {
23          "name": "Edge",
24          "minimumVersion": "17"
25        }
26      ]
27    }
28  },
29  "message": "You seem to be using an unsupported browser."
30}

NetworkCheck 

This section discusses how to check that the user's network connectivity is good enough to perform video functions.

connectivityMeasure

The connectivityMeasure API allows the ability to check user connectivity requirements for video capture by calculating the latency and upload speed.

The connectivityMeasure function is shown in the snippet:

JavaScript
1DocserverNetworkCheck.connectivityMeasure({
2    uploadURL:   urlBasePath + '/network-speed',
3    latencyURL:  urlBasePath + '/network-latency',
4    onNetworkCheckUpdate: onNetworkCheckUpdate,
5    errorFn: (e) => {
6      console.error('An error occurred while calling connectivityMeasure: ', e);
7    }
8});

Verifications are performed in this order:

• Latency: This checks the latency to verify if it is good do the next check. If not, it returns latency failure without doing a download and upload speed check.

• Upload speed: This verifies the upload speed and returns the results.

Parameters

The parameters for the connectivityMeasure function are shown in the table.

Examples usage

An example code usage for connectivityMeasure is shown in the snippet:

JavaScript
1// call it once document loaded
2window.onload = () => {
3    function onNetworkCheckUpdate(networkCheckResults) {
4        console.log({networkCheckResults});
5        if (!networkCheckResults.goodConnectivity) {
6            console.log('BAD user connectivity');
7            if (networkCheckResults.upload) {
8                console.log('Upload requirements not reached');
9                console.log('Upload speed threshold is ' + DocserverNetworkCheck.UPLOAD_SPEED_THRESHOLD);
10            } else if (networkCheckResults.latencyMs) {
11                console.log('Latency requirements not reached');
12                console.log('Latency speed threshold is ' + DocserverNetworkCheck.LATENCY_SPEED_THRESHOLD);
13            } else {
14                console.log('Failed to check user connectivity requirements');
15            }
16
17            // STOP user process and display error message
18        }
19    }
20    const urlBasePath = '/demo-doc';
21    DocserverNetworkCheck.connectivityMeasure({
22        uploadURL:   urlBasePath + '/network-speed',
23        latencyURL:  urlBasePath + '/network-latency',
24        onNetworkCheckUpdate: onNetworkCheckUpdate,
25        errorFn: (e) => {
26            console.error('An error occurred while calling connectivityMeasure: ', e);
27        }
28    });
29}

Response

Success response

If connectivityMeasure was successful, then the response will display with the parameters in the table.

Result of onNetworkCheckUpdate with good connectivity

A true response for goodConnectivity is shown in the snippet:

JSON
1{
2   "goodConnectivity": true,
3   "latencyMs": 44,
4   "upload": 5391
5 }

Result onNetworkCheckUpdate with bad connectivity

A false response for goodConnectivity is shown in the snippet:

JSON
1{
2  "goodConnectivity": false,
3  "latencyMs": 44,
4  "upload": 0 // upload speed check not done
5}

getDeviceStream 

This request provides access to the given camera device and returns the associated MediaStream as shown in the snippet:

JavaScript
1DocserverVideo.getDeviceStream

Make sure that JavaScript initDocCaptureClient function was already called before calling this function.

Parameters

The parameters for the getDeviceStream function are shown below.

Note: End of capture and capture status analysis are handled on onDocCaptured callback.

This callback is called when global status of a side capture is different to IN_PROGRESS.

For more details, please refer to: GetDocSessionDocumentById.

Example usage

Example code usage 1

An example usage for getDeviceStream is shown in the snippet:

JavaScript
1// be sure to initialize the client first
2const docCaptureClient = await DocserverVideo.initDocCaptureClient(docCaptureOptions);
3// request the video stream of the default camera device
4const videoStream = await DocserverVideo.getDeviceStream();

Example code usage 2

An example usage for getDeviceStream is shown in the snippet:

JavaScript
1// be sure to initialize the client first
2const docCaptureClient = await DocserverVideo.initDocCaptureClient(docCaptureOptions);
3// request video stream of the default camera device with error callback handler
4const videoStream = await DocserverVideo.getDeviceStream({errorFn: (err) => {console.debug("get User Media Stream failed", err);}})

Success response

If the getDeviceStream request is successful then the parameter below will be returned.

initDocCaptureClient 

The initDocCaptureClient function initializes a document capture client with the given configuration.

The returned client lets you start and stop the document capture on a given video stream, catch document tracking information, and manage errors as shown in the snippet:

JavaScript
1DocserverVideo.initDocCaptureClient

This JS function has to be called before getDeviceStream function to improve 4K phone capture coverage.

Example parameters usage

An example usage of the parameters for initDocCaptureClient is shown in the snippet:

JavaScript
1// init a doc capture client
2const docCaptureOptions = {
3    docserverVideoUrl: 'doc_server_endpoint',
4    fullDocCapture: true,
5    sessionId: sessionId,
6    onChangeDocumentSide: (data) => {
7        console.log('onChangeDocumentSide: ', data);
8        // Handle the flip of the document
9	},
10    onClientInitEnd: () => { 
11        console.log("Init ended. Remove loading for video")
12        // display the video stream to the user
13    },
14    trackingFn: (trackingInfo) => { console.log("onTracking", trackingInfo) },
15    onDocCaptured: (doc) => {
16        console.log("onDoc", doc);
17        console.log('Full Document ID: ' + doc.id);
18        console.log('Full Document status: ', doc.status);
19        // Handle the end of capture and capture status analysis
20        // Disconnect the client
21    },
22    errorFn: (error) => { console.log("doc capture error", error) },
23};
24const docCaptureClient = await DocserverVideo.initDocCaptureClient(docCaptureOptions);

Parameters

The parameters for initDocCaptureClient are shown in the table.

OnChangeDocumentSide Info

The content of the callback onChangeDocumentSide() is shown in the table :

OnClientInitEnd Info

The onClientInitEnd() callback has no content. After invoking initDocCaptureClient and receiving the client in response on the JavaScript side, and once the end-user is prepared for document autocapture, a loading animation should be displayed on the interface.

Following this, open the video stream with getDeviceStream and initiate the capture process with client.start. It is essential to wait for the onClientInitEnd callback before displaying the video preview from the end-user. Failure to implement or properly use onClientInitEnd may result in visual glitches.

Tracking Info

The content of the callback trackingFn() is shown in the table :

uploadProgress:

uploadProgress can be handled optionally by the client application to show a progress bar after capture is performed, and before the server gives final result. When uploadProgress reaches the value 1, means all the data expected by the server has been received. The client application will now wait for the server result which will happen in onDocCaptured() callback.

Example:

JavaScript
1{ uploadProgress: 0.238 }

Here 23.8 % of data has been received so far by the server.

Note: For more information, please consult the demonstration on GitHub: https://github.com/idemia/WebCaptureSDK

OnDocCaptured Info

The content of the callback onDocCaptured() is shown in the table and almost similar to the response of the API GetDocSessionDocumentById :

Success response

If the initDocCaptureClient request is successful then the parameters in the table will be returned.

start 

The start function uses the capture client to start a document capture, as shown in the snippet:

JavaScript
1start

The sessionId that was pushed during initialization phase will be automatically used.

Parameters

The parameters for the start function are shown in the table.

Example usage

An example usage of how to start a document capture session for a specific capture identifier is shown in the snippet:

JavaScript
1// Init a doc capture client
2const docCaptureClient = await DocserverVideo.initDocCaptureClient(docCaptureOptions);
3
4// Get a videoStream
5const videoStream = await DocserverVideo.getDeviceStream();
6
7// start capture session
8docCaptureClient.start({
9    stream: videoStream
10});

finishSession 

The finishSession function notifies a back end that full capture of a document is complete even if the user made multiple attempts to capture his document.

The API can be called at any moment after session creation except during a capture document side. After calling this API, no more captures are authorized and this API cannot be called again for the session.

Note that only the last captured document will be taken into account.

JavaScript
1finishSession

Example usage

An example usage is shown in the snippet:

JavaScript
1// Init client, get a video stream, start and proceed capture
2// ...
3
4// Finish the document capture session
5docCaptureClient.finishSession();

disconnect 

The disconnect function is called to stop the document capture.

JavaScript
1disconnect

Example usage

An example usage is shown in the snippet:

JavaScript
1// Init client, get a video stream, start and proceed capture
2// ...
3
4// Stop the document capture session
5docCaptureClient.disconnect();

JS Objects 

CaptureDataJS

Parameters

The parameters for CaptureDataJS are shown in the table.

Success example usage

• An example of a successful capture of a front side is shown in the snippet:

JSON
1{
2  "id":"702dddd3-c3d7-48b0-aded-4a806acfe6dd",
3  "status":"DONE",
4  "startTime":"2022-09-06T15:45:58.932Z",
5  "endTime":"2022-09-06T15:46:03.598Z",
6  "documentId":"82544ddf-9cde-4077-a5b5-6e4d5363da32",
7  "side":{
8     "id":"SIDE1",
9     "name":"FRONT"
10  },
11  "image":"imageB64",
12  "corners":[ [ 92, 84 ], [ 3150, 160 ], [ 2982, 1934 ], [164, 1960] ],
13  "rules":[
14     {
15        "name":"MRZ",
16        "status":"DONE",
17        "result":{
18           "rawData":"[\"IDFRASMITH<<<<<<<<<<<<<<<<<<775005\",\"0000005000600JOHN<<BOB7006061F8\"]",
19           "identity":{
20              "gender":"M",
21              "fullName":"JOHN  BOB SMITH",
22              "givenNames":[
23                 "JOHN",
24                 "BOB"
25              ],
26              "surname":"SMITH",
27              "dateOfBirth":"1986-12-02"
28           },
29           "documentInfo":{
30              "documentNumber":"110677502568",
31              "issuingCountry":"FRA",
32              "mrz":[
33                 "IDFRASMITH<<<<<<<<<<<<<<<<<<775005",
34                 "0000005000600JOHN<<BOB7006061F8"
35              ]
36           }
37        }
38     }
39  ]
40}

Failure example usage

• The capture of a front side failed below because the end user may has captured twice the same side and one rule was required. An example is shown in the snippet:

JSON
1{
2  "id":"9b844aa6-fbbc-45b0-8902-2d151209cd14",
3  "status":"FAILED",
4  "startTime":"2022-09-06T15:46:09.397Z",
5  "endTime":"2022-09-06T15:46:14.003Z",
6  "documentId":"82544ddf-9cde-4077-a5b5-6e4d5363da32",
7  "side":{
8     "id":"SIDE1",
9     "name":"FRONT"
10  },
11  "image":"imageB64",
12  "corners":[ [ 92, 84 ], [ 3150, 160 ], [ 2982, 1934 ], [164, 1960] ],
13  "rules":[
14     {
15        "name":"MRZ",
16        "status":"FAILED",
17        "diagnostic":{
18           "duplicateRules":true
19        },
20        "result":{
21           "rawData":"[\"IDFRASMITH<<<<<<<<<<<<<<<<<<775005\",\"0000005000600JOHN<<BOB7006061F8\"]",
22           "identity":{
23              "gender":"M",
24              "fullName":"JOHN BOB SMITH",
25              "givenNames":[
26                 "JOHN",
27                 "BOB"
28              ],
29              "surname":"SMITH",
30              "dateOfBirth":"1986-12-02"
31           },
32           "documentInfo":{
33              "documentNumber":"110677502568",
34              "issuingCountry":"FRA",
35              "mrz":[
36                 "IDFRASMITH<<<<<<<<<<<<<<<<<<775005",
37                 "0000005000600JOHN<<BOB7006061F8"
38              ]
39           }
40        }
41     }
42  ],
43  "diagnostic":{
44     "duplicateRules":true
45  }
46}

• The capture of a back side failed below because the end user may has captured twice the same side and two rules were required. An example is shown in the snippet: :

JSON
1{
2  "id":"64b95cd3-efbf-46e4-8066-618bcbf7f366",
3  "status":"FAILED",
4  "startTime":"2022-09-06T16:52:30.519Z",
5  "endTime":"2022-09-06T16:52:35.670Z",
6  "documentId":"1d2f5c9a-3c11-4139-8832-7712580f39e9",
7  "side":{
8    "id":"SIDE2",
9    "name":"BACK"
10  },
11  "image":"imageB64",
12  "corners":[ [ 92, 84 ], [ 3150, 160 ], [ 2982, 1934 ], [164, 1960] ],
13  "rules":[
14    {
15      "name":"PDF417",
16      "status":"FAILED",
17      "diagnostic":{
18        "duplicateRules":true
19      },
20      "result":{
21        "rawData":"rawDataB64"
22      }
23    },
24    {
25      "name":"MRZ",
26      "status":"FAILED",
27      "diagnostic":{
28        "missingRules":true
29      }
30    }
31  ],
32  "diagnostic":{
33    "missingRules":true,
34    "duplicateRules":true
35  }
36}

• The capture of a front side exceeded the capture timeout. It was not possible to detect any document. An example is shown in the snippet:

JSON
1{
2   "id": "d939cd53-d781-4661-b129-58883f948875",
3   "status": "TIMEOUT",
4   "side": { "id": "SIDE1", "name": "FRONT" },
5   "diagnostic": { "tooFar": "true" },
6  
7   "rules": [{
8        "name": "MRZ",
9        "status": "TIMEOUT"
10    }]
11 }

CaptureDiagnostic

The CaptureDiagnostic object describes the diagnostic quality of the capture as shown in the snippet.

Parameters

The parameters for CaptureDiagnostic are shown in the table.

Example usage

An example usage for CaptureDiagnostic is shown in the snippet:

• The document is captured with a bad quality :

JSON
1{
2  "blur": "true",
3  "tooFar": "true",
4  "glare": "true"
5}

• The user may have captured the same document side twice is indicated by the absence of an MRZ (Machine Readable Zone) detection.

JSON
1{
2  "missingRules": "true"
3}

• The user may have captured the same document side twice is indicated by the absence of an MRZ (Machine Readable Zone) detection.

JSON
1{
2  "duplicateRules": "true"
3}

CaptureRule

The CaptureRule object describes the capture rule name, status, and result as shown in the snippet:

Parameters

The parameters for CaptureRule are shown in the table.

Example usage

An example usage for CaptureRule is shown in the snippet:

JSON
1{
2  "name": "OCR",
3  "status": "DONE",
4  "result": {
5    "rawData": "ocr_raw_data",
6    "identity": {
7      "placeOfBirth": "",
8      "fullName": "John Doe",
9      "dateOfBirth": "1979-10-10",
10      "gender": "M",
11      "completeAddress": "1st Avenue New York, NY 10017"
12    },
13    "documentInfo": {
14      "documentNumber": "180978453573",
15      "issuingCountry": "USA",
16      "dateOfIssuance": "2015-10-30",
17      "dateOfExpiry": "2025-10-30"
18    }
19  }
20}

CaptureRuleResult

The CaptureRuleResult object describes information extracted from the captured document as shown in the snippet:

Parameters

The parameters for CaptureRuleResult are shown in the table.

Example usage

An example usage for CaptureRuleResult is shown in the snippet:

• PDF417 rule result

JSON
1{
2  "rawData": "QAoeDUFOU0kgNjM2MDQxMDQwMDAySUQwMDQxMDIyN1pNMDI2ODAwMzdJRERBUTczMTIzNTMKRENTRE9FCkRERVUKREFDTUFSWQpEREZVCkRBREpBTkUKRERHTgpEQkQwNDAxMjAxNQpEQkIwOTA4MTk5OApEQkEwNDAxMjAxOQpEQkMyCkRBVTA3NiBpbgpEQVlCUiAKREFHMjIyIEVMTSBSRApEQUlPTEQgVE9XTgpEQUpNRQpEQUsxMjM0NTAwMDAgIApEQ0ZOT05FCkRDR1VTQQpEQVcxMTAKREFaR1IKRENLRjE1MDkxNzMxMjM1MzcwMDEKRERBTgpEREIwOTAzMjAxMApEREQxDVpNWk1BWQpaTUJVMTgwOTA4MjAxNgpaTUNVMjEwOTA4MjAxOQ0=",
3  "identity": {
4    "gender": "F",
5    "fullName": "MARY JANE DOE",
6    "givenNames": [
7      "MARY",
8      "JANE"
9    ],
10    "surname": "DOE",
11    "dateOfBirth": "1998-09-08",
12    "completeAddress": "222 ELM RD, OLD TOWN, ME",
13    "address": {
14      "streets": [
15        "222 ELM RD"
16      ],
17      "city": "OLD TOWN",
18      "state": "ME",
19      "postalCode": "123450000  "
20    }
21  },
22  "documentInfo": {
23    "documentNumber": "7312353",
24    "dateOfIssuance": "2015-04-01",
25    "dateOfExpiry": "2019-04-01",
26    "issuingCountry": "USA"
27  }
28}

• MRZ rule result

JSON
1{
2  "rawData": "[\"IDFRASAMPLE<<<<<<<<<<<<<<<<<<775005\",\"9906995099998TEST<<JEAN9612021M8\"]",
3  "identity": {
4    "gender": "M",
5    "fullName": "TEST JEAN SAMPLE",
6    "givenNames": [
7      "TEST",
8      "JEAN"
9    ],
10    "surname": "SAMPLE",
11    "dateOfBirth": "1996-12-02"
12  },
13  "documentInfo": {
14    "documentNumber": "990699509999",
15    "issuingCountry": "FRA",
16    "mrz" : [
17      "IDFRASAMPLE<<<<<<<<<<<<<<<<<<775005",
18      "9906995099998TEST<<JEAN8612021F8"
19    ]
20  }
21}

DocumentSide

The DocumentSide object describes extracted information related to the side of the document being captured during the document session.

Parameters

The parameters for DocumentSide are shown in the table.

Example usage

An example usage for DocumentSide is shown in the snippet:

JSON
1{
2  "id": "SIDE1",
3  "name":"FRONT"
4}

DocumentInfo

This object describes extracted information related to the side of the document being captured during the document session.

Parameters

The parameters for DocumentInfo are shown in the table.

Example usage

An example usage for DocumentInfo is shown in the snippets:

JSON
1{
2  "documentNumber": "180978453573",
3  "dateOfIssuance": "2015-10-30",
4  "dateOfExpiry": "2025-10-30",
5  "issuingCountry": "USA"
6}

JSON
1{
2  "documentNumber": "1999979925688",
3  "dateOfIssuance": "2015-10-30",
4  "dateOfExpiry": "2025-10-30",
5  "issuingCountry": "FRA",
6  "mrz": [
7    "IDFRAVALXXXL<<<<<<<<<<<<<<<<<<445115",
8    "1999979925688ARMELIA<<MXXCE9912991F8"
9  ]
10}

Identity

The Identity object describes information that is extracted about the user's identity from the captured document.

Parameters

The parameters for Identity are shown in the table.

Example usage

An example usage for Identity is shown in the snippet:

JSON
1{
2  "fullName": "John Doe",
3  "dateOfBirth": "1979-01-31",
4  "placeOfBirth": "New York",
5  "gender": "M",
6  "completeAddress": "06 NEEDHAM STREET, NEWTON, MA 024611638",
7  "address": {
8    "streets": ["06 NEEDHAM STREET", "APT # 555"],
9    "city": "NEWTON",
10    "state": "MA",
11    "postalCode": "024611638"
12  }
13}

IdentityAddress

The IdentityAddress object describes information that is extracted about the user's identity from the captured document.

Parameters

The parameters for IdentityAddress are shown in the table.

Example usage

An example usage for IdentityAddress is shown in the snippet:

JSON
1{
2  "address": {
3    "streets": ["06 NEEDHAM STREET", "APT # 555"],
4    "city": "NEWTON",
5    "state": "MA",
6    "postalCode": "024611638"
7  }
8}

Global Error Codes 

The table shows the global error codes for document autocapture SDK :

Enums 

CaptureRuleName

The CaptureRuleName extracts the rule name at the end of the autocapture as shown in the snippet:

The parameter values for CaptureRuleName are described in the table.

The allowed values are:

• MRZ: The Machine Readable Zone (MRZ) content is extracted at the end of the autocapture.
• PDF417: Auto capture continues until a valid barcode is decoded or until the timeout expiration.

CaptureRuleStatus

The CaptureRuleStatus sends a status response for the rule name extraction at the end of the autocapture as shown in the snippet:

The parameter values for CaptureRuleStatus are shown in the table.

The allowed values are:

• IN_PROGRESS: The user starts streaming video capture to webDocServer
• DONE: A capture is done and identity information is extracted depending on the applied rules
• FAILED: Unable to extract the identity information from the detected document
• TIMEOUT: Unable to detect a document from user video stream within a configured timeout
• ABORTED: The user aborted the session
• ERROR: A technical error has occurred during document capture

DocumentCaptureStatus

The DocumentCaptureStatus function returns the status of the document capture as shown in the snippet:

The parameter values for DocumentCaptureStatus are shown in the in the table.

The allowed values are:

• IN_PROGRESS: The user starts streaming video capture to webDocServer
• DONE: A capture is done and identity information is extracted depending on the applied rules
• FAILED: Unable to extract the identity information from the detected document
• TIMEOUT: Unable to detect a document from user video stream within a configured timeout
• ABORTED: The user aborted the session
• ERROR: A technical error has occurred during document capture

DocumentSideName

The DocumentSideName function describes the physical side of the document that is being captured as shown in the snippet:

The parameter values for DocumentSideName are described in the table.

The allowed values are:

• FRONT: Front of the document
• BACK: Back of the document
• INSIDE_PAGE: Used for passport-like documents

FAQs 

Where can I find sample source code showing API integration? 

A demo app is available to showcase the integration of IDEMIA WebCapture SDK for IDEMIA Identity offer:

• GitHub Repository: https://github.com/idemia/WebCaptureSDK
• Section: ID Document Autocapture

How do I run sample source code from GitHub? 

1. Install npm on your machine

2. Download the GitHub sources.

3. Update the demo configuration /server/config/defaults.js as shown in the snippet:

JavaScript
1// Remote server to call
2DOCSERVER_VIDEO_URL: 'https://<host>:<port>',
3WEB_SDK_LIVENESS_ID_DOC: 'YOUR_API_KEY',
4
5// Callback management
6DISABLE_CALLBACK: true, // Set this key to true to disable callback functionality
7SERVER_PUBLIC_ADDRESS: 'https://<host>:<port>',
8DOC_CAPTURE_CALLBACK_URL: '/<callback-service>'

Note: You must point to the desired platform. By default you are calling a staging platform.

You can also enable ID&V Demo integration as shown in the snippet:

JavaScript
1// ID&V Demo integration
2GIPS_URL: 'https://<host>:<port>/gips/rest',
3GIPS_RS_API_Key: 'YOUR_API_KEY',
4IDPROOFING: false // Enable ID&V Demo integration : true or false

4. Go to GitHub sources root and install npm (only once) as shown in the snippet:

Shell
1npm i --verbose

You must run the demo every time you want to use it as shown in the snippet:

Shell
1npm run start

5. Go to https://localhost:9943/demo-doc/

How do I test sample source code from GitHub with an Android phone? 

1. Run sample source code from GitHub on your local machine.

2. Setup your phone:

• Download and install scrcpy: https://github.com/Genymobile/scrcpy#get-the-app
• Enable developer options on Android phone: https://developer.android.com/studio/debug/dev-options
• Enable the Debugging option: https://developer.android.com/studio/debug/dev-options#debugging
• Plug the USB cable into your phone and select the File Sharing USB mode or similar
• Always accept the certificate or key from the computer when prompted on the device

Open a terminal, go to the the installation folder, and launch it once as shown in the snippet:

Shell
1adb devices

Start the adb deamon once and display the status of the connected device as shown in the snippet:

Shell
1* daemon not running; starting now at tcp:5037
2* daemon started successfully
3List of devices attached
4XXXX128PX       device

If you don't see your device:

• Try to unplug or plug the USB cable
• Set the proper USB mode
• Check if the debugging option is enabled on device

3. Redirect the mobile port to your local machine port as shown in the snippet:

Shell
1adb reverse tcp:[device port] tcp:[machine port]

An example usage is shown in the snippet:

Shell
1adb reverse tcp:9943 tcp:9943

This will forward all mobile connections on port 9943 to local machine port 9943. So if you open a browser with http://localhost:9943, all requests will be sent to your local server running on port 9943.

4. Display the phone screen on the local machine launching the command as shown in the snippet:

Shell
1scrscpy

The device screen should now be displayed on your local machine.

How do I debug sample source code from GitHub with an Android phone? 

1. Follow procedure regarding how to test sample source code from GitHub with an Android phone.

2. Open the Chrome browser on you local machine and go to: chrome://inspect/#devices.

3. Click inspect.

If you have an issue, check port settings and target settings as shown:

4. Open https://localhost:9943/demo-doc/ on your smartphone's Chrome browser.

On you local machine, look at console traces (section Console). You are are also able to add break-points on section Sources.

Why a black screen is visible at the end of the autocapture? 

The presence of a black screen serves security purposes. During this period, the system will compute the final best image of the person, and the video stream must remain uninterrupted. To ensure a seamless user experience, the black screen should be concealed within the webpage responsible for the auto-capture user interface.

Upon receiving the 'pending' message in the trackingFn callback, it's essential to display a loader to the end user. This informs them that the capture process is still ongoing, and they should patiently await their results. This best practice is already incorporated within our 'demo-server' sample application, is accessible on GitHub at: https://github.com/idemia/WebCaptureSDK

How do I generate a self-signed certificate? 

1. Install openssl and execute the command as shown in the snippet:

Bash
1openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 3650 -subj '/CN=demo-doc' -config openssl.cnf -extensions v3_req -nodes

2. Import your private key and certificate into a PKCS#12 keystore file as shown in the snippet:

Bash
1openssl pkcs12 -export -out demo-doc.p12 -inkey key.pem -in cert.pem -keypbe AES-256-CBC -certpbe AES-256-CBC

Note: This configuration is for development only. In production, you must obtain your server certificate from a public trusted authority and use a domain name you own.

How to integrate the SDK in a WebView? 

When integrating the WebCapture SDK in a WebView, it is important to configure some settings of the Android or iOS app. Not following the recommendations will lead to unexpected behaviors or errors such as fatal exceptions, camera preview not displayed...

Android WebView

1. One must add the CAMERA permission in the app's AndroidManifest.xml file:

XML
1<uses-permission android:name="android.permission.CAMERA"></uses-permission>

2. After creating the WebView object, one must modify the default WebSettings as follows:

Java
1// webView object has been instantiated
2WebSettings webSettings = webView.getSettings();
3webSettings.setJavaScriptEnabled(true);
4webSettings.setDomStorageEnabled(true);
5webSettings.setMediaPlaybackRequiresUserGesture(false); // CRITICAL

iOS WKWebView

1. One must include the NSCameraUsageDescription property in the App's Info.plist file
2. When creating the WKWebView instance, it must be configured as follows:

JavaScript
1let prefs = WKWebpagePreferences()
2prefs.allowsContentJavaScript = true
3let configuration = WKWebViewConfiguration()
4configuration.defaultWebpagePreferences = prefs
5configuration.allowsInlineMediaPlayback = true // CRITICAL
6let webView = WKWebView(frame: .zero, configuration: configuration)