Skip to main content

MRZ Scanner | Web Document and Barcode Scanner

The MRZ (Machine Readable Zone) Scanner is able to scan and decode the MRZ data on an ID card or passport.

alt text

Integrating the MRZ Scanner UI#

Configuration#

ScanbotSDK MRZ Scanner takes an instance of MrzScannerConfiguration as its argument. This is your main object for configuration options, styling and receiving the results.

MrzScannerConfiguration inherits the base properties:

  • containerId โ€“ The id of the containing HTML element where the MRZ Scanner will be initialized. Required
  • videoConstraints โ€“ The desired video resolution. Optional, defaults to 3840x2160
  • mirrored - Whether the screen should be mirrored. Useful when using a user-facing camera. false by default
  • onError โ€“ Callback when something went wrong. Optional

Additionally, ScanbotSDK MRZ Scanner has the following configurable options:

  • onMrzDetected โ€“ Your callback for receiving detection results. Required

The result of onMrzDetected is a MrzResult object that contains the following properties:

documentNumber?: MrzField;issuingAuthority?: MrzField;departmentOfIssuance?: MrzField;givenNames?: MrzField;surname?: MrzField;nationality?: MrzField;birthDate?: MrzField;gender?: MrzField;expiryDate?: MrzField;personalNumber?: MrzField;travelDocType?: MrzField;travelDocTypeVariant?: MrzField;optional1?: MrzField;optional2?: MrzField;discreetIssuingStateOrOrganization?: MrzField;kindOfDocumentField?: MrzField;documentType?: MrzField;format?: MrzField;pinCode?: MrzField;languageCode?: MrzField;versionNumber?: MrzField;checkDigits?: MrzCheckDigits;

MrzCheckDigits contains values of various check digit types as follows:

general?: MrzField;documentNumber?: MrzField;birthDate?: MrzField;expiryDate?: MrzField;personalNumber?: MrzField;

MrzField contains the following fields:

name?: string;value?: string;confidence?: number;validated?: MRZFieldValidationStatus;

MRZFieldValidationStatus is a custom type:

type MRZFieldValidationStatus ='Success'| 'Failure'| 'NotValidated';

Styling#

ScanbotSDK MRZ Scanner has the following style options and their default values:

style?: {    window: {        aspectRatio: 4,        paddingPropLeft: 0.2,        borderColor: "white",        left: "50%",        top: "50%",        transform: "translate(-50%, -50%)"    },    text: {        color: string = "white";        size: string = "0.9em";        weight: number = 300;    },    hint: "Please align the code in the frame above to scan it"    backgroundColor: string = "rgba(0, 0, 0, 0.7)";}

window element is used to configure the view-finder. It uses the WindowStyleConfiguration interface that has the following attributes:

width?: string;height?: string;aspectRatio?: number;paddingPropLeft?: number;borderColor?: string;left?: string;top?: string;transform?: string;

width and height elements can be used for configuring the size of the view-finder in pixels. However, aspectRatio and paddingPropLeft elements can be used for configuring the size of the view-finder in a more responsive way. aspectRatio specifies the aspect ratio as width/height paddingPropLeft specifies the proportional distance of the view-finder from the left side of the window

To change a specific style, simply assign it another value, e.g:

configuration.style.window.borderColor: "pink"

Default style configuration:

const WindowStyle: WindowStyleConfiguration = {    aspectRatio: 4,    paddingPropLeft: 0.2,    borderColor: "white",    left: "50%",    top: "50%",    transform: "translate(-50%, -50%)"}const TextStyle: TextStyleConfiguration = {    color: "white",    size: "0.9em",    weight: 300,}
const MrzScannerStyle: ViewFinderConfiguration = {    window: WindowStyle,    text: TextStyle,    backgroundColor: "rgba(0, 0, 0, 0.7)",    hint: "Please hold the device over the MRZ code to start scanning"}

Opening the Scanner#

To open the MRZ Scanner, simply call the relevant SDK function with the configuration object:

const config = {    containerId: MRZ_SCANNER_CONTAINER,    onMrzDetected: onMrzDetected,    onError: onError};
const scanner = await scanbotSDK.createMrzScanner(configuration);

You should store the MRZ Scanner object in a globally accessible location, as additional MRZ Scanner actions are functions of that object.

API#

To handle MRZ results (avoid duplicate scans etc), ScanbotSDK offers the following convenient methods to pause and resume detection while you are processing the data on your side:

resumeDetection(): void;
pauseDetection(): void;
isDetectionPaused(): boolean;

As with the Document Scanner, the MRZ Scanner should also be properly disposed of when you have detected and processed the relevant MRZ: