Get Started

This page will guide you through the process of adding ID Capture to your Web application. ID Capture is a mode of the Scandit Data Capture SDK that allows you to capture and extract information from personal identification documents, such as driver's licenses, passports, and ID cards.

The general steps are:

• Create a DataCaptureContext.
• Access a Camera.
• Use IdCaptureSettings to configure the scan process.
• Implement an IdCaptureListener to receive scan results.
• Set up DataCaptureView and IdCaptureOverlay to see the camera feed and the scan UI.
• Begin the scanning by adding an IdCapture to DataCaptureContext and starting a camera.

warning

Using ID Capture at the same time as other modes (e.g. Barcode Capture) is not supported.

Prerequisites

Before starting with adding a capture mode, make sure that you have a valid Scandit Data Capture SDK license key and that you added the necessary dependencies. If you have not done that yet, check out this guide.

tip

You can retrieve your Scandit Data Capture SDK license key by signing in to your Scandit account.

Please note that your license may support only a subset of ID Capture features. If you would like to use additional features please contact us at Scandit Support.

Module Overview

The modules that need to be included in your project depend on the features you want to use. The following table lists what modules you need to include in your project, depending on the features you want to use.

Module	Required for Feature
ScanditCaptureCore	Always
ScanditIdCapture	Always
ScanditIdCaptureBackend	Extract data from VIZ (e.g. front of IDs and driver licenses, human-readable data on Passport, etc.)
ScanditIdAamvaBarcodeVerification	Verify US Driver Licenses
ScanditIdVoidedDetection	Reject voided IDs

tip

Note that your license may support only a subset all ID Capture capabilities. If you need to use additional features, contact us.

Configure and Initialize the Library

In addition to the configuration detailed in the installation guide, there are some additional steps required for ID Capture.

For ID Capture, the result of idCaptureLoader() must be passed to the ConfigureOptions.moduleLoaders option.

In this example, we will scan VIZ documents, so we also need to set IdCaptureLoaderOptions.enableVIZDocuments to true:

import { configure } from '@scandit/web-datacapture-core';
import { idCaptureLoader } from '@scandit/web-datacapture-id';

await configure({
	licenseKey: '-- ENTER YOUR SCANDIT LICENSE KEY HERE --',
	libraryLocation: '/sdc-lib/',
	moduleLoaders: [idCaptureLoader({ enableVIZDocuments: true })],
});

warning

You must await the returned promise as shown to be able to continue.

Server Side Rendering and Server Side Generation

If you use a web framework that renders also on the server (SSR or SSG) it’s recommended to execute the library only on the client turning off the rendering on the server.

For more information:

• GatsbyJS - Using client side only packages.
• NextJS - Lazy Loading with no ssr.

Show loading status with default UI

To show some feedback to the user about the loading status you have two options: use the default UI provided with the SDK or subscribe to the loading status and update your own custom UI. Let’s see how we you can show the default UI first:

import { configure, DataCaptureView, DataCaptureContext } from "@scandit/web-datacapture-core"
const view = new DataCaptureView();

view.connectToElement(document.getElementById('data-capture-view'));
view.showProgressBar();
view.setProgressBarMessage('Loading ...');

await configure({
	licenseKey: '-- ENTER YOUR SCANDIT LICENSE KEY HERE --',
	libraryLocation: '/engine/',
	moduleLoaders: [idCaptureLoader({ enableVIZDocuments: true })],
});

view.hideProgressBar();

const context: DataCaptureContext = await DataCaptureContext.create();
await view.setContext(context);

Show loading status with custom UI

You can also just subscribe for the loading status of the library by simply attaching a listener like this:

import { configure, loadingStatus } from "@scandit/web-datacapture-core"
loadingStatus.subscribe((info) => {
	// updateUI(info.percentage, info.loadedBytes)
});

await configure({
	licenseKey: 'SCANDIT_LICENSE_KEY',
	libraryLocation: '/engine',
	moduleLoaders: [barcodeCaptureLoader()],
});

note

We suggest serving the library files with the proper headers Content-Length and Content-Encoding if any compression is present. In case of totally missing information, we show an estimated progress.

Create the Data Capture Context

