Get Started With ID Capture

Quick overview

ID Capture provides the capability to scan personal identification documents, such as identity cards, passports or visas. In this guide you will learn step by step how to add ID Capture to your application. Roughly, the steps are:

Note

Using ID Capture at the same time as other modes (e.g. Barcode Capture or Text Capture) is currently 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.

Note

You can retrieve your Scandit Data Capture SDK license key, by signing in to your account at ssl.scandit.com.

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 support@scandit.com.

Configure and Initialize the Library

The library needs to be configured and initialized before it can be used, this is done via the configure function.

The configuration expects a valid Scandit Data Capture SDK license key as part of the options.

The ConfigureOptions.libraryLocation configuration option must be provided and point to the location of the Scandit Data Capture library/engine location (external WebAssembly files): scandit-datacapture-sdk*.min.js and scandit-datacapture-sdk*.wasm. WebAssembly requires these separate files which are loaded by our main library at runtime. They can be found inside the engine folder in the library you either added and installed via npm or access via a CDN; if you added and installed the library, these files should be put in a path that’s accessible to be downloaded by the running library script. The configuration option that you provide should then point to the folder containing these files, either as a path of your website or an absolute URL (like the CDN one). By default the library will look at the root of your website. If you use a CDN to access the library, you will want to set this to the following values depending on the data capture mode you are using:

Please ensure that the library version of the imported library corresponds to the version of the external Scandit Data Capture library/engine files retrieved via the libraryLocation option, either by ensuring the served files are up-to-date or the path/URL specifies a specific version. In case a common CDN is used here (jsDelivr or UNPKG) the library will automatically internally set up the correct URLs pointing directly at the files needed for the matching library version. It is highly recommended to handle the serving of these files yourself on your website/server, ensuring optimal compression, correct wasm files MIME type, no request redirections and correct caching headers usage; thus resulting in faster loading.

We recommended to call configure as soon as possible in your application so that the files are already downloaded and initialized when the capture process is started.

For ID Capture, the result of Id.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:

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

Note

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

Configure and Initialize the Library with loading status

Optionally you can also subscribe for the loading status of the library by simply attach a listener like this

Scandit.loadingStatus.subscribe((info) => {
 // updateUI(info.percentage, info.loadedBytes)
});

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

Note

In order to have the progress information the library files must be served with the proper headers Content-Length and Content-Encoding if any compression is present. In case of missing information the percentage will be null

Create the Data Capture Context

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

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

Add the Camera

You need to also create the Camera:

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

const cameraSettings = Scandit.IdCapture.recommendedCameraSettings;

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

if (camera != null) {
  await camera.applySettings(cameraSettings);
}

Create ID Capture Settings

Use IdCaptureSettings to configure the types of documents that you’d like to scan. Check IdDocumentType for all the available options.

Warning

Using IdDocumentType.DLVIZ or IdDocumentType.IdCardVIZ together with any MRZ document (IdDocumentType.IdCardMRZ, IdDocumentType.VisaMRZ, IdDocumentType.PassportMRZ, IdDocumentType.SwissDLMRZ) while SupportedSides.FrontAndBack is enabled is currently not supported.

const settings = new Scandit.IdCaptureSettings();
settings.supportedDocuments = [
  Scandit.IdDocumentType.IdCardVIZ,
  Scandit.IdDocumentType.AAMVABarcode,
  Scandit.IdDocumentType.DLVIZ,
]

Implement the Listener

To receive scan results, implement IdCaptureListener. A result is delivered as CapturedId. This class contains data common for all kinds of personal identification documents. For more specific information use its non-null result properties (for example CapturedId.aamvaBarcodeResult).

const listener = {
  didCaptureId: (idCapture, session) => {
    if (session.newlyCapturedId.aamvaBarcodeResult != null) {
        // Handle the information extracted.
    }
  },
  didFailWithError: (idCapture, error, session) => {
    // Handle the error.
  }
};

Create a new ID Capture mode with the chosen settings. Then register the listener:

const idCapture = await Scandit.IdCapture.forContext(context, settings);
idCapture.addListener(listener);

Use a Capture View to Visualize the Scan Process

When using the built-in camera as frame source, 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 Scandit.DataCaptureView.forContext(context);
view.connectToElement(htmlElement);

Then create an instance of IdCaptureOverlay attached to the view:

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

Turn on the Camera

Finally, turn on the camera to start scanning:

await camera.switchToDesiredState(Scandit.FrameSourceState.On);

And this is it. You can now scan documents.

Capture both the front and the back side of documents

By default, when IdDocumentType.DLVIZ or IdDocumentType.IdCardVIZ are selected, Id Capture scans only the front side of documents. Sometimes however, you may be interested in extracting combined information from both the front and the back side.

Warning

Capturing combined information from both sides of documents is possible only for their parts intended to be read by humans (for example Visual Inspection Zone (VIZ) of a Machine-Readable Travel Document (MRTD)). It is currently not possible to obtain a single result that would additionally contain the information parsed from Machine-Readable Zones (MRZ) or barcodes, such as PDF417.

First, enable scanning of both sides of documents in IdCaptureSettings:

settings.supportedDocuments = [Scandit.IdDocumentType.IdCardVIZ, Scandit.IdDocumentType.DLVIZ];
settings.supportedSides = Scandit.SupportedSides.FrontAndBack;

Start by scanning the front side of a document. After you receive the result in IdCaptureListener, inspect VIZResult.isBackSideCaptureSupported. If scanning of the back side of your document is supported, flip the document and capture the back side as well. The next result that you receive is a combined result that contains the information from both sides. You may verify this by checking VIZResult.capturedSides. After both sides of the document are scanned, you may proceed with another document.

Sometimes, you may not be interested in scanning the back side of a document, after you completed the front scan. For example, your user may decide to cancel the process. Internally, Id Capture maintains the state of the scan, that helps it to provide better combined results. To abandon capturing the back of a document, reset this state by calling:

await idCapture.reset();

Otherwise, Id Capture may assume that the front side of a new document is actually the back side of an old one, and provide you with nonsensical results.

Detect Tampered or Fake Documents

Id Capture helps to detect tampered or fake documents. This feature is currently limited to documents that follow the Driver License/Identification specification by American Association of Motor Vehicle Administrators (AAMVA).

Use AamvaVizBarcodeComparisonVerifier to perform basic, on-device document verification by comparing the human-readable data from the front side with the data encoded in the barcode.

This verifier may permit minor data divergence to compensate, for example, for a single character misread by OCR. While this verifier automatically detects many fraudulent documents, a failed check does not necessarily mean that the document is invalid. It is up to the user to subject such documents to additional scrutiny.

The verification is performed in the front & back scanning mode. Create the verifier and initialize IdCapture with the following settings:

const context = await DataCaptureContext.create();

const verifier = AamvaVizBarcodeComparisonVerifier.create();

const settings = new IdCaptureSettings()
settings.supportedDocuments = [IdDocumentType.DLVIZ]
settings.supportedSides = SupportedSides.FrontAndBack

const idCapture = await IdCapture.forContext(dataCaptureContext, settings)

Then proceed to capture the front side & the back side of a document as usual. After you capture the back side and receive the combined result for both sides, you may run the verifier as follows:

const idCaptureListener = {
    didCaptureId: async (_, session) => {
        const capturedId = session.newlyCapturedId;
        const vizResult = capturedId.vizResult;

        if (vizResult && vizResult.capturedSides === Scandit.SupportedSides.FrontAndBack) {
            const result = await verifier.verify(session.newlyCapturedId);
            if (result.checksPassed) {
                // Nothing suspicious was detected.
            } else {
                // You may inspect the results of individual checks, if you wish:
                if (result.datesOfBirthMatch.checkResult === ComparisonCheckResult.Failed) {
                    // The holder’s date of birth from the front side does not match the one encoded in the barcode.
                }
            }
        }
    }
}

The returned value allows you to query both the overall result of the verification and the results of individual checks. See AamvaVizBarcodeComparisonResult for details.

Supported documents

You can find the list of supported documents here.

What’s next?

To dive further into the Scandit Data Capture SDK we recommend the following articles: