AutoCapture

This project contains Datachecker's AutoCapture tool, that captures images of identity documents (ID/Passport/Driver license). The tool only takes a capture once a document is detected and it passes the quality control.

The tool will be run in the browser and is therefore written in JavaScript.

Trigger mechanism

The tool performs the following checks:

Is the environment not too dark (under exposure)?
Is there a document?
Is the detected document not too far?
Is the detected document not too close?
Is the image sharp?

Prerequisites

Please visit Datachecker API documentation.

Datachecker OAuth Token
Datachecker SDK Token

Steps

Request OAUTH Token
Put OAuth in header
SDK configuration (add SDK token)
Run SDK

OAuth Token

Datachecker uses OAuth authorization. In order to request the SDK token you will need to provide a valid OAuth token in the header.

Example header:

header = {'Authorization': `Bearer ${response.accessToken}`}

This OAuth token can be retrieved with the Datachecker OAuth Token API. The scope "productapi.sdk.read" needs to be present to make use of the SDK token. If this scope is missing you will not be able to retrieve an SDK token.

Example OAuth:

fetch(<BASE_ENDPOINT>+"/oauth/token", {
    method: 'POST',
    body: JSON.stringify({
        "clientId": <CLIENTID>,
        "clientSecret": <CLIENTSECRET>,
        "scopes": [
            "productapi.sdk.read",
        ]
    })
})
.then(response => response.json())

Note: Contact Datachecker for client_id and client_secret.

SDK Token

The SDK is locked. In order to use the SDK in production a token is required. The application can only be started with a valid token. This token is a base64 string. The token can be generated by calling the Datachecker SDK Token API.

Example:

fetch(<BASE_ENDPOINT>+"/sdk/token?customer_reference=<CUSTOMER>&services=AUTO_CAPTURE", {
    method: 'GET',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': `Bearer <ACCESSTOKEN>`
    }
})
.then(response => response.json())

Configuration

To run this tool, you will need initialise with the following variables.

ATTRIBUTE	FORMAT	DEFAULT VALUE	EXAMPLE	NOTES
`ALWAYS_FLIP`	bool	`false`	`true`	optional Always perform flipping even when `MRZ` scanning is `false`.
`APPROVAL`	bool	`false`	`false`	optional Approval screen after capture as an extra quality check.
`ASSETS_FOLDER`	string	`""`	`"../"`	optional Specifies location of locally hosted assets folder. (see Asset Fetching Configuration)
`ASSETS_MODE`	string	`"CDN"`	`"LOCAL"`	optional Specifies mode of asset fetching, either through CDN or locally hosted assets. (see Asset Fetching Configuration)
`BACKGROUND_COLOR`	string (Hex color code)	`"#1d3461"`	`"#1d3461"`	optional Specifies the background color using a hex color code.
`CAPTURE_BTN_AFTER`	int	`5000`	`0`	optional Configures a delay for the capture button's appearance in milliseconds. Setting this parameter to `0` disables the button. For active use, specify the delay before the button is displayed.
`CONTAINER_ID`	string		`"AC_mount"`	required div id to mount tool on. If the `div` does not exist it will be created and placed in `<body>`.
`CROP_CARD`	bool	`false`	`false`	optional Enable cropping of card as output.
`CROP_FACE`	bool	`true`	`true`	optional Enable cropping of face as output.
`DEBUG`	bool	`false`	`false`	optional When debug is `true` more detailed logs will be visible.
`GLARE_LIVE_CHECK`	bool	`true`	`true`	optional Enable glare detection.
`LANGUAGE`	string	`"nl"`	`"nl"`	required Notifications in specific language.
`MRZ_SETTINGS`	object	see MRZ_SETTINGS	see MRZ_SETTINGS	optional Settings of MRZ scanning.
`MRZ`	bool	`false`	`false`	optional Enable MRZ scanning.
`onComplete`	javascript function		`function(data) {console.log(data)}`	required Callback function on complete.
`onError`	javascript function	`function(error) {console.log(error)}`	`function(error) {console.log(error)}`	required Callback function on error.
`onImage`	javascript function	`function(data) {console.log(data)}`	`function(data) {console.log(data)}`	optional Callback function on image.
`onUserExit`	javascript function	`function(error) {console.log(error)}`	`function(error) {window.history.back()}`	required Callback function on user exit.
`ROI_MODE`	string	`"landscape-landscape"`	`portrait-landscape`	optional Frame orientation options: `"portrait-landscape"`, `"landscape-landscape"`
`TOKEN`	string		see SDK Token	required Datachecker SDK token.

