diff --git a/.gitignore b/.gitignore index 516d053..bed50ce 100644 --- a/.gitignore +++ b/.gitignore @@ -45,7 +45,6 @@ yarn.lock /src /doc /Web.config -/samples.url /samples /temp /public diff --git a/Api Reference.url b/Api Reference.url index c790c25..ba9188f 100644 --- a/Api Reference.url +++ b/Api Reference.url @@ -1,2 +1,2 @@ [InternetShortcut] -URL=https://www.dynamsoft.com/help/Barcode-Reader-WASM/ \ No newline at end of file +URL=https://www.dynamsoft.com/barcode-reader/programming/javascript/api-reference/?ver=9.2.11 \ No newline at end of file diff --git a/README.md b/README.md index f28e0c0..42f9f69 100644 --- a/README.md +++ b/README.md @@ -1,56 +1,56 @@ -# Barcode Reader for Your Website +# Barcode Reader for Your Website - User Guide -[Dynamsoft Barcode Reader JavaScript Edition](https://www.dynamsoft.com/barcode-reader/sdk-javascript/) is equipped with industry-leading algorithms for exceptional speed, accuracy and read rates in barcode reading. With its well-designed API, you can turn your web page into a barcode scanner with just a few lines of code. +[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 integrated, your users can open your website in a browser, access their cameras and read barcodes directly from the video input. +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 this library into your website. +In this guide, you will learn step by step on how to integrate the DBR-JS SDK into your website. Table of Contents * [Hello World - Simplest Implementation](#hello-world---simplest-implementation) * [Building your own page](#building-your-own-page) - * [Include the library](#include-the-library) - * [Configure the library](#configure-the-library) - * [Interact with the library](#interact-with-the-library) + * [Include the SDK](#include-the-sdk) + * [Configure the SDK](#configure-the-sdk) + * [Interact with the SDK](#interact-with-the-sdk) * [Customize the UI](#customize-the-ui-optional) * [API Documentation](#api-documentation) * [System Requirements](#system-requirements) -* [Advanced Usage](#advanced-usage) * [How to Upgrade](#how-to-upgrade) +* [Next Steps](#next-steps) **Popular Examples** -* Hello World - [Guide](#hello-world---simplest-implementation) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.0.2/1.hello-world/1.hello-world.html) \| [Run](https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/1.hello-world.html?ver=9.0.2&utm_source=github) -* Angular App - [Guide](https://www.dynamsoft.com/barcode-reader/programming/javascript/samples-demos/helloworld-angular.html?ver=9.0.2&utm_source=github) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.0.2/1.hello-world/3.read-video-angular) \| [Run](https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/3.read-video-angular/dist/hello-world/?ver=9.0.2&utm_source=github) -* React App - [Guide](https://www.dynamsoft.com/barcode-reader/programming/javascript/samples-demos/helloworld-reactjs.html?ver=9.0.2&utm_source=github) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.0.2/1.hello-world/4.read-video-react) \| [Run](https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/4.read-video-react/build/?ver=9.0.2&utm_source=github) -* Vue App - [Guide](https://www.dynamsoft.com/barcode-reader/programming/javascript/samples-demos/helloworld-vuejsv3.html?ver=9.0.2&utm_source=github) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.0.2/1.hello-world/6.read-video-vue3) \| [Run](https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/6.read-video-vue3/dist/?ver=9.0.2&utm_source=github) -* PWA App - [Guide](https://www.dynamsoft.com/barcode-reader/programming/javascript/samples-demos/helloworld-pwa.html?ver=9.0.2&utm_source=github) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.0.2/1.hello-world/10.read-video-pwa) \| [Run](https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/10.read-video-pwa/helloworld-pwa.html?ver=9.0.2&utm_source=github) -* Read Driver Licenses - [Guide](https://www.dynamsoft.com/barcode-reader/programming/javascript/samples-demos/use-cases.html?ver=latest#read-the-pdf417-barcode-on-the-drivers-license?ver=9.0.2&utm_source=github) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.0.2/4.use-case/2.read-a-drivers-license.html) \| [Run](https://demo.dynamsoft.com/samples/dbr/js/4.use-case/2.read-a-drivers-license.html?ver=9.0.2&utm_source=github) -* Fill A Form - [Guide](https://www.dynamsoft.com/barcode-reader/programming/javascript/samples-demos/use-cases.html?ver=latest#read-barcodes-and-fill-form-fields?ver=9.0.2&utm_source=github) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.0.2/4.use-case/1.fill-a-form-with-barcode-reading.html) \| [Run](https://demo.dynamsoft.com/samples/dbr/js/4.use-case/1.fill-a-form-with-barcode-reading.html?ver=9.0.2&utm_source=github) +* Hello World - [Guide](#hello-world---simplest-implementation) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.2.11/1.hello-world/1.hello-world.html) \| [Run](https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/1.hello-world.html?ver=9.2.11&utm_source=github) +* Angular App - [Guide](https://www.dynamsoft.com/barcode-reader/programming/javascript/samples-demos/helloworld-angular.html?ver=9.2.11&utm_source=github) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.2.11/1.hello-world/3.read-video-angular) \| [Run](https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/3.read-video-angular/dist/hello-world/?ver=9.2.11&utm_source=github) +* React App - [Guide](https://www.dynamsoft.com/barcode-reader/programming/javascript/samples-demos/helloworld-reactjs.html?ver=9.2.11&utm_source=github) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.2.11/1.hello-world/4.read-video-react) \| [Run](https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/4.read-video-react/build/?ver=9.2.11&utm_source=github) +* Vue App - [Guide](https://www.dynamsoft.com/barcode-reader/programming/javascript/samples-demos/helloworld-vuejsv3.html?ver=9.2.11&utm_source=github) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.2.11/1.hello-world/6.read-video-vue3) \| [Run](https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/6.read-video-vue3/dist/?ver=9.2.11&utm_source=github) +* PWA App - [Guide](https://www.dynamsoft.com/barcode-reader/programming/javascript/samples-demos/helloworld-pwa.html?ver=9.2.11&utm_source=github) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.2.11/1.hello-world/10.read-video-pwa) \| [Run](https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/10.read-video-pwa/helloworld-pwa.html?ver=9.2.11&utm_source=github) +* Read Driver Licenses - [Guide](https://www.dynamsoft.com/barcode-reader/programming/javascript/samples-demos/use-cases.html?ver=latest#read-the-pdf417-barcode-on-the-drivers-license?ver=9.2.11&utm_source=github) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.2.11/4.use-case/2.read-a-drivers-license.html) \| [Run](https://demo.dynamsoft.com/samples/dbr/js/4.use-case/2.read-a-drivers-license.html?ver=9.2.11&utm_source=github) +* Fill A Form - [Guide](https://www.dynamsoft.com/barcode-reader/programming/javascript/samples-demos/use-cases.html?ver=latest#read-barcodes-and-fill-form-fields?ver=9.2.11&utm_source=github) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.2.11/4.use-case/1.fill-a-form-with-barcode-reading.html) \| [Run](https://demo.dynamsoft.com/samples/dbr/js/4.use-case/1.fill-a-form-with-barcode-reading.html?ver=9.2.11&utm_source=github) You can also: -* Try the Official Demo - [Run](https://demo.dynamsoft.com/barcode-reader-js/?ver=9.0.2&utm_source=github) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-demo/) -* Try Online Examples - [Run](https://demo.dynamsoft.com/Samples/DBR/JS/index.html?ver=9.0.2&utm_source=github) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-samples/tree/v9.0.2/) +* Try the Official Demo - [Run](https://demo.dynamsoft.com/barcode-reader-js/?ver=9.2.11&utm_source=github) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-demo/) +* Try Online Examples - [Run](https://demo.dynamsoft.com/Samples/DBR/JS/index.html?ver=9.2.11&utm_source=github) \| [Github](https://github.com/Dynamsoft/barcode-reader-javascript-samples/tree/v9.2.11/) ## Hello World - Simplest Implementation -Let's start with the "Hello World" example of the library which demonstrates how to use the minimum code to enable a web page to read barcodes from a live video stream. +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](#system-requirements) * Camera access -### Step One: Check the code of the example +### Understand the code The complete code of the "Hello World" example is shown below @@ -59,11 +59,11 @@ The complete code of the "Hello World" example is shown below
- + + ``` * UNPKG ```html - + ``` -#### Host the library yourself +#### Host the SDK yourself -Besides using the CDN, you can also download the library and host its files on your own website / server before including it in your application. +Besides using the CDN, you can also download the SDK and host its files on your own website / server before including it in your application. -Options to download the library: +Options to download the SDK: * From the website - Download the JavaScript Package + Download the JavaScript Package * yarn @@ -171,10 +171,10 @@ Options to download the library: npm install dynamsoft-javascript-barcode --save ``` -Depending on how you downloaded the library and where you put it, you can typically include it like this: +Depending on how you downloaded the SDK and how you intend to use it, you can typically include it like this: ```html - + ``` or @@ -183,42 +183,46 @@ or ``` -Read more on [how to host the library](https://www.dynamsoft.com/barcode-reader/programming/javascript/user-guide/advanced-usage.html?ver=9.0.2&utm_source=github&product=dbr&package=js#hosting-the-library). +or + +```ts +import { BarcodeScanner } from 'dynamsoft-javascript-barcode'; +``` -### Configure the library +### Configure the SDK -Before using the library, you need to configure a few things. +Before using the SDK, you need to configure a few things. #### Specify the license -The library requires a license to work, use the API `license` to specify a license key. +The SDK requires a license to work, use the API `license` to specify a license key. ```javascript Dynamsoft.DBR.BarcodeScanner.license = "YOUR-LICENSE-KEY"; ``` -To test the library, you can request a 30-day trial license via the [customer portal](https://www.dynamsoft.com/customer/license/trialLicense?ver=9.0.2&utm_source=github&product=dbr&package=js). +To test the SDK, you can request a 30-day trial license via the [customer portal](https://www.dynamsoft.com/customer/license/trialLicense?ver=9.2.11&utm_source=github&product=dbr&package=js). -> If you registered a Dynamsoft account and downloaded the library from the official website, Dynamsoft will generate a 30-day trial license for you and put the license key into all the samples that come with the library. +> If you registered a Dynamsoft account and downloaded the SDK from the official website, Dynamsoft will automatically generate a 30-day trial license for you and put the license key into all the samples that come with the SDK. #### Specify the location of the "engine" files This is usually only required with frameworks like Angular or React, etc. where dbr.js is compiled into another file. -The purpose is to tell the library where to find the engine files (\*.worker.js, \*.wasm.js and \*.wasm, etc.). The API is called `engineResourcePath`: +The purpose is to tell the SDK where to find the engine files (\*.worker.js, \*.wasm.js and \*.wasm, etc.). The API is called `engineResourcePath`: ```javascript //The following code uses the jsDelivr CDN, feel free to change it to your own location of these files -Dynamsoft.DBR.BarcodeScanner.engineResourcePath = "https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@9.0.2/dist/"; +Dynamsoft.DBR.BarcodeScanner.engineResourcePath = "https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@9.2.11/dist/"; ``` -### Interact with the library +### Interact with the SDK #### Create a `BarcodeScanner` object -You can use one of two classes ( `BarcodeScanner` and `BarcodeReader` ) to interact with the library. `BarcodeReader` is a low-level class that processes images directly. `BarcodeScanner` , on the other hand, inherits from `BarcodeReader` and provides high-level APIs and a built-in GUI to allow continuous barcode scanning on video frames. We'll focus on `BarcodeScanner` in this guide. +You can use one of two classes ( `BarcodeScanner` and `BarcodeReader` ) to interact with the SDK. `BarcodeReader` is a low-level class that processes images directly. `BarcodeScanner` , on the other hand, inherits from `BarcodeReader` and provides high-level APIs and a built-in GUI to allow continuous barcode scanning on video frames. We'll focus on `BarcodeScanner` in this guide. -To use the library, we first create a `BarcodeScanner` object. +To use the SDK, we first create a `BarcodeScanner` object. ```javascript Dynamsoft.DBR.BarcodeScanner.license = "YOUR-LICENSE-KEY"; @@ -258,16 +262,19 @@ await scanner.setResolution(1280, 720); ```javascript // Sets up the scanner behavior let scanSettings = await scanner.getScanSettings(); -// Disregards duplicated results found in a specified time period (in milliseconds) -scanSettings.duplicateForgetTime = 5000; -// Sets a scan interval in milliseconds so the library may release the CPU from time to time +// Disregards duplicated results found in a specified time period (in milliseconds). +scanSettings.duplicateForgetTime = 5000; // The default is 3000 +// Sets a scan interval in milliseconds so the SDK may release the CPU from time to time. // (setting this value larger is a simple way to save battery power and reduce device heating). -scanSettings.intervalTime = 100; +scanSettings.intervalTime = 100; // The default is 0. +// Sets captureAndDecodeInParallel to false, which tells the SDK not to acquire the next frame while decoding the first. +// This is another way to save battery power and is recommended on low-end phones. However, it does slow down the decoding speed. +scanSettings.captureAndDecodeInParallel = false; // The default is true. await scanner.updateScanSettings(scanSettings); ``` ```javascript -// Uses one of the built-in RuntimeSetting templates: "single" (decode a single barcode, the default mode), "speed", "balance" and "coverage" +// Uses one of the built-in RuntimeSetting templates: "single" (decode a single barcode, the default mode), "speed", "balance", "coverage", "dense" and "distance" await scanner.updateRuntimeSettings("speed"); // Makes changes to the template. The code below demonstrates how to specify enabled symbologies @@ -286,8 +293,6 @@ As you can see from the above code snippets, there are three types of configurat * `get/updateRuntimeSettings`: Configures the decode engine with either a built-in template or a comprehensive `RuntimeSettings` object. For example, the following uses the built-in "speed" settings with updated `localizationModes`. -> Find the full list of the runtime settings here. - ```javascript await barcodeScanner.updateRuntimeSettings("speed"); //await barcodeScanner.updateRuntimeSettings("balance"); //alternative @@ -303,7 +308,9 @@ As you can see from the above code snippets, there are three types of configurat Try in [JSFiddle](https://jsfiddle.net/DynamsoftTeam/f24h8c1m/). - See also [settings samples](https://www.dynamsoft.com/barcode-reader/programming/javascript/samples-demos/parameter-settings.html?ver=9.0.2&utm_source=github). + See also [settings samples](https://www.dynamsoft.com/barcode-reader/programming/javascript/samples-demos/parameter-settings.html?ver=9.2.11&utm_source=github). + +> Find the full list of the runtime settings here. ### Customize the UI (optional) @@ -332,7 +339,7 @@ The built-in UI of the `BarcodeScanner` object is defined in the file `dist/dbr. document.getElementsByClassName('dce-btn-close')[0].hidden = true; // Hide the close button ``` -* Build the UI element into your own web page and specify it with the API `setUIElement(HTMLElement)`. +* Build the UI element from scratch and connect it to the SDK with the API `setUIElement(HTMLElement)`. * Embed the video @@ -361,7 +368,7 @@ The built-in UI of the `BarcodeScanner` object is defined in the file `dist/dbr. * Add the camera list and resolution list - If the class names for these lists match the default ones, `dce-sel-camera` and `dce-sel-resolution` , the library will automatically populate the lists and handle the camera/resolution switching. + If the class names for these lists match the default ones, `dce-sel-camera` and `dce-sel-resolution` , the SDK will automatically populate the lists and handle the camera/resolution switching. ```html