The first step to add capture capabilities to your application is to create a new data capture context.

import { DataCaptureContext } from "@scandit/web-datacapture-core"

// the license key used in configure() will be used
const context = await DataCaptureContext.create();

Add the Camera

You need to also create the Camera:

import { Camera } from "@scandit/web-datacapture-core";
import { IdCapture } from "@scandit/web-datacapture-id";


const camera = Camera.default;
await context.setFrameSource(camera);

const cameraSettings = IdCapture.recommendedCameraSettings;

// Depending on the use case further camera settings adjustments can be made here.

await camera.applySettings(cameraSettings);

Create ID Capture Settings

Use IdCaptureSettings to configure the scanner type to use and the documents that should be accepted and/or rejected.

Check IdCaptureDocumentType for all available options.

const settings = new IdCaptureSettings();

// Documents from any region:
settings.acceptedDocuments.push(new IdCard(Region.AnyRegion));
// Only documents issued by a specific country:
settings.acceptedDocuments.push(new IdCard(Region.Germany));
// Regional documents:
settings.acceptedDocuments.push(new RegionSpecific.ApecBusinessTravelCard());
// Reject passports from certain regions:
settings.rejectedDocuments.push(new Passport(Region.Cuba));

// To scan only one-sided documents and a given zone:
settings.scannerType = new SingleSideScanner({ barcode: true });
// or
settings.scannerType = new SingleSideScanner({ machineReadableZone: true });
// or
settings.scannerType = new SingleSideScanner({ visualInspectionZone: true });

// To scan both sides of the document:
settings.scannerType = new FullDocumentScanner();

Create a new ID Capture mode with the chosen settings:

const idCapture = IdCapture.forContext(context, settings);

Implement the Listener

To receive scan results, implement IdCaptureListener. The listener provides two callbacks: onIdCaptured and onIdRejected.

idCapture.addListener({
	onIdCaptured: (data) => {
		// Success! Handle extracted data here.
	},
	onIdRejected: (data, reason) => {
		// Something went wrong. Inspect the reason to determine the follow-up action.
	}
});

Handling Success

Capture results are delivered as a CapturedId. This class contains data common for all kinds of personal identification documents.

For more specific information, use its non-null result properties (e.g. CapturedId.barcode).

On a successful scan you may read the extracted data from CapturedId:

onIdCaptured: (data) => {
	const fullName = data.fullName;
	const dateOfBirth = data.dateOfBirth;
	const dateOfExpiry = data.dateOfExpiry;
	const documentNumber = data.documentNumber;

	// Process data:
	processData(fullName, dateOfBirth, dateOfExpiry, documentNumber);
}

tip

All data fields are optional, so it's important to verify whether the required information is present if some of the accepted documents may not contain certain data.

Handling Rejection

The ID scanning process may fail for various reasons. Start from inspecting RejectionReason to understand the cause.

You may wish to implement the follow-up action based on the reason of failure:

onIdRejected: (data, reason) => {
	if (reason === RejectionReason.Timeout) {
		// Ask the user to retry, or offer alternative input method.
	} else if (reason === RejectionReason.DocumentExpired) {
		// Ask the user to provide alternative document.
	} else if (reason === RejectionReason.HolderUnderage) {
		// Reject the process.
	}
}

Set up Capture View and Overlay

When using the built-in camera as frameSource, you will typically want to display the camera preview on the screen together with UI elements that guide the user through the capturing process.

To do that, add a DataCaptureView to your view hierarchy:

const view = await DataCaptureView.forContext(context);
view.connectToElement(htmlElement);

Then create an instance of IdCaptureOverlay attached to the view:

import { IdCaptureOverlay } from "@scandit/web-datacapture-id";

// ...

let overlay = await IdCaptureOverlay.withIdCaptureForView(
	idCapture,
	dataCaptureView
);

The overlay chooses the displayed UI automatically, based on the selected IdCaptureSettings.

If you prefer to show a different UI or to temporarily hide it, set the appropriate IdCaptureOverlay.idLayout.

Start the Capture Process

Finally, turn on the camera to start scanning:

import { FrameSourceState } from "@scandit/web-datacapture-core";

// ...

await camera.switchToDesiredState(FrameSourceState.On);