Skip to main content

Barcode Scanner | Cordova Document Scanner

The Scanbot SDK provides a ready-to-use UI screen component for Barcode and QR-Code scanning.

alt text

Supported Barcode Types#

1D Barcodes#

2D Barcodes#

tip

You might also be interested in an overview in our blog post Types of barcodes and their usage.

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.',  orientationLockMode: '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 of status="CANCELED":
    • true If the config value autoCancelTimeout was specified, AND the UI was auto-canceled due to timeout.
    • false If 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.   */  orientationLockMode?: CameraOrientationMode;  /**   * 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;}

Integrating the Batch Barcode Scanner UI#

The Batch Barcode Scanner supports scanning and collecting multiple barcodes and QR-codes in a row.

alt text

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.',  orientationLockMode: '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 of status="CANCELED":
    • true If the config value autoCancelTimeout was specified, AND the UI was auto-canceled due to timeout.
    • false If 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.     */    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    /**     * 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;}

Detection on Still Images#

ScanbotSdk.detectBarcodesOnImage(args: {imageFileUri: string, barcodeFormats?: BarcodeFormat[], acceptedDocumentFormats?: BarcodeDocumentFormat[], minimumTextLength?: number, maximumTextLength?: number, minimum1DBarcodesQuietZone?: number})

Detects barcodes on a still image (PNG or JPG file) regardless of the image source (e.g. scanned document image, image picked from photo library, etc).

import ScanbotSdk 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 result = await this.SDK.detectBarcodesOnImage({  imageFileUri: 'file:///some/image-file.jpg',  //barcodeFormats: ['QR_CODE', 'EAN_13', ...], // optional filter for specific barcode types  // see further args...});
// handle the detected barcode(s) from result// result.barcodes[n]...

Input Args#

  • imageFileUri: File URI of the input image to detect barcodes on (file:///...).
  • barcodeFormats: Optional array of barcode formats that acts as a detection filter. By default all supported formats will be detected.
  • acceptedDocumentFormats: An optional array of barcode document formats that act as a detection filter. By default all supported document formats will be detected. See below.
  • minimumTextLength: Optional minimum required text length of the detected barcodes. The default is 0 (setting is turned off). NOTE: This feature works on ITF barcodes only.
  • maximumTextLength: Optional maximum text length of the detected barcodes. The default is 0 (setting is turned off). NOTE: Currently supports ITF barcodes only.
  • minimum1DBarcodesQuietZone: Optional minimum required quiet zone on the barcodes. Measured in modules (the size of minimal bar on the barcodes). The default is 10. NOTE: Currently supports ITF barcodes only.

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 of status="CANCELED":
    • true If the config value autoCancelTimeout was specified, AND the UI was auto-canceled due to timeout.
    • false If the user closed the UI via the "cancel" button.

Barcode Document Formats#

  • 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