diff --git a/_includes/samples_index.html b/_includes/samples_index.html index af82c6bb..6f6bb394 100644 --- a/_includes/samples_index.html +++ b/_includes/samples_index.html @@ -1075,7 +1075,7 @@ ✨ Full Demo
Official Online Demo
Explore all features and capabilities in our comprehensive live demo
- - + --> @@ -1295,7 +1295,7 @@

data-balloon-length="large" data-balloon-pos="down" aria-label="Simulates a shopping experience where users scan barcodes to add items to a dynamic cart." - >Cart BuilderCart Builder
Scan and SearchScan and Search
Show Result Texts on Video >
+
+ Scan DPM CodesSource +
User Guide
  • - Start with RTU-BarcodeScanner + Get Started
  • - Customize your BarcodeScanner + Use in Framework
    • -
  • - Develop with Foundational APIs -
      -
    • - Get Started +
    • + Explore Features +
        +
      • + Basic Features +
        • -
      • - Use in Framework +
      • + Handle Different Cases +
      • - Explore Features + Barcode Results +
        • +
      • + Advanced Features +
        • @@ -226,1156 +204,1161 @@
      • API Reference
          -
        • - BarcodeScanner APIs -
          • -
        • - Foundational APIs -
          • {%- include liquid_searchVersionTreeFile.html ver=include.ver curPath=include.curPath targetRelativePath="sidelist-understanding.html" -%} diff --git a/_includes/sidelist-programming/sidelist-parameters.html b/_includes/sidelist-programming/sidelist-parameters.html index 895271c3..b384a8c4 100644 --- a/_includes/sidelist-programming/sidelist-parameters.html +++ b/_includes/sidelist-programming/sidelist-parameters.html @@ -260,6 +260,7 @@
        • BarcodeWidthRangeArray
        • BarcodeZoneBarCountRangeArray
        • BarcodeZoneMinDistanceToImageBorders
          • +
        • BarcodeZoneWidthToHeightRatioRangeArray
        • Code128Subset
        • DataMatrixModuleIsotropic
        • DataMatrixSizeOptions
          • diff --git a/programming/javascript/api-reference/barcode-reader-module.md b/programming/javascript/api-reference/barcode-reader-module.md index 0ba5c384..438a2c9a 100644 --- a/programming/javascript/api-reference/barcode-reader-module.md +++ b/programming/javascript/api-reference/barcode-reader-module.md @@ -34,6 +34,7 @@ This class defines common functionality in the `BarcodeReader` module. At presen * [DecodedBarcodesUnit](./interfaces/decoded-barcodes-unit.md) * [DeformationResistedBarcode](./interfaces/deformation-resisted-barcode.md) * [DeformationResistedBarcodeImageUnit](./interfaces/deformation-resisted-barcode-image-unit.md) +* [ECI-segment](./interfaces/eci-segment.md) * [ExtendedBarcodeResult](./interfaces/extended-barcode-result.md) * [LocalizedBarcodeElement](./interfaces/localized-barcode-element.md) * [LocalizedBarcodesUnit](./interfaces/localized-barcodes-unit.md) diff --git a/programming/javascript/api-reference/barcode-scanner.md b/programming/javascript/api-reference/barcode-scanner.md deleted file mode 100644 index a2a495e5..00000000 --- a/programming/javascript/api-reference/barcode-scanner.md +++ /dev/null @@ -1,789 +0,0 @@ ---- -layout: default-layout -title: BarcodeScanner JavaScript Edition - API Reference -keywords: Documentation, BarcodeScanner JavaScript Edition, API, APIs -breadcrumbText: BarcodeScanner API References -description: This is the OFFICIAL API Reference for Dynamsoft BarcodeScanner JavaScript Edition. This documentation is the authoritative and most up-to-date source for BarcodeScanner class APIs -needAutoGenerateSidebar: true -needGenerateH3Content: true -noTitleIndex: true ---- - - - -# Barcode Scanner JavaScript Edition API Reference - -BarcodeScanner is a ready-to-use class that combines barcode decoding with camera control and UI. Add barcode scanning to your web app with just a few lines of code—camera access, viewfinder rendering, and lifecycle management are all handled for you. - -## Constructor - -### BarcodeScanner - -```ts -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*](#barcodescannerconfig). - -**Code Snippet** - -```js -const barcodeScanner = new Dynamsoft.BarcodeScanner({ - license: "YOUR_LICENSE_KEY_HERE", - scannerViewConfig: { - // container: "#camera-view-container", - }, - // showUploadImageButton: true, - // scanMode: Dynamsoft.EnumScanMode.SM_MULTI_UNIQUE, -}); -``` - -## Methods - -### launch() - -Launches the scanner and optionally renders the scanning UI based on scanMode and container configuration. - -```ts -launch(): Promise -``` - -**Returns** - -A promise that resolves to a [`BarcodeScanResult`](#barcodescanresult). - -**Code Snippet** - -```js -(async () => { - // Launch the scanner and wait for the result - try { - const result = await barcodeScanner.launch(); - // print the BarcodeScanResult to the console - console.log(result); - } catch (error){ - console.error(error); - } -})(); -``` - -### dispose() - -Disposes the scanner instance and cleans up all related resources. - -```ts -dispose(): void -``` - -**Code Snippet** - -```js -barcodeScanner.dispose(); -console.log("Scanner resources released."); -``` - -### decode() - -Decodes a barcode from an image, URL, or canvas element. - -```ts -decode(imageOrFile: Blob | string | DSImageData | HTMLImageElement | HTMLVideoElement | HTMLCanvasElement,templateName?: string): Promise -``` - -**Parameters** - -`imageOrFile`: The input image source. - -`templateName` (optional): The name of the [`CaptureVisionTemplate`]({{ site.dcvb_js_api }}capture-vision-router/preset-templates.html) to be used. - -**Returns** - -A promise that resolves to a `CapturedResult`. - -**Code Snippet** - -```js -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`. - -```ts -interface BarcodeScannerConfig { - license?: string; - scanMode?: EnumScanMode; - templateFilePath?: string; - utilizedTemplateNames?: UtilizedTemplateNames; - engineResourcePaths?: EngineResourcePaths; - uiPath?: string; - barcodeFormats?: EnumBarcodeFormat | Array; - duplicateForgetTime?: number; - showPoweredByDynamsoft?: boolean; - autoStartCapturing? : boolean; - container?: HTMLElement | string | undefined; - onUniqueBarcodeScanned?: (result: BarcodeResultItem) => void | Promise; - showResultView?: boolean; - showUploadImageButton?: boolean; - scannerViewConfig?: ScannerViewConfig; - resultViewConfig?: ResultViewConfig; - onInitPrepare?: () => void; - onInitReady?: (components: {cameraView: CameraView;cameraEnhancer: CameraEnhancer;cvRouter: CaptureVisionRouter;}) => void; - onCameraOpen?: (components: {cameraView: CameraView;cameraEnhancer: CameraEnhancer;cvRouter: CaptureVisionRouter;}) => void; - onCaptureStart?: (components: {cameraView: CameraView;cameraEnhancer: CameraEnhancer;cvRouter: CaptureVisionRouter;}) => void; -} -``` - -#### license - -The license key to activate the barcode scanner. - -**Type:** `string` - ---- - -#### scanMode - -Defines the scan mode of the BarcodeScanner. - -**Type:** [`EnumScanMode`](#enumscanmode) - -**Default:** `SM_SINGLE` - ---- - -#### templateFilePath - -Path to a CaptureVisionTemplate file used for barcode reading. - -**Type:** `string` - ---- - -#### utilizedTemplateNames - -Defines template names mapped to scanning modes. - -**Type:** `UtilizedTemplateNames` - -**Default:** `{"single": "ReadBarcodes_SpeedFirst", "multi_unique": "ReadBarcodes_SpeedFirst", "image": "ReadBarcodes_ReadRateFirst"}` - ---- - -#### engineResourcePaths - -Paths to engine resources like WASM or workers. See [EngineResourcePaths](https://www.dynamsoft.com/capture-vision/docs/web/programming/javascript/api-reference/core/core-module-class.html?product=dbr&lang=javascript#engineresourcepaths) for details. - -**Type:** `EngineResourcePaths` - ---- - -#### uiPath - -Path to the custom UI (`.xml` template file) for the ScannerView. - -**Type:** `string` - ---- - -#### barcodeFormats - -Specifies the barcode formats to recognize. See [EnumBarcodeFormat](https://www.dynamsoft.com/capture-vision/docs/core/enums/barcode-reader/barcode-format.html?lang=js&product=dbr). - -**Type:** `EnumBarcodeFormat | Array` - ---- - -#### duplicateForgetTime - -Time in milliseconds before a barcode (same format + text) can trigger `onUniqueBarcodeScanned` again. - -**Type:** `number` - -**Default:** `3000` - ---- - -#### showPoweredByDynamsoft - -Whether to show the "powered by" message. - -**Type:** `boolean` - -**Default:** `true` - ---- - -#### autoStartCapturing - -Whether to start capturing directly after opening the camera. - -**Type:** `boolean` - -**Default:** `true` - ---- - -#### container - -A container element or selector for rendering the scanner and/or result view. - -**Type:** `HTMLElement | string` - ---- - -#### showResultView - -Whether to display a result view in SM_MULTI_UNIQUE mode. - -**Type:** `boolean` - -**Default:** `true` - ---- - -#### showUploadImageButton - -Determines the visibility of the "uploadImage" button that allows the user to upload an image for decoding. - -**Type:** `boolean` - -**Default:** `false` - ---- - -#### scannerViewConfig - -Configuration for the scanner view. - -**Type:** [`ScannerViewConfig`](#scannerviewconfig) - ---- - -#### resultViewConfig - -Configuration for the result view (only valid in SM_MULTI_UNIQUE). - -**Type:** [`ResultViewConfig`](#resultviewconfig) - ---- - -#### onUniqueBarcodeScanned - -A callback triggered when a unique barcode (by format + text) is scanned. Only valid in SM_MULTI_UNIQUE mode. - -**Type:** `(result: BarcodeResultItem) => void | Promise` - ---- - -#### onInitPrepare - -A callback function that is triggered before the scanner components are initialized. - -**Type:** `() => void` - ---- - -#### onInitReady - -Called when the scanner components have been successfully initialized and are ready. - -**Type:** `(components: {cameraView: CameraView; cameraEnhancer: CameraEnhancer; cvRouter: CaptureVisionRouter}) => void` - ---- - -#### onCameraOpen - -Called when the camera is successfully opened for the first time or after each camera switch. - -**Type:** `(components: {cameraView: CameraView; cameraEnhancer: CameraEnhancer; cvRouter: CaptureVisionRouter}) => void` - ---- - -#### onCaptureStart - -Called when the capture process begins. - -**Type:** `(components: {cameraView: CameraView; cameraEnhancer: CameraEnhancer; cvRouter: CaptureVisionRouter}) => void` - ---- - -**Code Snippet** - -```html -
          - -``` - -### 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. - -```ts -interface ScannerViewConfig { - container?: HTMLElement | string | undefined; - showCloseButton?: boolean; - mirrorFrontCamera?: boolean; - cameraSwitchControl?: CameraSwitchControlMode; - showFlashButton?: boolean; - customHighlightForBarcode?: (result: BarcodeResultItem) => DrawingItem; -} -``` - -#### container - -A dedicated container for the ScannerView (video stream). - -**Type:** `HTMLElement | string | undefined` - ---- - -#### showCloseButton - -Determines the visibility of the "closeButton" button that allows the user to close the ScannerView. - -**Type:** `boolean` - -**Default:** `true` - ---- - -#### mirrorFrontCamera - -Whether to mirror the camera feed when using the front-facing camera. - -**Type:** `boolean` - -**Default:** `true` - ---- - -#### cameraSwitchControl - -Specifies the mode and visibility of the camera switch control, enabling users to change between cameras. See [CameraSwitchControlMode](#cameraswitchcontrolmode). - -**Type:** `CameraSwitchControlMode` - -**Default:** `"hidden"` - ---- - -#### showFlashButton - -Controls the visibility of the "Flash" button that lets the user toggle the camera's torch. - -**Type:** `boolean` - -**Default:** `false` - ---- - -#### customHighlightForBarcode - -A callback function that allows customization of the visual highlight for detected barcodes. See [DrawingItem](https://www.dynamsoft.com/camera-enhancer/docs/web/programming/javascript/api-reference/drawingitem.html). - -**Type:** `(result: BarcodeResultItem) => DrawingItem` - ---- - -**Code Snippet** - -```js -const barcodeScannerViewConfig = { - // Hide the close button that shows up at the top right of the view - showCloseButton: false, - // Show the flash button that lets the user toggle the camera's torch. - showFlashButton: true, - // Shows the camera switcher that can toggle between front and back cameras. - cameraSwitchControl: "toggleFrontBack", - // Change the highlight style for all detected barcodes - customHighlightForBarcode: (item) => { - const imageDrawingStyleId = Dynamsoft.DCE.DrawingStyleManager.createDrawingStyle({ - lineWidth: 5, fillStyle: "rgba(0, 255, 255, 0.5)", strokeStyle: "rgba(0, 255, 255, 1)" - }); - const drawingItem = new Dynamsoft.DCE.RectDrawingItem( - { - x: item.location.points[0].x, - y: item.location.points[0].y, - width: item.location.points[1].x - item.location.points[0].x, - height: item.location.points[2].y - item.location.points[0].y, - isMeasuredInPercentage: false - }, - imageDrawingStyleId - ) - return drawingItem; - }, -}; - -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. - -```ts -interface ResultViewConfig { - container?: HTMLElement | string | undefined; - toolbarButtonsConfig?: BarcodeResultViewToolbarButtonsConfig; -} -``` - -#### container - -A dedicated container for the ResultView. - -**Type:** `HTMLElement | string | undefined` - ---- - -#### toolbarButtonsConfig - -Configures the main bottom toolbar of the ResultView. - -**Type:** [`BarcodeResultViewToolbarButtonsConfig`](#barcoderesultviewtoolbarbuttonsconfig) - ---- - -**Code Snippet** - -```js -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. - -```ts -interface BarcodeResultViewToolbarButtonsConfig { - clear?: ToolbarButtonConfig; - done?: ToolbarButtonConfig; -} -``` - -#### clear - -Configuration for the clear button of the toolbar. - -**Type:** [`ToolbarButtonConfig`](#toolbarbuttonconfig) - ---- - -#### done - -Configuration for the done button of the toolbar. - -**Type:** [`ToolbarButtonConfig`](#toolbarbuttonconfig) - ---- - -**Code Snippet** - -```js -// 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. - -```ts -interface ToolbarButtonConfig { - label: string; - className?: string; - isHidden?: boolean; -} -``` - -#### label - -The text label of the button. - -**Type:** `string` - ---- - -#### className - -Assigns a custom class to the button (usually to apply custom styling). - -**Type:** `string` - ---- - -#### isHidden - -Hides/Shows the button in the toolbar. - -**Type:** `boolean` - ---- - -### 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). - -```ts -interface BarcodeScanResult { - status: ResultStatus; - barcodeResults?: BarcodeResultItem[]; - originalImageResult?: DSImageData; - barcodeImage?: DSImageData; -} -``` - -#### status - -The status of the barcode scanning, which can be success, cancelled, or failed (indicating that something has gone wrong during the scanning process). - -**Type:** [`ResultStatus`](#resultstatus) - ---- - -#### barcodeResults - -An array of BarcodeResultItem representing the decoded barcode(s). - -**Type:** [`Array`]({{ site.js_api }}interfaces/barcode-result-item.html) - ---- - -#### originalImageResult - -A `DSImageData` object that represents the original image of the successfully decoded barcode. - -**Type:** [`DSImageData`]({{ site.dcvb_js_api }}core/basic-structures/ds-image-data.html) - ---- - -#### barcodeImage - -A `DSImageData` object containing the cropped barcode image. - -**Type:** [`DSImageData`]({{ site.dcvb_js_api }}core/basic-structures/ds-image-data.html) - ---- - -**Code Snippet** - -```js -(async () => { - // Launch the scanner and wait for the result - const result = await barcodeScanner.launch(); - // Prints the result status message to the console - console.log(result.status.message); - // Prints the result status code to the console - console.log(result.status.code); - // 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. - console.log(result.barcodeResults); -})(); -``` - -### UtilizedTemplateNames - -An object that defines the names of templates utilized by the BarcodeScanner for different scanning modes. - -```ts -interface UtilizedTemplateNames { - single: string; - multi_unique: string; - image: string; -} -``` - -#### single - -Template name used for single barcode scanning mode. - -**Type:** `string` - ---- - -#### multi_unique - -Template name used for scanning multiple unique barcodes. - -**Type:** `string` - ---- - -#### image - -Template name used when barcode scanning is based on a provided image input. - -**Type:** `string` - ---- - -**Code Snippet** - -```js -const barcodeScannerConfig = { - //.. - utilizedTemplateNames:{ - single: `ReadBarcodes_SpeedFirst`, - multi_unique: `ReadBarcodes_SpeedFirst`, - image: `ReadBarcodes_ReadRateFirst`, - } - //.. -} -``` - -> [!NOTE] -> Various preset templates are at your disposal for barcode reading: - -> | Template Name | Function Description | -> | ------------------------------ | -------------------------------------------------------------- | -> | **ReadBarcodes_Default** | Scans multiple barcodes by default setting. | -> | **ReadSingleBarcode** | Quickly scans a single barcode. | -> | **ReadBarcodes_SpeedFirst** | Prioritizes speed in scanning multiple barcodes. | -> | **ReadBarcodes_ReadRateFirst** | Maximizes the number of barcodes read. | -> | **ReadBarcodes_Balance** | Balances speed and quantity in reading multiple barcodes. | -> | **ReadDenseBarcodes** | Specialized in reading barcodes with high information density. | -> | **ReadDistantBarcodes** | Capable of reading barcodes from extended distances. | - -### 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`](#enumresultstatus). - -```ts -type ResultStatus = { - code: EnumResultStatus; - message: string; -} -``` - -## Types - -### CameraSwitchControlMode - -- `"hidden"`: Hides the camera switch control entirely. Users will not be able to switch cameras manually. - -- `"listAll"`: List all available cameras (e.g., front, back, external cameras). - -- `"toggleFrontBack"`: Allows toggling only between the front and back cameras. - -```ts -type CameraSwitchControlMode = "hidden" | "listAll" | "toggleFrontBack"; -``` - -## Enums - -### EnumScanMode - -```ts -enum EnumScanMode { - SM_SINGLE = 0, - SM_MULTI_UNIQUE = 1 -} -``` - -### EnumResultStatus - -```ts -enum EnumResultStatus { - RS_SUCCESS = 0, - RS_CANCELLED = 1, - RS_FAILED = 2 -} -``` \ No newline at end of file diff --git a/programming/javascript/api-reference/enum-barcode-format.md b/programming/javascript/api-reference/enum-barcode-format.md index fd48b81c..d55e18cb 100644 --- a/programming/javascript/api-reference/enum-barcode-format.md +++ b/programming/javascript/api-reference/enum-barcode-format.md @@ -19,103 +19,110 @@ codeAutoHeight: true > > ```javascript -enum EnumBarcodeFormat { - /** No barcode format specified.*/ - BF_NULL = 0x00, - /** Represents all supported barcode formats. Useful for scanning operations where any type of barcode is acceptable. */ - BF_ALL = 0xFFFFFFFEFFFFFFFF, - /** Default barcode formats that are commonly used. This is a subset of `BF_ALL` tailored for general use. */ - BF_DEFAULT = 0xFE3BFFFF, - /** One-dimensional barcode formats, including BF_CODE_39, BF_CODE_128, BF_CODE_93, BF_CODABAR, BF_ITF, BF_EAN_13, BF_EAN_8, BF_UPC_A, BF_UPC_E, INDUSTRIAL_25, BF_CODE_39_Extended, BF_CODE_11 and BF_MSI_CODE. */ - BF_ONED = 0x3007FF, - /** Code 39 format, widely used in various industries for inventory and manufacturing. */ - BF_CODE_39 = 0x1, - /** Code 128 format, a high-density barcode for alphanumeric or numeric-only data. */ - BF_CODE_128 = 0x2, - /** Code 93 format, similar to Code 39 but more compact and secure with support for the full ASCII character set. */ - BF_CODE_93 = 0x4, - /** Codabar format, used for various numeric barcodes in libraries, blood banks, and parcels. */ - BF_CODABAR = 0x8, - /** Interleaved 2 of 5 format, a numeric-only barcode used in warehousing, distribution, and logistics. */ - BF_ITF = 0x10, - /** EAN-13 format, a superset of the UPC-A barcode used worldwide for marking retail goods. */ - BF_EAN_13 = 0x20, - /** EAN-8 format, a compressed version of EAN-13 for smaller packages. */ - BF_EAN_8 = 0x40, - /** UPC-A format, widely used in the United States and Canada for tracking trade items in stores. */ - BF_UPC_A = 0x80, - /** UPC-E format, a smaller version of the UPC-A barcode used for smaller packages. */ - BF_UPC_E = 0x100, - /** Industrial 2 of 5 format, an older, numeric-only barcode used in the industrial sector. */ - BF_INDUSTRIAL_25 = 0x200, - /** Extended Code 39 format, capable of encoding the full ASCII character set by combining standard Code 39 characters. */ - BF_CODE_39_EXTENDED = 0x400, - /** GS1 DataBar barcode formats, including BF_GS1_DATABAR_OMNIDIRECTIONAL, BF_GS1_DATABAR_TRUNCATED, BF_GS1_DATABAR_STACKED, BF_GS1_DATABAR_STACKED_OMNIDIRECTIONAL, BF_GS1_DATABAR_EXPANDED, BF_GS1_DATABAR_EXPANDED_STACKED, BF_GS1_DATABAR_LIMITED. These barcodes are designed for use in retail and healthcare for fresh foods and small items. */ - BF_GS1_DATABAR = 0x3F800, - BF_GS1_DATABAR_OMNIDIRECTIONAL = 0x800, - BF_GS1_DATABAR_TRUNCATED = 0x1000, - BF_GS1_DATABAR_STACKED = 0x2000, - BF_GS1_DATABAR_STACKED_OMNIDIRECTIONAL = 0x4000, - BF_GS1_DATABAR_EXPANDED = 0x8000, - BF_GS1_DATABAR_EXPANDED_STACKED = 0x10000, - BF_GS1_DATABAR_LIMITED = 0x20000, - /** Patch code, a special barcode used for document scanning applications to separate batches of documents. */ - BF_PATCHCODE = 0x40000, - /** Micro PDF417, a compact version of PDF417 used for applications where space is limited. */ - BF_MICRO_PDF417 = 0x80000, - /** MSI Code, a barcode used in inventory and warehouse to encode information in the distribution of goods. */ - BF_MSI_CODE = 0x100000, - /** Code 11, used primarily for labeling telecommunications equipment. */ - BF_CODE_11 = 0x200000, - /** Two-Digit Add-On, an extension to UPC and EAN codes for magazines and books. */ - BF_TWO_DIGIT_ADD_ON = 0x400000, - /** Five-Digit Add-On, used with UPC and EAN codes for additional data, such as suggested retail price. */ - BF_FIVE_DIGIT_ADD_ON = 0x800000, - /** Code 32, also known as Italian PharmaCode, used specifically in the Italian pharmaceutical industry. */ - BF_CODE_32 = 0x1000000, - /** PDF417, a two-dimensional barcode used in a variety of applications, capable of encoding large amounts of data. */ - BF_PDF417 = 0x2000000, - /** QR Code, a widely used two-dimensional barcode with high data capacity and error correction capability. */ - BF_QR_CODE = 0x4000000, - /** DataMatrix, a two-dimensional barcode used for marking small items, providing high data density and reliability. */ - BF_DATAMATRIX = 0x8000000, - /** Aztec, a two-dimensional barcode known for its compact size and suitability for encoding small amounts of data efficiently. */ - BF_AZTEC = 0x10000000, - /** MaxiCode, a two-dimensional barcode used primarily for parcel and package tracking in logistics and postal services. */ - BF_MAXICODE = 0x20000000, - /** Micro QR, a smaller version of the QR Code designed for applications where space is limited. */ - BF_MICRO_QR = 0x40000000, - /** GS1 Composite, a group of barcodes used in conjunction with GS1 DataBar or linear barcodes to provide additional information. */ - BF_GS1_COMPOSITE = 0x80000000, - /** Nonstandard barcode, a placeholder for barcodes that do not conform to established industry standards. */ - BF_NONSTANDARD_BARCODE = 0x100000000, - /** DotCode, a two-dimensional barcode designed for high-speed printing applications. */ - BF_DOTCODE = 0x200000000, - /** PharmaCode, a general category that includes both BF_PHARMACODE_ONE_TRACK and BF_PHARMACODE_TWO_TRACK. */ - BF_PHARMACODE = 0xC00000000, - /** PharmaCode One Track, used in the pharmaceutical industry for packaging control. */ - BF_PHARMACODE_ONE_TRACK = 0x400000000, - /** PharmaCode Two Track, an extension of PharmaCode for encoding additional data. */ - BF_PHARMACODE_TWO_TRACK = 0x800000000, - /** Matrix 2 of 5, an older form of barcode used in warehouse sorting and conveyor systems. */ - BF_MATRIX_25 = 0x1000000000, - /** Postal code barcodes, including various formats (BF_USPSINTELLIGENTMAIL, BF_POSTNET, BF_PLANET, BF_AUSTRALIANPOST, BF_RM4SCC and BF_KIX) used by postal services worldwide for efficient mail sorting and delivery. */ - BF_POSTALCODE = 0x3F0000000000000, - /** USPS Intelligent Mail, a barcode used by the United States Postal Service to provide greater information and tracking capabilities. */ - BF_USPSINTELLIGENTMAIL = 0x10000000000000, - /** Postnet, used by the USPS for automating the sorting of mail. */ - BF_POSTNET = 0x20000000000000, - /** Planet, another USPS barcode, similar to Postnet, but with additional data capacity. */ - BF_PLANET = 0x40000000000000, - /** Australian Post, barcodes used by the Australian postal service for mail sorting. */ - BF_AUSTRALIANPOST = 0x80000000000000, - /** RM4SCC (Royal Mail 4 State Customer Code), used by the UK's Royal Mail for automated mail sorting. */ - BF_RM4SCC = 0x100000000000000, - /** KIX (Klant index - Customer index), used by the Dutch postal service for sorting mail. */ - BF_KIX = 0x200000000000000, +enum EnumBarcodeFormat: { + /**No barcode format in BarcodeFormat*/ + BF_NULL: bigint; + /**All supported formats in BarcodeFormat*/ + BF_ALL: bigint; + /**Use the default barcode format settings*/ + BF_DEFAULT: bigint; + /**Combined value of BF_CODABAR, BF_CODE_128, BF_CODE_39, BF_CODE_39_Extended, BF_CODE_93, BF_EAN_13, BF_EAN_8, INDUSTRIAL_25, BF_ITF, BF_UPC_A, BF_UPC_E, BF_MSI_CODE; */ + BF_ONED: bigint; + /**Combined value of BF_GS1_DATABAR_OMNIDIRECTIONAL, BF_GS1_DATABAR_TRUNCATED, BF_GS1_DATABAR_STACKED, BF_GS1_DATABAR_STACKED_OMNIDIRECTIONAL, BF_GS1_DATABAR_EXPANDED, BF_GS1_DATABAR_EXPANDED_STACKED, BF_GS1_DATABAR_LIMITED*/ + BF_GS1_DATABAR: bigint; + /**Code 39 */ + BF_CODE_39: bigint; + /**Code 128 */ + BF_CODE_128: bigint; + /**Code 93 */ + BF_CODE_93: bigint; + /**Codabar */ + BF_CODABAR: bigint; + /**Interleaved 2 of 5 */ + BF_ITF: bigint; + /**EAN-13 */ + BF_EAN_13: bigint; + /**EAN-8 */ + BF_EAN_8: bigint; + /**UPC-A */ + BF_UPC_A: bigint; + /**UPC-E */ + BF_UPC_E: bigint; + /**Industrial 2 of 5 */ + BF_INDUSTRIAL_25: bigint; + /**CODE39 Extended */ + BF_CODE_39_EXTENDED: bigint; + /**GS1 Databar Omnidirectional*/ + BF_GS1_DATABAR_OMNIDIRECTIONAL: bigint; + /**GS1 Databar Truncated*/ + BF_GS1_DATABAR_TRUNCATED: bigint; + /**GS1 Databar Stacked*/ + BF_GS1_DATABAR_STACKED: bigint; + /**GS1 Databar Stacked Omnidirectional*/ + BF_GS1_DATABAR_STACKED_OMNIDIRECTIONAL: bigint; + /**GS1 Databar Expanded*/ + BF_GS1_DATABAR_EXPANDED: bigint; + /**GS1 Databar Expanded Stacked*/ + BF_GS1_DATABAR_EXPANDED_STACKED: bigint; + /**GS1 Databar Limited*/ + BF_GS1_DATABAR_LIMITED: bigint; + /**Patch code. */ + BF_PATCHCODE: bigint; + /**Code 32 */ + BF_CODE_32: bigint; + /**PDF417 */ + BF_PDF417: bigint; + /**QRCode */ + BF_QR_CODE: bigint; + /**DataMatrix */ + BF_DATAMATRIX: bigint; + /**AZTEC */ + BF_AZTEC: bigint; + /**MAXICODE */ + BF_MAXICODE: bigint; + /**Micro QR Code*/ + BF_MICRO_QR: bigint; + /**Micro PDF417*/ + BF_MICRO_PDF417: bigint; + /**GS1 Composite Code*/ + BF_GS1_COMPOSITE: bigint; + /**MSI Code*/ + BF_MSI_CODE: bigint; + /**Code 11 */ + BF_CODE_11: bigint; + /**Two-Digit Add-On */ + BF_TWO_DIGIT_ADD_ON: bigint; + /**Five-Digit Add-On */ + BF_FIVE_DIGIT_ADD_ON: bigint; + /**Matrix 2 of 5 */ + BF_MATRIX_25: bigint; + /**Combined value of BF_USPSINTELLIGENTMAIL, BF_POSTNET, BF_PLANET, BF_AUSTRALIANPOST, BF_RM4SCC.*/ + BF_POSTALCODE: bigint; + /**Nonstandard barcode */ + BF_NONSTANDARD_BARCODE: bigint; + /**USPS Intelligent Mail.*/ + BF_USPSINTELLIGENTMAIL: bigint; + /**Postnet.*/ + BF_POSTNET: bigint; + /**Planet.*/ + BF_PLANET: bigint; + /**Australian Post.*/ + BF_AUSTRALIANPOST: bigint; + /**Royal Mail 4-State Customer Barcode.*/ + BF_RM4SCC: bigint; + /**KIX.*/ + BF_KIX: bigint; + /**DotCode.*/ + BF_DOTCODE: bigint; + /**_PHARMACODE_ONE_TRACK.*/ + BF_PHARMACODE_ONE_TRACK: bigint; + /**PHARMACODE_TWO_TRACK.*/ + BF_PHARMACODE_TWO_TRACK: bigint; + /**PHARMACODE.*/ + BF_PHARMACODE: bigint; /**Telepen*/ - BF_TELEPEN = 0x2000000000, + BF_TELEPEN: bigint; /**Telepen Numeric. A variation of the Telepen format optimized for encoding numeric data only.*/ - BF_TELEPEN_NUMERIC = 0x4000000000 + BF_TELEPEN_NUMERIC: bigint; } ``` \ No newline at end of file diff --git a/programming/javascript/api-reference/index.md b/programming/javascript/api-reference/index.md index 6f6da32b..4b52e8a5 100644 --- a/programming/javascript/api-reference/index.md +++ b/programming/javascript/api-reference/index.md @@ -75,11 +75,11 @@ noTitleIndex: true * [CameraEnhancer]({{ site.dce_js_api }}index.html) * [CameraView]({{ site.dce_js_api }}cameraview.html) -* [ImageEditorView]({{ site.dce_js_api }}imageeditorview.html) + * [CameraEnhancerModule]({{ site.dce_js_api }}cameraenhancermodule.html) * [DrawingItem]({{ site.dce_js_api }}drawingitem.html) * [DrawingLayer]({{ site.dce_js_api }}drawinglayer.html) -* [DrawingStyleManager]({{ site.dce_js_api }}drawinglayer.html) +* [DrawingStyleManager]({{ site.dce_js_api }}drawingstylemanager.html) * [Feedback]({{ site.dce_js_api }}feedback.html) ### Interfaces @@ -101,6 +101,24 @@ noTitleIndex: true * [EnumDrawingItemState]({{ site.dce_js_api }}enum/enumdrawingitemstate.html) * [EnumEnhancedFeatures]({{ site.dce_js_api }}enum/enumenhancedfeatures.html) +## [DynamsoftCodeParser]({{ site.dcp_js_api }}code-parser-module.html) + +### Classes + +* [CodeParser]({{ site.dcp_js_api }}code-parser.html) +* [CodeParserModule]({{ site.dcp_js_api }}code-parser-module-class.html) + +### Interfaces + +* [ParsedResult]({{ site.dcp_js_api }}interfaces/parsed-result.html) +* [ParsedResultItem]({{ site.dcp_js_api }}interfaces/parsed-result-item.html) + +### Enumerations + +* [EnumCodeType]({{ site.dcp_js_api }}enum-code-type.html) +* [EnumMappingStatus]({{ site.dcp_js_api }}enum-mapping-status.html) +* [EnumValidationStatus]({{ site.dcp_js_api }}enum-validation-status.html) + ## [DynamsoftCore]({{ site.dcvb_js_api }}core/core-module.html) ### Classes @@ -176,5 +194,7 @@ noTitleIndex: true ### Classes * [UtilityModule]({{ site.dcvb_js_api }}utility/utility-module-class.html) -* [ImageManager]({{ site.dcvb_js_api }}utility/image-manager.html) +* [ImageDrawer]({{ site.dcvb_js_api }}utility/image-drawer.html) +* [ImageIO]({{ site.dcvb_js_api }}utility/image-io.html) +* [ImageProcessor]({{ site.dcvb_js_api }}utility/image-processor.html) * [MultiFrameResultCrossFilter]({{ site.dcvb_js_api }}utility/multi-frame-result-cross-filter.html) \ No newline at end of file diff --git a/programming/javascript/api-reference/interfaces/barcode-result-item.md b/programming/javascript/api-reference/interfaces/barcode-result-item.md index 955f1fcc..097058e9 100644 --- a/programming/javascript/api-reference/interfaces/barcode-result-item.md +++ b/programming/javascript/api-reference/interfaces/barcode-result-item.md @@ -24,6 +24,7 @@ interface BarcodeResultItem extends Core.CapturedResultItem { details: BarcodeDetails; isDPM: boolean; isMirrored: boolean; + eciSegments: Array; } ``` +| [isMirrored](#ismirrored) | *boolean* | +| [eciSegments](#ecisegments) | *Array\* | --> ## format @@ -135,4 +137,20 @@ Whether the barcode is mirrored or reversed from its normal orientation. ```typescript isMirrored: boolean; -``` \ No newline at end of file +``` + +## eciSegments + +An array of ECI (Extended Channel Interpretation) segments present in the barcode, if any. Each segment is represented by an `ECISegment` object. + +```typescript +eciSegments: Array; +``` + +**See also** + +* [ECISegment]({{ site.js_api }}interfaces/eci-segment.html) + +**Remarks** + +New added in CaptureVisionBundle version 3.4.2000 & BarcodeReaderBundle version 11.4.2000. diff --git a/programming/javascript/api-reference/interfaces/decoded-barcode-element.md b/programming/javascript/api-reference/interfaces/decoded-barcode-element.md index 4c179730..e40e35c3 100644 --- a/programming/javascript/api-reference/interfaces/decoded-barcode-element.md +++ b/programming/javascript/api-reference/interfaces/decoded-barcode-element.md @@ -23,7 +23,8 @@ interface DecodedBarcodeElement extends Core.RegionObjectElement { angle: number; moduleSize: number; confidence: number; - extendedBarcodeResults: Array + extendedBarcodeResults: Array; + eciSegments: Array } ``` + +## eciValue + +The ECI assignment number as defined by ISO/IEC 15424. + +```typescript +eciValue: number; +``` + +## charsetEncoding + +The charset encoding name as defined by IANA (e.g., `"UTF-8"`, `"ISO-8859-1"`). + +```typescript +charsetEncoding: string; +``` + +## startIndex + +The start index of this ECI segment in the decoded barcode bytes. + +```typescript +startIndex: number; +``` + +## length + +The length in bytes of this segment within the decoded barcode bytes. + +```typescript +length: number; +``` + +**See also** + +* [BarcodeResultItem]({{ site.js_api }}interfaces/barcode-result-item.html) + +**Remarks** + +New added in CaptureVisionBundle version 3.4.2000 & BarcodeReaderBundle version 11.4.2000. \ No newline at end of file diff --git a/programming/javascript/api-reference/interfaces/pdf417-details.md b/programming/javascript/api-reference/interfaces/pdf417-details.md index 482196e1..f181cd76 100644 --- a/programming/javascript/api-reference/interfaces/pdf417-details.md +++ b/programming/javascript/api-reference/interfaces/pdf417-details.md @@ -18,7 +18,7 @@ interface PDF417Details extends BarcodeDetails { errorCorrectionLevel: number; hasLeftRowIndicator: number; hasRightRowIndicator: number; - codewords: Array; + codewords: Array; } ``` - + ``` ```bash # Or via npm -npm install dynamsoft-barcode-reader-bundle@11.2.4000 +npm install dynamsoft-barcode-reader-bundle@11.4.2000 ``` **Browser support:** Chrome 78+, Firefox 68+, Safari 14+, Edge 79+ (desktop and mobile). See [full system requirements](https://www.dynamsoft.com/faq/barcode-reader/web/capabilities/system-requirement.html). -## BarcodeScanner – One Line of Code +**License:** A built-in 24-hour trial license is used if no license is configured. For extended evaluation, [request a 30-day trial license](https://www.dynamsoft.com/customer/license/trialLicense?product=dbr&package=js). For production use, [contact sales](https://www.dynamsoft.com/company/contact/). -`BarcodeScanner` is a ready-to-use class that combines barcode decoding with camera control and UI—all in one. Add barcode scanning to your website with a single line of code: +## How to Integrate + +### Foundational API (Recommended) + +The **Foundational API** — centered on `CaptureVisionRouter` — is the primary and recommended way to use DBR-JS. ```js -new Dynamsoft.BarcodeScanner().launch().then(result=>alert(result.barcodeResults[0].text)); +// A built-in 24-hour trial license is used if no license is configured +// Create a camera view and connect it to the page +let cameraView = await Dynamsoft.DCE.CameraView.createInstance(); +document.querySelector("#camera-view-container").append(cameraView.getUIElement()); +let cameraEnhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance(cameraView); + +// Set up the barcode reading pipeline +const router = await Dynamsoft.CVR.CaptureVisionRouter.createInstance(); +router.setInput(cameraEnhancer); +router.addResultReceiver({ + onDecodedBarcodesReceived: (result) => { + for (const item of result.barcodeResultItems) { + console.log(item.text); + } + } +}); + +// Start scanning +await cameraEnhancer.open(); +await router.startCapturing("ReadSingleBarcode"); ```

          - Try it live on JSFiddle → + Try it live on JSFiddle →

          -> [!NOTE] -> The above uses a public trial license. For production, [get your own 30-day FREE trial license](https://www.dynamsoft.com/customer/license/trialLicense?product=dbr&package=js) and pass it via `new Dynamsoft.BarcodeScanner({license: "YOUR_LICENSE_KEY"})`. +**Why the Foundational API?** It gives you full control over the entire capture pipeline: decoding, camera management, result filtering, UI, and seamless integration with other Dynamsoft products. + +- **Modular and extensible** – Start with barcode reading, then plug in document detection, label recognition, or ID parsing without re-architecting +- **Full customization** – Control camera input, processing logic, scan region, UI, and output handling to match your exact use case +- **High performance** – Shared computation across components enables real-time processing even in multi-step workflows +- **Intermediate result access** – Inspect and react to in-progress data for validation, feedback, or adaptive processing + +The Foundational API also supports decoding from static images — no camera required: + +```js +const router = await Dynamsoft.CVR.CaptureVisionRouter.createInstance(); +const result = await router.capture("PATH-TO-YOUR-IMAGE", "ReadBarcodes_Default"); +for (const item of result.items) { + console.log(item.text); +} +``` + +### BarcodeScanner (Official Simplified Wrapper) -That's it. The `BarcodeScanner` class handles everything: +`BarcodeScanner` is an official simplified wrapper built on top of the Foundational API. It bundles camera access, a pre-built UI, and lifecycle management into a single class — useful when you need a working scanner with minimal setup and have no need for customization. -- **Camera access** – Automatic device selection, permissions, and video streaming -- **UI rendering** – Built-in viewfinder with scan region highlighting -- **Lifecycle management** – Start, pause, resume, and cleanup handled for you +```js +new Dynamsoft.BarcodeScanner().launch().then(result => alert(result.barcodeResults[0].text)); +``` -This is the recommended way to use DBR-JS for most applications. For advanced use cases requiring custom UI or integration with other Dynamsoft products, there's also a lower-level Foundational API. +

          + Try it live on JSFiddle → +

          -## Next Step +> [!IMPORTANT] +> **Roadmap notice:** `BarcodeScanner` is officially maintained and fully supported throughout **v11** with no planned breaking changes. Starting from **v12**, it will no longer be bundled as part of the DBR-JS product but will continue to be maintained as an official wrapper, which is distributed as a separate package. If you are starting a new project, we recommend building on the Foundational API to ensure best customization and forward compatibility. -| Approach | Best For | Guide | -|----------|----------|-------| -| **Quick Start** | Most users – get scanning in minutes with built-in UI | [BarcodeScanner Guide](user-guide/index.html) | -| **Full Control** | Custom UI, multi-product workflows, or advanced tuning | [Foundational API Guide](user-guide/foundational-api.html) | +## Next Steps -Not sure which to choose? Start with BarcodeScanner – you can always switch later. Or [contact us](https://www.dynamsoft.com/contact/) to discuss your use case. +- **Get started** → [Foundational API Guide](user-guide/index.html) — full walkthrough from setup to first scan +- **Use in a framework** → [React / Vue / Angular integration](user-guide/use-in-framework.html) +- **Explore samples** → [Official samples and demos](samples-demos/) +- **Upgrading?** → [Migration guide from v10 to v11](upgrade-guide/10to11.html) -## See Also +**Reference:** -- [BarcodeScanner API Reference](api-reference/barcode-scanner.html) -- [Samples and Demos](samples-demos/) +- [Foundational API Reference](api-reference/index.html) +- [BarcodeScanner Wrapper Guide](https://github.com/Dynamsoft/barcode-scanner-javascript/blob/main/docs/user-guide.md) - [Release Notes](release-notes/) diff --git a/programming/javascript/migrate-from-v10/index.md b/programming/javascript/migrate-from-v10/index.md index d8c2d6df..5adc283e 100644 --- a/programming/javascript/migrate-from-v10/index.md +++ b/programming/javascript/migrate-from-v10/index.md @@ -26,7 +26,7 @@ needAutoGenerateSidebar: true To use version 11, include the following script in your HTML: ```html - + ``` ## APIs changes introduced in v11 diff --git a/programming/javascript/release-notes/index.md b/programming/javascript/release-notes/index.md index 59d83f74..279216c7 100644 --- a/programming/javascript/release-notes/index.md +++ b/programming/javascript/release-notes/index.md @@ -9,6 +9,7 @@ breadcrumbText: Release Notes # DBR JavaScript SDK - Release Notes +- [11.4.2000 (04/16/2026)](js-11.html#1142000-04212026) - [11.2.4000 (11/11/2025)](js-11.html#1124000-11112025) - [11.2.2000 (11/04/2025)](js-11.html#1122000-11042025) - [11.0.6000 (08/14/2025)](js-11.html#1106000-08142025) diff --git a/programming/javascript/release-notes/js-11.md b/programming/javascript/release-notes/js-11.md index 14ea5641..74bda10e 100644 --- a/programming/javascript/release-notes/js-11.md +++ b/programming/javascript/release-notes/js-11.md @@ -10,6 +10,98 @@ noTitleIndex: true # Release Notes for Dynamsoft Barcode Reader JavaScript SDK +## 11.4.2000 (04/21/2026) + +### ⚠️ Roadmap notice: Foundational API Becomes Primary + +Starting with this release, the **Foundational API** (`CaptureVisionRouter` and related classes) is officially the primary and recommended integration path for DBR-JS. `BarcodeScanner` transitions to the role of an **officially maintained simplified wrapper**. + +**What this means in practice:** + +- **v11 (current)** – No breaking changes. `BarcodeScanner` continues to work exactly as before and will receive maintenance updates and bug fixes for the entire v11 lifecycle. +- **v12 (future)** – `BarcodeScanner` will no longer be bundled as part of the main `dynamsoft-barcode-reader-bundle` package. It will be distributed separately but will still be officially supported. + +**Why this change:** + +- **Foundational scales; the wrapper doesn't.** When projects move beyond basic demos — integrating other DCV components (document detection, label recognition), or building production workflows — `BarcodeScanner` hits a wall. Developers may end up rebuilding on the Foundational API. +- **One clear path, not two.** Two parallel API surfaces create confusion at evaluation time — for developers and for the AI coding assistants they increasingly use. A single recommended path simplifies onboarding. +- **AI tools close the boilerplate gap.** Much of `BarcodeScanner`'s value was fewer lines of code. With AI-assisted coding now common, developers can scaffold Foundational API code just as quickly. + +**Recommended action for new projects:** Build on the Foundational API to ensure forward compatibility. See the [Foundational API Guide](../user-guide/index.html) for a full walkthrough. + +**Existing projects using `BarcodeScanner`:** The wrapper will continue to receive long-term support. No action required for v11. When v12 is released, a guide will be provided for migrating to the Foundational API or continuing to use the wrapper. + +### Highlights + +#### AI-Powered Barcode Detection and Decoding + +- **PDF417 Localization Model** – Introduces the [`PDF417Localization`]({{ site.dcvb_parameters }}barcode-reader-task-settings/localization-modes.html#modelnamearray) neural network model for improved detection of PDF417 barcodes, especially under challenging conditions. + +- **Code39/ITF Decoding Model** – Adds the [`Code39ITFDecoder`]({{ site.dcvb_parameters }}barcode-reader-task-settings/deblur-modes.html#modelnamearray) model for enhanced decoding of Code 39 and ITF barcodes under blurred or low-resolution conditions. + +- **Deblur Models for 2D Barcodes** – Adds the [`DataMatrixQRCodeDeblur`]({{ site.dcvb_parameters }}barcode-reader-task-settings/deblur-modes.html#modelnamearray) and [`PDF417Deblur`]({{ site.dcvb_parameters }}barcode-reader-task-settings/deblur-modes.html#modelnamearray) models to provide more effective recovery from motion and focus blur for DataMatrix, QR Code, and PDF417 barcodes. + +#### ECI (Extended Channel Interpretation) Support + +- **ECI Information Return** – Adds support for retrieving Extended Channel Interpretation (ECI) data from barcodes. The new [`ECISegment`]({{ site.js_api }}/interfaces/eci-segment.html) interface, along with the `eciSegments` property in the [`BarcodeResultItem`]({{ site.js_api }}/interfaces/barcode-result-item.html#ecisegments) and [`DecodedBarcodeElement`]({{ site.js_api }}/interfaces/decoded-barcode-element.html#ecisegments) interfaces, enables access to character encoding information embedded in barcodes. + +- **ECI-Based Text Interpretation** – Adds support for interpreting ECI segments during barcode decoding, improving compatibility with international character sets. + +#### Performance Improvements + +- **On-Demand Model Loading** – Implements lazy loading for AI models, reducing initialization time by loading models only when first needed. + +- **Smart Model Selection** – Models are now loaded based on configured barcode formats, minimizing memory usage by excluding unused models. + +- **Improved Confidence Scoring** – Enhances confidence score calculation for results from neural network models, providing more accurate quality indicators. + +- **DPM Barcode Optimization** – Improves recognition rate for Direct Part Marking (DPM) barcodes commonly used in industrial and manufacturing environments. + +### API Changes + +#### New + +- Added [`BarcodeZoneWidthToHeightRatioRangeArray`]({{ site.dcvb_parameters }}barcode-format-specification/barcode-zone-width-to-height-ratio-range-array.html) parameter for filtering barcodes based on aspect ratio constraints. + +- Added [`SetResultCrossVerificationCriteria()`]({{ site.dcvb_js_api }}utility/multi-frame-result-cross-filter.html#setresultcrossverificationcriteria) and [`GetResultCrossVerificationCriteria()`]({{ site.dcvb_js_api }}utility/multi-frame-result-cross-filter.html#getresultcrossverificationcriteria) methods to `MultiFrameResultCrossFilter` for configurable multi-frame result verification. + +- Added [`AuxiliaryRegionElement`]({{ site.dcvb_js_api }}core/intermediate-results/auxiliary-region-element.html) class for representing additional region information detected during processing (e.g., MRZ (Machine Readable Zone), portrait zones). + +- Added `ROET_AUXILIARY_REGION` to [`RegionObjectElementType`]({{ site.dcvb_js_api }}core/enum-region-object-element-type.html) enumeration for the new `AuxiliaryRegionElement` class. + +#### Changed + +- Barcode text encoding fallback changed from UTF-8 to ISO-8859-1 when no ECI information is present in the barcode. + +- All methods under the [`ImageProcessor`]({{ site.dcvb_js_api }}utility/image-processor.html) class now additionally accept [`DSImageData`]({{ site.dcvb_js_api }}core/basic-structures/ds-image-data.html) as an image input type. + +- All methods under the [`ImageIO`]({{ site.dcvb_js_api }}utility/image-io.html), [`ImageProcessor`]({{ site.dcvb_js_api }}utility/image-processor.html), and [`ImageDrawer`]({{ site.dcvb_js_api }}utility/image-drawer.html) classes have been changed to static methods. + +- [`CodeParserModule.loadSpec()`]({{ site.dcp_js_api }}code-parser-module-class.html#loadspec) now returns a `Promise` instead of `void`. + +- Updated default value of `compensation` parameter in [`convertToBinaryLocal()`]({{ site.dcvb_js_api }}utility/image-processor.html#converttobinarylocal) from 0 to 10. + +- [`convertToBinaryGlobal()`]({{ site.dcvb_js_api }}utility/image-processor.html#converttobinaryglobal) and [`convertToBinaryLocal()`]({{ site.dcvb_js_api }}utility/image-processor.html#converttobinarylocal) of `ImageProcessor` class now support color, binary and grayscale images as input. + +- Parser resource files (.json) have been consolidated into encrypted .data files for improved security and simplified distribution: + - `AADHAAR.data`, `AAMVA_DL_ID.data`, `GS1_AI.data`, `MRTD.data`, `SOUTH_AFRICA_DL.data`, `VIN.data` + +- `CameraEnhancer.open()` now returns `Promise` when operating in `singleFrameMode`. + +#### Removed + +- Removed `DataMatrixModuleIsotropic` parameter – use [`BarcodeZoneWidthToHeightRatioRangeArray`]({{ site.dcvb_parameters }}barcode-format-specification/barcode-zone-width-to-height-ratio-range-array.html) instead. + +- Removed `MinRatioOfBarcodeZoneWidthToHeight` parameter – use [`BarcodeZoneWidthToHeightRatioRangeArray`]({{ site.dcvb_parameters }}barcode-format-specification/barcode-zone-width-to-height-ratio-range-array.html) instead. + +### Fixed + +- Fixed incorrect coordinate in barcode result when using neural network models with a specified region. + +- Fixed crash and hang issues that could occur in certain scenarios. + +- Fixed various minor bugs and improved overall stability. + ## 11.2.4000 (11/11/2025) ### Fixed @@ -18,7 +110,7 @@ noTitleIndex: true ## 11.2.2000 (11/04/2025) -### ✨ Key Highlights +### Highlights #### AI-Powered Barcode Detection and Decoding - New Localization Models – Introduces [`OneDLocalization`]({{ site.dcvb_parameters }}barcode-reader-task-settings/localization-modes.html#modelnamearray) and [`DataMatrixQRCodeLocalization`]({{ site.dcvb_parameters }}barcode-reader-task-settings/localization-modes.html#modelnamearray) neural network models for improved detection of **blurred / low-resolution 1D codes**, or **partially damaged DataMatrix/QR codes**. @@ -40,17 +132,9 @@ noTitleIndex: true ### Developer Notes -- Backward Compatibility – Fully compatible with existing integrations; no code-level changes required for upgrade. -- Configuration Flexibility – Expanded parameter set allows comprehensive model configuration for scenario-specific tuning. -- Production Stability – All new models validated in enterprise environments. - -#### Updates for [BarcodeScanner](https://dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/barcode-scanner.html) - -- In **single** mode, if the target barcode is not found among the candidates, there is now an opportunity to rescan. - -- Fixed an issue where the barcode location could be inaccurate in certain cases. -- Fixed a problem where, in specific cases when the camera was occupied, the video stream could not be displayed correctly. -- Other known issues fixed. +- **Backward Compatibility** – Fully compatible with existing integrations; no code-level changes required for upgrade. +- **Configuration Flexibility** – Expanded parameter set allows comprehensive model configuration for scenario-specific tuning. +- **Production Stability** – All new models validated in enterprise environments. #### Engineering Optimizations @@ -77,7 +161,15 @@ noTitleIndex: true #### Deprecated - Deprecated the `DeblurModelNameArray` argument in the `DeblurModes` parameter. Use `ModelNameArray` instead. -- Deprecated the `appendModelBuffer()` method in the `CaptureVisionRouter` class. Use `appendDLModelBuffer()` instead. +- Deprecated the `appendModelBuffer()` method in the `CaptureVisionRouter` class. Use `appendDLModelBuffer()` instead. + +#### BarcodeScanner Wrapper Updates + +- In **single** mode, if the target barcode is not found among the candidates, there is now an opportunity to rescan. + +- Fixed an issue where the barcode location could be inaccurate in certain cases. +- Fixed a problem where, in specific cases when the camera was occupied, the video stream could not be displayed correctly. +- Other known issues fixed. ## 11.0.6000 (08/14/2025) @@ -93,7 +185,7 @@ noTitleIndex: true ### Changed -- License Validation Behavior: Instead of stopping execution immediately on an invalid license module, the library now continues processing and returns results from modules with valid licenses. An warning is still reported to indicate the license issue. +- License Validation Behavior: Instead of stopping execution immediately on an invalid license module, the library now continues processing and returns results from modules with valid licenses. A warning is still reported to indicate the license issue. ### Fixed @@ -122,7 +214,7 @@ noTitleIndex: true - Simplified the loading and configuration of WASM resources, reducing the overall size of the WASM files. -#### Updates for [BarcodeScanner](https://dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/barcode-scanner.html) +#### BarcodeScanner Wrapper Updates - Added several new UI controls (not displayed by default). diff --git a/programming/javascript/user-guide/assets/1103000_new_control_components.png b/programming/javascript/user-guide/assets/1103000_new_control_components.png deleted file mode 100644 index a81c754f..00000000 Binary files a/programming/javascript/user-guide/assets/1103000_new_control_components.png and /dev/null differ diff --git a/programming/javascript/user-guide/assets/barcodeScanner_multiple_mode.png b/programming/javascript/user-guide/assets/barcodeScanner_multiple_mode.png deleted file mode 100644 index 9896503c..00000000 Binary files a/programming/javascript/user-guide/assets/barcodeScanner_multiple_mode.png and /dev/null differ diff --git a/programming/javascript/user-guide/assets/barcodeScanner_single_mode.png b/programming/javascript/user-guide/assets/barcodeScanner_single_mode.png deleted file mode 100644 index e30803dd..00000000 Binary files a/programming/javascript/user-guide/assets/barcodeScanner_single_mode.png and /dev/null differ diff --git a/programming/javascript/user-guide/assets/resultView.png b/programming/javascript/user-guide/assets/resultView.png deleted file mode 100644 index 1c62e74a..00000000 Binary files a/programming/javascript/user-guide/assets/resultView.png and /dev/null differ diff --git a/programming/javascript/user-guide/assets/scannerView.png b/programming/javascript/user-guide/assets/scannerView.png deleted file mode 100644 index 72ababff..00000000 Binary files a/programming/javascript/user-guide/assets/scannerView.png and /dev/null differ diff --git a/programming/javascript/user-guide/assets/scannerView1103000.png b/programming/javascript/user-guide/assets/scannerView1103000.png deleted file mode 100644 index dcda4084..00000000 Binary files a/programming/javascript/user-guide/assets/scannerView1103000.png and /dev/null differ diff --git a/programming/javascript/user-guide/assets/updateBarcodeFormat.png b/programming/javascript/user-guide/assets/updateBarcodeFormat.png deleted file mode 100644 index 49b91012..00000000 Binary files a/programming/javascript/user-guide/assets/updateBarcodeFormat.png and /dev/null differ diff --git a/programming/javascript/user-guide/barcode-scanner-customization.md b/programming/javascript/user-guide/barcode-scanner-customization.md deleted file mode 100644 index a5fd8701..00000000 --- a/programming/javascript/user-guide/barcode-scanner-customization.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -layout: default-layout -needAutoGenerateSidebar: true -needGenerateH3Content: true -noTitleIndex: true -title: Customizations - Dynamsoft Barcode Scanner v11.2.4000 JavaScript Edition -keywords: Documentation, Barcode Scanner, Dynamsoft Barcode Scanner JavaScript Edition, customization -description: Dynamsoft Barcode Scanner customization ---- - -# Customize Your BarcodeScanner - -- [Specify the barcode format](#specify-the-barcode-format) -- [Use customized template](#use-customized-template) -- [Configure the pre-built UIs](#configure-the-pre-built-uis) -- [Use BarcodeScanner in frameworks](#use-barcodescanner-in-frameworks) - -## Specify the barcode format - -Specifying the target barcode formats not only speeds up the recognition process but also improves accuracy. This is one of the most common customization needs. BarcodeScanner provides two ways to specify the barcode formats. For example, if your target formats are `QR_CODE` and `CODE_128`: - -> [!NOTE] -> See [all supported barcode formats](https://dynamsoft.com/barcode-reader/barcode-types/). - -### Option 1: Set via BarcodeScannerConfig - -Add the following configuration in [`BarcodeScannerConfig`]({{ site.js_api }}barcode-scanner.html#barcodescannerconfig): - -```js -const barcodeScanner = new Dynamsoft.BarcodeScanner({ - // ... - barcodeFormats:[Dynamsoft.DBR.EnumBarcodeFormat.BF_QR_CODE , Dynamsoft.DBR.EnumBarcodeFormat.BF_CODE_128], - // ... -}); -``` - -### Option 2: Specify in a template file - -The benefit of this approach is that the template file can be reused across different platforms or programming languages, ensuring performance consistency across scenarios. To do this, follow these steps: - -1. Open `dist\DBR-PresetTemplates.json` in your code editor. This file contains all the preset templates related to barcode reading. - -2. Add the `BarcodeFormatIds` to the `BarcodeReaderTaskSettingOptions` object. - -3. Update `BarcodeFormatIds` as shown below. You can get barcode format strings [here](https://www.dynamsoft.com/capture-vision/docs/core/enums/barcode-reader/barcode-format.html). - -description - -Refer to [`Use customized template`](#use-customized-template) for more details. - -> [!IMPORTANT] -> Due to the powerful customization capabilities, the number of configurable parameters in the templates is extensive and relatively complex. Feel free to [contact us](https://www.dynamsoft.com/contact/) if you need help creating a custom template. - -## Use customized template - -In more complex scenarios—such as blurred, damaged, curved, or unevenly lit barcodes—you might need a custom template to perform specific image processing steps. BarcodeScannerConfig provides a property to load a template file, allowing you to customize the algorithm's processing workflow. - -> [!WARNING] -> This operation will overwrite the built-in templates. - -```js - const barcodeScannerConfig = { - // The path to your custom JSON template that defines the scanning process. - templateFilePath: 'path/to/DBR-PresetTemplates.json' - }; - // Initialize the BarcodeScanner with the above BarcodeScannerConfig object - const barcodeScanner = new Dynamsoft.BarcodeScanner(barcodeScannerConfig); -``` - -## Configure the Pre-built UIs - -The built-in UI of `BarcodeScanner` is composed of `BarcodeScannerView` and `BarcodeResultView`. In `MULTI_UNIQUE` mode, `BarcodeResultView` is shown by default to ensure the essential workflow can proceed. Other UI components can be shown or hidden manually through `barcodeScannerConfig`. Let's break down these two Views: - -### BarcodeScannerView - -The `BarcodeScannerView` is composed of the following UI elements: - -description - -1. **Camera View**: The Camera View is the camera viewfinder UI component within the `BarcodeScannerView`. This viewfinder occupies the majority of the space within the `BarcodeScannerView` to give the user a clear view and precise control of the image being scanned. - -2. **Load Image Button**: This button allows the user to scan a file of a barcode-containing image from the device's local storage. You can decide whether to show or hide the button by [showUploadImageButton]({{ site.js_api }}barcode-scanner.html#showuploadimagebutton) property. - -3. **Close Scanner Button**: This button closes the Barcode Scanner, returns a [`BarcodeScanResult`]({{ site.js_api }}barcode-scanner.html#barcodescanresult) object and destroys the **`BarcodeScanner`** instance. You can decide whether to show or hide the button by [showCloseButton]({{ site.js_api }}barcode-scanner.html#showclosebutton) property. - -4. **Flash Button**: This button allows the user to toggle the camera's torch. You can decide whether to show or hide the button by [showFlashButton]({{ site.js_api }}barcode-scanner.html#showflashbutton) property. - -5. **Camera Switch Button**: This button allows the users to change between cameras. You can specify the mode and visibility of the camera switch control by [cameraSwitchControl]({{ site.js_api }}barcode-scanner.html#cameraswitchcontrol) property. - -### BarcodeResultView (MULTI_UNIQUE mode only) - -Here is a quick breakdown of the `MULTI_UNIQUE` UI elements of the `BarcodeResultView` view: - -description - -1. **Barcode Results List**: The list used to display the decoding results.The list is updated whenever a new barcode is successfully decoded, or the same code is detected again after a specific [duplicateForgetTime]({{ site.js_api }}barcode-scanner.html#duplicateforgettime). - -2. **Clear Button**: The button on the bottom left, which clears all elements of the current `Barcode Results List`. You can change the style of the Button with [BarcodeResultViewToolbarButtonsConfig]({{ site.js_api }}barcode-scanner.html#barcoderesultviewtoolbarbuttonsconfig). - -3. **Done Button**: The button on the bottom right, which closes the Barcode Scanner, returns a [`BarcodeScanResult`]({{ site.js_api }}barcode-scanner.html#barcodescanresult) object that includes all unique barcodes and destroys the **`BarcodeScanner`** instance. You can change the style of the Button with [BarcodeResultViewToolbarButtonsConfig]({{ site.js_api }}barcode-scanner.html#barcoderesultviewtoolbarbuttonsconfig). - -### Manually modify the UI file - -Another way to fully customize the UI is by directly editing the `.xml` file. In the `dist/ui/` directory, you'll find the `barcode-scanner.ui.xml` file, which is the default UI for the `BarcodeScanner`. - -> [!NOTE] -> Although it is essentially HTML, using a .xml extension can help prevent compatibility issues with the Live Server plugin. - -You can make a copy of it and apply your own modifications. For example, to double the size of the `UploadImage` icon, you can edit the file like this: - -```xml - -``` - -Once you've made your changes, just set the new `uiPath` in the configuration. If everything is configured correctly, the updated UI will appear the next time you refresh the page. - -```js - const barcodeScanner = new Dynamsoft.BarcodeScanner({ - //... - uiPath: "path/to/new-barcode-scanner.ui.xml?v=", - //... - }); -``` - -## Use BarcodeScanner in frameworks - -Integrating `BarcodeScanner` into frameworks like `Angular`, `React`, and `Vue` is a little different compared to native usage. You can also refer to [the ready-made samples for popular frameworks](https://github.com/Dynamsoft/barcode-reader-javascript-samples/tree/main/frameworks) directly without reading this guide. - -### Installation - -Open the terminal from your project root and install **Dynamsoft Barcode Reader SDK** with the following command: - -```sh -npm install dynamsoft-barcode-reader-bundle@11.2.4000 -E -``` - -### Component for video decoding - -Here's how to quickly set up a video barcode scanner using the `BarcodeScanner` class: - -```ts - const config = { - license: "YOUR-LICENSE-KEY", // Replace with your license key - } - const barcodeScanner = new BarcodeScanner(config); - barcodeScanner.launch().then((result)=>{ - console.log(result); // Handle the decoding result here - }); -``` - -#### Define the resource paths - -To ensure stability, especially in environments with limited internet access, it's a good idea to **host all required resources locally** (e.g., under the dist/ folder). -Below is an example using the official CDN — feel free to replace it with your own path: - -```ts - const config = { - license: "YOUR-LICENSE-KEY", - // Configures the paths where the .wasm files and other necessary resources for modules are located. - engineResourcePaths: { - // Using jsDelivr CDN as an example - rootDirectory: "https://cdn.jsdelivr.net/npm/", - }, - // Path to the UI (.xml template file). - uiPath: "https://cdn.jsdelivr.net/npm/dynamsoft-barcode-reader-bundle@11.2.4000/dist/ui/barcode-scanner.ui.xml", - }; -``` - -#### Set up the video container - -Specify the container where the scanner UI should be rendered: - -```ts - const config = { - container: ".barcode-scanner-view", // CSS selector for the scanner container - }; -``` - -Make sure your HTML includes the corresponding element: - -```html -
          -``` - -The above steps cover the key considerations when using the `BarcodeScanner` component within a modern JavaScript framework. To recap: - -- Install the SDK with an exact version to avoid compatibility issues. - -- Define resource paths explicitly — either via CDN or local dist/ folder — to ensure consistent loading behavior. - -- Configure and launch the scanner using the provided component API. - -- Set up a container element to properly display the scanner UI. - -By following these best practices, you'll ensure a stable and reliable integration of `BarcodeScanner` into your application. \ No newline at end of file diff --git a/programming/javascript/user-guide/explore-features/index.md b/programming/javascript/user-guide/explore-features/index.md index 80b53564..3532bce8 100644 --- a/programming/javascript/user-guide/explore-features/index.md +++ b/programming/javascript/user-guide/explore-features/index.md @@ -14,7 +14,7 @@ permalink: /programming/javascript/user-guide/explore-features/index.html Once you have got an application running with Dynamsoft Barcode Reader JavaScript edition, you can explore the many features of the SDK to see how to make the best out of the SDK. -> If you are just getting started with Dynamsoft Barcode Reader JavaScript Edition, we recommend that you read the [BarcodeScanner User Guide](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/user-guide/index.html) first. + ## Basic Features diff --git a/programming/javascript/user-guide/foundational-api.md b/programming/javascript/user-guide/foundational-api.md deleted file mode 100644 index dd8b72f8..00000000 --- a/programming/javascript/user-guide/foundational-api.md +++ /dev/null @@ -1,762 +0,0 @@ ---- -layout: default-layout -title: Foundational API Guide - Dynamsoft Barcode Reader JavaScript Edition -description: This is the foundational API guide for advanced customization of Dynamsoft Barcode Reader JavaScript SDK. -keywords: user guide, foundational api, javascript, js, advanced -breadcrumbText: Foundational API -noTitleIndex: true -needGenerateH3Content: true -needAutoGenerateSidebar: true -schema: schemas/dynamsoft-facilitates-mit-research-schema.json ---- - - - - - -> [!IMPORTANT] -> **Looking for the quickest way to add barcode scanning?** Most developers should use the [BarcodeScanner API](index.html) which provides a complete solution with just a few lines of code. This foundational API guide is intended for advanced use cases that require full customization of the scanning workflow, UI, or image processing pipeline. - -# Barcode Reader for Your Website - Foundational API Guide - -[Dynamsoft Barcode Reader JavaScript Edition](https://www.dynamsoft.com/barcode-reader/sdk-javascript/) (DBR-JS) is equipped with industry-leading algorithms for exceptional speed, accuracy and read rates in barcode reading. Using its well-designed API, you can turn your web page into a barcode scanner with just a few lines of code. Once the DBR-JS SDK gets integrated into your web page, your users can access a camera via the browser and read barcodes directly from its video input. - - - -In this guide, you will learn step by step on how to integrate the DBR-JS SDK into your website. - -Table of Contents - -- [Barcode Reader for Your Website - Foundational API Guide](#barcode-reader-for-your-website---foundational-api-guide) - - [Hello World - Simplest Implementation](#hello-world---simplest-implementation) - - [Understand the code](#understand-the-code) - - [About the code](#about-the-code) - - [Run the example](#run-the-example) - - [Preparing the SDK](#preparing-the-sdk) - - [Step 1: Include the SDK](#step-1-include-the-sdk) - - [Step 2: Prepare the SDK](#step-2-prepare-the-sdk) - - [1. Specify the license](#1-specify-the-license) - - [2. \[Optional\] Specify the location of the "engine" files](#2-optional-specify-the-location-of-the-engine-files) - - [Using the SDK](#using-the-sdk) - - [Step 1: Preload the module](#step-1-preload-the-module) - - [Step 2: Create a CaptureVisionRouter object](#step-2-create-a-capturevisionrouter-object) - - [Step 3: Connect an image source](#step-3-connect-an-image-source) - - [Step 4: Register a result receiver](#step-4-register-a-result-receiver) - - [Step 5: Start process video frames](#step-5-start-process-video-frames) - - [Customizing the process](#customizing-the-process) - - [1. Adjust the preset template settings](#1-adjust-the-preset-template-settings) - - [1.1. Change barcode settings](#11-change-barcode-settings) - - [1.2. Retrieve the original image](#12-retrieve-the-original-image) - - [1.3. Change reading frequency to save power](#13-change-reading-frequency-to-save-power) - - [1.4. Specify a scan region](#14-specify-a-scan-region) - - [2. Edit the preset templates directly](#2-edit-the-preset-templates-directly) - - [3. \[Important\] Filter the results](#3-important-filter-the-results) - - [Method 1: Verify results across multiple frames](#method-1-verify-results-across-multiple-frames) - - [Method 2: Eliminate redundant results detected within a short time frame](#method-2-eliminate-redundant-results-detected-within-a-short-time-frame) - - [4. Add feedback](#4-add-feedback) - - [Customizing the UI](#customizing-the-ui) - - [Documentation](#documentation) - - [API Reference](#api-reference) - - [How to Upgrade](#how-to-upgrade) - - [Release Notes](#release-notes) - - [Next Steps](#next-steps) - - - -## Hello World - Simplest Implementation - -Let's start with the "Hello World" example of the DBR-JS SDK which demonstrates how to use the minimum code to enable a web page to read barcodes from a live video stream. - -**Basic Requirements** - - - Internet connection - - A supported browser - - Camera access - -> Please refer to [system requirements](https://www.dynamsoft.com/faq/barcode-reader/web/capabilities/system-requirement.html) for more details. - -### Understand the code - -The complete code of the "Hello World" example is shown below - -```html - - - -
          - - - - - -``` - -

          - - Code in Github - -   - - Run via JSFiddle - -   - - Run in Dynamsoft - -

          - -> Don't want to deal with too many details? You can get a quick start with the [BarcodeScanner >>](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/user-guide/index.html) -> ```js -> // Scan instantly with a single line of code! -> new Dynamsoft.BarcodeScanner().launch().then(result=>alert(result.barcodeResults[0].text)); -> ``` - ------ - -#### About the code - -- `Dynamsoft.License.LicenseManager.initLicense()`: This method initializes the license for using the SDK in the application. Note that the string "**DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9**" used in this example points to an online license that requires a network connection to work. Read more on [Specify the license](#1-specify-the-license). - -- `Dynamsoft.Core.CoreModule.loadWasm()`: This is an optional code. Used to load wasm resources in advance, reducing latency between video playing and barcode decoding. - -- `Dynamsoft.CVR.CaptureVisionRouter.createInstance()`: This method creates a `CaptureVisionRouter` object `cvRouter` which controls the entire process in three steps: - - **Retrieve Images from the Image Source** - - `cvRouter` connects to the image source through the [ImageSourceAdapter](https://www.dynamsoft.com/capture-vision/docs/core/architecture/input.html#image-source-adapter?lang=js) interface with the method `setInput()`. - ```js - cvRouter.setInput(cameraEnhancer); - ``` - > The image source in our case is a [CameraEnhancer](https://www.dynamsoft.com/camera-enhancer/docs/web/programming/javascript/user-guide/index.html) object created with `Dynamsoft.DCE.CameraEnhancer.createInstance(cameraView)` - - **Coordinate Image-Processing Tasks** - - The coordination happens behind the scenes. `cvRouter` starts the process by specifying a preset template "ReadSingleBarcode" in the method `startCapturing()`. - ```js - cvRouter.startCapturing("ReadSingleBarcode"); - ``` - - **Dispatch Results to Listening Objects** - - The processing results are returned through the [CapturedResultReceiver](https://www.dynamsoft.com/capture-vision/docs/core/architecture/output.html#captured-result-receiver?lang=js) interface. The `CapturedResultReceiver` object is registered to `cvRouter` via the method `addResultReceiver()`. For more information, please check out [Register a result receiver](#step-4-register-a-result-receiver). - ```js - cvRouter.addResultReceiver({/*The-CapturedResultReceiver-Object"*/}); - ``` - - Also note that reading from video is extremely fast and there could be many duplicate results. We can use a [filter](#3-important-filter-the-results) with result deduplication enabled to filter out the duplicate results. The object is registered to `cvRouter` via the method `addResultFilter()`. - ```js - cvRouter.addResultFilter(filter); - ``` - -> Read more on [Capture Vision Router](https://www.dynamsoft.com/capture-vision/docs/core/architecture/#capture-vision-router). - -### Run the example - -You can run the example deployed to [the Dynamsoft Demo Server](https://demo.dynamsoft.com/Samples/DBR/JS/hello-world/hello-world.html?ver=11.2.40&utm_source=guide) or test it with [JSFiddle code editor](https://jsfiddle.net/DynamsoftTeam/csm2f9wb/). - -You will be asked to allow access to your camera, after which the video will be displayed on the page. After that, you can point the camera at a barcode to read it. - -When a barcode is decoded, you will see the result text show up under the video and the barcode location will be highlighted in the video feed. - -Alternatively, you can test locally by copying and pasting the code shown above into a local file (e.g. "hello-world.html") and opening it in your browser. - -> *Secure Contexts*: -> -> If you open the web page as `http://` , our SDK may not work correctly because the [MediaDevices: getUserMedia()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia) and other methods only work in [secure contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) (HTTPS, `localhost`, `127.0.0.1`, `file://`), in some or all supporting browsers. -> -> Regarding configuring https on your server, these guides for [nginx](https://nginx.org/en/docs/http/configuring_https_servers.html) / [IIS](https://aboutssl.org/how-to-create-a-self-signed-certificate-in-iis/) / [tomcat](https://dzone.com/articles/setting-ssl-tomcat-5-minutes) / [nodejs](https://nodejs.org/docs/v0.4.1/api/tls.html) might help. -> -> If the test doesn't go as expected, you can [contact us](https://www.dynamsoft.com/company/contact/?ver=11.2.40&utm_source=guide&product=dbr&package=js). - -## Preparing the SDK - -### Step 1: Include the SDK - -
          - - -
          -
          Use a public CDN
          - -The simplest way to include the SDK is to use either the [jsDelivr](https://jsdelivr.com/) or [UNPKG](https://unpkg.com/) CDN. The "hello world" example above uses **jsDelivr**. - -- jsDelivr - - ```html - - ``` - -- UNPKG - - ```html - - ``` - - - -- In frameworks like React, Vue and Angular, you may want to add the package as a dependency. - - ```sh - npm i dynamsoft-barcode-reader-bundle@11.2.4000 -E - # or - yarn add dynamsoft-barcode-reader-bundle@11.2.4000 -E - ``` - - NOTE that in frameworks, you need to [specify the location of the engine files](#2-optional-specify-the-location-of-the-engine-files). -
          - -
          -
          Host the SDK yourself
          - -Besides using the public CDN, you can also download the SDK and host its files on your own server or a commercial CDN before including it in your application. - -- From the website - - [Download Dynamsoft Barcode Reader JavaScript Package](https://www.dynamsoft.com/barcode-reader/downloads/?ver=11.2.40&utm_source=guide&product=dbr&package=js) - - The resources are located at path `dynamsoft/distributables/@`. - -- From npm - - ```sh - npm i dynamsoft-barcode-reader-bundle@11.2.4000 -E - ``` - - The resources are located at the path `node_modules/`, without `@`. You must copy "dynamsoft-xxx" packages elsewhere and add `@`. The `` can be obtained from `package.json` of each package. Another thing to do is to [specify the engineResourcePaths](#2-optional-specify-the-location-of-the-engine-files) so that the SDK can correctly locate the resources. - > Since "node_modules" is reserved for Node.js dependencies, and in our case the package is used only as static resources, we recommend either renaming the "node_modules" folder or moving the "dynamsoft-" packages to a dedicated folder for static resources in your project to facilitate self-hosting. - -You can typically include SDK like this: - -```html - -``` -
          - -
          - -*Note*: - -* Certain legacy web application servers may lack support for the `application/wasm` mimetype for .wasm files. To address this, you have two options: - 1. Upgrade your web application server to one that supports the `application/wasm` mimetype. - 2. Manually define the mimetype on your server. You can refer to the guides for [apache](https://developer.mozilla.org/en-US/docs/Learn/Server-side/Apache_Configuration_htaccess#media_types_and_character_encodings) / [IIS](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/staticcontent/mimemap) / [nginx](https://www.nginx.com/resources/wiki/start/topics/examples/full/#mime-types). - -* To work properly, the SDK requires a few engine files, which are relatively large and may take quite a few seconds to download. We recommend that you set a longer cache time for these engine files, to maximize the performance of your web application. - - ``` - Cache-Control: max-age=31536000 - ``` - - Reference: [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control). - -### Step 2: Prepare the SDK - -Before using the SDK, you need to configure a few things. - -#### 1. Specify the license - -To enable the SDK's functionality, you must provide a valid license. Utilize the API function initLicense to set your license key. - -```javascript -Dynamsoft.License.LicenseManager.initLicense("DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9"); -``` - -As previously stated, the key "DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9" serves as a test license valid for 24 hours, applicable to any newly authorized browser. To test the SDK further, you can request a 30-day free trial license via the Request a Trial License link. - -> Upon registering a Dynamsoft account and obtaining the SDK package from the official website, Dynamsoft will automatically create a 30-day free trial license and embed the corresponding license key into all the provided SDK samples. - -#### 2. [Optional] Specify the location of the "engine" files - -This step is generally necessary when utilizing frameworks such as Angular, React, Vue, or when managing the hosting of resource files yourself. - -The purpose is to tell the SDK where to find the engine files (\*.worker.js, \*.wasm.js and \*.wasm, etc.). - -```ts -// in framework -import { CoreModule } from "dynamsoft-barcode-reader-bundle"; -CoreModule.engineResourcePaths.rootDirectory = "https://cdn.jsdelivr.net/npm/"; -``` -```js -// in pure js -Dynamsoft.Core.CoreModule.engineResourcePaths.rootDirectory = "https://cdn.jsdelivr.net/npm/"; -``` -These code uses the jsDelivr CDN as an example, feel free to change it to your own location. - -## Using the SDK - -### Step 1: Preload the module - -The image processing logic is encapsulated within .wasm library files, and these files may require some time for downloading. To enhance the speed, we advise utilizing the following method to preload the libraries. - -```js -// Preload the .wasm files -await Dynamsoft.Core.CoreModule.loadWasm(); -``` - -### Step 2: Create a CaptureVisionRouter object - -To use the SDK, we first create a `CaptureVisionRouter` object. - -```javascript -Dynamsoft.License.LicenseManager.initLicense("DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9"); - -let cvRouter = null; -try { - cvRouter = await Dynamsoft.CVR.CaptureVisionRouter.createInstance(); -} catch (ex) { - console.error(ex); -} -``` - -*Tip*: - -When creating a `CaptureVisionRouter` object within a function which may be called more than once, it's best to use a "helper" variable to avoid double creation such as `pCvRouter` in the following code: - -```javascript -Dynamsoft.License.LicenseManager.initLicense("DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9"); - -let pCvRouter = null; // The helper variable which is a promise of cvRouter -let cvRouter = null; - -document.getElementById('btn-scan').addEventListener('click', async () => { - try { - cvRouter = await (pCvRouter = pCvRouter || Dynamsoft.CVR.CaptureVisionRouter.createInstance()); - } catch (ex) { - console.error(ex); - } -}); -``` - -### Step 3: Connect an image source - -The `CaptureVisionRouter` object, denoted as `cvRouter`, is responsible for handling images provided by an image source. In our scenario, we aim to detect barcodes directly from a live video stream. To facilitate this, we initialize a `CameraEnhancer` object, identified as `cameraEnhancer`, which is specifically designed to capture image frames from the video feed and subsequently forward them to `cvRouter`. - -To enable video streaming on the webpage, we create a `CameraView` object referred to as `cameraView`, which is then passed to `cameraEnhancer`, and its content is displayed on the webpage. - -```html -
          -``` - -```javascript -let cameraView = await Dynamsoft.DCE.CameraView.createInstance(); -let cameraEnhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance(cameraView); -document.querySelector("#camera-view-container").append(cameraView.getUIElement()); -cvRouter.setInput(cameraEnhancer); -``` - -### Step 4: Register a result receiver - -Once the image processing is complete, the results are sent to all the registered `CapturedResultReceiver` objects. Each `CapturedResultReceiver` object may encompass one or multiple callback functions associated with various result types. This time we use `onDecodedBarcodesReceived`: - - -```javascript -const resultsContainer = document.querySelector("#results"); -const resultReceiver = new Dynamsoft.CVR.CapturedResultReceiver(); -resultReceiver.onDecodedBarcodesReceived = (result) => { - if (result.barcodeResultItems?.length) { - resultsContainer.textContent = ''; - for (let item of result.barcodeResultItems) { - // In this example, the barcode results are displayed on the page below the video. - resultsContainer.textContent += `${item.formatString}: ${item.text}\n\n`; - } - } -}; -cvRouter.addResultReceiver(resultReceiver); -``` - -You can also write code like this. It is the same. - -```javascript -const resultsContainer = document.querySelector("#results"); -cvRouter.addResultReceiver({ onDecodedBarcodesReceived: (result) => { - if (result.barcodeResultItems?.length) { - resultsContainer.textContent = ''; - for (let item of result.barcodeResultItems) { - // In this example, the barcode results are displayed on the page below the video. - resultsContainer.textContent += `${item.formatString}: ${item.text}\n\n`; - } - } -}}); -``` - -Check out [CapturedResultReceiver](https://www.dynamsoft.com/capture-vision/docs/web/programming/javascript/api-reference/capture-vision-router/captured-result-receiver.html) for more information. - -### Step 5: Start process video frames - -With the setup now complete, we can proceed to process the images in two straightforward steps: - -1. Initiate the image source to commence image acquisition. In our scenario, we invoke the `open()` method on `cameraEnhancer` to initiate video streaming and simultaneously initiate the collection of images. These collected images will be dispatched to `cvRouter` as per its request. -2. Define a preset template to commence image processing. In our case, we utilize the "ReadSingleBarcode" template, specifically tailored for processing images containing a single barcode. - -```javascript -await cameraEnhancer.open(); -await cvRouter.startCapturing("ReadSingleBarcode"); -``` - -*Note*: - -* `cvRouter` is engineered to consistently request images from the image source. -* Various preset templates are at your disposal for barcode reading: - -| Template Name | Function Description | -| ------------------------------ | -------------------------------------------------------------- | -| **ReadBarcodes_Default** | Scans multiple barcodes by default setting. | -| **ReadSingleBarcode** | Quickly scans a single barcode. | -| **ReadBarcodes_SpeedFirst** | Prioritizes speed in scanning multiple barcodes. | -| **ReadBarcodes_ReadRateFirst** | Maximizes the number of barcodes read. | -| **ReadBarcodes_Balance** | Balances speed and quantity in reading multiple barcodes. | -| **ReadDenseBarcodes** | Specialized in reading barcodes with high information density. | -| **ReadDistantBarcodes** | Capable of reading barcodes from extended distances. | - -Read more on the [preset CaptureVisionTemplates](https://www.dynamsoft.com/capture-vision/docs/web/programming/javascript/api-reference/capture-vision-router/preset-templates.html). - -## Customizing the process - -### 1. Adjust the preset template settings - -When making adjustments to some basic tasks, we often only need to modify [SimplifiedCaptureVisionSettings](https://www.dynamsoft.com/capture-vision/docs/web/programming/javascript/api-reference/capture-vision-router/interfaces/simplified-capture-vision-settings.html). - -#### 1.1. Change barcode settings - -The preset templates can be updated to meet different requirements. For example, the following code limits the barcode format to QR code. - -```javascript -let settings = await cvRouter.getSimplifiedSettings("ReadSingleBarcode"); -settings.barcodeSettings.barcodeFormatIds = Dynamsoft.DBR.EnumBarcodeFormat.BF_QR_CODE; -await cvRouter.updateSettings("ReadSingleBarcode", settings); -await cvRouter.startCapturing("ReadSingleBarcode"); -``` - -For a list of adjustable barcode settings, check out [SimplifiedBarcodeReaderSettings](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/interfaces/simplified-barcode-reader-settings.html) and [EnumBarcodeFormat](https://www.dynamsoft.com/capture-vision/docs/core/enums/barcode-reader/barcode-format.html?lang=js&product=dbr). - -#### 1.2. Retrieve the original image - -Additionally, we have the option to modify the template to retrieve the original image containing the barcode. - -```javascript -let settings = await cvRouter.getSimplifiedSettings("ReadSingleBarcode"); -settings.outputOriginalImage = true; -await cvRouter.updateSettings("ReadSingleBarcode", settings); -await cvRouter.startCapturing("ReadSingleBarcode"); -``` - -Limit the barcode format to QR code, and retrieve the original image containing the barcode, at the same time. - -```javascript -let settings = await cvRouter.getSimplifiedSettings("ReadSingleBarcode"); -settings.outputOriginalImage = true; -settings.barcodeSettings.barcodeFormatIds = Dynamsoft.DBR.EnumBarcodeFormat.BF_QR_CODE; -await cvRouter.updateSettings("ReadSingleBarcode", settings); -await cvRouter.startCapturing("ReadSingleBarcode"); -``` - -Please be aware that it is necessary to update the `CapturedResultReceiver` object to obtain the original image. For instance: - -```javascript -const EnumCRIT = Dynamsoft.Core.EnumCapturedResultItemType; // Enum for captured result item types. -// Create a result receiver to handle the results. -cvRouter.addResultReceiver({ - // This function is called when any capture result is received. - onCapturedResultReceived: (result) => { - //Check for barcode results - let barcodeResultItems = result.items.filter((item) => item.type === EnumCRIT.CRIT_BARCODE); - if (barcodeResultItems.length > 0) { - let image = result.items.filter((item) => item.type === EnumCRIT.CRIT_ORIGINAL_IMAGE)[0]?.imageData; // Retrieve the original image. - if (image) document.body.appendChild(image.toCanvas()); // Append the image to DOM. - for (let item of barcodeResultItems) { - // Print each barcode result to the console. - console.log(`Barcode: ${item.text}, Format: ${item.formatString}`); - } - } - }, -}); -``` - -#### 1.3. Change reading frequency to save power - -The SDK is initially configured to process images sequentially without any breaks. Although this setup maximizes performance, it can lead to elevated power consumption, potentially causing the device to overheat. In many cases, it's possible to reduce the reading speed while still satisfying business requirements. The following code snippet illustrates how to adjust the SDK to process an image every 500 milliseconds: - -> Please bear in mind that in the following code, if an image's processing time is shorter than 500 milliseconds, the SDK will wait for the full 500 milliseconds before proceeding to process the next image. Conversely, if an image's processing time exceeds 500 milliseconds, the subsequent image will be processed immediately upon completion. - -```javascript -let settings = await cvRouter.getSimplifiedSettings("ReadSingleBarcode"); -settings.minImageCaptureInterval = 500; -await cvRouter.updateSettings("ReadSingleBarcode", settings); -await cvRouter.startCapturing("ReadSingleBarcode"); -``` - -#### 1.4. Specify a scan region - -We can specify a scan region to allow the SDK to process only part of the image, improving processing speed. The code snippet below demonstrates how to do this using the `cameraEnhancer` image source. - -```javascript -cameraEnhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance(cameraView); -// In this example, we set the scan region to cover the central 25% of the image. -cameraEnhancer.setScanRegion({ - x: 25, - y: 25, - width: 50, - height: 50, - isMeasuredInPercentage: true, -}); -``` - -*Note*: - -1. By configuring the region at the image source, images are cropped before processing, removing the need to adjust any further processing settings. -2. `cameraEnhancer` enhances interactivity by overlaying a mask on the video, clearly marking the scanning region. - -*See Also*: - -[CameraEnhancer::setScanRegion](https://www.dynamsoft.com/camera-enhancer/docs/web/programming/javascript/api-reference/acquisition.html#setscanregion) - - - - - - -### 2. Edit the preset templates directly - -The preset templates have many more settings that can be customized to suit your use case best. If you [download the SDK from Dynamsoft website](https://www.dynamsoft.com/barcode-reader/downloads/1000003-confirmation/), you can find the templates under - -* "/dynamsoft-barcode-reader-js-11.2.4000/dist/templates/" - -Upon completing the template editing, you can invoke the `initSettings` method and provide it with the template path as an argument. - -```javascript -await cvRouter.initSettings("PATH-TO-THE-FILE"); // E.g. "https://your-website/ReadSingleBarcode.json") -await cvRouter.startCapturing("ReadSingleBarcode"); // Make sure the name matches one of the CaptureVisionTemplates in the template JSON file. -``` - -### 3. [Important] Filter the results - -When processing video frames, the same barcode is often detected multiple times. To improve the user experience, we can use the [MultiFrameResultCrossFilter](https://www.dynamsoft.com/capture-vision/docs/web/programming/javascript/api-reference/utility/multi-frame-result-cross-filter.html) object. This object provides two methods for handling duplicate detections, which can be used independently or together, depending on what best suits your application needs: - -#### Method 1: Verify results across multiple frames - -```js -let filter = new Dynamsoft.Utility.MultiFrameResultCrossFilter(); -filter.enableResultCrossVerification("barcode", true); -await cvRouter.addResultFilter(filter); -``` - -*Note*: - -* `enableResultCrossVerification` was designed to cross-validate the outcomes across various frames in a video streaming scenario, enhancing the reliability of the final results. This validation is particularly crucial for barcodes with limited error correction capabilities, such as 1D codes. - -#### Method 2: Eliminate redundant results detected within a short time frame - -```js -let filter = new Dynamsoft.Utility.MultiFrameResultCrossFilter(); -filter.enableResultDeduplication("barcode", true); -await cvRouter.addResultFilter(filter); -``` - -*Note*: - -* `enableResultDeduplication` was designed to prevent high usage in video streaming scenarios, addressing the repetitive processing of the same code within a short period of time. - -Initially, the filter is set to forget a result 3 seconds after it is first received. During this time frame, if an identical result appears, it is ignored. - -> It's important to know that in version 9.x or earlier, the occurrence of an identical result would reset the timer, thus reinitiating the 3-second count at that point. However, in version 10.2.10 and later, an identical result no longer resets the timer but is instead disregarded, and the duration count continues uninterrupted. - -Under certain circumstances, this duration can be extended with the method `setDuplicateForgetTime()`. - -```js -let filter = new Dynamsoft.Utility.MultiFrameResultCrossFilter(); -filter.setDuplicateForgetTime("barcode", 5000); // Extend the duration to 5 seconds. -await cvRouter.addResultFilter(filter); -``` - -You can also enable both options at the same time: - -```js -let filter = new Dynamsoft.Utility.MultiFrameResultCrossFilter(); -filter.enableResultCrossVerification("barcode", true); -filter.enableResultDeduplication("barcode", true); -filter.setDuplicateForgetTime("barcode", 5000); -await cvRouter.addResultFilter(filter); -``` - -### 4. Add feedback - -When a barcode is detected within the video stream, its position is immediately displayed within the video. Furthermore, utilizing the "Dynamsoft Camera Enhancer" SDK, we can introduce feedback mechanisms, such as emitting a "beep" sound or triggering a "vibration". - -The following code snippet adds a "beep" sound for when a barcode is found: - -```js -const resultReceiver = new Dynamsoft.CVR.CapturedResultReceiver(); -resultReceiver.onDecodedBarcodesReceived = (result) => { - if (result.barcodeResultItems.length > 0) { - Dynamsoft.DCE.Feedback.beep(); - } -}; -cvRouter.addResultReceiver(resultReceiver); -``` - -## Customizing the UI - -```javascript -// Create a CameraView instance with default settings -let cameraView = await Dynamsoft.DCE.CameraView.createInstance(); -// Create a CameraView instance with a specified HTML file path, typically a local or remote URL -let cameraView1 = await Dynamsoft.DCE.CameraView.createInstance('@engineResourcePath/dce.mobile-native.ui.html'); -// Create a CameraView instance within a specified DOM element -let cameraView2 = await Dynamsoft.DCE.CameraView.createInstance(document.getElementById('my-ui')); -// Create a CameraView instance using a custom UI file path -let cameraView3 = await Dynamsoft.DCE.CameraView.createInstance('url/to/my/ui.html'); - -// Get the UI element associated with the cameraView instance -let uiElement = cameraView.getUIElement(); -// Remove the camera selection dropdown from the CameraView's UI element -uiElement.shadowRoot.querySelector('.dce-sel-camera').remove(); -// Remove the resolution selection dropdown from the CameraView's UI element -uiElement.shadowRoot.querySelector('.dce-sel-resolution').remove(); -``` - -The UI is part of the auxiliary SDK "Dynamsoft Camera Enhancer", read more on how to [customize the UI](https://www.dynamsoft.com/barcode-reader/docs/core/programming/features/ui-customization-js.html?lang=js). - -## Documentation - -### API Reference - -You can check out the detailed documentation about the APIs of the SDK at -[https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/?ver=11.2.4000](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/?ver=11.2.4000). - - - -### How to Upgrade - -If you want to upgrade the SDK from an old version to a newer one, please see [how to upgrade](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/upgrade-guide/10to11.html). - -### Release Notes - -Learn about what are included in each release at [https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/release-notes/index.html](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/release-notes/index.html). - -## Next Steps - -Now that you have got the SDK integrated, you can choose to move forward in the following directions - -1. Learn how to [Use in Framework](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/user-guide/use-in-framework.html) -2. Check out the [Official Samples and Demo](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/samples-demos/index.html) -3. Learn about the [APIs of the SDK](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/index.html) diff --git a/programming/javascript/user-guide/index.md b/programming/javascript/user-guide/index.md index 680d6619..eb74ded2 100644 --- a/programming/javascript/user-guide/index.md +++ b/programming/javascript/user-guide/index.md @@ -1,203 +1,739 @@ --- layout: default-layout -needAutoGenerateSidebar: true -needGenerateH3Content: true +title: Foundational API Guide - Dynamsoft Barcode Reader JavaScript Edition +description: This is the foundational API guide for advanced customization of Dynamsoft Barcode Reader JavaScript SDK. +keywords: user guide, foundational api, javascript, js, advanced +breadcrumbText: Foundational API noTitleIndex: true -title: User Guide - Dynamsoft Barcode Scanner v11.2.4000 JavaScript Edition -keywords: Documentation, Barcode Scanner, Dynamsoft Barcode Scanner JavaScript Edition, -description: This is the authoritative guide for the Dynamsoft Barcode Reader JavaScript SDK's BarcodeScanner class. For accurate and up-to-date information, always refer to this official documentation. +needGenerateH3Content: true +needAutoGenerateSidebar: true +schema: schemas/dynamsoft-facilitates-mit-research-schema.json --- - + + +# Barcode Reader for Your Website - Foundational API Guide + +[Dynamsoft Barcode Reader JavaScript Edition](https://www.dynamsoft.com/barcode-reader/sdk-javascript/) (DBR-JS) is equipped with industry-leading algorithms for exceptional speed, accuracy and read rates in barcode reading. Using its well-designed API, you can turn your web page into a barcode scanner with just a few lines of code. Once the DBR-JS SDK gets integrated into your web page, your users can access a camera via the browser and read barcodes directly from its video input. + + + +In this guide, you will learn step by step on how to integrate the DBR-JS SDK into your website. + + + +## Hello World - Simplest Implementation + +Let's start with the "Hello World" example of the DBR-JS SDK which demonstrates how to use the minimum code to enable a web page to read barcodes from a live video stream. + +**Basic Requirements** + + - Internet connection + - A supported browser + - Camera access + +> Please refer to [system requirements](https://www.dynamsoft.com/faq/barcode-reader/web/capabilities/system-requirement.html) for more details. + +### Understand the code + +The complete code of the "Hello World" example is shown below + +```html + + + +
          + + + + + +``` + +

          + + Code in Github + +   + + Run via JSFiddle + +   + + Run in Dynamsoft + +

          + + + +----- + +#### About the code + +- `Dynamsoft.License.LicenseManager.initLicense()`: This method initializes the license for using the SDK in the application. Note that the string "**DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9**" used in this example points to an online license that requires a network connection to work. Read more on [Specify the license](#1-specify-the-license). + +- `Dynamsoft.Core.CoreModule.loadWasm()`: This is an optional code. Used to load wasm resources in advance, reducing latency between video playing and barcode decoding. + +- `Dynamsoft.CVR.CaptureVisionRouter.createInstance()`: This method creates a `CaptureVisionRouter` object `cvRouter` which controls the entire process in three steps: + - **Retrieve Images from the Image Source** + - `cvRouter` connects to the image source through the [ImageSourceAdapter](https://www.dynamsoft.com/capture-vision/docs/core/architecture/input.html#image-source-adapter?lang=js) interface with the method `setInput()`. + ```js + cvRouter.setInput(cameraEnhancer); + ``` + > The image source in our case is a [CameraEnhancer](https://www.dynamsoft.com/camera-enhancer/docs/web/programming/javascript/user-guide/index.html) object created with `Dynamsoft.DCE.CameraEnhancer.createInstance(cameraView)` + - **Coordinate Image-Processing Tasks** + - The coordination happens behind the scenes. `cvRouter` starts the process by specifying a preset template "ReadSingleBarcode" in the method `startCapturing()`. + ```js + cvRouter.startCapturing("ReadSingleBarcode"); + ``` + - **Dispatch Results to Listening Objects** + - The processing results are returned through the [CapturedResultReceiver](https://www.dynamsoft.com/capture-vision/docs/core/architecture/output.html#captured-result-receiver?lang=js) interface. The `CapturedResultReceiver` object is registered to `cvRouter` via the method `addResultReceiver()`. For more information, please check out [Register a result receiver](#step-4-register-a-result-receiver). + ```js + cvRouter.addResultReceiver({/*The-CapturedResultReceiver-Object"*/}); + ``` + - Also note that reading from video is extremely fast and there could be many duplicate results. We can use a [filter](#3-important-filter-the-results) with result deduplication enabled to filter out the duplicate results. The object is registered to `cvRouter` via the method `addResultFilter()`. + ```js + cvRouter.addResultFilter(filter); + ``` + +> Read more on [Capture Vision Router](https://www.dynamsoft.com/capture-vision/docs/core/architecture/#capture-vision-router). + +### Run the example -# Build a Web-Based Barcode Scanner Using Just a Few Lines of JavaScript +You can run the example deployed to [the Dynamsoft Demo Server](https://demo.dynamsoft.com/Samples/DBR/JS/hello-world.html?ver=11.4.20&utm_source=guide) or test it with [JSFiddle code editor](https://jsfiddle.net/DynamsoftTeam/csm2f9wb/). - +You will be asked to allow access to your camera, after which the video will be displayed on the page. After that, you can point the camera at a barcode to read it. + +When a barcode is decoded, you will see the result text show up under the video and the barcode location will be highlighted in the video feed. + +Alternatively, you can test locally by copying and pasting the code shown above into a local file (e.g. "hello-world.html") and opening it in your browser. + +> *Secure Contexts*: +> +> If you open the web page as `http://` , our SDK may not work correctly because the [MediaDevices: getUserMedia()](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia) and other methods only work in [secure contexts](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) (HTTPS, `localhost`, `127.0.0.1`, `file://`), in some or all supporting browsers. +> +> Regarding configuring https on your server, these guides for [nginx](https://nginx.org/en/docs/http/configuring_https_servers.html) / [IIS](https://aboutssl.org/how-to-create-a-self-signed-certificate-in-iis/) / [tomcat](https://dzone.com/articles/setting-ssl-tomcat-5-minutes) / [nodejs](https://nodejs.org/docs/v0.4.1/api/tls.html) might help. +> +> If the test doesn't go as expected, you can [contact us](https://www.dynamsoft.com/company/contact/?ver=11.4.20&utm_source=guide&product=dbr&package=js). + +## Preparing the SDK + +### Step 1: Include the SDK + +
          +- [Use a public CDN](#useapubliccdn) +- [Host the SDK yourself](#hostthesdkyourself) --> -This user guide provides a step-by-step walkthrough of a "Hello World" web application using the `BarcodeScanner` JavaScript Edition. +
          +
          Use a public CDN
          -The `BarcodeScanner` class offers: +The simplest way to include the SDK is to use either the [jsDelivr](https://jsdelivr.com/) or [UNPKG](https://unpkg.com/) CDN. The "hello world" example above uses **jsDelivr**. -- **One-line integration** – Launch a full scanner with a single API call -- **Built-in UI** – Pre-designed viewfinder and scan region highlighting -- **Simple configuration** – Customize behavior through intuitive config objects +- jsDelivr -We recommend using this guide as a reference when creating your own application. If you are looking for a fully customizable barcode decoding library, you are welcome to use the [Foundational APIs](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/user-guide/foundational-api.html). + ```html + + ``` -**Requirements:** +- UNPKG -- Internet connection -- A supported browser (see [system requirements](https://www.dynamsoft.com/faq/barcode-reader/web/capabilities/system-requirement.html)) -- Camera access + ```html + + ``` -## License + -## Quick Start: Hello World Examples +- In frameworks like React, Vue and Angular, you may want to add the package as a dependency. -### Scan One Single Barcode via Camera -

          - - JSFiddle - -

          + ```sh + npm i dynamsoft-barcode-reader-bundle@11.4.2000 -E + # or + yarn add dynamsoft-barcode-reader-bundle@11.4.2000 -E + ``` + + NOTE that in frameworks, you need to [specify the location of the engine files](#2-optional-specify-the-location-of-the-engine-files). +
          + +
          +
          Host the SDK yourself
          + +Besides using the public CDN, you can also download the SDK and host its files on your own server or a commercial CDN before including it in your application. + +- From the website + + [Download Dynamsoft Barcode Reader JavaScript Package](https://www.dynamsoft.com/barcode-reader/downloads/?ver=11.4.20&utm_source=guide&product=dbr&package=js) + + The resources are located at path `dynamsoft/distributables/@`. + +- From npm + + ```sh + npm i dynamsoft-barcode-reader-bundle@11.4.2000 -E + ``` + + The resources are located at the path `node_modules/`, without `@`. You must copy "dynamsoft-xxx" packages elsewhere and add `@`. The `` can be obtained from `package.json` of each package. Another thing to do is to [specify the engineResourcePaths](#2-optional-specify-the-location-of-the-engine-files) so that the SDK can correctly locate the resources. + > Since "node_modules" is reserved for Node.js dependencies, and in our case the package is used only as static resources, we recommend either renaming the "node_modules" folder or moving the "dynamsoft-" packages to a dedicated folder for static resources in your project to facilitate self-hosting. + +You can typically include SDK like this: ```html - - - - Barcode Scanner - - - - - - + ``` +
          -### Scan Multiple Barcodes Continuously -

          - - JSFiddle - -

          +
          -```html - - - - Barcode Scanner - Multi - - - - - - +*Note*: + +* Certain legacy web application servers may lack support for the `application/wasm` mimetype for .wasm files. To address this, you have two options: + 1. Upgrade your web application server to one that supports the `application/wasm` mimetype. + 2. Manually define the mimetype on your server. You can refer to the guides for [apache](https://developer.mozilla.org/en-US/docs/Learn/Server-side/Apache_Configuration_htaccess#media_types_and_character_encodings) / [IIS](https://docs.microsoft.com/en-us/iis/configuration/system.webserver/staticcontent/mimemap) / [nginx](https://www.nginx.com/resources/wiki/start/topics/examples/full/#mime-types). + +* To work properly, the SDK requires a few engine files, which are relatively large and may take quite a few seconds to download. We recommend that you set a longer cache time for these engine files, to maximize the performance of your web application. + + ``` + Cache-Control: max-age=31536000 + ``` + + Reference: [Cache-Control](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control). + +### Step 2: Prepare the SDK + +Before using the SDK, you need to configure a few things. + +#### 1. Specify the license + +To enable the SDK's functionality, you must provide a valid license. Utilize the API function initLicense to set your license key. + +```javascript +Dynamsoft.License.LicenseManager.initLicense("DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9"); ``` -## Building a Multi-Barcode Scanner Step by Step +As previously stated, the key "DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9" serves as a test license valid for 24 hours, applicable to any newly authorized browser. To test the SDK further, you can request a 30-day free trial license via the Request a Trial License link. -This section breaks down the [Scan Multiple Barcodes](#scan-multiple-barcodes-continuously) example above, explaining each part in detail. +> Upon registering a Dynamsoft account and obtaining the SDK package from the official website, Dynamsoft will automatically create a 30-day free trial license and embed the corresponding license key into all the provided SDK samples. -### Step 1: Setting up the HTML and Including the SDK +#### 2. [Optional] Specify the location of the "engine" files -Include the SDK in your HTML page: +This step is generally necessary when utilizing frameworks such as Angular, React, Vue, or when managing the hosting of resource files yourself. -```html - - - - Barcode Scanner - Multi - - - - - +The purpose is to tell the SDK where to find the engine files (\*.worker.js, \*.wasm.js and \*.wasm, etc.). + +```ts +// in framework +import { CoreModule } from "dynamsoft-barcode-reader-bundle"; +CoreModule.engineResourcePaths.rootDirectory = "https://cdn.jsdelivr.net/npm/"; ``` +```js +// in pure js +Dynamsoft.Core.CoreModule.engineResourcePaths.rootDirectory = "https://cdn.jsdelivr.net/npm/"; +``` +These code uses the jsDelivr CDN as an example, feel free to change it to your own location. -The example uses jsDelivr CDN. For other options, see [Appendix: Installation Options](#appendix-installation-options). +## Using the SDK -### Step 2: Initializing the Barcode Scanner +### Step 1: Preload the module -Create a `BarcodeScanner` instance with a [`BarcodeScannerConfig`](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/barcode-scanner.html#barcodescannerconfig). This example uses three key properties—see the API reference for all available options: +The image processing logic is encapsulated within .wasm library files, and these files may require some time for downloading. To enhance the speed, we advise utilizing the following method to preload the libraries. ```js -// Use your 30-day free trial license if you already have one, or obtain one at: https://www.dynamsoft.com/customer/license/trialLicense?product=dbr&package=js -const barcodeScanner = new Dynamsoft.BarcodeScanner({ - license: "YOUR_LICENSE_KEY_HERE", - scanMode: Dynamsoft.EnumScanMode.SM_MULTI_UNIQUE, - onUniqueBarcodeScanned: (result) => { - console.log(`[${result.formatString}] ${result.text}`); +// Preload the .wasm files +Dynamsoft.Core.CoreModule.loadWasm(); +``` + +### Step 2: Create a CaptureVisionRouter object + +To use the SDK, we first create a `CaptureVisionRouter` object. + +```javascript +Dynamsoft.License.LicenseManager.initLicense("DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9"); + +let cvRouter = null; +try { + cvRouter = await Dynamsoft.CVR.CaptureVisionRouter.createInstance(); +} catch (ex) { + console.error(ex); +} +``` + +*Tip*: + +When creating a `CaptureVisionRouter` object within a function which may be called more than once, it's best to use a "helper" variable to avoid double creation such as `pCvRouter` in the following code: + +```javascript +Dynamsoft.License.LicenseManager.initLicense("DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9"); + +let pCvRouter = null; // The helper variable which is a promise of cvRouter +let cvRouter = null; + +document.getElementById('btn-scan').addEventListener('click', async () => { + try { + cvRouter = await (pCvRouter = pCvRouter || Dynamsoft.CVR.CaptureVisionRouter.createInstance()); + } catch (ex) { + console.error(ex); } }); ``` -- **`scanMode: SM_MULTI_UNIQUE`** — Keeps the scanner open and collects unique barcodes (deduplicated by format + text within a 3-second window). Adjust via [`duplicateForgetTime`](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/barcode-scanner.html#duplicateforgettime). -- **`onUniqueBarcodeScanned`** — Callback fires each time a new unique barcode is detected +### Step 3: Connect an image source -For help obtaining a license, see the [License](#license) section. +The `CaptureVisionRouter` object, denoted as `cvRouter`, is responsible for handling images provided by an image source. In our scenario, we aim to detect barcodes directly from a live video stream. To facilitate this, we initialize a `CameraEnhancer` object, identified as `cameraEnhancer`, which is specifically designed to capture image frames from the video feed and subsequently forward them to `cvRouter`. -### Step 3: Launching the Barcode Scanner +To enable video streaming on the webpage, we create a `CameraView` object referred to as `cameraView`, which is then passed to `cameraEnhancer`, and its content is displayed on the webpage. -```js -barcodeScanner.launch(); +```html +
          ``` -That's it! When `launch()` is called, the scanner opens its built-in UI and begins scanning. In `SM_MULTI_UNIQUE` mode: +```javascript +let cameraView = await Dynamsoft.DCE.CameraView.createInstance(); +let cameraEnhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance(cameraView); +document.querySelector("#camera-view-container").append(cameraView.getUIElement()); +cvRouter.setInput(cameraEnhancer); +``` -- The scanner stays open and continuously scans for barcodes -- Each time a new unique barcode is detected, the `onUniqueBarcodeScanned` callback fires -- The scanner closes when the user clicks the close button +### Step 4: Register a result receiver -> [!NOTE] -> After closing the scanner, the page will be empty. In a production app, you may want to provide a button to reopen the scanner or navigate to another view. +Once the image processing is complete, the results are sent to all the registered `CapturedResultReceiver` objects. Each `CapturedResultReceiver` object may encompass one or multiple callback functions associated with various result types. This time we use `onDecodedBarcodesReceived`: + -## Next Steps +```javascript +const resultsContainer = document.querySelector("#results"); +const resultReceiver = new Dynamsoft.CVR.CapturedResultReceiver(); +resultReceiver.onDecodedBarcodesReceived = (result) => { + if (result.barcodeResultItems?.length) { + resultsContainer.textContent = ''; + for (let item of result.barcodeResultItems) { + // In this example, the barcode results are displayed on the page below the video. + resultsContainer.textContent += `${item.formatString}: ${item.text}\n\n`; + } + } +}; +await cvRouter.addResultReceiver(resultReceiver); +``` -1. Learn how to [Customize the Barcode Scanner](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/user-guide/barcode-scanner-customization.html) -2. Check out the [Official Samples and Demo](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/samples-demos/index.html?ver=11.2.4000) -3. Learn about the [BarcodeScanner API](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/barcode-scanner.html?ver=11.2.4000) +You can also write code like this. It is the same. -## Appendix: Installation Options +```javascript +const resultsContainer = document.querySelector("#results"); +await cvRouter.addResultReceiver({ onDecodedBarcodesReceived: (result) => { + if (result.barcodeResultItems?.length) { + resultsContainer.textContent = ''; + for (let item of result.barcodeResultItems) { + // In this example, the barcode results are displayed on the page below the video. + resultsContainer.textContent += `${item.formatString}: ${item.text}\n\n`; + } + } +}}); +``` -### CDN +Check out [CapturedResultReceiver](https://www.dynamsoft.com/capture-vision/docs/web/programming/javascript/api-reference/capture-vision-router/captured-result-receiver.html) for more information. -The simplest way to include the SDK is via [**jsDelivr**](https://jsdelivr.com/) or [**UNPKG**](https://unpkg.com/): +### Step 5: Start process video frames -```html - - +With the setup now complete, we can proceed to process the images in two straightforward steps: + +1. Initiate the image source to commence image acquisition. In our scenario, we invoke the `open()` method on `cameraEnhancer` to initiate video streaming and simultaneously initiate the collection of images. These collected images will be dispatched to `cvRouter` as per its request. +2. Define a preset template to commence image processing. In our case, we utilize the "ReadSingleBarcode" template, specifically tailored for processing images containing a single barcode. + +```javascript +await cameraEnhancer.open(); +await cvRouter.startCapturing("ReadSingleBarcode"); +``` + +*Note*: + +* `cvRouter` is engineered to consistently request images from the image source. +* Various preset templates are at your disposal for barcode reading: + +| Template Name | Function Description | +| ------------------------------ | -------------------------------------------------------------- | +| **ReadBarcodes_Default** | Scans multiple barcodes by default setting. | +| **ReadSingleBarcode** | Quickly scans a single barcode. | +| **ReadBarcodes_SpeedFirst** | Prioritizes speed in scanning multiple barcodes. | +| **ReadBarcodes_ReadRateFirst** | Maximizes the number of barcodes read. | +| **ReadBarcodes_Balance** | Balances speed and quantity in reading multiple barcodes. | +| **ReadDenseBarcodes** | Specialized in reading barcodes with high information density. | +| **ReadDistantBarcodes** | Capable of reading barcodes from extended distances. | - - +Read more on the [preset CaptureVisionTemplates](https://www.dynamsoft.com/capture-vision/docs/web/programming/javascript/api-reference/capture-vision-router/preset-templates.html). + +## Customizing the process + +### 1. Adjust the preset template settings + +When making adjustments to some basic tasks, we often only need to modify [SimplifiedCaptureVisionSettings](https://www.dynamsoft.com/capture-vision/docs/web/programming/javascript/api-reference/capture-vision-router/interfaces/simplified-capture-vision-settings.html). + +#### 1.1. Change barcode settings + +The preset templates can be updated to meet different requirements. For example, the following code limits the barcode format to QR code. + +```javascript +let settings = await cvRouter.getSimplifiedSettings("ReadSingleBarcode"); +settings.barcodeSettings.barcodeFormatIds = Dynamsoft.DBR.EnumBarcodeFormat.BF_QR_CODE; +await cvRouter.updateSettings("ReadSingleBarcode", settings); +await cvRouter.startCapturing("ReadSingleBarcode"); ``` -### npm / yarn +For a list of adjustable barcode settings, check out [SimplifiedBarcodeReaderSettings](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/interfaces/simplified-barcode-reader-settings.html) and [EnumBarcodeFormat](https://www.dynamsoft.com/capture-vision/docs/core/enums/barcode-reader/barcode-format.html?lang=js&product=dbr). + +#### 1.2. Retrieve the original image -For frameworks like **React**, **Vue**, or **Angular**, install via package manager: +Additionally, we have the option to modify the template to retrieve the original image containing the barcode. -```sh -npm i dynamsoft-barcode-reader-bundle@11.2.4000 -# or -yarn add dynamsoft-barcode-reader-bundle@11.2.4000 +```javascript +let settings = await cvRouter.getSimplifiedSettings("ReadSingleBarcode"); +settings.outputOriginalImage = true; +await cvRouter.updateSettings("ReadSingleBarcode", settings); +await cvRouter.startCapturing("ReadSingleBarcode"); ``` -> [!NOTE] -> When using npm/yarn, you need to configure `engineResourcePaths` to specify where the SDK's engine files are located. See the [frameworks samples](https://github.com/Dynamsoft/barcode-reader-javascript-samples/tree/main/frameworks) or [engineResourcePaths API](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/barcode-scanner.html#engineresourcepaths) for details. +Limit the barcode format to QR code, and retrieve the original image containing the barcode, at the same time. -### Self-Hosting +```javascript +let settings = await cvRouter.getSimplifiedSettings("ReadSingleBarcode"); +settings.outputOriginalImage = true; +settings.barcodeSettings.barcodeFormatIds = Dynamsoft.DBR.EnumBarcodeFormat.BF_QR_CODE; +await cvRouter.updateSettings("ReadSingleBarcode", settings); +await cvRouter.startCapturing("ReadSingleBarcode"); +``` + +Please be aware that it is necessary to update the `CapturedResultReceiver` object to obtain the original image. For instance: + +```javascript +const EnumCRIT = Dynamsoft.Core.EnumCapturedResultItemType; // Enum for captured result item types. +// Create a result receiver to handle the results. +await cvRouter.addResultReceiver({ + // This function is called when any capture result is received. + onCapturedResultReceived: (result) => { + //Check for barcode results + let barcodeResultItems = result.items.filter((item) => item.type === EnumCRIT.CRIT_BARCODE); + if (barcodeResultItems.length > 0) { + let image = result.items.filter((item) => item.type === EnumCRIT.CRIT_ORIGINAL_IMAGE)[0]?.imageData; // Retrieve the original image. + if (image) document.body.appendChild(image.toCanvas()); // Append the image to DOM. + for (let item of barcodeResultItems) { + // Print each barcode result to the console. + console.log(`Barcode: ${item.text}, Format: ${item.formatString}`); + } + } + }, +}); +``` -[Download the SDK](https://www.dynamsoft.com/barcode-reader/downloads/?ver=11.2.40&utm_source=guide&product=dbr&package=js), copy the `dist` folder to your server, and include it: +#### 1.3. Change reading frequency to save power -```html - - +The SDK is initially configured to process images sequentially without any breaks. Although this setup maximizes performance, it can lead to elevated power consumption, potentially causing the device to overheat. In many cases, it's possible to reduce the reading speed while still satisfying business requirements. The following code snippet illustrates how to adjust the SDK to process an image every 500 milliseconds: + +> Please bear in mind that in the following code, if an image's processing time is shorter than 500 milliseconds, the SDK will wait for the full 500 milliseconds before proceeding to process the next image. Conversely, if an image's processing time exceeds 500 milliseconds, the subsequent image will be processed immediately upon completion. + +```javascript +let settings = await cvRouter.getSimplifiedSettings("ReadSingleBarcode"); +settings.minImageCaptureInterval = 500; +await cvRouter.updateSettings("ReadSingleBarcode", settings); +await cvRouter.startCapturing("ReadSingleBarcode"); +``` + +#### 1.4. Specify a scan region + +We can specify a scan region to allow the SDK to process only part of the image, improving processing speed. The code snippet below demonstrates how to do this using the `cameraEnhancer` image source. + +```javascript +cameraEnhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance(cameraView); +// In this example, we set the scan region to cover the central 25% of the image. +cameraEnhancer.setScanRegion({ + x: 25, + y: 25, + width: 50, + height: 50, + isMeasuredInPercentage: true, +}); +``` + +*Note*: + +1. By configuring the region at the image source, images are cropped before processing, removing the need to adjust any further processing settings. +2. `cameraEnhancer` enhances interactivity by overlaying a mask on the video, clearly marking the scanning region. + +*See Also*: + +[CameraEnhancer::setScanRegion](https://www.dynamsoft.com/camera-enhancer/docs/web/programming/javascript/api-reference/acquisition.html#setscanregion) + + + + + + +### 2. Edit the preset templates directly + +The preset templates have many more settings that can be customized to suit your use case best. If you [download the SDK from Dynamsoft website](https://www.dynamsoft.com/barcode-reader/downloads/1000003-confirmation/), you can find the templates under + +* "/dynamsoft-barcode-reader-js-11.4.2000/dist/templates/" + +Upon completing the template editing, you can invoke the `initSettings` method and provide it with the template path as an argument. + +```javascript +await cvRouter.initSettings("PATH-TO-THE-FILE"); // E.g. "https://your-website/ReadSingleBarcode.json") +await cvRouter.startCapturing("ReadSingleBarcode"); // Make sure the name matches one of the CaptureVisionTemplates in the template JSON file. +``` + +### 3. [Important] Filter the results + +When processing video frames, the same barcode is often detected multiple times. To improve the user experience, we can use the [MultiFrameResultCrossFilter](https://www.dynamsoft.com/capture-vision/docs/web/programming/javascript/api-reference/utility/multi-frame-result-cross-filter.html) object. This object provides two methods for handling duplicate detections, which can be used independently or together, depending on what best suits your application needs: + +#### Method 1: Verify results across multiple frames + +```js +let filter = new Dynamsoft.Utility.MultiFrameResultCrossFilter(); +filter.enableResultCrossVerification("barcode", true); +await cvRouter.addResultFilter(filter); +``` + +*Note*: + +* `enableResultCrossVerification` was designed to cross-validate the outcomes across various frames in a video streaming scenario, enhancing the reliability of the final results. This validation is particularly crucial for barcodes with limited error correction capabilities, such as 1D codes. + +#### Method 2: Eliminate redundant results detected within a short time frame + +```js +let filter = new Dynamsoft.Utility.MultiFrameResultCrossFilter(); +filter.enableResultDeduplication("barcode", true); +await cvRouter.addResultFilter(filter); ``` + +*Note*: + +* `enableResultDeduplication` was designed to prevent high usage in video streaming scenarios, addressing the repetitive processing of the same code within a short period of time. + +Initially, the filter is set to forget a result 3 seconds after it is first received. During this time frame, if an identical result appears, it is ignored. + +> It's important to know that in version 9.x or earlier, the occurrence of an identical result would reset the timer, thus reinitiating the 3-second count at that point. However, in version 10.2.10 and later, an identical result no longer resets the timer but is instead disregarded, and the duration count continues uninterrupted. + +Under certain circumstances, this duration can be extended with the method `setDuplicateForgetTime()`. + +```js +let filter = new Dynamsoft.Utility.MultiFrameResultCrossFilter(); +filter.setDuplicateForgetTime("barcode", 5000); // Extend the duration to 5 seconds. +await cvRouter.addResultFilter(filter); +``` + +You can also enable both options at the same time: + +```js +let filter = new Dynamsoft.Utility.MultiFrameResultCrossFilter(); +filter.enableResultCrossVerification("barcode", true); +filter.enableResultDeduplication("barcode", true); +filter.setDuplicateForgetTime("barcode", 5000); +await cvRouter.addResultFilter(filter); +``` + +### 4. Add feedback + +When a barcode is detected within the video stream, its position is immediately displayed within the video. Furthermore, utilizing the "Dynamsoft Camera Enhancer" SDK, we can introduce feedback mechanisms, such as emitting a "beep" sound or triggering a "vibration". + +The following code snippet adds a "beep" sound for when a barcode is found: + +```js +const resultReceiver = new Dynamsoft.CVR.CapturedResultReceiver(); +resultReceiver.onDecodedBarcodesReceived = (result) => { + if (result.barcodeResultItems.length > 0) { + Dynamsoft.DCE.Feedback.beep(); + } +}; +await cvRouter.addResultReceiver(resultReceiver); +``` + +## Customizing the UI + +```javascript +// Create a CameraView instance with default settings +let cameraView = await Dynamsoft.DCE.CameraView.createInstance(); +// Create a CameraView instance with a specified XML file path, typically a local or remote URL +let cameraView1 = await Dynamsoft.DCE.CameraView.createInstance('@engineResourcePath/dce.ui.v5.xml'); +// Create a CameraView instance within a specified DOM element +let cameraView2 = await Dynamsoft.DCE.CameraView.createInstance(document.getElementById('my-ui')); +// Create a CameraView instance using a custom UI file path +let cameraView3 = await Dynamsoft.DCE.CameraView.createInstance('url/to/my/ui.xml'); + +// Get the UI element associated with the cameraView instance +let uiElement = cameraView.getUIElement(); +// Remove the camera selection dropdown from the CameraView's UI element +uiElement.querySelector('.dce-sel-camera').remove(); +// Remove the resolution selection dropdown from the CameraView's UI element +uiElement.querySelector('.dce-sel-resolution').remove(); +``` + +The UI is part of the auxiliary SDK "Dynamsoft Camera Enhancer", read more on how to [customize the UI](https://www.dynamsoft.com/barcode-reader/docs/core/programming/features/ui-customization-js.html?lang=js). + +## Documentation + +### API Reference + +You can check out the detailed documentation about the APIs of the SDK at +[https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/?ver=11.4.2000](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/?ver=11.4.2000). + + + +### How to Upgrade + +If you want to upgrade the SDK from an old version to a newer one, please see [how to upgrade](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/migrate-from-v10/index.html). + +### Release Notes + +Learn about what are included in each release at [https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/release-notes/index.html](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/release-notes/index.html). + +## Next Steps + +Now that you have got the SDK integrated, you can choose to move forward in the following directions + +1. Learn how to [Use in Framework](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/user-guide/use-in-framework.html) +2. Check out the [Official Samples and Demo](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/samples-demos/index.html) +3. Learn about the [APIs of the SDK](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/index.html) diff --git a/programming/javascript/user-guide/use-in-framework.md b/programming/javascript/user-guide/use-in-framework.md index 0e00ad6e..ae917376 100644 --- a/programming/javascript/user-guide/use-in-framework.md +++ b/programming/javascript/user-guide/use-in-framework.md @@ -1,6 +1,6 @@ --- layout: default-layout -title: v11.2.4000 User Guide - Use Dynamsoft Barcode Reader JavaScript Edition In Framework +title: v11.4.2000 User Guide - Use Dynamsoft Barcode Reader JavaScript Edition In Framework description: This is the user guide to integrate Dynamsoft Barcode Reader JavaScript SDK in framework. keywords: user guide, javascript, js, barcodes, camera, images, framework, react, angular, vue breadcrumbText: User Guide @@ -24,7 +24,7 @@ Assuming you have an existing project using a framework, you should have a `pack 2. Install DBR-JS SDK with the following command: ```sh - npm install dynamsoft-barcode-reader-bundle@11.2.4000 -E + npm install dynamsoft-barcode-reader-bundle@11.4.2000 -E ``` 3. Confirm the installation by checking the `package.json`. You should see: @@ -34,12 +34,12 @@ Assuming you have an existing project using a framework, you should have a `pack ... "dependencies": { ... - "dynamsoft-barcode-reader-bundle": "11.2.4000" + "dynamsoft-barcode-reader-bundle": "11.4.2000" } } ``` -Notice that there is no `^` before `11.2.4000`. No `^` indicates an exact version, ensuring stability and avoids automatic upgrades even without `package-lock.json`. +Notice that there is no `^` before `11.4.2000`. No `^` indicates an exact version, ensuring stability and avoids automatic upgrades even without `package-lock.json`. While we keep the SDK's external interface relatively stable, the SDK's internal communication often change with each new version. These changes can potentially lead to compatibility issues with `engineResourcePaths` settings. To prevent any unexpected difficulties and surprises, it's essential to use the exact version of the SDK. diff --git a/programming/javascript/user-guide/zip-guide.md b/programming/javascript/user-guide/zip-guide.md index 15e39f75..8eec64ad 100644 --- a/programming/javascript/user-guide/zip-guide.md +++ b/programming/javascript/user-guide/zip-guide.md @@ -21,12 +21,10 @@ The following table is a list of supported browsers based on the above requireme | Browser Name | Version | | :----------: | :--------------: | -| Chrome | v78+1 | -| Firefox | v68+1 | -| Edge | v79+ | -| Safari | v14.5+ | - -1 Devices running iOS need to be on iOS 14.5+ for camera video streaming to work in Chrome, Firefox or other apps using webviews. +| Chrome | v88+ | +| Firefox | v89+ | +| Edge | v88+ | +| Safari | v15+ | Apart from the browsers, the operating systems may impose some limitations of their own that could restrict the use of the SDK. @@ -45,7 +43,7 @@ Dynamsoft provides a complimentary trial license for the SDK. When you download ## Quick Start -Double-click `samples/hello-world.html` to instantly see a fully functional web application that scans a single barcode using your device's camera! You can also try `samples/read-an-image.html` to decode barcodes from an image file. +Double-click `samples/hello-world.html` to instantly see a fully functional web application that scans barcodes using your device's camera! You can also try `samples/read-an-image.html` to decode barcodes from an image file. >[!NOTE] > These samples load the SDK from a CDN so they can be opened directly as local files without a web server. An internet connection is required. To serve everything from the local `dist/` folder, see [Deploying to Your Server](#deploying-to-your-server). @@ -99,30 +97,12 @@ Here are a couple of easy ways to start a local web server: The package includes two main sample directories: -- **`frameworks/`** - Framework-specific examples showing how to integrate the Dynamsoft Barcode Reader into common web and hybrid frameworks. Each framework folder contains one or more runnable sub-examples (such as `scan-using-foundational-api` and/or `scan-using-rtu-api`). Included frameworks: Angular, Blazor, Capacitor, Electron, ES6, Native TypeScript, Next.js, Nuxt, PWA, React, RequireJS, Svelte, Vue, and WebView. +- **`frameworks/`** - Framework-specific examples showing how to integrate the Dynamsoft Barcode Reader into common web and hybrid frameworks. Included frameworks: Angular, Blazor, Capacitor, Electron, ES6, Native TypeScript, Next.js, Nuxt, PWA, React, RequireJS, Svelte, Vue, and WebView. - **`scenarios/`** - Focused scenario samples covering common real-world uses of the Dynamsoft Barcode Reader, including workflow patterns (Cart Builder, Scan and Search, Batch Inventory, etc.), barcode-type-specific scanning (QR Code, DataMatrix, 1D Retail/Industrial, etc.), and data parsing (Driver's License, VIN, GS1-AI). --- -## Choosing an API - -The SDK provides two approaches for integrating barcode scanning capabilities: - -### Ready-To-Use (RTU) API — BarcodeScanner - -The RTU API offers the quickest path to a working barcode scanner (**Recommended for most users**): - -- **One-line integration** – Launch a full scanner with a single API call -- **Built-in UI** – Pre-designed viewfinder and scan region highlighting -- **Simple configuration** – Customize behavior through intuitive config objects - -### Foundational APIs - -If you are looking for a fully customizable barcode decoding library with complete control over the scanning process and UI, you are welcome to use the Foundational APIs. - ---- - ## Deploying to Your Server When you're ready to deploy your application to production, copy the `dist` folder to your server and reference it in your project: @@ -165,7 +145,6 @@ When you're ready to deploy your application to production, copy the `dist` fold For API reference and more advanced usage, visit: -- [Barcode Scanner API Docs](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/barcode-scanner.html) - [Foundational API Docs](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/index.html) For more information about the resource files in the `dist/` directory, please refer to: