Skip to content

Commit acab784

Browse files
Justin-dynamsoftJustin-dynamsoft
authored
Merge pull request #493 from dynamsoft-docs/preview
Preview
2 parents 10c2fc2 + 9747835 commit acab784

3 files changed

Lines changed: 135 additions & 32 deletions

File tree

‎programming/javascript/user-guide/foundational-api.md‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ In this guide, you will learn step by step on how to integrate the DBR-JS SDK in
3333

3434
<span style="font-size:20px">Table of Contents</span>
3535

36-
- [Barcode Reader for Your Website - User Guide](#barcode-reader-for-your-website---user-guide)
36+
- [Barcode Reader for Your Website - Foundational API Guide](#barcode-reader-for-your-website---foundational-api-guide)
3737
- [Hello World - Simplest Implementation](#hello-world---simplest-implementation)
3838
- [Understand the code](#understand-the-code)
3939
- [About the code](#about-the-code)
@@ -272,9 +272,6 @@ Besides using the public CDN, you can also download the SDK and host its files o
272272
273273
```sh
274274
npm i dynamsoft-barcode-reader-bundle@11.2.4000 -E
275-
# Compared with using CDN, you need to set up more resources.
276-
npm i dynamsoft-capture-vision-std@1.4.21 -E
277-
npm i dynamsoft-image-processing@2.4.31 -E
278275
```
279276
280277
The resources are located at the path `node_modules/<pkg>`, without `@<version>`. You must copy "dynamsoft-xxx" packages elsewhere and add `@<version>`. The `<version>` 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.

‎programming/javascript/user-guide/use-in-framework.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ CoreModule.engineResourcePaths.rootDirectory = '../assets/dist';
8989
9090
> Note:
9191
>
92-
> We recommend not renaming any module files within the `./dist` directory, as this may cause the rootDirectory configuration to not work properly. In such cases, you would need to define resource paths for each module individually.
92+
> We recommend not renaming any module files within the `./dist` directory, as this may cause the rootDirectory configuration to not work properly. You can copy “dynamsoft-barcode-reader-bundle” package elsewhere and add `@<version>`. The `<version>` can be obtained from package.json
9393
> In our case the packages are used only as static resources, we recommend moving the `./dist` to a dedicated folder for static resources in your project to facilitate self-hosting.
9494
9595
Next, we will demonstrate how to introduce `dynamsoft.config.ts` into a specific component. Don't skip the [Component for Reading Image](#component-for-reading-image) section even if you only need video barcode decoding.

‎programming/javascript/user-guide/zip-guide.md‎

Lines changed: 133 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,82 @@
1-
# Dynamsoft Barcode Reader JavaScript - Package Readme
1+
# Dynamsoft Barcode Reader JavaScript - ZIP Package Guide
22

33
Welcome! This package contains all resource files related to **Dynamsoft Barcode Reader JavaScript SDK**, and sample projects demonstrating how to use it.
44

55
---
66

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 test.
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+
Dynamsoft provides a complimentary trial license for the SDK. When you download the SDK package from the Dynamsoft website, after creating a Dynamsoft account, the following license will have a 30-day free trial:
38+
39+
`DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9`
40+
41+
>[!IMPORTANT]
42+
> 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=installer&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.
43+
44+
---
45+
46+
## Quick Start
47+
48+
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.
49+
50+
>[!NOTE]
51+
> 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).
52+
53+
---
54+
755
## How to Run the Samples
856

9-
### 1. Unzip the Sample Files
57+
### 1. Unzip the Package
1058

11-
After unzipping, you should see two folders: `dist`, which contains all the Barcode Reader JavaScript SDK resources, and `samples`, which includes subfolders for the individual sample projects.
59+
After unzipping, you should see the following structure:
60+
61+
- `dist/` — All Barcode Reader JavaScript SDK resources (`.js`, `.wasm`, worker files, etc.)
62+
- `samples/` — Sample projects, including standalone examples (`hello-world.html`, `read-an-image.html`), framework integrations, and scenario demos
63+
- `LICENSE` — Dynamsoft license terms
64+
- `LEGAL.txt` — Third-party license notices
1265

1366
### 2. Open the Samples in a Browser
1467

15-
To explore the full set of available samples, open the `index.html` file in your browser.
68+
To explore the full set of available samples, open the `samples/index.html` file in your browser.
1669

17-
>[!IMPORTANT]
18-
> Some browsers block local file access for security reasons. To avoid these restrictions, run the samples through a local web server.
70+
>[!NOTE]
71+
> The included samples load from a CDN by default. To use the local `dist/` folder instead, a web server is required (the browser blocks local file fetches over `file:///`):
72+
> - **Standalone & scenario samples**: Switch to the commented-out `<script>` tag that points to the local `dist/` folder. No other changes are needed — the SDK infers resource paths from the script tag location.
73+
> - **Framework samples**: These use npm imports and explicitly set `engineResourcePaths` to a CDN URL. Update `engineResourcePaths.rootDirectory` to point to the local `dist/` folder.
1974
20-
Here are a couple of easy ways to start one:
75+
Here are a couple of easy ways to start a local web server:
2176

2277
- Using Five Server VSCode extension
2378

24-
If you are using VS Code, simply install the [Five Server extension](https://marketplace.visualstudio.com/items?itemName=yandeu.five-server), open the `Samples` folder in the editor, and click "Go Live" in the bottom right corner of the editor. This will serve the sample project at http://127.0.0.1:5500/index.html.
79+
If you are using VS Code, simply install the [Five Server extension](https://marketplace.visualstudio.com/items?itemName=yandeu.five-server), open the `samples` folder in the editor, and click "Go Live" in the bottom right corner of the editor. This will serve the sample project at http://127.0.0.1:5500/index.html.
2580

2681
- Using Node.js and `serve`
2782

@@ -32,13 +87,7 @@ Here are a couple of easy ways to start one:
3287
npx serve . -l 8000
3388
```
3489

35-
Once the server is running, open your browser and navigate to:
36-
37-
```bash
38-
http://localhost:8000
39-
```
40-
41-
You'll see the `index.html` page, which links to all sample pages.
90+
Once the server is running, open your browser and navigate to `http://localhost:8000`. You'll see the `index.html` page, which links to all sample pages.
4291
4392
>[!TIP]
4493
> Don't want to set up a local server? You can view the latest version of our samples hosted on the Dynamsoft server here:
@@ -48,8 +97,69 @@ Here are a couple of easy ways to start one:
4897

4998
## Sample Folders
5099

51-
- `frameworks/` - This directory contains framework-specific examples demonstrating how to integrate the Dynamsoft Barcode Reader (JavaScript edition) into common web and hybrid frameworks. Each framework folder contains one or more runnable sub-examples (for example, scan-using-foundational-api and/or scan-using-rtu-api) showing practical integration patterns.
52-
- `scenarios/` - This directory contains focused scenario samples that show common real-world uses of the Dynamsoft Barcode Reader (JavaScript edition).
100+
The package includes two main sample directories:
101+
102+
- **`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.
103+
104+
- **`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).
105+
106+
---
107+
108+
## Choosing an API
109+
110+
The SDK provides two approaches for integrating barcode scanning capabilities:
111+
112+
### Ready-To-Use (RTU) API — BarcodeScanner
113+
114+
The RTU API offers the quickest path to a working barcode scanner (**Recommended for most users**):
115+
116+
- **One-line integration** – Launch a full scanner with a single API call
117+
- **Built-in UI** – Pre-designed viewfinder and scan region highlighting
118+
- **Simple configuration** – Customize behavior through intuitive config objects
119+
120+
### Foundational APIs
121+
122+
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.
123+
124+
---
125+
126+
## Deploying to Your Server
127+
128+
When you're ready to deploy your application to production, copy the `dist` folder to your server and reference it in your project:
129+
130+
1. Copy the `dist` folder to your server
131+
2. Include the script and configure the SDK to load all resources locally:
132+
133+
```html
134+
<!DOCTYPE html>
135+
<html>
136+
<head>
137+
<title>Barcode Scanner</title>
138+
<!-- Adjust the path based on where you host the dist folder -->
139+
<script src="assets/dynamsoft-barcode-reader/dist/dbr.bundle.js"></script>
140+
</head>
141+
<body>
142+
<script>
143+
new Dynamsoft.BarcodeScanner({
144+
license: "YOUR-LICENSE-KEY",
145+
engineResourcePaths: {
146+
rootDirectory: "assets/dynamsoft-barcode-reader/dist/"
147+
}
148+
}).launch().then(result => {
149+
if (result.barcodeResults.length) {
150+
alert(result.barcodeResults[0].text);
151+
} else {
152+
alert("No barcode found");
153+
}
154+
});
155+
</script>
156+
</body>
157+
</html>
158+
```
159+
160+
> When loading the SDK via a `<script>` tag, `engineResourcePaths` is optional — the SDK infers resource paths from the script tag location. It is required when using npm imports (e.g., in framework projects).
161+
162+
---
53163
54164
## Documentation
55165
@@ -58,18 +168,14 @@ For API reference and more advanced usage, visit:
58168
- [Barcode Scanner API Docs](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/barcode-scanner.html)
59169
- [Foundational API Docs](https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/index.html)
60170
61-
---
171+
For more information about the resource files in the `dist/` directory, please refer to:
62172
63-
## License
64-
65-
Dynamsoft provides a complimentary trial license for the SDK. When you download the SDK package from the Dynamsoft website, after creating a Dynamsoft account, the following license will have a 30-day free trial:
173+
- [What’s in the dist folder of dynamsoft-barcode-reader-bundle](https://www.dynamsoft.com/faq/barcode-reader/web/capabilities/what-is-in-the-dist-folder-of-dbr.html)
66174
67-
`DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9`
68-
69-
You can visit the Dynamsoft Customer Portal (https://www.dynamsoft.com/customer/license/trialLicense?product=dbr&utm_source=installer&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.
175+
---
70176
71-
## Contact
177+
## Support
72178
73-
If you run into any issues, please feel free to contact us at `support@dynamsoft.com`.
179+
If you run into any issues, please feel free to contact us at support@dynamsoft.com.
74180
75-
Copyright © Dynamsoft Corporation. All rights reserved.
181+
Copyright © 2026 Dynamsoft Corporation. All rights reserved.

0 commit comments

Comments
 (0)