Skip to content

Commit b4460af

Browse files
Tom-DynamsoftTom-Dynamsoft
committed
Revise ZIP package guide based on DX audit review
- Replace inline Quick Start code with reference to samples/hello-world.html (CDN-loaded samples work with double-click; local dist/ requires a web server) - Fix Self-Hosting section: rename to "Deploying to Your Server", fix engineResourcePaths pointing to CDN instead of local path, provide full working HTML example with context - Add CDN vs local guidance: explain standalone/scenario samples (switch script tag) vs framework samples (update engineResourcePaths) - Expand RTU acronym, list all 14 frameworks and scenario categories - Fix secure context note to cover both camera and license - Fix copyright, capitalization, and formatting nits
1 parent 3d1a21a commit b4460af

1 file changed

Lines changed: 55 additions & 55 deletions

File tree

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

Lines changed: 55 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
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

@@ -11,11 +11,10 @@ Welcome! This package contains all resource files related to **Dynamsoft Barcode
1111
When deploying your application / website for production, make sure to serve it via a secure HTTPS connection. This is required for two reasons:
1212

1313
- Access to the camera video stream is only granted in a security context. Most browsers impose this restriction.
14-
15-
> Some browsers like Chrome may grant the 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.
16-
1714
- Dynamsoft License requires a secure context to work.
1815

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+
1918
### Browser Compatibility
2019

2120
The following table is a list of supported browsers based on the above requirements:
@@ -27,7 +26,7 @@ The following table is a list of supported browsers based on the above requireme
2726
| Edge | v79+ |
2827
| Safari | v14.5+ |
2928

30-
<sup>1</sup> devices running iOS needs to be on iOS 14.5+ for camera video streaming to work in Chrome, Firefox or other Apps using webviews.
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.
3130

3231
Apart from the browsers, the operating systems may impose some limitations of their own that could restrict the use of the SDK.
3332

@@ -46,47 +45,38 @@ Dynamsoft provides a complimentary trial license for the SDK. When you download
4645

4746
## Quick Start
4847

49-
1. Create a new text file in the same directory as this file
50-
2. Copy the code below into the file
51-
3. Rename the file extension to `.html` and save it
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.
5249

53-
Double-click the file to open it in your browser, you'll instantly see a fully functional web application that scans a single barcode using your device's camera!
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).
5452
55-
```html
56-
<!DOCTYPE html>
57-
<html>
58-
<head>
59-
<title>Barcode Scanner</title>
60-
<script src="./dist/dbr.bundle.js"></script>
61-
</head>
62-
<body>
63-
<script>
64-
// 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.
65-
// Note that if you downloaded this sample from Dynamsoft while logged in, the license key below may already be your own 30-day trial license.
66-
new Dynamsoft.BarcodeScanner({license:"DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9"}).launch().then(result=>alert(result.barcodeResults[0].text));
67-
</script>
68-
</body>
69-
</html>
70-
```
53+
---
7154

7255
## How to Run the Samples
7356

74-
### 1. Unzip the Sample Files
57+
### 1. Unzip the Package
7558

76-
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
7765

7866
### 2. Open the Samples in a Browser
7967

8068
To explore the full set of available samples, open the `samples/index.html` file in your browser.
8169

82-
>[!IMPORTANT]
83-
> 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.
8474
85-
Here are a couple of easy ways to start one:
75+
Here are a couple of easy ways to start a local web server:
8676

8777
- Using Five Server VSCode extension
8878

89-
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.
9080

9181
- Using Node.js and `serve`
9282

@@ -97,13 +87,7 @@ Here are a couple of easy ways to start one:
9787
npx serve . -l 8000
9888
```
9989

100-
Once the server is running, open your browser and navigate to:
101-
102-
```bash
103-
http://localhost:8000
104-
```
105-
106-
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.
10791
10892
>[!TIP]
10993
> Don't want to set up a local server? You can view the latest version of our samples hosted on the Dynamsoft server here:
@@ -115,19 +99,19 @@ Here are a couple of easy ways to start one:
11599

116100
The package includes two main sample directories:
117101

118-
- **`frameworks/`** - Framework-specific examples demonstrating 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`) showing practical integration patterns.
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.
119103

120-
- **`scenarios/`** - Focused scenario samples that show common real-world uses of the Dynamsoft Barcode Reader.
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).
121105
122106
---
123107
124108
## Choosing an API
125109
126110
The SDK provides two approaches for integrating barcode scanning capabilities:
127111
128-
### RTU API (BarcodeScanner)
112+
### Ready-To-Use (RTU) API — BarcodeScanner
129113
130-
The RTU API offers the quickest path to a working barcode scanner(**Recommended for most users**):
114+
The RTU API offers the quickest path to a working barcode scanner (**Recommended for most users**):
131115
132116
- **One-line integration** – Launch a full scanner with a single API call
133117
- **Built-in UI** – Pre-designed viewfinder and scan region highlighting
@@ -139,25 +123,41 @@ If you are looking for a fully customizable barcode decoding library with comple
139123
140124
---
141125
142-
## Self-Hosting Resources
126+
## Deploying to Your Server
143127
144-
If you prefer to host the SDK resources on your own server instead of using a CDN:
128+
When you're ready to deploy your application to production, copy the `dist` folder to your server and reference it in your project:
145129

146130
1. Copy the `dist` folder to your server
147-
2. Include the script in your HTML:
131+
2. Include the script and configure the SDK to load all resources locally:
148132

149133
```html
150-
<!-- Adjust the path based on where you host the dist folder -->
151-
<script src="assets/dynamsoft-barcode-reader/dist/dbr.bundle.js"></script>
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>
152158
```
153159
154-
3. Define the resource paths in your code:
155-
156-
```ts
157-
engineResourcePaths: {
158-
rootDirectory: "https://cdn.jsdelivr.net/npm/",
159-
}
160-
```
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).
161161
162162
---
163163
@@ -178,4 +178,4 @@ For more information about the resource files in the `dist/` directory, please r
178178
179179
If you run into any issues, please feel free to contact us at support@dynamsoft.com.
180180
181-
Copyright Dynamsoft Corporation. All rights reserved.
181+
Copyright © 2025 Dynamsoft Corporation. All rights reserved.

0 commit comments

Comments
 (0)