Asset fetching Configuration

AutoCapture requires fetching assets, which can be done either through a CDN or by hosting them locally. Configure this in the tool settings as follows:

CDN Configuration

// configuration
{
    ASSETS_MODE: "CDN",
    // other configurations
}

Locally Hosting Configuration

To host assets locally, first copy them to your desired location:

cp -r dist/assets/ path/to/hosted/assets/

Then, configure the tool to use these local assets:

// configuration
{
    ASSETS_MODE: "LOCAL",
    ASSETS_FOLDER: "path/to/hosted/assets/",
    // other configurations
}

For comphrehensive integration examples, please refer to our Integration Examples.

Version Control

To ensure compatibility:

Separate Asset Versioning: The assets directory contains a version file, separate from the main file's version.
Compatibility Check: The main file will perform a version check and throw an error if the versions are incompatible.

Handling callbacks

Within the application, you can take advantage of four callback functions to enhance the user experience and manage the flow of your process.

Note: When integrating the application into Native Apps using web views, it's essential to adapt and utilize these callback functions according to the conventions and requirements of the native platforms (e.g., iOS, Android). Native app development environments may have specific ways of handling JavaScript callbacks, and you should ensure seamless communication between the web view and the native code.

Example Web (JS):

let AC = new AutoCapture();
AC.init({
    CONTAINER_ID: 'AC_mount',
    LANGUAGE: 'en',
    TOKEN: "<SDK_TOKEN>",
    onComplete: function(data) {
        console.log(data);
    },
    onImage: function(data) {
        console.log(data);
    },
    onError: function(error) {
        console.log(error)
    },
    onUserExit: function(error) {
        console.log(error);
        window.history.back();
    }
});

ATTRIBUTE	FORMAT	DEFAULT VALUE	EXAMPLE	NOTES
`onComplete`	javascript function		`function(data) {console.log(data)}`	required Callback that fires when all interactive tasks in the workflow have been completed.
`onError`	javascript function	`function(error) {console.log(error)}`	`function(error) {console.log(error)}`	required Callback that fires when an error occurs.
`onImage`	javascript function	`function(data) {console.log(data)}`	`function(data) {console.log(data)}`	optional Callback that fires when frame succesfully passes quality controls. This callback can be used when you want to process or analyze live frames. (See External-MRZ)
`onUserExit`	javascript function	`function(error) {console.log(error)}`	`function(error) {window.history.back()}`	required Callback that fires when the user exits the flow without completing it.

onComplete

This callback function will be called once all the tasks within the workflow succesfully have been completed. This callback function is required. The data parameter within the function represents the output of the completed process. You can customize this function to handle and display the data as needed.

Example Web (JS):

Within the example below we are logging the output (data) to console.

let AC = new AutoCapture();
AC.init({
    ...,
    onComplete: function(data) {
        console.log(data);
    }
});

onImage

This callback function will be called when a frame succesfully passes quality controls. This callback can be used when you want to process or analyze live frames (See External-MRZ). This callback function is optional. The data parameter within the function represents the frame that succesfully passed the quality controls. It's format is a base64 image string where the Data URI ("data:image/png;base64,") has been taken off.

Example Web (JS):

Within the example below we are logging the output (data) to console.

let AC = new AutoCapture();
AC.init({
    ...,
    onImage: function(data) {
        // data = "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADg....."
        console.log(data)
    }
});

onError

This callback can be used to alert users when something goes wrong during the process. This callback function is required. The error parameter within the function contains information about the specific error encountered, allowing you to log or display error messages for debugging or user guidance. The errors that are thrown are either known or unknown. The known errors can be found within the Languages dictionary. On the other hand, the unknown errors will be thrown as is.

