Skip to content

user-guide.md

Latest commit

 

History

History
182 lines (136 loc) · 7.5 KB

user-guide.md

File metadata and controls

182 lines (136 loc) · 7.5 KB

Build a Web-Based Barcode Scanner Using Just a Few Lines of JavaScript

This user guide provides a step-by-step walkthrough of a "Hello World" web application using the BarcodeScanner JavaScript Edition.

The BarcodeScanner class offers:

  • 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

We recommend using this guide as a reference when creating your own application. If you are looking for a fully customizable barcode decoding library, you are welcome to use the Foundational APIs.

Requirements:

License

A license key is required to use the SDK. Get a 30-day free trial license at: https://www.dynamsoft.com/customer/license/trialLicense?product=dbr&package=js

Quick Start: Hello World Examples

Scan a Single Barcode via Camera

▶ Try it on JSFiddle

<!DOCTYPE html>
<html>
<head>
    <title>Barcode Scanner</title>
    <script src="https://cdn.jsdelivr.net/npm/dynamsoft-barcode-reader-bundle@11.4.2001/dist/dbr.bundle.js"></script>
</head>
<body>
    <script>
        // Use your 30-day free trial license if you already have one, or obtain one at: https://www.dynamsoft.com/customer/license/trialLicense?product=dbr&package=js
        // new Dynamsoft.BarcodeScanner({license:"YOUR_LICENSE_KEY_HERE"}).launch().then(result=>alert(result.barcodeResults[0].text));
        new Dynamsoft.BarcodeScanner().launch().then(result=>alert(result.barcodeResults[0].text));
    </script>
</body>
</html>

Scan Multiple Barcodes Continuously

▶ Try it on JSFiddle

<!DOCTYPE html>
<html>
<head>
    <title>Barcode Scanner - Multi</title>
    <script src="https://cdn.jsdelivr.net/npm/dynamsoft-barcode-reader-bundle@11.4.2001/dist/dbr.bundle.js"></script>
</head>
<body>
    <script>
        // Use your 30-day free trial license if you already have one, or obtain one at: https://www.dynamsoft.com/customer/license/trialLicense?product=dbr&package=js
        // new Dynamsoft.BarcodeScanner({license:"YOUR_LICENSE_KEY_HERE",...}).launch();
        new Dynamsoft.BarcodeScanner({
            scanMode: Dynamsoft.EnumScanMode.SM_MULTI_UNIQUE,
            onUniqueBarcodeScanned: (result) => console.log(`[${result.formatString}] ${result.text}`)
        }).launch();
    </script>
</body>
</html>

Building a Multi-Barcode Scanner Step by Step

This section breaks down the Scan Multiple Barcodes example above, explaining each part in detail.

Step 1: Setting up the HTML and Including the SDK

Include the SDK in your HTML page:

<!DOCTYPE html>
<html>
<head>
    <title>Barcode Scanner - Multi</title>
    <script src="https://cdn.jsdelivr.net/npm/dynamsoft-barcode-reader-bundle@11.4.2001/dist/dbr.bundle.js"></script>
</head>
<body>
</body>
</html>

The example uses jsDelivr CDN. For other options, see Appendix: Installation Options.

Step 2: Initializing the Barcode Scanner

Create a BarcodeScanner instance with a BarcodeScannerConfig. This example uses three key properties—see the API reference for all available options:

// Use your 30-day free trial license if you already have one, or obtain one at: https://www.dynamsoft.com/customer/license/trialLicense?product=dbr&package=js
const barcodeScanner = new Dynamsoft.BarcodeScanner({
    license: "YOUR_LICENSE_KEY_HERE",
    scanMode: Dynamsoft.EnumScanMode.SM_MULTI_UNIQUE,
    onUniqueBarcodeScanned: (result) => {
        console.log(`[${result.formatString}] ${result.text}`);
    }
});
  • scanMode: SM_MULTI_UNIQUE — Keeps the scanner open and collects unique barcodes (deduplicated by format + text within a 3-second window). See scanMode in the API Reference.
  • onUniqueBarcodeScanned — Callback fires each time a new unique barcode is detected

For help obtaining a license, see the License section.

Step 3: Launching the Barcode Scanner

barcodeScanner.launch();

That's it! When launch() is called, the scanner opens its built-in UI and begins scanning. In SM_MULTI_UNIQUE mode:

  • The scanner stays open and continuously scans for barcodes
  • Each time a new unique barcode is detected, the onUniqueBarcodeScanned callback fires
  • The scanner closes when the user clicks the close button

Note

After closing the scanner, the page will be empty. In a production app, you may want to provide a button to reopen the scanner or navigate to another view.

Next Steps

  1. Learn how to Customize the Barcode Scanner
  2. Check out the RTU API Samples and Demo
  3. Learn about the BarcodeScanner API

Appendix: Installation Options

CDN

The simplest way to include the SDK is via jsDelivr or UNPKG:

<!-- jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/dynamsoft-barcode-reader-bundle@11.4.2001/dist/dbr.bundle.js"></script>

<!-- UNPKG -->
<script src="https://unpkg.com/dynamsoft-barcode-reader-bundle@11.4.2001/dist/dbr.bundle.js"></script>

npm / yarn

For frameworks like React, Vue, or Angular, install via package manager:

npm i dynamsoft-barcode-reader-bundle@11.4.2001
# or
yarn add dynamsoft-barcode-reader-bundle@11.4.2001

Note

When using npm/yarn, you need to configure engineResourcePaths to specify where the SDK's engine files are located. See the frameworks samples or engineResourcePaths API for details.

Self-Hosting

Download the SDK, copy the dist folder to your server, and include it:

<!-- Adjust the path based on where you host the dist folder -->
<script src="assets/dynamsoft-barcode-reader/dist/dbr.bundle.js"></script>