Skip to content

Commit deb6320

Browse files
Justin-dynamsoftShen-wbTom-Dynamsoft
authored
Dev (#282)
* feat(templates): update templates & add debug tool link * fix: update canonical links in HTML files for accurate routing * UPDATE * fix: update script path for local SDK loading in HTML files * fix: correct spelling of launchBarcodeScanner function * fix: update license initialization and update read-an-image.html * UPDATE VERSION * docs: update README with sample list and descriptions; add comments to hello-world example * refactor: clean up comments in hello-world example for clarity * Update hello-world.html comment * fix: update script source paths and decode template for consistency * docs: update README files to correct SDK links and enhance clarity; add new READMEs for ES6 and RequireJS * docs: enhance README for clarity and structure; add sections on sample folders and API choices * Fix secure context note structure and expand RTU acronym - Move file:/// exception note to cover both camera access and license (was previously nested under camera bullet only) - Expand "RTU" to "Ready-To-Use (RTU)" on first mention * Improve README clarity and structure - Promote "Running the Samples Locally" to its own section - Separate framework (npm) vs standalone/scenario (double-click or Five Server) instructions - Mention index.html as the sample gallery entry point - Remove redundant "API reference" line in Documentation section - Fix VIN spacing and de-duplicate Official Demo description * feat: add sample for scanning Direct Part Mark (DPM) codes * UPDATE * Update package.json * add rtu sample * Update app.vue * feat: update documentation for Next.js and Nuxt.js * Update read-an-image.html * UPDATE * Delete frameworks/nuxt/scan-using-rtu-api/curl.txt * Delete frameworks/nuxt/scan-using-rtu-api/response.html * Delete frameworks/nuxt/scan-using-rtu-api/dev.err * Update .gitignore * Update scan-a-single-barcode.html * UPDATE * Update README and index.html to enhance sample descriptions and add new section for Hello World samples * Update user guide link in index.html * Add scanMode configuration for multi-unique scanning in various scenarios --------- Co-authored-by: SHEN <1014628363@qq.com> Co-authored-by: Tom Kent <Tom-Dynamsoft@users.noreply.github.com> Co-authored-by: Dynamsoft-Shen <62587615+Shen-wb@users.noreply.github.com>
1 parent 2f0a723 commit deb6320

104 files changed

Lines changed: 3513 additions & 837 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 102 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,45 @@
1-
# Dynamsoft Barcode Reader samples for the web
1+
# Dynamsoft Barcode Reader Samples for the Web
22

3-
This repository contains multiple samples that demonstrates how to use the [Dynamsoft Barcode Reader JavaScript Edition](https://www.dynamsoft.com/barcode-reader/sdk-javascript/?utm_source=sampleReadme) for creating web-based barcode scanning applications.
3+
This repository contains multiple samples that demonstrate how to use the [Dynamsoft Barcode Reader JavaScript Edition](https://www.dynamsoft.com/barcode-reader/sdk-javascript/?utm_source=sampleReadme) for creating web-based barcode scanning applications.
4+
5+
---
6+
7+
## System Requirements
8+
9+
### Secure Context (HTTPS Deployment)
10+
11+
When deploying your application/website for production, make sure to serve it via a secure HTTPS connection. This is required for two reasons:
12+
13+
- Access to the camera video stream is only granted in a security context. Most browsers impose this restriction.
14+
- Dynamsoft License requires a secure context to work.
15+
16+
> Some browsers like Chrome may grant access for `http://127.0.0.1` and `http://localhost` or even for pages opened directly from the local disk (`file:///...`). This can be helpful for temporary development and testing.
17+
18+
### Browser Compatibility
19+
20+
The following table is a list of supported browsers based on the above requirements:
21+
22+
| Browser Name | Version |
23+
| :----------: | :--------------: |
24+
| Chrome | v78+<sup>1</sup> |
25+
| Firefox | v68+<sup>1</sup> |
26+
| Edge | v79+ |
27+
| Safari | v14.5+ |
28+
29+
<sup>1</sup> Devices running iOS need to be on iOS 14.5+ for camera video streaming to work in Chrome, Firefox or other apps using webviews.
30+
31+
Apart from the browsers, the operating systems may impose some limitations of their own that could restrict the use of the SDK.
32+
33+
---
34+
35+
## License
36+
37+
A default trial license is included which allows you to test the sample apps for up to 24 hours. You can [request a 30-day trial license](https://www.dynamsoft.com/customer/license/trialLicense?product=dbr&package=js&utm_source=sampleReadme) via the Dynamsoft website to evaluate further.
38+
39+
>[!IMPORTANT]
40+
> Once your trial license expires, the SDK will throw an error and cease to function. You can visit the [Dynamsoft Customer Portal](https://www.dynamsoft.com/customer/license/trialLicense?product=dbr&utm_source=sampleReadme&package=js) to view your trial license details. Additionally, it's possible to extend the trial period via the customer portal, allowing for a total trial duration of 60 days.
41+
42+
---
443

544
## Get the Code
645

@@ -16,28 +55,75 @@ git clone https://github.com/Dynamsoft/barcode-reader-javascript-samples.git --d
1655

1756
> [!NOTE]
1857
> If you expect unstable network conditions or prefer to work entirely offline, you can download the [offline package from Dynamsoft website](https://www.dynamsoft.com/barcode-reader/downloads/1000003-confirmation/). This includes the full repository and all required dependencies for offline use.
19-
>
20-
> **Running the Samples Locally**
21-
>
22-
> Opening HTML files directly may not work as expected. Instead, run a local development server. Here’s a quick method using [Visual Studio Code](https://code.visualstudio.com/):
23-
>
24-
> 1. Install the [Five Server extension](https://marketplace.visualstudio.com/items?itemName=yandeu.five-server) from the VS Code Marketplace.
25-
>
26-
> 2. Right-click on `hello-world.html` and select "Open with Five Server". This will serve the application at `http://127.0.0.1:5500/hello-world.html`.
2758
28-
## Request a trial license
59+
---
60+
61+
## Running the Samples Locally
62+
63+
The standalone samples (`hello-world.html`, `scan-a-single-barcode.html`, `read-an-image.html`) and scenario samples load the SDK from a CDN, so you can open them directly by double-clicking — no web server required (an internet connection is needed).
64+
65+
To browse all available samples, open `index.html` in your browser — it links to every sample in the repository.
66+
67+
For framework samples, follow the instructions in each subfolder's README (typically `npm install` then `npm run dev`).
68+
69+
If you need a web server for standalone or scenario samples (for example, to serve SDK resources from a local `dist/` folder), here's a quick method using [Visual Studio Code](https://code.visualstudio.com/):
2970

30-
A default license is included which allows you to test the sample apps for up to 24 hours. You can [request a 30-day trial license](https://www.dynamsoft.com/customer/license/trialLicense?product=dbr&package=js&utm_source=sampleReadme) via Dynamsoft website to evaluate further.
71+
1. Install the [Five Server extension](https://marketplace.visualstudio.com/items?itemName=yandeu.five-server) from the VS Code Marketplace.
72+
73+
2. Right-click on an HTML file and select "Open with Five Server". This will serve the application at `http://127.0.0.1:5500/`.
74+
75+
---
76+
77+
## Sample Folders
78+
79+
The repository includes two main sample directories:
80+
81+
- **`frameworks/`** - Framework-specific examples demonstrating how to integrate 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`) showing practical integration patterns.
82+
83+
- **`scenarios/`** - Focused scenario samples that show common real-world uses of Dynamsoft Barcode Reader.
84+
85+
---
86+
87+
## Choosing an API
88+
89+
The SDK provides two approaches for integrating barcode scanning capabilities:
90+
91+
### Ready-To-Use (RTU) API — BarcodeScanner
92+
93+
The RTU API offers the quickest path to a working barcode scanner (**Recommended for most users**):
94+
95+
- **One-line integration** – Launch a full scanner with a single API call
96+
- **Built-in UI** – Pre-designed viewfinder and scan region highlighting
97+
- **Simple configuration** – Customize behavior through intuitive config objects
98+
99+
### Foundational APIs
100+
101+
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.
102+
103+
---
31104

32105
## Documentation
33106

34107
For the developer guide and full API reference of Dynamsoft Barcode Reader JavaScript library, please check out the [documentation](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/?ver=11.2.4000&utm_source=sampleReadme).
35108

109+
- [Barcode Scanner API Docs](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/barcode-scanner.html?utm_source=sampleReadme)
110+
- [Foundational API Docs](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/index.html?utm_source=sampleReadme)
111+
112+
---
113+
36114
## Support
37115

38116
If you have any questions, feel free to [contact Dynamsoft support](https://www.dynamsoft.com/company/contact?utm_source=sampleReadme).
39117

40-
## Sample list
118+
---
119+
120+
## Sample List
121+
122+
### Hello World
123+
124+
- [hello-world.html](./hello-world.html) — Demonstrates continuously scanning and collecting multiple unique barcodes via camera.
125+
- [scan-a-single-barcode.html](./scan-a-single-barcode.html) — Demonstrates single-barcode scanning: stops and returns as soon as the first barcode is detected.
126+
- [read-an-image.html](./read-an-image.html) — Demonstrates how to decode and read barcodes from uploaded image files.
41127

42128
### Hello-world
43129

@@ -69,12 +155,13 @@ If you have any questions, feel free to [contact Dynamsoft support](https://www.
69155
- [show-result-texts-on-the-video/](./scenarios/show-result-texts-on-the-video/) — Overlay decoded text on live video while scanning.
70156
- [batch-inventory/](./scenarios/batch-inventory/) — Batch scanning workflow for inventory collection and export.
71157
- [read-a-drivers-license/](./scenarios/read-a-drivers-license/) — Demo for reading and parsing a driver's license image/data.
72-
- [read-vin/](./scenarios/read-vin/) — Demo for reading and parsing a VIN(vehicle identification number) code.
158+
- [read-vin/](./scenarios/read-vin/) — Demo for reading and parsing a VIN (vehicle identification number) code.
73159
- [read-and-parse-GS1-AI/](./scenarios/read-and-parse-GS1-AI/) — Example showing GS1 AI parsing and data extraction.
74160
- [scan-qr-code/](./scenarios/scan-qr-code/) — QR code targeted demo and settings.
75161
- [scan-common-1D-and-2D/](./scenarios/scan-common-1D-and-2D/) — Demo configured to detect a wide range of barcode formats.
76162
- [scan-common-2D-codes/](./scenarios/scan-common-2D-codes/) — Focused on common 2D barcode formats decoding.
77163
- [scan-datamatrix-code/](./scenarios/scan-datamatrix-code/) — DataMatrix code targeted demo with optimized settings.
164+
- [scan-dpm-codes/](./scenarios/scan-dpm-codes/) — Demo for reading Direct Part Mark (DPM) codes etched or marked on surfaces.
78165
- [scan-1D-Retail/](./scenarios/scan-1D-Retail/) — 1D retail barcode tuning example.
79166
- [scan-1D-Industrial/](./scenarios/scan-1D-Industrial/) — 1D industrial barcode tuning example.
80167
- [scan-from-distance/](./scenarios/scan-from-distance/) — Demo for scanning barcodes from a distance (zoom/ROI tuning).
@@ -83,4 +170,4 @@ If you have any questions, feel free to [contact Dynamsoft support](https://www.
83170

84171
### Official Online Demo
85172

86-
- [**Official Online Demo**](https://demo.dynamsoft.com/barcode-reader-js): Official demo for Dynamsoft Barcode Reader JavaScript Edition (written in Vue). Take our barcode scanner demo and see how it works in different modes!
173+
- [**Official Online Demo**](https://demo.dynamsoft.com/barcode-reader-js): Try the Dynamsoft Barcode Reader JavaScript Edition demo (written in Vue) and see how it works in different modes!

‎frameworks/angular/scan-using-foundational-api/package.json‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -10,23 +10,23 @@
1010
},
1111
"private": true,
1212
"dependencies": {
13-
"@angular/animations": "19.2.18",
14-
"@angular/common": "19.2.18",
15-
"@angular/compiler": "19.2.18",
16-
"@angular/core": "19.2.18",
17-
"@angular/forms": "19.2.18",
18-
"@angular/platform-browser": "19.2.18",
19-
"@angular/platform-browser-dynamic": "19.2.18",
20-
"@angular/router": "19.2.18",
13+
"@angular/animations": "19.2.19",
14+
"@angular/common": "19.2.19",
15+
"@angular/compiler": "19.2.19",
16+
"@angular/core": "19.2.19",
17+
"@angular/forms": "19.2.19",
18+
"@angular/platform-browser": "19.2.19",
19+
"@angular/platform-browser-dynamic": "19.2.19",
20+
"@angular/router": "19.2.19",
2121
"dynamsoft-barcode-reader-bundle": "11.2.4000",
2222
"rxjs": "~7.8.0",
2323
"tslib": "^2.3.0",
2424
"zone.js": "~0.15.0"
2525
},
2626
"devDependencies": {
27-
"@angular-devkit/build-angular": "19.2.18",
28-
"@angular/cli": "19.2.18",
29-
"@angular/compiler-cli": "19.2.18",
27+
"@angular-devkit/build-angular": "19.2.19",
28+
"@angular/cli": "19.2.19",
29+
"@angular/compiler-cli": "19.2.19",
3030
"@types/jasmine": "~5.1.0",
3131
"jasmine-core": "~5.1.0",
3232
"karma": "~6.4.0",

‎frameworks/angular/scan-using-foundational-api/src/app/dynamsoft.config.ts‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,7 @@ CoreModule.engineResourcePaths.rootDirectory = 'https://cdn.jsdelivr.net/npm/';
77
* To use the library, you need to first specify a license key using the API "initLicense()" as shown below.
88
*/
99

10-
LicenseManager.initLicense('DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9', {
11-
executeNow: true,
12-
});
10+
LicenseManager.initLicense('DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9', { executeNow: true });
1311

1412
/**
1513
* You can visit https://www.dynamsoft.com/customer/license/trialLicense?utm_source=samples&product=dbr&package=js to get your own trial license good for 30 days.

‎frameworks/angular/scan-using-rtu-api/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# 📦 Scan Single Barcode - Angular
22

3-
This sample shows how to integrate the `BarcodeScanner` from the [Dynamsoft Barcode Reader JavaScript SDK](https://www.dynamsoft.com/barcode-reader/overview/javascript/) in an **Angular** project for scanning a single barcode from live video.
3+
This sample shows how to integrate the `BarcodeScanner` from the [Dynamsoft Barcode Reader JavaScript SDK](https://www.dynamsoft.com/barcode-reader/sdk-javascript/) in an **Angular** project for scanning a single barcode from live video.
44

55
## ✨ Features
66

‎frameworks/angular/scan-using-rtu-api/src/app/app.component.css‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,6 @@
11
.barcode-scanner-hello-world-page {
22
width: 100%;
33
height: 100%;
4-
text-align: center;
54
}
65

76
.barcode-scanner-title {

‎frameworks/angular/scan-using-rtu-api/src/app/app.component.ts‎

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { Component, ElementRef, ViewChild } from '@angular/core';
2-
import { BarcodeScanner, BarcodeScannerConfig } from 'dynamsoft-barcode-reader-bundle';
2+
import { BarcodeScanner, BarcodeScannerConfig, EnumScanMode } from 'dynamsoft-barcode-reader-bundle';
33

44
@Component({
55
selector: 'app-root',
@@ -20,11 +20,18 @@ export class AppComponent {
2020

2121
// Specify where to render the scanner UI
2222
// If container is not specified, the UI will take up the full screen
23-
container: this.barcodeScannerViewRef.nativeElement,
23+
container: this.barcodeScannerViewRef.nativeElement,
2424

2525
// Specify the path for the definition file "barcode-scanner.ui.xml" for the scanner view.
2626
uiPath: "https://cdn.jsdelivr.net/npm/dynamsoft-barcode-reader-bundle@11.2.4000/dist/ui/barcode-scanner.ui.xml",
2727

28+
/*
29+
scanMode controls the scanning behavior:
30+
- SM_MULTI_UNIQUE: Continuously scans and collects each unique barcode.
31+
- SM_SINGLE: Stops scanning after the first barcode is detected.
32+
*/
33+
scanMode: EnumScanMode.SM_MULTI_UNIQUE,
34+
2835
// showUploadImageButton: true,
2936
// scannerViewConfig: {
3037
// showFlashButton: true,
@@ -35,6 +42,9 @@ export class AppComponent {
3542
engineResourcePaths: {
3643
rootDirectory: "https://cdn.jsdelivr.net/npm/",
3744
},
45+
46+
// The watermark can be removed via showPoweredByDynamsoft configuration option.
47+
// showPoweredByDynamsoft: false,
3848
}
3949

4050
// Create an instance of the BarcodeScanner with the provided configuration
@@ -46,7 +56,7 @@ export class AppComponent {
4656
alert(result.barcodeResults[0].text);
4757
}
4858
}
49-
async ngOnDestroy(): Promise<void> {
59+
async ngOnDestroy(): Promise<void> {
5060
// Dispose of the barcode scanner when the component unmounts
5161
this.barcodeScanner?.dispose();
5262
}

‎frameworks/blazor/scan-using-foundational-api/hello-world-blazor/BlazorApp/wwwroot/decodeVideo.js‎

Lines changed: 58 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,73 @@
11
// Create JS function "startVideoDecode"
22
window.startVideoDecode = async () => {
3-
const cameraViewContainer = document.getElementById("camera-view-container");
4-
const resultsContainer = document.getElementById("results");
3+
const cameraViewContainer = document.getElementById("camera-view-container");
4+
const resultsContainer = document.getElementById("results");
55

6-
try {
7-
// Create a `CameraEnhancer` instance for camera control and a `CameraView` instance for UI control.
8-
const cameraView = await Dynamsoft.DCE.CameraView.createInstance();
9-
cameraEnhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance(cameraView);
10-
// Get default UI and append it to DOM.
11-
cameraViewContainer.style.display = "block"
12-
cameraViewContainer.append(cameraView.getUIElement());
6+
try {
7+
// Create a `CameraEnhancer` instance for camera control and a `CameraView` instance for UI control.
8+
const cameraView = await Dynamsoft.DCE.CameraView.createInstance();
9+
cameraEnhancer = await Dynamsoft.DCE.CameraEnhancer.createInstance(cameraView);
10+
// Get default UI and append it to DOM.
11+
cameraViewContainer.style.display = "block"
12+
cameraViewContainer.append(cameraView.getUIElement());
1313

14-
// Create a `CaptureVisionRouter` instance and set `CameraEnhancer` instance as its image source.
15-
cvRouter = await Dynamsoft.CVR.CaptureVisionRouter.createInstance();
16-
cvRouter.setInput(cameraEnhancer);
14+
// Hide the "Powered by Message" overlay on the scanner view
15+
// cameraView.setPowerByMessageVisible(false);
1716

18-
// Define a callback for results.
19-
cvRouter.addResultReceiver({
20-
onDecodedBarcodesReceived: (result) => {
21-
if (!result.barcodeResultItems.length) return;
17+
// Create a `CaptureVisionRouter` instance and set `CameraEnhancer` instance as its image source.
18+
cvRouter = await Dynamsoft.CVR.CaptureVisionRouter.createInstance();
19+
cvRouter.setInput(cameraEnhancer);
2220

23-
resultsContainer.textContent = "";
24-
for (let item of result.barcodeResultItems) {
25-
resultsContainer.textContent += `${item.formatString}: ${item.text}\n\n`;
26-
}
27-
},
28-
});
21+
// Define a callback for results.
22+
cvRouter.addResultReceiver({
23+
onDecodedBarcodesReceived: (result) => {
24+
if (!result.barcodeResultItems.length) return;
2925

30-
// Filter out unchecked and duplicate results.
31-
const filter = new Dynamsoft.Utility.MultiFrameResultCrossFilter();
32-
// Filter out unchecked barcodes.
33-
filter.enableResultCrossVerification("barcode", true);
34-
// Filter out duplicate barcodes within 3 seconds.
35-
filter.enableResultDeduplication("barcode", true);
36-
await cvRouter.addResultFilter(filter);
26+
resultsContainer.textContent = "";
27+
for (let item of result.barcodeResultItems) {
28+
resultsContainer.textContent += `${item.formatString}: ${item.text}\n\n`;
29+
}
30+
},
31+
});
3732

38-
// Open camera and start scanning barcode.
39-
await cameraEnhancer.open();
40-
41-
cameraView.setScanLaserVisible(true);
42-
await cvRouter.startCapturing("ReadBarcodes_SpeedFirst");
43-
} catch (ex) {
44-
let errMsg = ex.message || ex;
45-
console.error(ex);
46-
}
33+
// Filter out unchecked and duplicate results.
34+
const filter = new Dynamsoft.Utility.MultiFrameResultCrossFilter();
35+
// Filter out unchecked barcodes.
36+
filter.enableResultCrossVerification("barcode", true);
37+
// Filter out duplicate barcodes within 3 seconds.
38+
filter.enableResultDeduplication("barcode", true);
39+
await cvRouter.addResultFilter(filter);
40+
41+
// Open camera and start scanning barcode.
42+
await cameraEnhancer.open();
43+
44+
cameraView.setScanLaserVisible(true);
45+
await cvRouter.startCapturing("ReadBarcodes_SpeedFirst");
46+
} catch (ex) {
47+
let errMsg = ex.message || ex;
48+
console.error(ex);
49+
}
4750
}
4851

4952
// Create JS function "stopVideoDecode"
5053
window.stopVideoDecode = async () => {
51-
const cameraViewContainer = document.getElementById("camera-view-container");
52-
const resultsContainer = document.getElementById("results");
54+
const cameraViewContainer = document.getElementById("camera-view-container");
55+
const resultsContainer = document.getElementById("results");
5356

54-
try {
55-
if (!cvRouter?.disposed) {
56-
await cvRouter?.dispose();
57-
}
58-
if (!cameraEnhancer?.disposed) {
59-
await cameraEnhancer?.dispose();
60-
}
61-
62-
// Reset components
63-
cameraViewContainer.style.display = "none";
64-
cameraViewContainer.innerHTML = "";
65-
resultsContainer.textContent = "";
66-
} catch (ex) {
67-
let errMsg = ex.message || ex;
68-
console.error(ex);
57+
try {
58+
if (!cvRouter?.disposed) {
59+
await cvRouter?.dispose();
6960
}
61+
if (!cameraEnhancer?.disposed) {
62+
await cameraEnhancer?.dispose();
63+
}
64+
65+
// Reset components
66+
cameraViewContainer.style.display = "none";
67+
cameraViewContainer.innerHTML = "";
68+
resultsContainer.textContent = "";
69+
} catch (ex) {
70+
let errMsg = ex.message || ex;
71+
console.error(ex);
72+
}
7073
}

0 commit comments

Comments
 (0)