dynamsoft-javascript-barcode
Version:
Dynamsoft Barcode Reader JS is a recognition SDK which enables you to embed barcode reading functionality in your web, desktop, and mobile applications. With a few lines of JavaScript code, you can develop a robust application to scan a linear barcode, QR
622 lines (582 loc) • 47.4 kB
HTML
<html>
<head>
<title></title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta charset="UTF-8">
<style type='text/css'>
body {
font: 400 16px/1.5 "Helvetica Neue", Helvetica, Arial, sans-serif;
color: #111;
background-color: #fbfbfb;
-webkit-text-size-adjust: 100%;
-webkit-font-feature-settings: "kern" 1;
-moz-font-feature-settings: "kern" 1;
-o-font-feature-settings: "kern" 1;
font-feature-settings: "kern" 1;
font-kerning: normal;
padding: 30px;
}
@media only screen and (max-width: 600px) {
body {
padding: 5px;
}
body>#content {
padding: 0px 20px 20px 20px ;
}
}
body>#content {
margin: 0px;
max-width: 900px;
border: 1px solid #e1e4e8;
padding: 10px 40px;
padding-bottom: 20px;
border-radius: 2px;
margin-left: auto;
margin-right: auto;
}
hr {
color: #bbb;
background-color: #bbb;
height: 1px;
flex: 0 1 auto;
margin: 1em 0;
padding: 0;
border: none;
}
/**
* Links
*/
a {
color: #0366d6;
text-decoration: none;
}
a:visited {
color: #0366d6;
}
a:hover {
color: #0366d6;
text-decoration: underline;
}
pre {
background-color: #f6f8fa;
border-radius: 3px;
font-size: 85%;
line-height: 1.45;
overflow: auto;
padding: 16px;
}
/**
* Code blocks
*/
code {
background-color: rgba(27, 31, 35, .05);
border-radius: 3px;
font-size: 85%;
margin: 0;
word-wrap: break-word;
padding: .2em .4em;
font-family: SFMono-Regular, Consolas, Liberation Mono, Menlo, Courier, monospace;
}
pre>code {
background-color: transparent;
border: 0;
display: inline;
line-height: inherit;
margin: 0;
overflow: visible;
padding: 0;
word-wrap: normal;
font-size: 100%;
}
/**
* Blockquotes
*/
blockquote {
margin-left: 30px;
margin-top: 0px;
margin-bottom: 16px;
border-left-width: 3px;
padding: 0 1em;
color: #828282;
border-left: 4px solid #e8e8e8;
padding-left: 15px;
font-size: 18px;
letter-spacing: -1px;
font-style: italic;
}
blockquote * {
font-style: normal ;
letter-spacing: 0;
color: #6a737d ;
}
/**
* Tables
*/
table {
border-spacing: 2px;
display: block;
font-size: 14px;
overflow: auto;
width: 100%;
margin-bottom: 16px;
border-spacing: 0;
border-collapse: collapse;
}
td {
padding: 6px 13px;
border: 1px solid #dfe2e5;
}
th {
font-weight: 600;
padding: 6px 13px;
border: 1px solid #dfe2e5;
}
tr {
background-color: #fff;
border-top: 1px solid #c6cbd1;
}
table tr:nth-child(2n) {
background-color: #f6f8fa;
}
/**
* Others
*/
img {
max-width: 100%;
}
p {
line-height: 24px;
font-weight: 400;
font-size: 16px;
color: #24292e;
}
ul {
margin-top: 0;
}
li {
color: #24292e;
font-size: 16px;
font-weight: 400;
line-height: 1.5;
}
li+li {
margin-top: 0.25em;
}
* {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
color: #24292e;
}
a:visited {
color: #0366d6;
}
h1,
h2,
h3 {
border-bottom: 1px solid #eaecef;
color: #111;
/* Darker */
}
code>* {
font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace ;
}
</style>
<style type='text/css'>pre code.hljs{display:block;overflow-x:auto;padding:1em}code.hljs{padding:3px 5px}.hljs{color:#383a42;background:#fafafa}.hljs-comment,.hljs-quote{color:#a0a1a7;font-style:italic}.hljs-doctag,.hljs-formula,.hljs-keyword{color:#a626a4}.hljs-deletion,.hljs-name,.hljs-section,.hljs-selector-tag,.hljs-subst{color:#e45649}.hljs-literal{color:#0184bb}.hljs-addition,.hljs-attribute,.hljs-meta .hljs-string,.hljs-regexp,.hljs-string{color:#50a14f}.hljs-attr,.hljs-number,.hljs-selector-attr,.hljs-selector-class,.hljs-selector-pseudo,.hljs-template-variable,.hljs-type,.hljs-variable{color:#986801}.hljs-bullet,.hljs-link,.hljs-meta,.hljs-selector-id,.hljs-symbol,.hljs-title{color:#4078f2}.hljs-built_in,.hljs-class .hljs-title,.hljs-title.class_{color:#c18401}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:700}.hljs-link{text-decoration:underline}</style>
</head>
<body>
<div id='content'>
<h1 id="barcode-reader-for-your-website---user-guide">Barcode Reader for Your Website - User Guide</h1>
<p><a href="https://www.dynamsoft.com/barcode-reader/sdk-javascript/">Dynamsoft Barcode Reader JavaScript Edition</a> (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.</p>
<p><img src="https://img.shields.io/npm/v/dynamsoft-javascript-barcode.svg" alt="version" /><br />
<img src="https://img.shields.io/npm/dm/dynamsoft-javascript-barcode.svg" alt="downloads" /><br />
<img src="https://img.shields.io/jsdelivr/npm/hm/dynamsoft-javascript-barcode.svg" alt="jsdelivr" /><br />
<img src="https://img.shields.io/snyk/vulnerabilities/npm/dynamsoft-javascript-barcode.svg" alt="vulnerabilities" /></p>
<p>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.</p>
<video controls width="400" autoplay="true">
<source src="https://tst.dynamsoft.com/public/docs/dbr/javascript/How%20to%20Use%20Dynamsoft%20Barcode%20Reader%20JavaScript%20SDK%20v1.1.mp4">
</video>
<p>In this guide, you will learn step by step on how to integrate the DBR-JS SDK into your website.</p>
<p><span style="font-size:20px">Table of Contents</span></p>
<ul>
<li><a href="#hello-world---simplest-implementation">Hello World - Simplest Implementation</a></li>
<li><a href="#understand-the-code">Understand the code</a></li>
<li><a href="#run-the-example">Run the example</a></li>
<li><a href="#building-your-own-page">Building your own page</a></li>
<li><a href="#include-the-sdk">Include the SDK</a></li>
<li><a href="#configure-the-sdk">Configure the SDK</a></li>
<li><a href="#interact-with-the-sdk">Interact with the SDK</a></li>
<li><a href="#customize-the-ui-optional">Customize the UI (optional)</a></li>
<li><a href="#api-documentation">API Documentation</a></li>
<li><a href="#system-requirements">System Requirements</a></li>
<li><a href="#how-to-upgrade">How to Upgrade</a></li>
<li><a href="#release-notes">Release Notes</a></li>
<li><a href="#next-steps">Next Steps</a></li>
</ul>
<p><strong>Popular Examples</strong></p>
<ul>
<li>Hello World - <a href="#hello-world---simplest-implementation">Guide</a> | <a href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.6.11/1.hello-world/1.hello-world.html">Github</a> | <a href="https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/1.hello-world.html?ver=9.6.11&utm_source=npm">Run</a></li>
<li>Angular App - <a href="https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/samples-demos/helloworld-angular.html?ver=9.6.11&utm_source=npm">Guide</a> | <a href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.6.11/1.hello-world/3.read-video-angular">Github</a> | <a href="https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/3.read-video-angular/dist/hello-world/?ver=9.6.11&utm_source=npm">Run</a></li>
<li>React App - <a href="https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/samples-demos/helloworld-reactjs.html?ver=9.6.11&utm_source=npm">Guide</a> | <a href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.6.11/1.hello-world/4.read-video-react">Github</a> | <a href="https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/4.read-video-react/build/?ver=9.6.11&utm_source=npm">Run</a></li>
<li>Vue App - <a href="https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/samples-demos/helloworld-vuejsv3.html?ver=9.6.11&utm_source=npm">Guide</a> | <a href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.6.11/1.hello-world/6.read-video-vue3">Github</a> | <a href="https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/6.read-video-vue3/dist/?ver=9.6.11&utm_source=npm">Run</a></li>
<li>PWA App - <a href="https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/samples-demos/helloworld-pwa.html?ver=9.6.11&utm_source=npm">Guide</a> | <a href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.6.11/1.hello-world/10.read-video-pwa">Github</a> | <a href="https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/10.read-video-pwa/helloworld-pwa.html?ver=9.6.11&utm_source=npm">Run</a></li>
<li>Read Driver Licenses - <a href="https://www.dynamsoft.com/barcode-reader/docs/core/programming/usecases/scan-and-parse-AAMVA.html?ver=9.6.11&utm_source=npm&&lang=js">Guide</a> | <a href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.6.11/4.use-case/2.read-a-drivers-license.html">Github</a> | <a href="https://demo.dynamsoft.com/samples/dbr/js/4.use-case/2.read-a-drivers-license.html?ver=9.6.11&utm_source=npm">Run</a></li>
<li>Fill A Form - <a href="https://www.dynamsoft.com/barcode-reader/docs/core/programming/usecases/scan-barcodes-as-input.html?lang=js&&utm_source=npm">Guide</a> | <a href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.6.11/4.use-case/1.fill-a-form-with-barcode-reading.html">Github</a> | <a href="https://demo.dynamsoft.com/samples/dbr/js/4.use-case/1.fill-a-form-with-barcode-reading.html?ver=9.6.11&utm_source=npm">Run</a></li>
<li>Debug Camera and Collect Video Frame - <a href="https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/samples-demos/debug.html?lang=js&&utm_source=npm">Guide</a> | <a href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.6.11/5.others/debug">Github</a></li>
</ul>
<p>You can also:</p>
<ul>
<li>Try the Official Demo - <a href="https://demo.dynamsoft.com/barcode-reader-js/?ver=9.6.11&utm_source=npm">Run</a> | <a href="https://github.com/Dynamsoft/barcode-reader-javascript-demo/">Github</a></li>
<li>Try Online Examples - <a href="https://demo.dynamsoft.com/Samples/DBR/JS/index.html?ver=9.6.11&utm_source=npm">Run</a> | <a href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/tree/v9.6.11/">Github</a></li>
</ul>
<h2 id="hello-world---simplest-implementation">Hello World - Simplest Implementation</h2>
<p>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. </p>
<ul>
<li>Basic Requirements</li>
<li>Internet connection</li>
<li><a href="#system-requirements">A supported browser</a></li>
<li>Camera access</li>
</ul>
<h3 id="understand-the-code">Understand the code</h3>
<p>The complete code of the "Hello World" example is shown below</p>
<pre><code class="hljs html language-html"><span class="hljs-meta"><!DOCTYPE html></span>
<span class="hljs-tag"><<span class="hljs-name">html</span>></span>
<span class="hljs-tag"><<span class="hljs-name">body</span>></span>
<span class="hljs-tag"><<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">"https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@9.6.11/dist/dbr.js"</span>></span><span class="undefined"></span><span class="hljs-tag"></<span class="hljs-name">script</span>></span>
<span class="hljs-tag"><<span class="hljs-name">script</span>></span><span class="javascript">
<span class="hljs-comment">// Specifies a license, you can visit https://www.dynamsoft.com/customer/license/trialLicense?ver=9.6.11&utm_source=npm&product=dbr&package=js to get your own trial license good for 30 days. </span>
Dynamsoft.DBR.BarcodeScanner.license = <span class="hljs-string">'DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9'</span>;
<span class="hljs-comment">// Initializes and uses the SDK</span>
(<span class="hljs-keyword">async</span> () => {
<span class="hljs-keyword">let</span> scanner = <span class="hljs-keyword">await</span> Dynamsoft.DBR.BarcodeScanner.createInstance();
scanner.onFrameRead = <span class="hljs-function"><span class="hljs-params">results</span> =></span> {
<span class="hljs-keyword">if</span> (results.length > <span class="hljs-number">0</span>) <span class="hljs-built_in">console</span>.log(results);
};
scanner.onUniqueRead = <span class="hljs-function">(<span class="hljs-params">txt, result</span>) =></span> {
alert(txt);
};
<span class="hljs-keyword">await</span> scanner.show();
})();
</span><span class="hljs-tag"></<span class="hljs-name">script</span>></span>
<span class="hljs-tag"></<span class="hljs-name">body</span>></span>
<span class="hljs-tag"></<span class="hljs-name">html</span>></span>
</code></pre>
<p align="center" style="text-align:center; white-space: normal; ">
<a target="_blank" href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/blob/v9.6.11/1.hello-world/1.hello-world.html" title="Code in Github" style="text-decoration:none;">
<img src="https://cdn.jsdelivr.net/npm/simple-icons@3.0.1/icons/github.svg" alt="Code in Github" width="20" height="20" style="width:20px;height:20px;">
</a>
<a target="_blank" href="https://jsfiddle.net/DynamsoftTeam/pL4e7yrd/" title="Run via JSFiddle" style="text-decoration:none;">
<img src="https://cdn.jsdelivr.net/npm/simple-icons@3.0.1/icons/jsfiddle.svg" alt="Run via JSFiddle" width="20" height="20" style="width:20px;height:20px;" >
</a>
<a target="_blank" href="https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/1.hello-world.html?ver=9.6.11&utm_source=npm" title="Run in Dynamsoft" style="text-decoration:none;">
<img src="https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@6.0.0/svgs/solid/circle-play.svg" alt="Run in Dynamsoft" width="20" height="20" style="width:20px;height:20px;">
</a>
</p>
<hr />
<h4 id="about-the-code">About the code</h4>
<ul>
<li>The DBR-JS SDK is included in the code via the <strong>jsDelivr</strong> CDN.</li>
</ul>
<blockquote>
<p>In some rare cases, you might not be able to access the CDN. If this happens, you can use <a href="https://download2.dynamsoft.com/dbr/dynamsoft-barcode-reader-js/dynamsoft-barcode-reader-js-9.6.11/dist/dbr.js">https://download2.dynamsoft.com/dbr/dynamsoft-barcode-reader-js/dynamsoft-barcode-reader-js-9.6.11/dist/dbr.js</a> for the test. However, please DO NOT use CDN of <code>download2.dynamsoft.com</code> in your production application because it is temporary. Instead, you can try <a href="#host-the-sdk-yourself">hosting the SDK yourself</a>.</p>
</blockquote>
<ul>
<li><p><code>license</code>: This property specifies a license key. Note that the license "DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9" used in this example is an online license and requires network connection to work. Read more on <a href="#specify-the-license">Specify the license</a>.</p></li>
<li><p><code>createInstance()</code>: This method creates a <code>BarcodeScanner</code> object. This object can read barcodes directly from a video input with the help of its interactive UI (hidden by default) and the <a target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices" title="MediaDevices interface">MediaDevices interface</a>.</p></li>
<li><p><code>onFrameRead</code>: This event is triggered every time the SDK finishes scanning a video frame. The <code>results</code> object contains all the barcode results that the SDK have found on this frame. In this example, we print the results to the browser console.</p></li>
<li><p><code>onUniqueRead</code>: This event is triggered when the SDK finds a new barcode, which is not a duplicate among multiple frames. <code>txt</code> holds the barcode text value while <code>result</code> is an object that holds details of the barcode. In this example, an alert will be displayed for this new barcode.</p></li>
<li><p><code>show()</code>: This method brings up the built-in UI of the <code>BarcodeScanner</code> object and starts scanning.</p></li>
</ul>
<h3 id="run-the-example">Run the example</h3>
<p>You can run the example deployed to <a target="_blank" href="https://demo.dynamsoft.com/Samples/DBR/JS/1.hello-world/1.hello-world.html?ver=9.6.11&utm_source=npm" title="Run in Dynamsoft">the Dynamsoft Demo Server</a> or test it with <a target="_blank" href="https://jsfiddle.net/DynamsoftTeam/pL4e7yrd/" title="Run in JSFiddle">JSFiddle code editor</a>. You will be asked to allow access to your camera, after which the video will be displayed on the page. After that, you can point the camera at a barcode to read it.</p>
<p>When a barcode is decoded, you will see the result text pop up and the barcode location will be highlighted in the video feed.</p>
<p>Alternatively, you can make a local test simply by taking the code in step 1, pasting it in a file with the name "hello-world.html" and open it in a browser.</p>
<p><em>Note</em>:</p>
<p>If you open the web page as <code>file:///</code> or <code>http://</code> , the camera may not work correctly because the API <a target="_blank" href="https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia" title="getUserMedia">getUserMedia</a> usually requires HTTPS to access the camera.</p>
<p>To make sure your web application can access the camera, please configure your web server to support HTTPS. The following links may help.</p>
<ol>
<li>NGINX: <a target="_blank" href="https://nginx.org/en/docs/http/configuring_https_servers.html" title="Configuring HTTPS servers">Configuring HTTPS servers</a></li>
<li>IIS: <a target="_blank" href="https://aboutssl.org/how-to-create-a-self-signed-certificate-in-iis/" title="Create a Self Signed Certificate in IIS">Create a Self Signed Certificate in IIS</a></li>
<li>Tomcat: <a target="_blank" href="https://dzone.com/articles/setting-ssl-tomcat-5-minutes" title="Setting Up SSL on Tomcat in 5 minutes">Setting Up SSL on Tomcat in 5 minutes</a></li>
<li>Node.js: <a target="_blank" href="https://nodejs.org/docs/v0.4.1/api/tls.html" title="npm tls">npm tls</a></li>
</ol>
<p>If the test doesn't go as expected, you can <a href="https://www.dynamsoft.com/company/contact/?ver=9.6.11&utm_source=npm">contact us</a>.</p>
<p><strong>Pinned Message:</strong></p>
<ul>
<li><a href="https://github.com/Dynamsoft/barcode-reader-javascript-samples/issues/99#issuecomment-1407584605">Temporary solution for iPhone 14 Pro Max rear camera not focusing</a></li>
</ul>
<h2 id="building-your-own-page">Building your own page</h2>
<h3 id="include-the-sdk">Include the SDK</h3>
<h4 id="use-a-public-cdn">Use a public CDN</h4>
<p>The simplest way to include the SDK is to use either the <a href="https://jsdelivr.com/">jsDelivr</a> or <a href="https://unpkg.com/">UNPKG</a> CDN. The "hello world" example above uses <strong>jsDelivr</strong>.</p>
<ul>
<li>jsDelivr</li>
</ul>
<pre><code class="hljs html language-html"> <span class="hljs-tag"><<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">"https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@9.6.11/dist/dbr.js"</span>></span><span class="undefined"></span><span class="hljs-tag"></<span class="hljs-name">script</span>></span>
</code></pre>
<ul>
<li>UNPKG </li>
</ul>
<pre><code class="hljs html language-html"> <span class="hljs-tag"><<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">"https://unpkg.com/dynamsoft-javascript-barcode@9.6.11/dist/dbr.js"</span>></span><span class="undefined"></span><span class="hljs-tag"></<span class="hljs-name">script</span>></span>
</code></pre>
<h4 id="host-the-sdk-yourself">Host the SDK yourself</h4>
<p>Besides using the public CDN, you can also download the SDK and host its files on your own server or a commercial CDN before including it in your application.</p>
<p>Options to download the SDK:</p>
<ul>
<li><p>From the website</p>
<p><a target="_blank" href="https://www.dynamsoft.com/barcode-reader/downloads/?ver=9.6.11&utm_source=npm" title="Download the JavaScript Package">Download the JavaScript Package</a></p></li>
<li><p>yarn</p></li>
</ul>
<pre><code class="hljs cmd language-cmd"> yarn add dynamsoft-javascript-barcode
</code></pre>
<ul>
<li>npm</li>
</ul>
<pre><code class="hljs cmd language-cmd"> npm install dynamsoft-javascript-barcode --save
</code></pre>
<p>Depending on how you downloaded the SDK and how you intend to use it, you can typically include it like this:</p>
<pre><code class="hljs html language-html"><span class="hljs-tag"><<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">"/dynamsoft-barcode-reader-js-9.6.11/dist/dbr.js"</span>></span><span class="undefined"></span><span class="hljs-tag"></<span class="hljs-name">script</span>></span>
</code></pre>
<p>or</p>
<pre><code class="hljs html language-html"><span class="hljs-tag"><<span class="hljs-name">script</span> <span class="hljs-attr">src</span>=<span class="hljs-string">"/node_modules/dynamsoft-javascript-barcode/dist/dbr.js"</span>></span><span class="undefined"></span><span class="hljs-tag"></<span class="hljs-name">script</span>></span>
</code></pre>
<p>or</p>
<pre><code class="hljs ts language-ts"><span class="hljs-keyword">import</span> { BarcodeScanner } <span class="hljs-keyword">from</span> <span class="hljs-string">'dynamsoft-javascript-barcode'</span>;
</code></pre>
<p><strong>NOTE</strong></p>
<ul>
<li><p>Some older web application servers do not set <code>.wasm</code> mimetype as <code>application/wasm</code>. Upgrade your web application servers, or define the mimetype yourselves:</p></li>
<li><p><a href="https://developer.mozilla.org/en-US/docs/Learn/Server-side/Apache_Configuration_htaccess#media_types_and_character_encodings">Apache</a></p></li>
<li><p><a href="https://docs.microsoft.com/en-us/iis/configuration/system.webserver/staticcontent/mimemap">IIS</a></p></li>
<li><p><a href="https://www.nginx.com/resources/wiki/start/topics/examples/full/#mime-types">Nginx</a></p></li>
<li><p>To work properly, the SDK requires a few engine files, which are relatively large and may take quite a few seconds to download. We recommend that you set a longer cache time for these engine files, to maximize the performance of your web application.</p></li>
</ul>
<pre><code class="hljs cmd language-cmd"> Cache-Control: max-age=<span class="hljs-number">31536000</span>
</code></pre>
<p>Reference: <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control">Cache-Control</a>.</p>
<h3 id="configure-the-sdk">Configure the SDK</h3>
<p>Before using the SDK, you need to configure a few things.</p>
<h4 id="specify-the-license">Specify the license</h4>
<p>The SDK requires a license to work, use the API <code>license</code> to specify a license key.</p>
<pre><code class="hljs javascript language-javascript">Dynamsoft.DBR.BarcodeScanner.license = <span class="hljs-string">"YOUR-LICENSE-KEY"</span>;
</code></pre>
<p>To test the SDK, you can request a 30-day trial license via the <a href="https://www.dynamsoft.com/customer/license/trialLicense?ver=9.6.11&utm_source=npm&product=dbr&package=js">customer portal</a>.</p>
<blockquote>
<p>If you register a Dynamsoft account and download 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 attached to the SDK.</p>
</blockquote>
<h4 id="specify-the-location-of-the-engine-files">Specify the location of the "engine" files</h4>
<p>This is usually only required with frameworks like Angular or React, etc. where dbr.js is compiled into another file.</p>
<p>The purpose is to tell the SDK where to find the engine files (*.worker.js, *.wasm.js and *.wasm, etc.). The API is called <code>engineResourcePath</code>:</p>
<pre><code class="hljs javascript language-javascript"><span class="hljs-comment">//The following code uses the jsDelivr CDN, feel free to change it to your own location of these files</span>
Dynamsoft.DBR.BarcodeScanner.engineResourcePath = <span class="hljs-string">"https://cdn.jsdelivr.net/npm/dynamsoft-javascript-barcode@9.6.11/dist/"</span>;
</code></pre>
<h3 id="interact-with-the-sdk">Interact with the SDK</h3>
<h4 id="create-a-barcodescanner-object">Create a <code>BarcodeScanner</code> object</h4>
<p>You can use one of two classes ( <code>BarcodeScanner</code> and <code>BarcodeReader</code> ) to interact with the SDK. <code>BarcodeReader</code> is a low-level class that processes images directly. <code>BarcodeScanner</code> , on the other hand, inherits from <code>BarcodeReader</code> and provides high-level APIs and a built-in GUI to allow continuous barcode scanning on video frames. We'll focus on <code>BarcodeScanner</code> in this guide.</p>
<p>To use the SDK, we first create a <code>BarcodeScanner</code> object.</p>
<pre><code class="hljs javascript language-javascript">Dynamsoft.DBR.BarcodeScanner.license = <span class="hljs-string">"YOUR-LICENSE-KEY"</span>;
<span class="hljs-keyword">let</span> scanner = <span class="hljs-literal">null</span>;
<span class="hljs-keyword">try</span> {
scanner = <span class="hljs-keyword">await</span> Dynamsoft.DBR.BarcodeScanner.createInstance();
} <span class="hljs-keyword">catch</span> (ex) {
<span class="hljs-built_in">console</span>.error(ex);
}
</code></pre>
<p>Tip: When creating a <code>BarcodeScanner</code> object within a function which may be called more than once, it's best to use a "helper" variable to avoid double creation such as <code>pScanner</code> in the following code</p>
<pre><code class="hljs javascript language-javascript">Dynamsoft.DBR.BarcodeScanner.license = <span class="hljs-string">"YOUR-LICENSE-KEY"</span>;
<span class="hljs-keyword">let</span> pScanner = <span class="hljs-literal">null</span>;
<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'btn-scan'</span>).addEventListener(<span class="hljs-string">'click'</span>, <span class="hljs-keyword">async</span> () => {
<span class="hljs-keyword">try</span> {
<span class="hljs-keyword">const</span> scanner = <span class="hljs-keyword">await</span> (pScanner = pScanner || Dynamsoft.DBR.BarcodeScanner.createInstance());
} <span class="hljs-keyword">catch</span> (ex) {
<span class="hljs-built_in">console</span>.error(ex);
}
});
</code></pre>
<h4 id="customize-the-barcodescanner-settings-optional">Customize the <code>BarcodeScanner</code> Settings (optional)</h4>
<p>Let's take a look at the following code snippets:</p>
<pre><code class="hljs javascript language-javascript"><span class="hljs-comment">// Sets which camera and what resolution to use</span>
<span class="hljs-keyword">let</span> allCameras = <span class="hljs-keyword">await</span> scanner.getAllCameras();
<span class="hljs-keyword">await</span> scanner.setCurrentCamera(allCameras[<span class="hljs-number">0</span>].deviceId);
<span class="hljs-keyword">await</span> scanner.setResolution(<span class="hljs-number">1280</span>, <span class="hljs-number">720</span>);
</code></pre>
<pre><code class="hljs javascript language-javascript"><span class="hljs-comment">// Sets up the scanner behavior</span>
<span class="hljs-keyword">let</span> scanSettings = <span class="hljs-keyword">await</span> scanner.getScanSettings();
<span class="hljs-comment">// Disregards duplicated results found in a specified time period (in milliseconds).</span>
scanSettings.duplicateForgetTime = <span class="hljs-number">5000</span>; <span class="hljs-comment">// The default is 3000</span>
<span class="hljs-comment">// Sets a scan interval in milliseconds so the SDK may release the CPU from time to time.</span>
<span class="hljs-comment">// (setting this value larger is a simple way to save battery power and reduce device heating).</span>
scanSettings.intervalTime = <span class="hljs-number">100</span>; <span class="hljs-comment">// The default is 0.</span>
<span class="hljs-comment">// Sets captureAndDecodeInParallel to false, which tells the SDK not to acquire the next frame while decoding the first.</span>
<span class="hljs-comment">// This is another way to save battery power and is recommended on low-end phones. However, it does slow down the decoding speed.</span>
scanSettings.captureAndDecodeInParallel = <span class="hljs-literal">false</span>; <span class="hljs-comment">// The default is true.</span>
<span class="hljs-keyword">await</span> scanner.updateScanSettings(scanSettings);
</code></pre>
<pre><code class="hljs javascript language-javascript"><span class="hljs-comment">// Uses one of the built-in RuntimeSetting templates: "single" (decode a single barcode, the default mode), "speed", "balance", "coverage", "dense" and "distance"</span>
<span class="hljs-keyword">await</span> scanner.updateRuntimeSettings(<span class="hljs-string">"speed"</span>);
<span class="hljs-comment">// Makes changes to the template. The code below demonstrates how to specify enabled symbologies</span>
<span class="hljs-keyword">let</span> runtimeSettings = <span class="hljs-keyword">await</span> scanner.getRuntimeSettings();
runtimeSettings.barcodeFormatIds = Dynamsoft.DBR.EnumBarcodeFormat.BF_ONED | Dynamsoft.DBR.EnumBarcodeFormat.BF_QR_CODE;
<span class="hljs-keyword">await</span> scanner.updateRuntimeSettings(runtimeSettings);
</code></pre>
<p><a href="https://jsfiddle.net/DynamsoftTeam/yfkcajxz/">Try in JSFiddle</a></p>
<p>As you can see from the above code snippets, there are three types of configurations:</p>
<ul>
<li><p>Customize the data source: This configuration includes which camera to use, the preferred resolution, etc. Learn more <a href="https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia#Syntax" target="_blank" title="here">here</a>.</p></li>
<li><p><code>get/updateScanSettings</code>: Configures the behavior of the scanner which includes <code>duplicateForgetTime</code> and <code>intervalTime</code>, etc.</p></li>
<li><p><code>get/updateRuntimeSettings</code>: Configures the decode engine with either a built-in template or a comprehensive <code>RuntimeSettings</code> object. For example, the following uses the built-in "speed" settings with updated <code>localizationModes</code>.</p></li>
</ul>
<pre><code class="hljs javascript language-javascript"> <span class="hljs-keyword">await</span> barcodeScanner.updateRuntimeSettings(<span class="hljs-string">"speed"</span>);
<span class="hljs-comment">//await barcodeScanner.updateRuntimeSettings("balance"); //alternative</span>
<span class="hljs-comment">//await barcodeScanner.updateRuntimeSettings("coverage"); //alternative</span>
<span class="hljs-keyword">let</span> settings = <span class="hljs-keyword">await</span> barcodeScanner.getRuntimeSettings();
settings.localizationModes = [
Dynamsoft.DBR.EnumLocalizationMode.LM_CONNECTED_BLOCKS,
Dynamsoft.DBR.EnumLocalizationMode.LM_SCAN_DIRECTLY,
Dynamsoft.DBR.EnumLocalizationMode.LM_LINES, <span class="hljs-number">0</span>, <span class="hljs-number">0</span>, <span class="hljs-number">0</span>, <span class="hljs-number">0</span>, <span class="hljs-number">0</span>
];
<span class="hljs-keyword">await</span> barcodeScanner.updateRuntimeSettings(settings);
</code></pre>
<p>Try in <a href="https://jsfiddle.net/DynamsoftTeam/f24h8c1m/">JSFiddle</a>.</p>
<p>See also <a href="https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/samples-demos/parameter-settings.html?ver=9.6.11&utm_source=npm">settings samples</a>.</p>
<blockquote>
<p>Find the full list of the runtime settings <a href="https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/global-interfaces.html?ver=9.6.11&utm_source=npm&&ver=latest#runtimesettings" target="_blank" title="here">here</a>.</p>
</blockquote>
<h3 id="customize-the-ui-optional">Customize the UI (optional)</h3>
<p>The built-in UI of the <code>BarcodeScanner</code> object is defined in the file <code>dist/dbr.ui.html</code> . There are a few ways to customize it:</p>
<h4 id="modify-the-file-distdbruihtml-directly">Modify the file <code>dist/dbr.ui.html</code> directly</h4>
<p>This option is only possible when you <a href="#host-the-sdk-yourself">Host the SDK yourself</a> instead of using a public CDN.</p>
<h4 id="copy-the-file-distdbruihtml-to-your-application-modify-it-and-use-the-the-api-defaultuielementurl-to-set-it-as-the-default-ui">Copy the file <code>dist/dbr.ui.html</code> to your application, modify it and use the the API <code>defaultUIElementURL</code> to set it as the default UI</h4>
<pre><code class="hljs javascript language-javascript"> <span class="hljs-comment">// This line only takes effect before the method `createInstance()` is called.</span>
Dynamsoft.DBR.BarcodeScanner.defaultUIElementURL = <span class="hljs-string">"THE-URL-TO-THE-FILE"</span>;
</code></pre>
<h4 id="append-the-default-ui-element-to-your-page-customize-it-before-showing-it">Append the default UI element to your page, customize it before showing it</h4>
<pre><code class="hljs html language-html"> <span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"div-ui-container"</span>></span><span class="hljs-tag"></<span class="hljs-name">div</span>></span>
</code></pre>
<pre><code class="hljs javascript language-javascript"> <span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'div-ui-container'</span>).appendChild(scanner.getUIElement());
<span class="hljs-built_in">document</span>.getElementsByClassName(<span class="hljs-string">'dce-btn-close'</span>)[<span class="hljs-number">0</span>].hidden = <span class="hljs-literal">true</span>; <span class="hljs-comment">// Hide the close button</span>
</code></pre>
<h4 id="build-the-ui-element-from-scratch-and-connect-it-to-the-sdk-with-the-api-setuielementhtmlelement">Build the UI element from scratch and connect it to the SDK with the API <code>setUIElement(HTMLElement)</code></h4>
<ol>
<li><strong>Embed the video</strong></li>
</ol>
<pre><code class="hljs html language-html"> <span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"div-ui-container"</span> <span class="hljs-attr">style</span>=<span class="hljs-string">"width:100%;height:100%;"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"dce-video-container"</span> <span class="hljs-attr">style</span>=<span class="hljs-string">"position:relative;width:100%;height:500px;"</span>></span><span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"><<span class="hljs-name">script</span>></span><span class="javascript">
(<span class="hljs-keyword">async</span> () => {
<span class="hljs-keyword">let</span> scanner = <span class="hljs-keyword">await</span> Dynamsoft.DBR.BarcodeScanner.createInstance();
<span class="hljs-keyword">await</span> scanner.setUIElement(<span class="hljs-built_in">document</span>.getElementById(<span class="hljs-string">'div-ui-container'</span>));
scanner.onFrameRead = <span class="hljs-function"><span class="hljs-params">results</span> =></span> {
<span class="hljs-built_in">console</span>.log(results);
};
scanner.onUniqueRead = <span class="hljs-function">(<span class="hljs-params">txt, result</span>) =></span> {
alert(txt);
};
<span class="hljs-keyword">await</span> scanner.show();
})();
</span><span class="hljs-tag"></<span class="hljs-name">script</span>></span>
</code></pre>
<blockquote>
<p>The video element will be created and appended to the DIV element with the class <code>dce-video-container</code> , make sure the class name is the same. Besides, the CSS property <code>position</code> of the DIV element must be either <code>relative</code> , <code>absolute</code> , <code>fixed</code> , or <code>sticky</code> .</p>
</blockquote>
<p><a href="https://jsfiddle.net/DynamsoftTeam/2jzeq1r6/">Try in JSFiddle</a></p>
<ol start="2">
<li><p><strong>[Optional] Add the camera list and resolution list</strong></p>
<p>If the class names of the created select elements match the default class names, i.e. <code>dce-sel-camera</code> and <code>dce-sel-resolution</code> respectively, the SDK will automatically populate the lists and handle the camera/resolution switching.</p></li>
</ol>
<pre><code class="hljs html language-html"> <span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"div-ui-container"</span> <span class="hljs-attr">style</span>=<span class="hljs-string">"width:100%;height:100%;"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">select</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"dce-sel-camera"</span>></span><span class="hljs-tag"></<span class="hljs-name">select</span>></span><span class="hljs-tag"><<span class="hljs-name">br</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"dce-video-container"</span> <span class="hljs-attr">style</span>=<span class="hljs-string">"position:relative;width:100%;height:500px;"</span>></span><span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
</code></pre>
<p><a href="https://jsfiddle.net/DynamsoftTeam/nbj75vxu/">Try in JSFiddle</a></p>
<pre><code class="hljs html language-html"> <span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">id</span>=<span class="hljs-string">"div-ui-container"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">select</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"dce-sel-camera"</span>></span><span class="hljs-tag"></<span class="hljs-name">select</span>></span>
<span class="hljs-tag"><<span class="hljs-name">select</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"dce-sel-resolution"</span>></span><span class="hljs-tag"></<span class="hljs-name">select</span>></span>
<span class="hljs-tag"><<span class="hljs-name">br</span>></span>
<span class="hljs-tag"><<span class="hljs-name">div</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"dce-video-container"</span> <span class="hljs-attr">style</span>=<span class="hljs-string">"position:relative;width:100%;height:500px;"</span>></span><span class="hljs-tag"></<span class="hljs-name">div</span>></span>
<span class="hljs-tag"></<span class="hljs-name">div</span>></span>
</code></pre>
<p><a href="https://jsfiddle.net/DynamsoftTeam/25v08paf/">Try in JSFiddle</a></p>
<blockquote>
<p>By default, only 3 hard-coded resolutions (1920 x 1080, 1280 x 720，640 x 480) are populated as options. You can show a customized set of options by hardcoding them.</p>
</blockquote>
<pre><code class="hljs html language-html"> <span class="hljs-tag"><<span class="hljs-name">select</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"dce-sel-resolution"</span>></span>
<span class="hljs-tag"><<span class="hljs-name">option</span> <span class="hljs-attr">class</span>=<span class="hljs-string">"dce-opt-gotResolution"</span> <span class="hljs-attr">value</span>=<span class="hljs-string">"got"</span>></span><span class="hljs-tag"></<span class="hljs-name">option</span>></span>
<span class="hljs-tag"><<span class="hljs-name">option</span> <span class="hljs-attr">data-width</span>=<span class="hljs-string">"1280"</span> <span class="hljs-attr">data-height</span>=<span class="hljs-string">"720"</span>></span>1280x720<span class="hljs-tag"></<span class="hljs-name">option</span>></span>
<span class="hljs-tag"><<span class="hljs-name">option</span> <span class="hljs-attr">data-width</span>=<span class="hljs-string">"1920"</span> <span class="hljs-attr">data-height</span>=<span class="hljs-string">"1080"</span>></span>1920x1080<span class="hljs-tag"></<span class="hljs-name">option</span>></span>
<span class="hljs-tag"></<span class="hljs-name">select</span>></span>
</code></pre>
<p><a href="https://jsfiddle.net/DynamsoftTeam/tnfjks4q/">Try in JSFiddle</a></p>
<blockquote>
<p>Generally, you need to provide a resolution that the camera supports. However, in case a camera does not support the specified resolution, it usually uses the cloest supported resolution. As a result, the selected resolution may not be the actual resolution. In this case, add an option with the class name <code>dce-opt-gotResolution</code> (as shown above) and the SDK will automatically use it to show the <strong>actual resolution</strong>.</p>
</blockquote>
<p>See the section of the Explore Features guide on <a href="{{site.features}}customize-the-ui.html?lang=js">UI customization</a> to learn more.</p>
<h2 id="api-documentation">API Documentation</h2>
<p>You can check out the detailed documentation about the APIs of the SDK at<br />
<a href="https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/?ver=9.6.11">https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/?ver=9.6.11</a>.</p>
<h2 id="system-requirements">System Requirements</h2>
<p>DBR requires the following features to work:</p>
<ul>
<li><p>Secure context (HTTPS deployment)</p>
<p>When deploying your application / website for production, make sure to serve it via a secure HTTPS connection. This is required for two reasons</p></li>
<li><p>Access to the camera video stream is only granted in a security context. Most browsers impose this restriction.</p></li>
</ul>
<blockquote>
<p>Some browsers like Chrome may grant the access for <code>http://127.0.0.1</code> and <code>http://localhost</code> or even for pages opened directly from the local disk (<code>file:///...</code>). This can be helpful for temporary development and test.</p>
</blockquote>
<ul>
<li><p>Dynamsoft License requires a secure context to work.</p></li>
<li><p><code>WebAssembly</code>, <code>Blob</code>, <code>URL</code>/<code>createObjectURL</code>, <code>Web Workers</code></p>
<p>The above four features are required for the SDK to work.</p></li>
<li><p><code>MediaDevices</code>/<code>getUserMedia</code></p>
<p>This API is only required for in-browser video streaming. If a browser does not support this API, the <a href="https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/api-reference/BarcodeScanner.html?ver=9.6.11&utm_source=npm#singleframemode">Single Frame Mode</a> will be used automatically. If the API exists but doesn't work correctly, the Single Frame Mode can be used as an alternative way to access the camera.</p></li>
<li><p><code>getSettings</code></p>
<p>This API inspects the video input which is a <code>MediaStreamTrack</code> object about its constrainable properties.</p></li>
</ul>
<p>The following table is a list of supported browsers based on the above requirements:</p>
<table>
<thead>
<tr>
<th style="text-align:center;">Browser Name</th>
<th style="text-align:center;">Version</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align:center;">Chrome</td>
<td style="text-align:center;">v59+<sup>1</sup></td>
</tr>
<tr>
<td style="text-align:center;">Firefox</td>
<td style="text-align:center;">v52+ (v55+ on Android/iOS<sup>1</sup>)</td>
</tr>
<tr>
<td style="text-align:center;">Edge<sup>2</sup></td>
<td style="text-align:center;">v16+</td>
</tr>
<tr>
<td style="text-align:center;">Safari<sup>3</sup></td>
<td style="text-align:center;">v11+</td>
</tr>
</tbody>
</table>
<p><sup>1</sup> iOS 14.3+ is required for camera video streaming in Chrome and Firefox or Apps using webviews.</p>
<p><sup>2</sup> On Edge, due to strict Same-origin policy, you must host the SDK files on the same domain as your web page.</p>
<p><sup>3</sup> Safari v11.x already has the required features, but it has many other issues, so we recommend v12+.</p>
<p>Apart from the browsers, the operating systems may impose some limitations of their own that could restrict the use of the SDK. Browser compatibility ultimately depends on whether the browser on that particular operating system supports the features listed above.</p>
<h2 id="how-to-upgrade">How to Upgrade</h2>
<p>If you want to upgrade the SDK from an old version to a newer one, please see <a href="https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/upgrade-guide/?ver=9.6.11&utm_source=npm">how to upgrade</a>.</p>
<h2 id="release-notes">Release Notes</h2>
<p>Learn about what are included in each release at <a href="https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/release-notes/?ver=latest">https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/release-notes/?ver=latest</a>.</p>
<h2 id="next-steps">Next Steps</h2>
<p>Now that you have got the SDK integrated, you can choose to move forward in the following directions</p>
<ol>
<li>Check out the <a href="https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/samples-demos/index.html?ver=latest">Official Samples and Demo</a></li>
<li>Learn how to make use of the <a href="https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/user-guide/explore-features/index.html?ver=latest">SDK features</a></li>
<li>See how the SDK works in <a href="https://www.dynamsoft.com/barcode-reader/docs/web/programming/javascript/user-guide/use-cases/index.html?ver=latest">Popular Use Cases</a></li>
</ol>
</div>
</body>
</html>