Barcode Scanner UI | Cordova Document Scanner
The Scanbot SDK provides a Ready-To-Use UI screen component for Barcode and QR-Code scanning.
Integrating the Barcode Scanner UI
Use the plugin API method ScanbotSdk.UI.startBarcodeScanner() to start the Barcode Scanner UI.
import ScanbotSdk, { BarcodeScannerConfiguration } from 'cordova-plugin-scanbot-sdk';
private SDK = ScanbotSdk.promisify();
// Always make sure you have a valid license on runtime via SDK.getLicenseInfo()
if (!licenseCheckMethod()) { return; }
const configs: BarcodeScannerConfiguration = {
// Customize colors, text resources, behavior, etc..
finderTextHint: 'Please align the barcode or QR code in the frame above to scan it.',
interfaceOrientation: 'PORTRAIT',
finderLineColor: '#0000ff',
//barcodeFormats: ['QR_CODE', 'EAN_13', ...], // optional filter for specific barcode types
// see further configs ...
};
const result = await this.SDK.UI.startBarcodeScanner({uiConfigs: configs});
if (result.status === 'CANCELED') {
// user has canceled the scanning operation
return;
}
// handle the scanned barcode(s) from result
// result.barcodes[n]...
Handling the Result
The result object contains the following fields:
result.status: Result status,'OK'if at least one barcode was scanned,'CANCELED'if the user canceled the operation.result.barcodes[]: An array of detected barcodes. If no barcodes were detected, the array will be empty or null.result.barcodes[n].type: Format of detected barcode/QR code (e.g.CODE_128,EAN_13,QR_CODE, etc).result.barcodes[n].text: Text value of detected and decoded barcode/QR code.result.imageFileUri: Optional file URI of the captured camera image.result.canceledDueToTimeout: Optional boolean field. Available only in case ofstatus="CANCELED":trueIf the config valueautoCancelTimeoutwas specified, AND the UI was auto-canceled due to timeout.falseIf the user closed the UI via the "cancel" button.
Customization
The UI and the behavior of the Barcode Scanner can be customized by passing the configs value via BarcodeScannerConfiguration.
All configuration options are optional.
export interface BarcodeScannerConfiguration
{
/**
* An optional array of barcode document formats that act as a detection filter.
* By default all supported document formats will be detected.
*/
acceptedDocumentFormats?: BarcodeDocumentFormat[];
/**
* Orientation lock mode of the UI and the camera preview.
* By default the orientation is not locked.
*/
interfaceOrientation?: UIInterfaceOrientationMask;
/**
* Background color of the detection overlay.
*/
cameraOverlayColor?: string;
/**
* Whether the cancel button is hidden or not.
*/
cancelButtonHidden?: boolean;
/**
* String being displayed on the cancel button.
*/
cancelButtonTitle?: string;
/**
* Aspect ratio of finder frame (width \ height), which is used to build actual finder frame.
* Default is 1 - it is a square frame, which is good for QR capturing.
*/
finderAspectRatio?: FinderAspectRatio;
/**
* 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;
/**
* Foreground color of the flash button when flash is off.
*/
flashButtonInactiveColor?: string;
/**
* String being displayed on the flash button.
*/
flashButtonTitle?: string;
/**
* Whether flash is toggled on or off.
*/
flashEnabled?: boolean;
/**
* Whether scanner screen should make a sound on successful barcode or MRZ detection.
*/
successBeepEnabled?: boolean;
/**
* Background color of the top bar.
*/
topBarBackgroundColor?: string;
/**
* Foreground color of the cancel button and when flash button is on.
*/
topBarButtonsColor?: string;
/**
* Accepted barcode formats
*/
barcodeFormats?: BarcodeFormat[];
/**
* Specifies the way of barcode images generation or disables this generation at all.
* Use, if you want to receive a full sized image with barcodes. Defaults to NONE.
*/
barcodeImageGenerationType?: BarcodeImageGenerationType;
/**
* Controls whether buttons should use all capitals style, as defined by the Android Material Design. Defaults to TRUE.
* Android only.
*/
useButtonsAllCaps?: boolean;
/**
* Time in seconds until the screen is automatically cancelled. Set to 0 to disable automatic cancellation.
* Defaults to 0 (disabled).
*/
autoCancelTimeout?: number;
/**
* Optional minimum required text length of the detected barcode.
* The default is 0 (setting is turned off).
* NOTE: This feature works on ITF barcodes only.
*/
minimumTextLength?: number,
/**
* Optional maximum required text length of the detected barcode.
* The default is 0 (setting is turned off).
* NOTE: This feature works on ITF barcodes only.
*/
maximumTextLength?: number,
/**
* Optional minimum required quiet zone on the barcode.
* Measured in modules (the size of minimal bar on the barcode).
* The default is 10.
* NOTE: This feature works on ITF barcodes only.
*/
minimum1DBarcodesQuietZone?: number
/**
* The relative initial zoom level of the camera in the range [0,1], where 0 is zoomed out and 1 is zoomed in.
* The default value is 0.
*/
cameraZoomFactor?: number;
/**
* The engine mode of the barcode recognizer. Defaults to NEXT_GEN.
* To use legacy recognizer, please specify LEGACY
*/
engineMode?: EngineMode;
/**
* When set to `true`, the scanner assumes that the barcode can be a GS1 barcode.
* Turn it off, if you don't want to see decoded FNC1 characters ("]C1" and ASCII char 29).
* The default value is `true`.
* NOTE: Currently works for CODE128 barcodes only!
*/
gs1DecodingEnabled?: boolean;
/**
* The checksum algorithms for MSI Plessey barcodes.
* The default value is [MSIPlesseyChecksumAlgorithm.Mod10].
*/
msiPlesseyChecksumAlgorithm?: MSIPlesseyChecksumAlgorithm;
/**
* With this option enabled, the scanner removes check digits for UPC, EAN and MSI Plessey codes.
* Has no effect if both single and double digit MSI Plessey checksums are enabled.
* The default is `false`.
*/
stripCheckDigits?: boolean;
/**
* If `true`, enables the mode which slightly decreases the scanning quality and energy consumption, thereby increasing the scanning speed.
* The default is `false`.
* Android only.
*/
lowPowerMode?: boolean;
}
Integrating the Batch Barcode Scanner UI
The Batch Barcode Scanner supports scanning and collecting multiple barcodes and QR-codes in a row.
Use the plugin API method ScanbotSdk.UI.startBatchBarcodeScanner() to start the Batch Barcode Scanner UI.
import ScanbotSdk, { BatchBarcodeScannerConfiguration } from 'cordova-plugin-scanbot-sdk';
private SDK = ScanbotSdk.promisify();
// Always make sure you have a valid license on runtime via SDK.getLicenseInfo()
if (!licenseCheckMethod()) { return; }
const configs: BatchBarcodeScannerConfiguration = {
// Customize colors, text resources, behavior, etc..
finderTextHint: 'Please align the barcode or QR code in the frame above to scan it.',
interfaceOrientation: 'PORTRAIT',
finderLineColor: '#0000ff',
//barcodeFormats: ['QR_CODE', 'EAN_13', ...], // optional filter for specific barcode types
// see further configs ...
};
const result = await this.SDK.UI.startBatchBarcodeScanner({uiConfigs: configs});
if (result.status === 'CANCELED') {
// user has canceled the scanning operation
return;
}
// handle the scanned barcode(s) from result
// result.barcodes[n]...
Handling the Result
The result object contains the following fields:
result.status: Result status,'OK'if at least one barcode was scanned,'CANCELED'if the user canceled the operation.result.barcodes[]: An array of detected barcodes. If no barcodes were detected, the array will be empty or null.result.barcodes[n].type: Format of detected barcode/QR code (e.g.CODE_128,EAN_13,QR_CODE, etc).result.barcodes[n].text: Text value of detected and decoded barcode/QR code.result.canceledDueToTimeout: Optional boolean field. Available only in case ofstatus="CANCELED":trueIf the config valueautoCancelTimeoutwas specified, AND the UI was auto-canceled due to timeout.falseIf the user closed the UI via the "cancel" button.
Customization
The UI and the behavior of the Batch Barcode Scanner can be customized by passing the configs value via BatchBarcodeScannerConfiguration.
All configuration options are optional.
export interface BatchBarcodeScannerConfiguration
{
/**
* An optional array of barcode document formats that act as a detection filter.
* By default all supported document formats will be detected.
*/
acceptedDocumentFormats?: BarcodeDocumentFormat[];
/**
* Orientation lock mode of the UI and the camera preview.
* By default the orientation is not locked.
*/
interfaceOrientation?: UIInterfaceOrientationMask;
/**
* String used for displaying amount of scanned barcodes. Use %d for number formatting symbol.
*/
barcodesCountText?: string;
/**
* Text color of the barcodes count label.
*/
barcodesCountTextColor?: string;
/**
* Background color of the detection overlay.
*/
cameraOverlayColor?: string;
/**
* Whether the cancel button is hidden or not.
*/
cancelButtonHidden?: boolean;
/**
* String being displayed on the cancel button.
*/
cancelButtonTitle?: string;
/**
* String being displayed on the clear button.
*/
clearButtonTitle?: string;
/**
* String being displayed on the delete button.
*/
deleteButtonTitle?: string;
/**
* Foreground color of the top bar buttons on the details screen.
*/
detailsActionColor?: string;
/**
* Background color of the details screen.
*/
detailsBackgroundColor?: string;
/**
* Text color in the details barcodes list. Also affects image background, separator and progress spinner.
*/
detailsPrimaryColor?: string;
/**
* String used to show process of fetching mapped data for barcodes.
*/
fetchingStateText?: string;
/**
* Aspect ratio of finder frame (width \ height), which is used to build actual finder frame.
* Default is 1 - it is a square frame, which is good for QR capturing.
*/
finderAspectRatio?: FinderAspectRatio;
/**
* 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;
/**
* Whether flash is toggled on or off.
*/
flashEnabled?: boolean;
/**
* String to show that no barcodes were scanned yet.
*/
noBarcodesTitle?: string;
/**
* Enables or disables the barcode detection.
*/
recognitionEnabled?: boolean;
/**
* String being displayed on the submit button.
*/
submitButtonTitle?: string;
/**
* Whether scanner screen should make a sound on successful barcode or MRZ detection.
*/
successBeepEnabled?: boolean;
/**
* Background color of the top bar.
*/
topBarBackgroundColor?: string;
/**
* Foreground color of the top bar buttons on the scanning screen.
*/
topBarButtonsColor?: string;
/**
* Foreground color of the flash button when flash is off.
*/
topBarButtonsInactiveColor?: string;
/**
* Accepted barcode formats
*/
barcodeFormats?: BarcodeFormat[];
/**
* Controls whether buttons should use all capitals style, as defined by the Android Material Design. Defaults to TRUE.
* Android only.
*/
useButtonsAllCaps?: boolean;
/**
* Optional minimum required text length of the detected barcode.
* The default is 0 (setting is turned off).
* NOTE: This feature works on ITF barcodes only.
*/
minimumTextLength?: number,
/**
* Optional maximum required text length of the detected barcode.
* The default is 0 (setting is turned off).
* NOTE: This feature works on ITF barcodes only.
*/
maximumTextLength?: number,
/**
* Optional minimum required quiet zone on the barcode.
* Measured in modules (the size of minimal bar on the barcode).
* The default is 10.
* NOTE: This feature works on ITF barcodes only.
*/
minimum1DBarcodesQuietZone?: number
/**
* The engine mode of the barcode recognizer. Defaults to NEXT_GEN.
* To use legacy recognizer, please specify LEGACY
*/
engineMode?: EngineMode;
/**
* When set to `true`, the scanner assumes that the barcode can be a GS1 barcode.
* Turn it off, if you don't want to see decoded FNC1 characters ("]C1" and ASCII char 29).
* The default value is `true`.
* NOTE: Currently works for CODE128 barcodes only!
*/
gs1DecodingEnabled?: boolean;
/**
* The checksum algorithms for MSI Plessey barcodes.
* The default value is [MSIPlesseyChecksumAlgorithm.Mod10].
*/
msiPlesseyChecksumAlgorithm?: MSIPlesseyChecksumAlgorithm;
/**
* With this option enabled, the scanner removes check digits for UPC, EAN and MSI Plessey codes.
* Has no effect if both single and double digit MSI Plessey checksums are enabled.
* The default is `false`.
*/
stripCheckDigits?: boolean;
/**
* If `true`, enables the mode which slightly decreases the scanning quality and energy consumption, thereby increasing the scanning speed.
* The default is `false`.
* Android only.
*/
lowPowerMode?: 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 LicenseWhat do you think of this documentation?
What can we do to improve it? Please be as detailed as you like.