From 3d1a21a5f15d54b5b612fc6abb1ede442ab2b4a4 Mon Sep 17 00:00:00 2001 From: Justin Date: Fri, 13 Feb 2026 14:26:41 +0800 Subject: [PATCH 1/5] Enhance zip guide with system requirements, browser compatibility, quick start instructions, and API options --- .../javascript/user-guide/zip-guide.md | 132 ++++++++++++++++-- 1 file changed, 119 insertions(+), 13 deletions(-) diff --git a/programming/javascript/user-guide/zip-guide.md b/programming/javascript/user-guide/zip-guide.md index 0ce8babc..61edf904 100644 --- a/programming/javascript/user-guide/zip-guide.md +++ b/programming/javascript/user-guide/zip-guide.md @@ -4,6 +4,71 @@ Welcome! This package contains all resource files related to **Dynamsoft Barcode --- +## System Requirements + +### Secure Context (HTTPS Deployment) + +When deploying your application / website for production, make sure to serve it via a secure HTTPS connection. This is required for two reasons: + +- Access to the camera video stream is only granted in a security context. Most browsers impose this restriction. + + > 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. + +- Dynamsoft License requires a secure context to work. + +### Browser Compatibility + +The following table is a list of supported browsers based on the above requirements: + +| Browser Name | Version | +| :----------: | :--------------: | +| Chrome | v78+1 | +| Firefox | v68+1 | +| Edge | v79+ | +| Safari | v14.5+ | + +1 devices running iOS needs to be on iOS 14.5+ for camera video streaming to work in Chrome, Firefox or other Apps using webviews. + +Apart from the browsers, the operating systems may impose some limitations of their own that could restrict the use of the SDK. + +--- + +## License + +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: + +`DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9` + +>[!IMPORTANT] +> 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. + +--- + +## Quick Start + +1. Create a new text file in the same directory as this file +2. Copy the code below into the file +3. Rename the file extension to `.html` and save it + +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! + +```html + + + + Barcode Scanner + + + + + + +``` + ## How to Run the Samples ### 1. Unzip the Sample Files @@ -12,7 +77,7 @@ After unzipping, you should see two folders: `dist`, which contains all the Barc ### 2. Open the Samples in a Browser -To explore the full set of available samples, open the `index.html` file in your browser. +To explore the full set of available samples, open the `samples/index.html` file in your browser. >[!IMPORTANT] > Some browsers block local file access for security reasons. To avoid these restrictions, run the samples through a local web server. @@ -48,8 +113,53 @@ Here are a couple of easy ways to start one: ## Sample Folders -- `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. -- `scenarios/` - This directory contains focused scenario samples that show common real-world uses of the Dynamsoft Barcode Reader (JavaScript edition). +The package includes two main sample directories: + +- **`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. + +- **`scenarios/`** - Focused scenario samples that show common real-world uses of the Dynamsoft Barcode Reader. + +--- + +## Choosing an API + +The SDK provides two approaches for integrating barcode scanning capabilities: + +### 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. + +--- + +## Self-Hosting Resources + +If you prefer to host the SDK resources on your own server instead of using a CDN: + +1. Copy the `dist` folder to your server +2. Include the script in your HTML: + +```html + + +``` + +3. Define the resource paths in your code: + +```ts +engineResourcePaths: { + rootDirectory: "https://cdn.jsdelivr.net/npm/", +} +``` + +--- ## Documentation @@ -58,18 +168,14 @@ 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: -## License - -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: +- [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) -`DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9` - -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. +--- -## Contact +## Support -If you run into any issues, please feel free to contact us at `support@dynamsoft.com`. +If you run into any issues, please feel free to contact us at support@dynamsoft.com. -Copyright © Dynamsoft Corporation. All rights reserved. \ No newline at end of file +Copyright Dynamsoft Corporation. All rights reserved. From b4460af5a80d887da297b492a1505bd9e14fe877 Mon Sep 17 00:00:00 2001 From: Tom Kent Date: Fri, 13 Feb 2026 14:04:15 -0800 Subject: [PATCH 2/5] 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 --- .../javascript/user-guide/zip-guide.md | 110 +++++++++--------- 1 file changed, 55 insertions(+), 55 deletions(-) diff --git a/programming/javascript/user-guide/zip-guide.md b/programming/javascript/user-guide/zip-guide.md index 61edf904..09dd3cb9 100644 --- a/programming/javascript/user-guide/zip-guide.md +++ b/programming/javascript/user-guide/zip-guide.md @@ -1,4 +1,4 @@ -# Dynamsoft Barcode Reader JavaScript - Package Readme +# Dynamsoft Barcode Reader JavaScript - ZIP Package Guide Welcome! This package contains all resource files related to **Dynamsoft Barcode Reader JavaScript SDK**, and sample projects demonstrating how to use it. @@ -11,11 +11,10 @@ Welcome! This package contains all resource files related to **Dynamsoft Barcode When deploying your application / website for production, make sure to serve it via a secure HTTPS connection. This is required for two reasons: - Access to the camera video stream is only granted in a security context. Most browsers impose this restriction. - - > 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. - - Dynamsoft License requires a secure context to work. +> 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. + ### Browser Compatibility 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 | Edge | v79+ | | Safari | v14.5+ | -1 devices running iOS needs to be on iOS 14.5+ for camera video streaming to work in Chrome, Firefox or other Apps using webviews. +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. Apart from the browsers, the operating systems may impose some limitations of their own that could restrict the use of the SDK. @@ -46,47 +45,38 @@ Dynamsoft provides a complimentary trial license for the SDK. When you download ## Quick Start -1. Create a new text file in the same directory as this file -2. Copy the code below into the file -3. Rename the file extension to `.html` and save it +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 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! +>[!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). -```html - - - - Barcode Scanner - - - - - - -``` +--- ## How to Run the Samples -### 1. Unzip the Sample Files +### 1. Unzip the Package -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. +After unzipping, you should see the following structure: + +- `dist/` — All Barcode Reader JavaScript SDK resources (`.js`, `.wasm`, worker files, etc.) +- `samples/` — Sample projects, including standalone examples (`hello-world.html`, `read-an-image.html`), framework integrations, and scenario demos +- `LICENSE` — Dynamsoft license terms +- `LEGAL.txt` — Third-party license notices ### 2. Open the Samples in a Browser To explore the full set of available samples, open the `samples/index.html` file in your browser. ->[!IMPORTANT] -> Some browsers block local file access for security reasons. To avoid these restrictions, run the samples through a local web server. +>[!NOTE] +> 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:///`): +> - **Standalone & scenario samples**: Switch to the commented-out ` + + + + Barcode Scanner + + + + + + + ``` -3. Define the resource paths in your code: - -```ts -engineResourcePaths: { - rootDirectory: "https://cdn.jsdelivr.net/npm/", -} -``` +> When loading the SDK via a `