Skip to main content

Barcode Scanner | Cordova Barcode Scanner

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 clean 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);

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.
BarcodeScannerConfiguration#

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

Options:

    /**    * Allowed orientations for automatic interface rotations. *    */    allowedInterfaceOrientations?: UIOrientationMode;    /**    * Specifies the barcode images generation type or disables this generation altogether.    * Use if you want to receive a full sized image with barcodes.    * Defaults to SBSDKBarcodeImageGenerationTypeNone.    */    barcodeImageGenerationType?: BarcodeImageGenerationType;    /**    * Foreground color of the flash button when flash is on.    */    bottomButtonsActiveColor?: string;    /**    * Foreground color of the flash button when flash is off.    */    bottomButtonsInactiveColor?: 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;    /**    * 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;    /**    * 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.    */    topBarButtonsColor?: string;    /**     * An optional list of barcode formats to enable for detection. If the     * list contains "ALL_FORMATS", then all supported formats will be     * enabled.     */    barcodeFormats?: [BarcodeFormat | "ALL_FORMATS"];    /**     * An optional list of barcode formats to enable for detection. If the     * list contains "ALL_FORMATS", then all supported formats will be     * enabled.     */    barcodeFormats?: [BarcodeFormat | "ALL_FORMATS"];    /**     * 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 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       /**     * With this option, the scanner assumes that the barcode can be a GS1 barcode, and modify the behavior as needed.     * You can set it to 'false', if you don't want to see decoded FNC1 characters ("]C1" and ASCII char 29).     * The default is 'true'.     * NOTE: Currently works for CODE128 barcodes only!     */    enableGS1Decoding?: boolean    /**     * 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;

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{    /**     * 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.     */    orientationLockMode?: CameraOrientationMode;    /**     * 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     /**     * With this option, the scanner assumes that the barcode can be a GS1 barcode, and modify the behavior as needed.     * You can set it to 'false', if you don't want to see decoded FNC1 characters ("]C1" and ASCII char 29).     * The default is 'true'.     * NOTE: Currently works for CODE128 barcodes only!     */     enableGS1Decoding?: boolean}

Barcode Detection from Still Images#

ScanbotBarcodeSdk.detectBarcodesOnImage(successCallback, errorCallback, options) This method provides the functionality of detecting barcodes from a still image, e.g. a JPG image from Photo Library or other source. The image must be passed as a file URI.

Options:

  • imageFileUri - A valid file URI of the image (e.g. file:///some/path/image-with-barcodes.jpg). Supported image formats are JPG and PNG. Please make sure your app has the read permission to access this file.

Result:

  • result.barcodes[] - List of recognized barcodes as items. Same structure as in the startBarcodeScanner result.

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

Barcode Document Format Values#

  • AAMVA - Identifies an AAMVA Driver License
  • BOARDING_PASS - Identifies a Boarding Pass
  • DE_MEDICAL_PLAN - Identifies a German Medical Plan Code
  • DISABILITY_CERTIFICATE - Identifies a Disability Certificate Code
  • ID_CARD_PDF_417 - Identifies a PDF417 code (eg. ID card, passport, driver license)
  • SEPA - Identifies a SEPA QR Code
  • SWISS_QR - Identifies a Swiss QR Code
  • VCARD - Identifier a VCARD QR Code

Building Production Apps#

iOS#

The native Scanbot Barcode SDK iOS Framework (ScanbotBarcodeScannerSDK.framework) is bundled in this Cordova Plugin and contains the architectures arm64 and x86_64. You can thus run it on most iOS devices as well as on simulators during the development phase. To be able to submit a production build to App Store Connect (App Store / TestFlight) the architecture x86_64 must be removed (striped out) from the Scanbot Barcode SDK Framework. This architecture is only for simulators and is not allowed to be submitted to App Store Connect.

A typical error message when submitting an app with unsupported architectures:

ERROR ITMS-90087: "Unsupported Architectures. The executable for [...].app/Frameworks/ScanbotBarcodeScannerSDK.framework contains unsupported architectures '[x86_64]'."

To fix this error and properly prepare an app bundle for submission we provide a script, which can be found here:

plugins/cordova-plugin-scanbot-barcode-scanner/src/ios/Frameworks/ScanbotBarcodeScannerSDK.framework/strip-SBSDK-Framework.sh

This script removes the unnecessary architectures from the frameworks binary, code signs the framework and adds the crash symbols (dSYM) file to your app's archive.

To add this script in your build process, you need to apply a few changes in the Xcode project:

  1. Open the generated Xcode project file with Xcode IDE: <YOUR_APP_PROJECT_PATH>/platforms/ios/<YOUR_APP_NAME>.xcodeproj
  2. Go to TARGETS settings and open the tab Build Phases. Add a new Run Script Phase and make sure this phase is below the Embed Frameworks build phase.
  3. Adjust this Run Script Phase with the following script data:

Script code:

bash "$BUILT_PRODUCTS_DIR/$FRAMEWORKS_FOLDER_PATH/ScanbotBarcodeScannerSDK.framework/strip-SBSDK-Framework.sh"

Script Input File:

$(SRCROOT)/../../plugins/cordova-plugin-scanbot-barcode-scanner/src/ios/Frameworks/ScanbotBarcodeScannerSDK.framework.dSYM

alt text

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 to 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).