Skip to main content

Barcode Scanner UI | Cordova Barcode Scanner

Barcode and QR Code Scanning UI

Barcode Scanner

ScanbotBarcodeSdk.startBarcodeScanner(BarcodeScannerConfiguration config) Opens a Scanning UI for barcodes and QR codes.

alt

Example:

var options = {
finderLineColor: '#ff0000',
cancelButtonTitle: 'Cancel',
finderTextHint: 'Please align any supported 1D or 2D barcode in the frame above to scan it.',
barcodeFormats: ['ALL_FORMATS'], // or use a filter like so ['DATA_MATRIX', 'QR_CODE', ...]
// see further customization options below ...
};

ScanbotBarcodeSdk.startBarcodeScanner(function(result) {
if (result.status === 'OK') {
showBarcodeResults(result.barcodes);
}
}, sdkErrorCallback, options);

Result:

  • result.status - OK If at least one barcode was detected, CANCELED if the user has canceled the operation (tapped on the "cancel" button).
  • result.barcodes[] - List of recognized barcodes as items. See the barcode item structure below.
  • result.imageFileUri - Optional file URI of the barcode image. See the config parameter barcodeImageGenerationType to enable image snapping.

Barcode item structure:

  • type - Format of detected barcode/QR code (e.g. "CODE_128", "EAN_13", "QR_CODE", etc).
  • text - Raw text value of detected barcode/QR code.
  • textWithExtension - The raw text with extension encoded in the barcode.
  • sourceImageUri - URI of the image, containing the cropped image of the detected barcode. Available only for iOS, and only when the configs.storeImages option is set to true.
  • rawBytes - The array of raw bytes contained in the barcode.

BarcodeScannerConfiguration

Use this configuration class to customize the UI and the behavior of the Barcode Scanner UI. All config properties are optional.

Options:

    /**
* Background color of the detection overlay.
*/
cameraOverlayColor?: string;
/**
* Whether the cancel button is hidden or not.
* iOS only
*/
cancelButtonHidden?: boolean;
/**
* String being displayed on the cancel button.
*/
cancelButtonTitle?: 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 1 - it is a square frame, which is good for QR capturing.
*/
finderAspectRatio?: FinderAspectRatio;
/**
* 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.
*/
topBarButtonsColor?: string;
/**
* An optional list of barcode formats to enable for detection. If the
* list is empty, then all supported formats will be enabled.
*/
barcodeFormats?: BarcodeFormat[];
/**
* An optional array of barcode document formats that act as a detection filter.
* By default all supported document formats will be detected.
*/
acceptedDocumentFormats?: BarcodeDocumentFormat[];
/**
* Optional minimum required text length of the detected barcode.
* The default is 0 (setting is turned off).
* NOTE: This feature works on ITF and MSI Plessey 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 and MSI Plessey 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 and MSI Plessey barcodes only.
*/
minimum1DBarcodesQuietZone?: number
/**
* The engine mode of the barcode recognizer. Defaults to NEXT_GEN.
* To use legacy recognizer, please specify LEGACY
*/
engineMode?: EngineMode;
/**
* 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;
/**
* 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 algorithm 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 barcodes.
* 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 the energy consumption, thereby increasing the scanning speed.
* The default is `false`.
* Android only.
*/
lowPowerMode?: boolean;
/**
* The preferred camera module (options: FRONT or BACK, default: BACK).
*/
cameraModule?: CameraModule;
/*
* The expected density of QR codes. A higher density finds more QR codes in an image but the performance is slightly reduced.
*/
codeDensity?: CodeDensity;
/**
* Orientation lock mode of the UI and the camera preview.
* By default the orientation is not locked.
*/
orientationLockMode?: UIInterfaceOrientationMask;
/**
* Controls whether buttons should use all capitals style, as defined by Android Material Design. Defaults to TRUE.
* Android only.
*/
useButtonsAllCaps?: boolean;
/**
* Use a filter to determine which type of barcode can be detected; see `BarcodeFilter`.
*/
barcodeFilter?: BarcodeFilter;
/**
* Displays contours of the barcode and allows users to select the barcode on an AR-like layer.
*/
selectionOverlayConfiguration?: SelectionOverlayConfiguration;
/**
* Sets the initial scan delay in ms. Default = 0 (disabled).
*/
initialScanDelay?: number;
/**
* Specifies the manner in which barcode images are generated or disables this generation altogether.
* Use if you want to receive a full sized image with barcodes.
* Defaults to NONE.
*/
barcodeImageGenerationType?: BarcodeImageGenerationType;
/**
* String being displayed on the flash button.
* iOS only.
*/
flashButtonTitle?: string;
/**
* Time in seconds until the screen is automatically cancelled. Set to 0 to disable automatic cancellation.
* Defaults to 0 (disabled).
*/
autoCancelTimeout?: number;
/**
* Sets the delay after the scan in ms. Default = 0 (disabled).
*/
delayAfterScan?: number;
/**
* Foreground color of the flash button when flash is off.
*/
topBarButtonsInactiveColor?: string;

Notes

  • acceptedDocumentFormats is an optional array of barcode document formats that act as a detection filter. By default, all supported document formats will be detected.

Batch Barcode Scanner

ScanbotBarcodeSdk.startBatchBarcodeScanner(BatchBarcodeScannerConfiguration config) Opens a Scanning UI to scan multiple barcodes and QR codes.

Callbacks:

successCallback : function(result)
  • result.status - 'OK' if a barcode was detected, 'CANCELED' if the user canceled the operation (tapped on the "cancel" button).
  • result.barcodes[] - 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.
errorCallback : function(error)
  • error.status - 'ERROR' in all error cases.
  • error.message - Contains the error message as a string.

Options:

All settings are optional.

  • barcodeFormats is an optional array of barcode formats that acts as a detection filter. By default all supported formats will be detected.

  • acceptedDocumentFormats is an optional array of barcode document formats that act as a detection filter. By default all supported document formats will be detected.

export interface BatchBarcodeScannerConfiguration
{
/**
* Background color of the detection overlay.
*/
cameraOverlayColor?: string;
/**
* Whether the cancel button is hidden or not.
* iOS only.
*/
cancelButtonHidden?: boolean;
/**
* String being displayed on the cancel button.
*/
cancelButtonTitle?: 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 1 - it is a square frame, which is good for QR capturing.
*/
finderAspectRatio?: FinderAspectRatio;
/**
* Whether flash is toggled on or off.
*/
flashEnabled?: boolean;
/**
* Whether scanner screen should make a sound on successful barcode detection.
*/
successBeepEnabled?: boolean;
/**
* Background color of the top bar.
*/
topBarBackgroundColor?: string;
/**
* Foreground color of the cancel button.
*/
topBarButtonsColor?: string;
/**
* An optional list of barcode formats to enable for detection. If the
* list is empty, then all supported formats will be enabled.
*/
barcodeFormats?: BarcodeFormat[];
/**
* An optional array of barcode document formats that act as a detection filter.
* By default all supported document formats will be detected.
*/
acceptedDocumentFormats?: BarcodeDocumentFormat[];
/**
* Optional minimum required text length of the detected barcode.
* The default is 0 (setting is turned off).
* NOTE: This feature works on ITF and MSI Plessey 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 and MSI Plessey 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 and MSI Plessey barcodes only.
*/
minimum1DBarcodesQuietZone?: number
/**
* The engine mode of the barcode recognizer. Defaults to NEXT_GEN.
* To use the legacy recognizer, please specify LEGACY.
*/
engineMode?: EngineMode;
/**
* 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;
/**
* 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 algorithm 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 barcodes.
* 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;
/**
* The preferred camera module (options: FRONT or BACK, default: BACK).
*/
cameraModule?: CameraModule;
/*
* The expected density of QR codes. A higher density finds more QR codes in an image but the performance is slightly reduced.
*/
codeDensity?: CodeDensity;
/**
* Orientation lock mode of the UI and the camera preview.
* By default the orientation is not locked.
*/
orientationLockMode?: UIInterfaceOrientationMask;
/**
* Controls whether buttons should use all capitals style, as defined by the Android Material Design. Defaults to TRUE.
* Android only.
*/
useButtonsAllCaps?: boolean;
/**
* Use a filter to determine which type of barcode can be detected; see `BarcodeFilter`.
*/
barcodeFilter?: BarcodeFilter;
/**
* Displays contours of the barcode and allows users to select the barcode on an AR-like layer.
*/
selectionOverlayConfiguration?: SelectionOverlayConfiguration;
/**
* Sets the initial scan delay in ms. Default = 0 (disabled).
*/
initialScanDelay?: number;
/**
* String used for displaying the number of scanned barcodes. Use %d for number formatting symbol.
*/
barcodesCountText?: string;
/**
* Text color of the barcodes count label.
*/
barcodesCountTextColor?: 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;
/**
* String to show that no barcodes were scanned yet.
*/
noBarcodesTitle?: string;
/**
* String being displayed on the submit button.
*/
submitButtonTitle?: string;
/**
* Foreground color of the flash button when flash is off.
*/
topBarButtonsInactiveColor?: string;
}

Barcode Format

The following barcode formats are currently supported on Android and iOS.

