Skip to main content

Capacitor MRZ Scanner UI Components - SDK Features

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

  startMrzScanner(
configuration: MrzScannerConfiguration,
): Promise<ResultWrapper<MrzScannerResult>>

alt text

Integrating the MRZ Scanner UI

Use the plugin API method ScanbotSDK.startMrzScanner() to start the MRZ Scanner UI.

import { ScanbotSDK, MrzScannerConfiguration } from 'capacitor-plugin-scanbot-sdk';
// Always make sure you have a valid license on runtime via ScanbotSDK.getLicenseInfo()
if (!licenseCheckMethod()) { return; }

const configuration: MrzScannerConfiguration = {
// Customize colors, text resources, behavior, etc..
finderTextHint: 'Please hold your phone over the 2- or 3-line MRZ code at the front of your passport.',
orientationLockMode: 'PORTRAIT',
// see further configs ...
};

const result = await ScanbotSDK.startMrzScanner(configuration);

if (result.status === 'CANCELED') {
// User has canceled the scanning operation
return;
}

Handling the Result

The promise resolves to an object in the following format:

export interface RecognizeMRZResult {
/** True if the recognition was successful, false otherwise */
recognitionSuccessful: boolean;
/** The recognized document type */
documentType: MRZDocumentType;
/** Total number of check digits as required by the travel document type */
checkDigitsCount: number;
/** Number of successfully validated check digits. */
validCheckDigitsCount: number;
/** The raw string of the recognized machine readable zone. */
rawString: string;
/** MRZ Document */
mrz: MRZDocument;
}

Customization

The UI and the behavior of the MRZ Scanner can be customized by passing the configs value via MrzScannerConfiguration. All configuration options are optional.

export interface MrzScannerConfiguration {
/** The preferred camera module (default - BACK) */
cameraModule?: CameraModule;

/** Background color outside of the finder window. */
cameraOverlayColor?: string;

/** Title of the cancel button. */
cancelButtonTitle?: string;

/** Whether the cancel button is hidden or not. iOS only. */
cancelButtonHidden?: boolean;

/** Title of the button that opens the screen where the user can allow the usage of the camera by the app. */
enableCameraButtonTitle?: string;

/** Text that will be displayed when the app is not allowed to use the camera, prompting the user to enable the usage of the camera. */
enableCameraExplanationText?: string;

/** Foreground color of the detection overlay. */
finderLineColor?: string;

/** Width of finder frame border. Default is 2. */
finderLineWidth?: number;

/** String being displayed as description. */
finderTextHint?: string;

/** Foreground color of the description label. */
finderTextHintColor?: string;

/** Aspect ratio of finder frame (width \ height), which is used to build actual finder frame. Default is 7 - which is good for standard machine readable zones. */
finderAspectRatio?: AspectRatio;

/** Controls whether the flash toggle button is hidden or not. iOS only. */
flashButtonHidden?: boolean;

/** Title of the flash toggle button. iOS only. */
flashButtonTitle?: string;

/** Controls whether the flash should be initially enabled. The default value is FALSE. */
flashEnabled?: boolean;

/** UI Interface orientation lock mode */
orientationLockMode?: OrientationLockMode;

/** Controls whether to play a beep sound after a successful detection. Default value is TRUE. */
successBeepEnabled?: boolean;

/** The background color of the top toolbar. */
topBarBackgroundColor?: string;

/** The color of all active toggle buttons in the toolbar. */
topBarButtonsActiveColor?: string;

/** The color of all inactive toggle buttons in the toolbar. */
topBarButtonsInactiveColor?: string;

/** Controls whether buttons should use all capitals style, as defined by the Android Material Design. Defaults to TRUE. Android only. */
useButtonsAllCaps?: boolean;

/** If `true`, replaces the cancel button in the top bar with a back arrow icon. The default value is FALSE. Android only. */
replaceCancelButtonWithIcon?: boolean;

/** Preview mode of the camera. FILL_IN or FIT_IN. Default is FILL_IN. Android only */
cameraPreviewMode?: CameraPreviewMode;

/** Whether touch-to-focus is enabled on camera preview. Enabled by default. Android only. */
touchToFocusEnabled?: boolean;
}

Want to scan longer than one minute?

Generate your free "no-strings-attached" Trial License and properly test the Scanbot SDK.

Get your free Trial License

What do you think of this documentation?