Table of contents
Swift
Objective-C

Barcode Scanner JavaScript Edition API Reference

BarcodeScanner is a configurable barcode scanning module featuring a pre-built UI that supports both live camera and still image decoding. Designed for effortless integration into web applications, it offers a ready-to-use, customizable interface to streamline barcode scanning implementation.

Constructor

BarcodeScanner

new BarcodeScanner(config?: BarcodeScannerConfig)

Parameters

config (optional): Assigns the license and configures the different settings of the BarcodeScanner, including the container, supported barcode formats, and more. This config object is of type BarcodeScannerConfig.

Code Snippet

const barcodeScanner = new Dynamsoft.BarcodeScanner({
  license: "YOUR_LICENSE_KEY_HERE",
  scannerViewConfig: {
  //  container: "#camera-view-container",
  //  showCloseButton: true,
  },
  // showUploadImageButton: true,
  // scanMode: Dynamsoft.EnumScanMode.SM_MULTI_UNIQUE,
  // showResultView: true,
});

Methods

launch()

Launches the scanner and optionally renders the scanning UI based on scanMode and container configuration.

launch(): Promise<BarcodeScanResult>

Returns

A promise that resolves to a BarcodeScanResult.

Code Snippet

(async () => {
    // Launch the scanner and wait for the result
    try {
        const result = await barcodeScanner.launch();
        console.log(result); // print the BarcodeScanResult to the console
    } catch (error){
        console.error(error);
    }
})();

dispose()

Disposes the scanner instance and cleans up all related resources.

dispose(): void

Code Snippet

barcodeScanner.dispose();
console.log("Scanner resources released.");

decode()

Decodes a barcode from an image, URL, or canvas element.

decode(imageOrFile: Blob | string | DSImageData | HTMLImageElement | HTMLVideoElement | HTMLCanvasElement,templateName?: string): Promise<CapturedResult>

Parameters

imageOrFile: The input image source.

templateName (optional): The name of the CaptureVisionTemplate to be used.

Returns

A promise that resolves to a CapturedResult.

Code Snippet

const imageUrl = 'https://example.com/image.png';
const results = barcodeScanner.decode(imageUrl);
//... do something with the results

Interfaces

BarcodeScannerConfig

Configuration options for initializing a BarcodeScanner.

interface BarcodeScannerConfig {
  license?: string;
  scanMode?: EnumScanMode;
  templateFilePath?: string;
  utilizedTemplateNames?: UtilizedTemplateNames;
  engineResourcePaths?: EngineResourcePaths;
  uiPath?: string;
  barcodeFormats?: EnumBarcodeFormat | Array<EnumBarcodeFormat>;
  duplicateForgetTime?: number;
  removePoweredByMessage?: boolean;
  container?: HTMLElement | string | undefined;
  onUniqueBarcodeScanned?: (result: BarcodeResultItem) => void | Promise<void>;
  showResultView?: boolean;
  showUploadImageButton?: boolean;
  scannerViewConfig?: ScannerViewConfig;
  resultViewConfig?: ResultViewConfig;
}
Property Type Default Value Description
license string N/A The license key to activate the barcode scanner.
scanMode(optional) EnumScanMode SM_SINGLE Defines the scan mode of the BarcodeScanner
templateFilePath(optional) string N/A Path to a CaptureVisionTemplate file used for barcode reading.
utilizedTemplateNames(optional) UtilizedTemplateNames {"single": "ReadSingleBarcode", "multi_unique": "ReadBarcodes_SpeedFirst", "image": "ReadBarcodes_ReadRateFirst"} Defines template names mapped to scanning modes.
engineResourcePaths(optional) EngineResourcePaths N/A Paths to engine resources like WASM or workers. See EngineResourcePaths for details.
uiPath (optional) string N/A Path to the custom UI (.xml template file) for the ScannerView.
barcodeFormats(optional) EnumBarcodeFormat | Array<EnumBarcodeFormat> N/A EnumBarcodeFormat or an array of EnumBarcodeFormat specifying the formats to recognize.
duplicateForgetTime(optional) number 3000 Time interval in milliseconds before duplicate barcodes can be reported again.
removePoweredByMessage(optional) boolean false Whether to remove the “powered by” message.
container(optional) HTMLElement | string N/A A container element or selector for rendering the scanner and/or result view.
onUniqueBarcodeScanned void | Promise<void> N/A A callback triggered when a unique barcode is scanned (only valid in SM_MULTI_UNIQUE).
showResultView(optional) boolean false Whether to display a result view in SM_MULTI_UNIQUE mode.
showUploadImageButton(optional) boolean false Determines the visibility of the “uploadImage” button that allows the user to upload an image for decoding.
scannerViewConfig(optional) ScannerViewConfig see ScannerViewConfig Configuration for the scanner view.
resultViewConfig(optional) ResultViewConfig see ResultViewConfig Configuration for the result view (only valid in SM_MULTI_UNIQUE).

Code Snippet

<body>
    <div id="camera-view-container" style="width: 100%; height: 80vh"></div>
    <script>
      const barcodeScannerConfig = {
        license: "YOUR_LICENSE_KEY_HERE",
        // Defines scan behavior:
        //   - SM_MULTI_UNIQUE: Keeps scanning and continuously collecting unique decoded barcode results.
        //   - SM_SINGLE: Scans once a result is found.
        scanMode: Dynamsoft.EnumScanMode.SM_MULTI_UNIQUE,
        // The path to your custom JSON template that defines the scanning process.
        templateFilePath:'./DBR-PresetTemplates.json',
        // engineResourcePaths typically is only assigned when using a framework like React/Angular/Vue where the resources are not in the same location as the script reference.
        engineResourcePaths: {rootDirectory:"https://cdn.jsdelivr.net/npm/[email protected]/dist"},
        barcodeFormats: [Dynamsoft.DBR.EnumBarcodeFormat.BF_QR_CODE , Dynamsoft.DBR.EnumBarcodeFormat.BF_CODE_128],
        removePoweredByMessage: true,
        duplicateForgetTime: 3000,
        showUploadImageButton: true,
        // The container for rendering the scanner and/or result view. Note that ResultView is only valid for SM_MULTI_UNIQUE mode. If not specified, a full-viewport default UI will be created.
        container: "#camera-view-container",
        onUniqueBarcodeScanned: (result) => {
        // do something with the result
        },
        showResultView: true,
        scannerViewConfig: {
          // the ResultViewConfig goes in here - see ResultViewConfig section
        },
        resultViewConfig: {
          // the ResultViewConfig goes in here - see ResultViewConfig section
        }
      };
      // Initialize the BarcodeScanner with the above BarcodeScannerConfig object
      const barcodeScanner = new Dynamsoft.BarcodeScanner(barcodeScannerConfig);
    </script>
</body>

ScannerViewConfig

The ScannerViewConfig is used to configure the UI elements of the BarcodeScannerView. If the ScannerViewConfig is not assigned, then the library will use the default BarcodeScannerView.

interface ScannerViewConfig {
  container?: HTMLElement | string | undefined;
  showCloseButton?: boolean;
}
Property Type Default Value Description
container (optional) HTMLElement | string | undefined N/A A dedicated container for the ScannerView (video stream).
showCloseButton (optional) boolean false Determines the visibility of the “closeButton” button that allows the user to close the ScannerView.

Code Snippet

const barcodeScannerViewConfig = {
  showCloseButton: true // display the close button that shows up at the top right of the view
};

const barcodeScannerConfig = {
    license: "YOUR_LICENSE_KEY_HERE",
    scannerViewConfig: barcodeScannerViewConfig
};

ResultViewConfig

The ResultViewConfig is used to configure the UI elements of the BarcodeResultView. If the ResultViewConfig is not assigned, then the library will use the default BarcodeResultView.

interface ResultViewConfig {
  container?: HTMLElement | string | undefined;
  toolbarButtonsConfig?: BarcodeResultViewToolbarButtonsConfig;
}
Property Type Default Value Description
container (optional) HTMLElement | string | undefined N/A A dedicated container for the ResultView.
toolbarButtonsConfig (optional) BarcodeResultViewToolbarButtonsConfig see BarcodeResultViewToolbarButtonsConfig Configures the main bottom toolbar of the ResultView.

Code Snippet