1D Barcodes

  • BarcodeFormat.CODE_39
  • BarcodeFormat.CODE_93
  • BarcodeFormat.CODE_128
  • BarcodeFormat.CODABAR
  • BarcodeFormat.UPC_A
  • BarcodeFormat.UPC_E
  • BarcodeFormat.EAN_8
  • BarcodeFormat.EAN_13
  • BarcodeFormat.ITF
  • BarcodeFormat.RSS_14
  • BarcodeFormat.RSS_EXPANDED

2D Barcodes

  • BarcodeFormat.QR_CODE
  • BarcodeFormat.AZTEC
  • BarcodeFormat.PDF_417
  • BarcodeFormat.DATA_MATRIX

Data parsers

Barcodes, especially the two-dimensional ones, e.g. data matrices and QR codes, are often used to encode structured data or documents. This structured data can be parsed into document-like data structures that let you access the data fields conveniently, for example Swiss QR-Codes, SEPA forms, medical plans, boarding passes, medical certificates and vCard addresses.

The following data parsers are currently supported:

  • AAMVA: Parse the AAMVA data format from PDF-417 barcodes on US driver’s licenses.
  • Boarding pass data from PDF-417 barcodes.
  • Parser for German Medical Certificates (aka. Disability Certificate or AU-Bescheinigung) coded in a PDF-417 barcode.
  • GS1 encoded data from barcodes.
  • Data from PDF-417 barcodes on ID Cards.
  • Parse and extract data from XML of Data Matrix barcodes on Medical Plans (German Medikationsplan).
  • Data parser of QR-Code values printed on SEPA pay forms.
  • vCard data from a QR-Code (e.g. on business cards).
  • Swiss QR data from a QR-Code for easy, automatic and efficient payments.

Storage

By default, the native Scanbot Barcode Scanner SDKs as well as the Plugin itself use the internal and secure storage locations for all snapped barcode image files.

  • On Android all files will be stored in the internal files directory of your application. No permissions are required for your app to read or write files in this directory.

  • On iOS all files will be stored in the Application Support folder of your application.

Customize Storage Location

It is strongly recommended to use the default storage location. However, you can override the storage directory on initialization of the Plugin. The initializeSdk method can take an optional parameter storageBaseDirectory to set a custom storage location.

The value of the storageBaseDirectory must be a file URL ('file:///...) pointing to a valid platform-specific file system path. If this directory does not exist yet, the Plugin will try to create it. To work with the file system we recommend the Cordova Plugin cordova-plugin-file

For the full demo code please check out our example app on GitHub.

⚠️ Note: When overriding the default storage location, make sure

  • you have implemented a suitable storage permissions request handling on Android
  • you fully understand the consequences regarding the accessibility (security) of the produced document files.

👉 For more details about the storage locations on Android and iOS please also see:

Storage Cleanup

There is no automatic file-cleaning mechanism in this Plugin because only your app can decide when the perfect time is to remove the optional barcode image files snapped by this Plugin.

This Plugin provides the method cleanup() to delete all optional barcode images:

Example:

ScanbotBarcodeSdk.cleanup(function(result) {
// cleanup do
}, sdkErrorCallback);

Building Production Apps

iOS

Under the hood, Scanbot Cordova Barcode Scanner SDK uses Scanbot iOS Barcode Scanner SDK as an embedded framework or XCFramework, containing all iOS 64-bit simulator and device architectures, and crash symbols. It can be used with Objective-C as well as with Swift.

note

Xcode 11 or later must be used.

Android

The Scanbot Android SDK uses native libraries under the hood and supports following ABIs: armeabi-v7a, arm64-v8a, x86 and x86_64.

By default the native libraries of all these architectures will be included in the app package (APK), which will result in a big APK file. Please consider removing support for x86 and x86_64 architectures. In most cases, both "x86" architectures can be removed for the release (production) build, since they are only used on emulators and on some rare devices with the Intel Atom architecture.

To exclude certain ABIs from the APK, use the abiFilters property in the Android Gradle settings of your project. To apply any custom Gradle settings on a Cordova-generated Android project, create the additional custom .gradle file with the name

platforms/android/app/build-extras.gradle

and define your custom Gradle settings in it. In this case we define abiFilters to exclude x86 and x86_64 architectures:

ext.postBuildExtras = {
android.defaultConfig.ndk.abiFilters = ["armeabi-v7a", "arm64-v8a"]
}
info

However, if you need to support all architectures and optimize the APK size, we highly recommend checking out the Android App Bundle approach. It allows you to create and distribute dedicated and smaller APKs via the PlayStore (basically it is similar to the iOS App Store approach).

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?