@scandit/web-id-bolt

Scandit ID Bolt

ID Bolt is a pre-built ID scanning workflow that seamlessly integrates into any website allowing users to scan their identity documentation in just one second.. ID Bolt works on-device, via desktop and mobile in a unified solution, ensuring no identity information is collected by third-party servers and reduces latency for quick scanning performance.

Learn more about ID Bolt at https://www.scandit.com/products/id-bolt/.

Get started

Add the ID Bolt client as a dependency:

npm i @scandit/web-id-bolt

Copy the following snippet to get started.

Your application defines when the ID Bolt pop-up is opened. In this snippet, we open it after a click on a button present in the page:

import {
	Passport,
	IdCard,
	DriverLicense,
	DocumentSelection,
	IdBoltSession,
	Region,
	ReturnDataMode,
	Validators,
} from "./web-id-bolt/dist";

const ID_BOLT_URL = "https://app.id-scanning.com";

const LICENSE_KEY = "-- YOUR LICENSE KEY HERE --";

async function startIdBolt() {
	// define which documents are allowed to be scanned. More complex rules can be added.
	const documentSelection = DocumentSelection.create({
		accepted: [new Passport(Region.Any), new IdCard(Region.Any), new DriverLicense(Region.Any)],
	});
	// initialization of the ID Bolt session
	const idBoltSession = IdBoltSession.create(ID_BOLT_URL, {
		licenseKey: LICENSE_KEY,
		documentSelection,
		// define what data you expect in the onCompletion listener (set below)
		returnDataMode: ReturnDataMode.Full,
		// add validation rules on the scanned document
		validation: [Validators.notExpired()],
		locale: "en",
		onCompletion: (result) => {
			// the ID has been captured and validation was successful. In this example the result
			// will contain the document data because `returnDataMode` was set to ReturnDataMode.Full.
			alert(`Thank you ${result.capturedId?.fullName ?? ""}`);
		},
		onCancellation: (reason) => {
			// the ID Bolt pop-up has been terminated without a succesful scan
		},
	});
	// open the pop-up
	await idBoltSession.start();
}

// open ID Bolt when some button is clicked
const someButton = document.getElementById("someButton");
someButton.addEventListener("click", startIdBolt);

For completeness this is the HTML you will need for the example:

<button id="someButton">Start ID Bolt</button>

If you have Content-Security-Policy headers (CSP) which prevent loading iframes on your page, you need to adapt the value like so:

frame-src 'self' https://app.id-scanning.com https://id-service.scandit.com

API

IdBoltSession

The main class of ID Bolt. It represents a session in which the end-user is guided through a workflow to scan their ID. The IdBoltSession.onCompletion() callback is called when the user has scanned their ID, the ID has been accepted and the ID Bolt pop-up is closed. Similarly, IdBoltSession.onCancellation() is called when the user closes the ID Bolt pop-up without finishing the full process successfully.

Using validators, ID Bolt can verify the expiration date or other features of the ID. Optionally, this can be done without sharing any personally identifiable information (PII) with your website.

Methods

static create(serviceUrl: string, options: IdBoltCreateSessionOptions): IdBoltSession

Primary way to create an ID Bolt session.

• serviceUrl: string: the URL that ID Bolt loads when started. Provided in your account on the Scandit dashboard. Note: app.id-scanning.com is an alias that points to Scandit’s servers. In a production environment it can be changed to your own domain name pointing to Scandit’s servers. This will require you to configure a CNAME record in the DNS settings of your domain.
• options: IdBoltCreateSessionOptions: an object specifying the session options:
  • licenseKey: string: your license key, provided in you account on the Scandit dashboard.
  • documentSelection: DocumentSelection: an object specifying the acceptable documents. See DocumentSelection further below.
  • returnDataMode: ReturnDataMode: defines the extent of the data returned by the onCompletion() callback. Use ReturnDataMode.FullWithImages to get all extracted data and images, or ReturnDataMode.Full to get all extracted data without images.
  • validation?: Validators[]: an optional array of validators. See Validators further below. Default: []
  • locale?: string: the language in which the text is displayed. Currently only english ("en") is supported. Default: "en".
  • onCompletion: (result: CompletionResult) => void: A callback that is called when the user has successfully scanned their ID. Depending on the ReturnDataMode value you passed in IdBoltSession, result.capturedId will contain the document data or null.
  • onCancellation?: () => void: A callback that is called when the user has closed the ID Bolt pop-up without having finished the scanning workflow.

Once created, a session object does nothing until you execute start() on it:

const idBoltSession = IdBoltSession.create(ID_BOLT_URL, {
	licenseKey: LICENSE_KEY,
	documentSelection,
	returnDataMode: ReturnDataMode.FullWithImages,
	validation: [Validators.notExpired()],
	onCompletion: (result) => alert(`Thanks ${result.capturedId?.fullName}`),
});
await idBoltSession.start();

async IdBoltSession.start(): Promise<string>

Open the ID Bolt pop-up to start the scanning workflow. This method returns a session ID identifying the session.

DocumentSelection

A class to define which types of documents the ID Bolt will accept. The list of documents is provided as couples of Region and DocumentType, for example passports from the USA.

Not accepted documents may still get recognized by the scanner. In this case the user will be notified to use one of the accepted document types.

Methods

static DocumentSelection.create(selection: Selection): DocumentSelection

Primary way to create a DocumentSelection instance with all the accepted and rejected documents.

Only Selection.accepted is mandatory.

Example:

const documentSelection = DocumentSelection.create({
	accepted: [new Passport(Region.FRA)],
	rejected: [new DriversLivense(Region.CHE)],
});

If you have very specific rules, you can use the Selection.customCallback option in which you can decide if the scanned document should be accepted or not:

const documentSelection = DocumentSelection.create({
	accepted: [new Passport(Region.USA)],
	customCallback: (capturedId: CapturedId, preCheckResults: PreCheckResults) => {
		if (capturedId.documentNumber === "123") {
			return {
				valid: false,
				// this message will be displayed to the user
				message: `Documents starting with "123" are not accepted.`,
			};
		}
		// when not returning anything, the default behavior will take place
	},
});

Document Types

Each type of document is represented as its own class.

Passport

Represents passports of a specific region

Example:

new Passport(Region.USA);

IdCard

Represents id cards of a specific region

Example:

new IdCard(Region.USA);

DriversLicense

Represents drivers licenses of a specific region

Example:

new DriversLicense(Region.USA);

Validators

Validators allow to run checks on the scanned ID. Validators are only run on accepted documents.

Validators.notExpired()

Checks that the document has not expired.

Note that this test will not pass if the expiration date could not be determined from the extracted data.

Validators.notExpiredIn(duration: Duration)

Checks that the document has still not expired after the duration passed in argument.

Duration is an object with following properties:

• days?: number
• months?: number

One of Duration.days and Duration.months has to be provided.

In the following example, the ID must not expire in the next 12 months:

const idBoltSession = IdBoltSession.create(ID_BOLT_URL, {
	licenseKey: LICENSE_KEY,
	documentSelection: ...,
	returnDataMode: ReturnDataMode.FullWithImages,
	validation: [Validators.notExpiredIn({months: 12})],
});

Note that this test will not pass if the expiration date could not be determined from the extracted data.

Validators.US.isRealID()

Checks that the scanned driver license is compliant with the rules of Real ID defined by the American Association of Motor Vehicle Administrators (AAMVA).

Note that this test will not pass if the scanned document is not an AAMVA document.

interface CapturedId

The interface defining the object you receive in CompletionResult.capturedId.

CapturedId:

• firstName: string | null
• lastName: string | null
• fullName: string
• sex: string | null
• nationality: string | null
• address: string | null
• issuingCountry: string | null: The ISO (Alpha-3 code) abbreviation of the issuing country of the document.
• documentNumber: string | null
• documentAdditionalNumber: string | null
• dateOfBirth: DateResult | null
• age: number | null
• dateOfExpiry: DateResult | null
• isExpired: boolean | null
• dateOfIssue: DateResult | null
• documentType: DocumentType | null
• capturedResultTypes: string[]
• images: [Object] | null: object containing base64 encoded jpg images:
  • cropped: string[]: contains cropped images of the ID, in the order they were captured, only available when the visual inspection zone is scanned
  • fullFrame: string[]: contains full frame images in the order they were captured.

interface DateResult

An object representing a date.

DateResult:

• day: number
• month: number
• year: number

interface PreCheckResults

An object containing the current acceptance status for the scanned document according to the configured rules in IdBoltSession.documentSelection.

PreCheckResults:

• isAccepted: boolean: the scanned document is acceptable
• isRejected: boolean: the scanned document is excluded
• valid: boolean: final outcome, the document is considered acceptable if it is not rejected and accepted.

const Region

An enumeration of regions (mostly countries).

Example:

// France
Region.France;

// Any (world wide)
Region.Any;

enum DocumentType

An enumeration of the available main document types.

DocumentType:

• Passport
• IdCard
• DriverLicense

enum ReturnDataMode

Values used by IdBoltCreateSessionOptions to define what data is returned by IdBoltCreateSessionOptions.onCompletion().

ReturnDataMode:

• Full: all extracted data is returned, but images are excluded.
• FullWithImages: all extracted data is returned, including images of the scanned ID.