Example Web (JS):

Within the example below we are logging the output (error) to console.

let AC = new AutoCapture();
AC.init({
    ...,
    onError: function(error) {
        console.log(error)
    }
});

onUserExit

This callback can be used to implement actions like returning users to the previous page or prompting them for confirmation before exiting to ensure they don't lose any unsaved data or work. This callback function is required. The error parameter within the function contains information about the specific error encountered, allowing you to log or display error messages for debugging or user guidance. The error that is thrown is "exit".

Example Web (JS):

Within the example below we are logging the output (error) to console. Finally, we move back one page in the session history with window.history.back().

let AC = new AutoCapture();
AC.init({
    ...,
    onUserExit: function(error) {
        console.log(error);
        window.history.back()
    }
});

Usage/Examples

The tool first needs to be initialised to load all the models. Once its initialised, it will be started.

let AC = new AutoCapture();
AC.init({
    CONTAINER_ID: ...,
    LANGUAGE: ...,
    TOKEN: ...,
    onComplete: ...,
    onError: ...,
    onUserExit: ...
});

To stop the camera and delete the container with its contents the stop function can be called. This function will automatically be called within onComplete, onError and onUserExit thus do not have to be called within your own custom versions of these functions.

...
AC.stop();

Example below:

let AC = new AutoCapture();
AC.init({
    CONTAINER_ID: 'AC_mount',
    LANGUAGE: 'nl',
    TOKEN: "<SDK_TOKEN>",
    onComplete: function(data) {
        console.log(data);
    },
    onError: function(error) {
        console.log(error)
    },
    onUserExit: function(error) {
        console.log(error);
        window.history.back()
    }
});

Importing SDK

Import the SDK with one of the three methods: Script tag, ES6 or CommonJS.

Script Tag

Easily add AutoCapture to your HTML files using the Script Tag method.

<!-- Add AutoCapture directly in your HTML -->
<script src="dist/autocapture.obf.js"></script>

NPM

For projects using NPM and a module bundler like Webpack or Rollup, you can import AutoCapture as an ES6 module or with CommonJS require syntax.

// Import AutoCapture in your JavaScript file

// ES6 style import
import AutoCapture from '@datachecker/autocapture';

// CommonJS style require
let AutoCapture = require('@datachecker/autocapture')

Demo

<!DOCTYPE html>
<html>
<head>
<title>AutoCapture</title>
</head>

<body>
    <div id="AC_mount"></div>
</body>

<script src="autocapture.obf.js" type="text/javascript"></script>

<script>
    let AC = new AutoCapture();
    AC.init({
        CONTAINER_ID: 'AC_mount',
        LANGUAGE: 'nl',
        TOKEN: "<SDK_TOKEN>",
        onComplete: function (data) {
            console.log(data)
        },
        onError: function(error) {
            console.log(error)
        },
        onUserExit: function(error) {
            console.log(error);
            window.history.back()
        }
    });
</script>

</html>

For comphrehensive integration examples, please refer to our Integration Examples.

Languages

There are two ways in which notifications can be loaded: from file, from object (json).

File

The languages can be found in assets/language/. The current support languages are en and nl. More languages could be created.

The notifications can be loaded in configuration like the following:

let AC = new AutoCapture();
AC.init({
    LANGUAGE: 'en',
    ...

To create support for a new language, a js file needs to be created with specific keys. The keys can be derived from the current language js files (assets/language/en.js).

Example:

var LANGUAGE = {
    "start_prompt": "Tap to start",
    "flip": "Flip the document",
    "flip_frontside": "Flip the document to the frontside",
    "flip_backside": "Flip the document to the backside",
    "std_msg_0": "Place your document",
    "exp_dark": "Environment is too dark",
    "exp_bright": "Environment is too bright",
    "blur": "Hold still...",
    "glare": "Glare detected",
    "size": "Move closer",
    "focus": "Focus on document.",
    "approval_prompt": "Is the image right?",
    "retry": "Try again",
    "confirm": "Accept",
    "capture_error": "We were unable to capture an image. Camera access is required.",
    "mrz_search": "Searching MRZ...",
    "continue": "Continue",
    "tutorial": "Follow the instructions",
    "rotate_phone": "Please rotate your phone upright",
    "camera_selection": "Please select the back camera"
}

Object (json)

Notifications can also be loaded as a json object like the following:

let AC = new AutoCapture();
AC.init({
    LANGUAGE: JSON.stringify(
        {
            "start_prompt": "Tap to start",
            "flip": "Flip the document",
            "flip_frontside": "Flip the document to the frontside",
            "flip_backside": "Flip the document to the backside",
            "std_msg_0": "Place your document in the frame",
            "exp_dark": "Environment is too dark",
            "exp_bright": "Environment is too bright",
            "blur": "Hold still...",
            "glare": "Glare detected",
            "size": "Move closer",
            "focus": "Focus on document.",
            "approval_prompt": "Is the image right?",
            "retry": "Try again",
            "confirm": "Accept",
            "capture_error": "We were unable to capture an image. Camera access is required.",
            "mrz_search": "Searching MRZ...",
            "continue": "Continue",
            "tutorial": "Follow the instructions",
            "rotate_phone": "Please rotate your phone upright",
        }
    ),
    ...

Models

The tool uses a collection of neural networks. Make sure that you host the full directory so the models can be accessed. The models path can be configured. (see Configuration) The models are located under models/.

Face

There is a face detector within the SDK. This detector will try to find the portrait picture on the document. If it is found, this face will be present in the output. Else, the output will not have any mention of face. When more faces are found only one face is being returned. The face with the highest score will be returned.

Example:

{
    "image": ["...base64_img"],
    "face": {
        "score": 0.9,
        "data": "...base64_img"
    },
}

MRZ

The application offers Machine Readable Zone (MRZ) scanning functionality, which allows it to extract information from documents containing MRZ data. This is achieved through Optical Character Recognition (OCR) techniques. The application includes an internal OCR engine specifically designed for MRZ scanning. Additionally, users have the option to integrate an external OCR engine (see External MRZ) for MRZ scanning if the internal OCR engine consumes excessive RAM.

Supported Document Types

The MRZ scanning tool supports various types of documents, including:

TD1: Travel Document Type 1
TD2: Travel Document Type 2
TD3: Travel Document Type 3
Dutch eDL: Dutch electronic driver's license

MRZ Scanning Process

The MRZ scanning process involves the following steps:

Quality Checks: MRZ scanning initiates only after passing all necessary quality checks to ensure the document's readability.
Crop and Perspective Correction: The tool identifies the location of the MRZ on the document and performs cropping and perspective correction to isolate the MRZ area. This cropped section is then used as an image for the scanning process.
- Note: When an external OCR is used, the image that will be used is the cropped card instead of the isolated MRZ area. (see External MRZ)
Retries: If the initial scan does not yield the desired results, the tool offers the option to retry scanning. In that case, the tool will try to use the next frame. Only frames that pass all the quality checks will be used. The number of retries can be configured using the following setting: (see Configuration).

MRZ_RETRIES: 5

To enable infinite retries, use:

MRZ_RETRIES: -1

Enabling MRZ Scanning

To enable MRZ scanning use MRZ: true(see Configuration).

MRZ Configuration (MRZ_SETTINGS)

ATTRIBUTE	FORMAT	DEFAULT VALUE	EXAMPLE	NOTES
`FLIP_EXCEPTION`	Array<String>	`[]`	`["P"]`	optional If `FLIP` is `true` skip these misc values. Examples of possible misc values are: `["P", "I", "D"]`.
`FLIP_INCLUDE`	Array<Object>	`[{ "misc": "all", "country": "all", "nationality": "all"}]`	`[{ "misc": "P", "country": "NLD", "nationality": "NLD", }]`	optional If `FLIP` is `true` only flip if these values are included in the `mrz` output.
`FLIP`	bool	`true`	`true`	optional Prompt user to flip card.
`MIN_VALID_SCORE`	int	`50`	`50`	optional Minimum valid score of MRZ. The valid score is a range between 0-100 indicating how valid the found MRZ is.
`MRZ_RETRIES`	int	`5`	`5`	optional Amount of retries for MRZ scanning before continuing. Use `-1` for infinite retries.
`OCR`	bool	`true`	`true`	optional Wether to use the internal OCR for MRZ reading. An external OCR can also be used see MRZ.

Example:

let AC = new AutoCapture();
AC.init({
    CONTAINER_ID: 'AC_mount',
    MRZ: true,
    MRZ_SETTINGS: {
        MRZ_RETRIES: -1,
        FLIP: true,
        FLIP_EXCEPTION: [],
        FLIP_INCLUDE: [
            {
                "misc": "I",
                "country": "all",
                "nationality": "all",
            },
            {
                "misc": "D",
                "country": "all",
                "nationality": "all",
            },
            {
                "misc": "P",
                "country": "NLD",
                "nationality": "NLD",
            },
        ],
        MIN_VALID_SCORE: 90,
        OCR: true
    },
    TOKEN: "<SDK_TOKEN>",
    onComplete: function (data) {
        console.log(data)
    },
    onError: function(error) {
        console.log(error)
    },
    onUserExit: function (error) {
        console.log(error)
        window.history.back()
    }
})

Example output:

{   
    "angle": "...",
    "type": "PASSPORT",
    "subtype": "<",
    "country": "NLD",
    "lname": "DE",
    "lname2": "BRUIJN",
    "spacing": "",
    "fname": "WILLEKE",
    "mname1": "LISELOTTE",
    "name_complement": "",
    "number": "SPECI2014",
    "check_digit_document_number": "2",
    "nationality": "NLD",
    "date_of_birth": "1965-03-10",
    "check_digit_date_of_birth": "1",
    "sex": "F",
    "expiration_date": "2024-03-09",
    "check_digit_expiration_date": "6",
    "complement": "999999990<<<<<84",
    "mrz_type": "td3",
    "raw_mrz": [
        "P<NLDDE<BRUIJN<<WILLEKE<LISELOTTE<<<<<<<<<<<",
        "SPECI20142NLD6503101F2403096999999990<<<<<84"
    ],
    "check_digit_composite": "4",
    "personal_number": "999999990",
    "check_digit_personal_number": "8",
    "valid_number": true,
    "valid_date_of_birth": true,
    "valid_expiration_date": true,
    "valid_personal_number": true,
    "valid_composite": true,
    "valid_misc": true,
    "valid_score": 100,
    "misc": "P",
    "names": "WILLEKE LISELOTTE",
    "surname": "DE BRUIJN"
}

External MRZ

It is possible to retrieve the MRZ externally and then send it to the SDK using the following approach:

Using the onImage Callback

Utilize the onImage callback to trigger an external process with the current frames.
If this external process successfully retrieves the MRZ information, it can then be sent to the SDK using the parse_mrz function.

The parse_mrz function expects the MRZ lines as an argument, provided as a single string with line breaks ("\n") separating the lines.

Here's an example of how this can be implemented in JavaScript:

// Initialize the AutoCapture SDK
let AC = new AutoCapture();
AC.init({
    // ... other configurations
    onImage: function (data) {
        // External OCR process retrieves MRZ information
        let MRZ_text = EXTERNAL_OCR_FUNCTION(data); // Example MRZ text: "P<NLDDE<BRUIJN<<WILLEKE<LISELOTTE<<<<<<<<<<<\nSPECI20142NLD6503101F2403096999999990<<<<<84"
        
        // Send the retrieved MRZ information to the SDK for parsing
        AC.parse_mrz(MRZ_text);
    },
});

Output

The SDK will output in the following structure:

{
    "image": ["...base64_img"],
    "face": {
        "score": "...",
        "data": "...base64_img"
    },
    "force_capture": ["bool"],
    "meta": [
        {
            "angle": "...",
            "coordinates": [
                ["...", "..."],
                ["...", "..."],
                ["...", "..."],
                ["...", "..."]
            ]
        }
    ],
    "token": "sdk_token"
}

With MRZ:

{
    "image": ["...base64_img"],
    "face": {
        "score": "...",
        "data": "...base64_img"
    },
    "force_capture": [false, false],
    "meta": [
        {
            "angle": "...",
            "coordinates": [
                ["...", "..."],
                ["...", "..."],
                ["...", "..."],
                ["...", "..."]
            ]
        }
    ],
    "mrz": {
        "angle": "...",
        "type": "...",
        "subtype": "...",
        "country": "...",
        "lname": "...",
        "lname2": "...",
        "spacing": "...",
        "fname": "...",
        "mname1": "...",
        "name_complement": "...",
        "number": "...",
        "check_digit_document_number": "...",
        "nationality": "...",
        "date_of_birth": "...",
        "check_digit_date_of_birth": "...",
        "sex": "...",
        "expiration_date": "...",
        "check_digit_expiration_date": "...",
        "complement": "...",
        "mrz_type": "...",
        "raw_mrz": [
            "...",
            "..."
        ],
        "check_digit_composite": "...",
        "personal_number": "...",
        "check_digit_personal_number": "...",
        "valid_number": true,
        "valid_date_of_birth": true,
        "valid_expiration_date": true,
        "valid_personal_number": true,
        "valid_composite": true,
        "valid_misc": true,
        "valid_score": true,
        "misc": "...",
        "names": "...",
        "surname": "..."
    },
    "token": "sdk_token"
}

Example:

{
    "image": ["iVBORw0KGgoAAAANSUhEUgAAAysAAAS..."],
    "face": {
        "score": 0.9,
        "data": "iVBORw0KGgoAAAANSUhEUgAAAysAAAS..."
    },
    "force_capture": [
        false,
        true
    ],
    "meta": [
        {
            "angle": 0,
            "coordinates": [
                [0, 0],
                [0, 100],
                [150, 100],
                [150, 0]
            ]
        }
    ],
    "mrz": {
        "angle": "...",
        "type": "PASSPORT",
        "subtype": "<",
        "country": "NLD",
        "lname": "DE",
        "lname2": "BRUIJN",
        "spacing": "",
        "fname": "WILLEKE",
        "mname1": "LISELOTTE",
        "name_complement": "",
        "number": "SPECI2014",
        "check_digit_document_number": "2",
        "nationality": "NLD",
        "date_of_birth": "1965-03-10",
        "check_digit_date_of_birth": "1",
        "sex": "F",
        "expiration_date": "2024-03-09",
        "check_digit_expiration_date": "6",
        "complement": "999999990<<<<<84",
        "mrz_type": "td3",
        "raw_mrz": [
            "P<NLDDE<BRUIJN<<WILLEKE<LISELOTTE<<<<<<<<<<<",
            "SPECI20142NLD6503101F2403096999999990<<<<<84"
        ],
        "check_digit_composite": "4",
        "personal_number": "999999990",
        "check_digit_personal_number": "8",
        "valid_number": true,
        "valid_date_of_birth": true,
        "valid_expiration_date": true,
        "valid_personal_number": true,
        "valid_composite": true,
        "valid_misc": true,
        "valid_score": 100,
        "misc": "P",
        "names": "WILLEKE LISELOTTE",
        "surname": "DE BRUIJN"
    },
    "token": "sdk_token"
}

@datachecker/autocapture

AutoCapture

Trigger mechanism

Prerequisites

Steps

OAuth Token

SDK Token

Configuration

Asset fetching Configuration

CDN Configuration

Locally Hosting Configuration

Version Control

Handling callbacks

onComplete

onImage

onError

onUserExit

Usage/Examples

Importing SDK

Script Tag

NPM

Demo

Languages

File

Object (json)

Models

Face

MRZ

Supported Document Types

MRZ Scanning Process

Enabling MRZ Scanning

MRZ Configuration (MRZ_SETTINGS)

External MRZ

Output

Readme

Keywords

Package Sidebar

Install

Repository

Homepage

DownloadsWeekly Downloads

Version

License

Unpacked Size

Total Files

Last publish

Collaborators

Weekly Downloads