const barcodeResultViewConfig = {
    toolbarButtonsConfig: {
      clear: {
          label: "Clear-all", // Changes the text label of the clear button to "Clear-all"; string is "Clear" by default
          isHidden: true // Hides the clear button; false by default
      },
      done: {
          label: "Return Home", // Changes the text label of the done button to "Return Home"; string is "Done" by default
          isHidden: false // Hides the done button; false by default
      }
  },
}

const barcodeScannerConfig = {
    license: "YOUR_LICENSE_KEY_HERE",
    resultViewConfig: barcodeResultViewConfig
};

BarcodeResultViewToolbarButtonsConfig

The BarcodeResultViewToolbarButtonsConfig is used to configure the buttons of the toolbar in the BarcodeResultView.

interface BarcodeResultViewToolbarButtonsConfig {
  clear?: ToolbarButtonConfig;
  done?: ToolbarButtonConfig;
}
Property Type Description
clear (optional) ToolbarButtonConfig Configuration for the clear button of the toolbar.
done (optional) ToolbarButtonConfig Configuration for the done button of the toolbar.

Code Snippet

// Default value as shown below
const barcodeScannerButtonConfig = {
    clear: {
        label: "Clear", 
        isHidden: false
    },
    done: {
        label: "Done",
        isHidden: false
    }
};

const barcodeResultViewConfig = {
    toolbarButtonsConfig: barcodeScannerButtonConfig
};

ToolbarButtonConfig

The interface used to configure the properties of the toolbar button.

interface ToolbarButtonConfig {
  label: string;
  className?: string;
  isHidden?: boolean;
}
Property Type Description
label string The text label of the button.
className string Assigns a custom class to the button (usually to apply custom styling).
isHidden boolean Hides/Shows the button in the toolbar.

BarcodeScanResult

The BarcodeScanResult is the most basic interface that is used to represent the full barcode scan result object. It comes with a result status, the original and cropped image result, and the detailed info of the decoded barcode(s).

interface BarcodeScanResult {
  status: ResultStatus;
  barcodeResults?: BarcodeResultItem[];
  originalImageResult?: DSImageData;
  barcodeImage?: DSImageData;
}
Property Type Description
status (optional) ResultStatus The status of the barcode scanning, which can be success, cancelled, or failed (indicating that something has gone wrong during the scanning process).
originalImageResult (optional) DSImageData A DSImageData object that represents the original image of the successfully decoded barcode.
barcodeResults (optional) Array<BarcodeResultItem> An array of BarcodeResultItem Represents the decoded barcode(s).

Code Snippet

(async () => {
    // Launch the scanner and wait for the result
    const result = await barcodeScanner.launch();
    console.log(result.status.message); // prints the result status message to the console
    console.log(result.status.code); // prints the result status code to the console
    console.log(result.barcodeResults); // prints an array containing all the decoded barcode results to the console. Note that in SM_SINGLE mode, the length of this array is 1.
})();

UtilizedTemplateNames

An object that defines the names of templates utilized by the BarcodeScanner for different scanning modes.

interface UtilizedTemplateNames {
  single: string;
  multi_unique: string;
  image: string;
}
Property Type Description
single string Template name used for single barcode scanning mode.
multi_unique string Template name used for scanning multiple unique barcodes.
image string Template name used when barcode scanning is based on a provided image input.

Code Snippet

const barcodeScannerConfig = {
    //..
    utilizedTemplateNames:{
      single: `ReadSingleBarcode`,
      multi_unique: `ReadBarcodes_SpeedFirst`,
      image: `ReadBarcodes_ReadRateFirst`,
    }
    //..
}

ResultStatus

ResultStatus is used to represent the status of the barcode scanning result. This status can be success, cancelled if the user closes the scanner during scanning, or failed if something went wrong during the scanning process. The code of the result status is a EnumResultStatus.

type ResultStatus = {
  code: EnumResultStatus;
  message: string;
}

Enums

EnumScanMode

enum EnumScanMode {
    SM_SINGLE = 0,
    SM_MULTI_UNIQUE = 1
}

EnumResultStatus

enum EnumResultStatus {
    RS_SUCCESS = 0,
    RS_CANCELLED = 1,
    RS_FAILED = 2
}

This page is compatible for:

Is this page helpful?

YesYes NoNo

In this article: