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;
}
PropertyTypeDefault ValueDescription
licensestringN/AThe to activate the barcode scanner.
scanMode(optional)EnumScanModeSM_SINGLEDefines the scan mode of the BarcodeScanner
templateFilePath(optional)stringN/APath 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)EngineResourcePathsN/APaths to engine resources like WASM or workers. See EngineResourcePaths for details.
uiPath (optional)stringN/APath to the custom UI (.xml template file) for the ScannerView.
barcodeFormats(optional)EnumBarcodeFormat | Array<EnumBarcodeFormat>N/AEnumBarcodeFormat or an array of EnumBarcodeFormat specifying the formats to recognize.
duplicateForgetTime(optional)number3000Time interval in milliseconds before duplicate barcodes can be reported again.
removePoweredByMessage(optional)booleanfalseWhether to remove the “powered by” message.
container(optional)HTMLElement | stringN/AA container element or selector for rendering the scanner and/or result view.
onUniqueBarcodeScannedvoid | Promise<void>N/AA callback triggered when a unique barcode is scanned (only valid in SM_MULTI_UNIQUE).
showResultView(optional)booleanfalseWhether to display a result view in SM_MULTI_UNIQUE mode.
showUploadImageButton(optional)booleanfalseDetermines the visibility of the “uploadImage” button that allows the user to upload an image for decoding.
scannerViewConfig(optional)ScannerViewConfigsee ScannerViewConfigConfiguration for the scanner view.
resultViewConfig(optional)ResultViewConfigsee ResultViewConfigConfiguration 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;
}
PropertyTypeDefault ValueDescription
container (optional)HTMLElement | string | undefinedN/AA dedicated container for the ScannerView (video stream).
showCloseButton (optional)booleanfalseDetermines 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;
}
PropertyTypeDefault ValueDescription
container (optional)HTMLElement | string | undefinedN/AA dedicated container for the ResultView.
toolbarButtonsConfig (optional)BarcodeResultViewToolbarButtonsConfigsee BarcodeResultViewToolbarButtonsConfigConfigures 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;
}
PropertyTypeDescription
clear (optional)ToolbarButtonConfigConfiguration for the clear button of the toolbar.
done (optional)ToolbarButtonConfigConfiguration 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;
}
PropertyTypeDescription
labelstringThe text label of the button.
classNamestringAssigns a custom class to the button (usually to apply custom styling).
isHiddenbooleanHides/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;
}
PropertyTypeDescription
status (optional)ResultStatusThe status of the barcode scanning, which can be success, cancelled, or failed (indicating that something has gone wrong during the scanning process).
originalImageResult (optional)DSImageDataA 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;
}
PropertyTypeDescription
singlestringTemplate name used for single barcode scanning mode.
multi_uniquestringTemplate name used for scanning multiple unique barcodes.
imagestringTemplate 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: