scandit-sdk

<!doctype html> <html class="default no-js"> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge"> <title>Scandit Barcode Scanner SDK for the Web</title> <meta name="description" content="Documentation for Scandit Barcode Scanner SDK for the Web"> <meta name="viewport" content="width=device-width, initial-scale=1"> <link rel="stylesheet" href="assets/css/main.css"> <script async src="assets/js/search.js" id="search-script"></script> </head> <body> <header> <div class="tsd-page-toolbar"> <div class="container"> <div class="table-wrap"> <div class="table-cell" id="tsd-search" data-index="assets/js/search.json" data-base="."> <div class="field"> <label for="tsd-search-field" class="tsd-widget search no-caption">Search</label> <input id="tsd-search-field" type="text" /> </div> <ul class="results"> <li class="state loading">Preparing search index...</li> <li class="state failure">The search index is not available</li> </ul> <a href="index.html" class="title">Scandit Barcode Scanner SDK for the Web</a> </div> <div class="table-cell" id="tsd-widgets"> <div id="tsd-filter"> <a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a> <div class="tsd-filter-group"> <div class="tsd-select" id="tsd-filter-visibility"> All <ul class="tsd-select-list"> <li data-value="public">Public</li> <li data-value="protected">Public/Protected</li> <li data-value="private" class="selected">All</li> </ul> </div> <input type="checkbox" id="tsd-filter-inherited" checked /> <label class="tsd-widget" for="tsd-filter-inherited">Inherited</label> </div> </div> <a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a> </div> </div> </div> </div> <div class="tsd-page-title"> <div class="container"> <h1>Scandit Barcode Scanner SDK for the Web</h1> </div> </div> </header> <div class="container container-main"> <div class="row"> <div class="col-8 col-content"> <div class="tsd-panel tsd-typography"> <a href="#scandit-barcode-scanner-sdk-for-the-web" id="scandit-barcode-scanner-sdk-for-the-web" style="color: inherit; text-decoration: none;"> <h1>Scandit Barcode Scanner SDK for the Web</h1> </a> <blockquote> 🚨 Notice: A more recent version of the Scandit Data Capture SDK which includes performance improvements and additional features is available <a href="https://www.npmjs.com/package/scandit-web-datacapture-barcode">here</a>. A 5.x → 6.x migration guide can be found <a href="https://docs.scandit.com/data-capture-sdk/web/migrate-to-6.html">here</a>. </blockquote> Enterprise barcode/text scanning performance in your browser via JavaScript and WebAssembly. Made by <a href="https://www.scandit.com/">Scandit</a> <img src="https://img.shields.io/npm/v/scandit-sdk.svg" alt="npm"> <img src="https://img.shields.io/npm/dm/scandit-sdk.svg" alt="npm"> <img src="https://img.shields.io/jsdelivr/npm/hm/scandit-sdk.svg" alt="jsDelivr hits (npm)"> <img src="https://img.shields.io/snyk/vulnerabilities/npm/scandit-sdk.svg" alt="Snyk Vulnerabilities for npm package"> <img src="https://img.badgesize.io/https://cdn.jsdelivr.net/npm/scandit-sdk/build/browser/index.min.js.svg?compression=gzip&label=Main%20Library%20Size" alt="main library size"> <img src="https://img.badgesize.io/https://cdn.jsdelivr.net/npm/scandit-sdk/build/scandit-engine-sdk.min.js.svg?compression=gzip&label=Scandit%20Data%20Capture%20JS%20Size" alt="scandit data capture js size"> <img src="https://img.badgesize.io/https://cdn.jsdelivr.net/npm/scandit-sdk/build/scandit-engine-sdk.wasm.svg?compression=gzip&label=Scandit%20Data%20Capture%20WASM%20Size" alt="scandit data capture wasm size"> Access cameras available on the devices for video input, display a picker interface, configure in-depth settings for barcodes, text and performance, and let users easily scan barcodes and text in your web application. Try out our live demo <a href="http://websdk.scandit.com">here</a>. Find out more information on our product <a href="https://www.scandit.com/products/sdk-web/">here</a>. To use this library you must possess a valid Scandit account and license key. You can register for a free trial <a href="https://ssl.scandit.com/customers/new?p=test&source=websdk">here</a>. This library is meant to be used natively in a web browser, if you are instead looking for a Cordova/PhoneGap plugin, please go <a href="https://github.com/Scandit/barcodescanner-sdk-cordova">here</a>. Table of Contents: <ul> <li><a href="#quick-start-web-application">Quick Start: Web Application</a></li> <li><a href="#getting-started-web-application">Getting Started: Web Application</a></li> <li><a href="#getting-started-local-development">Getting Started: Local Development</a></li> <li><a href="#configuration">Configuration</a></li> <li><a href="#usage">Usage</a></li> <li><a href="#example-applications">Example Applications</a></li> <li><a href="#web-component-integration">Web Component Integration</a></li> <li><a href="#advanced-components-and-sample-apps">Advanced Components and Sample Apps</a></li> <li><a href="#browser-support-and-requirements">Browser Support and Requirements</a></li> <li><a href="#documentation">Documentation</a></li> <li><a href="#faq">FAQ</a></li> <li><a href="#important-notes">Important Notes</a></li> <li><a href="#support">Support</a></li> <li><a href="#project-commands">Project Commands</a></li> <li><a href="#changelog--release-notes-and-versioning">Changelog / Release Notes and Versioning</a></li> <li><a href="#built-tested-and-documented-with">Built, Tested and Documented With</a></li> <li><a href="#authors">Authors</a></li> <li><a href="#license">License</a></li> </ul> <a href="#quick-start-web-application" id="quick-start-web-application" style="color: inherit; text-decoration: none;"> <h2>Quick Start: Web Application</h2> </a> Import the library first: <pre><code class="language-html"><script src="https://cdn.jsdelivr.net/npm/scandit-sdk@5.x"></script> </code></pre> Add an HTML element to host barcode picker UI: <pre><code class="language-html"><div id="scandit-barcode-picker"></div> </code></pre> Configure the library and start scanning: <pre><code class="language-js">ScanditSDK.configure("YOUR_LICENSE_KEY_IS_NEEDED_HERE", { engineLocation: "https://cdn.jsdelivr.net/npm/scandit-sdk@5.x/build/", }) .then(() => { return ScanditSDK.BarcodePicker.create(document.getElementById("scandit-barcode-picker"), { // enable some common symbologies scanSettings: new ScanditSDK.ScanSettings({ enabledSymbologies: ["ean8", "ean13", "upca", "upce"] }), }); }) .then((barcodePicker) => { // barcodePicker is ready here, show a message every time a barcode is scanned barcodePicker.on("scan", (scanResult) => { alert(scanResult.barcodes[0].data); }); }); </code></pre> Alternatively you can use our Web Component (currently beta), please check the <a href="#web-component-integration">Web Component Integration</a> section. That's it! You will find below more details about library <a href="#getting-started-web-application">loading/setup</a>, <a href="#configuration">configuration</a> and <a href="#usage">usage</a>. <a href="#getting-started-web-application" id="getting-started-web-application" style="color: inherit; text-decoration: none;"> <h2>Getting Started: Web Application</h2> </a> These instructions will help you set up the library for a quick and simple deployment as a JavaScript script included in your webpage / web application. You can use the <a href="https://jsdelivr.com">jsDelivr</a> or <a href="https://unpkg.com">UNPKG</a> CDN to easily <a href="https://semver.npmjs.com">specify a certain version (range)</a> and include our library as follows (example for <code>5.13.0</code>: the current version automatically retrieved when specifying a <code>5.x</code> version; check our latest available library <a href="https://docs.scandit.com/stable/web/CHANGELOG.md">here</a>): <pre><code class="language-html"><script src="https://cdn.jsdelivr.net/npm/scandit-sdk@5.x"></script> </code></pre> or <pre><code class="language-html"><script src="https://unpkg.com/scandit-sdk@5.x"></script> </code></pre> Or download the library with <a href="https://github.com/npm/npm">npm</a> / <a href="https://github.com/yarnpkg/yarn">Yarn</a>, save it and include it from your local files. Via NPM: <pre><code class="language-bash">npm install scandit-sdk --save </code></pre> Via Yarn: <pre><code class="language-bash">yarn add scandit-sdk </code></pre> Include as <a href="https://github.com/umdjs/umd">UMD module</a> (this is most probably what you need): <pre><code class="language-html"><script src="/node_modules/scandit-sdk/build/browser/index.min.js"></script> </code></pre> Include as <a href="https://jakearchibald.com/2017/es-modules-in-browsers/">ES module</a>: <pre><code class="language-html"><script type="module" src="/node_modules/scandit-sdk/build/browser/index.esm.min.js"></script> </code></pre> Non-minified modules are also available if needed: just include the non-".min" file. The library will then be accessible via the global <code>ScanditSDK</code> object. <a href="#getting-started-local-development" id="getting-started-local-development" style="color: inherit; text-decoration: none;"> <h2>Getting Started: Local Development</h2> </a> These instructions will help you set up the library for local development and testing purposes, include it in a more complex JavaScript or TypeScript project and make it part of your final deployed code later built and bundled via tools like <a href="https://github.com/webpack/webpack">Webpack</a>, <a href="https://github.com/rollup/rollup">Rollup</a> or <a href="https://github.com/browserify/browserify">Browserify</a>. Download the library with <a href="https://github.com/npm/npm">npm</a> / <a href="https://github.com/yarnpkg/yarn">Yarn</a>. Via NPM: <pre><code class="language-bash">npm install scandit-sdk --save </code></pre> Via Yarn: <pre><code class="language-bash">yarn add scandit-sdk </code></pre> We provide two different bundled versions of the library depending on your needs: <ul> <li><a href="http://www.commonjs.org/specs/modules/1.0/">CommonJS module</a> (with type definitions) - <code>build/main</code></li> <li><a href="https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/import">ES6 module</a> (with type definitions) - <code>build/module</code></li> </ul> For reference, you also have the following browser bundles: <ul> <li><a href="https://github.com/umdjs/umd">UMD module</a> - <code>build/browser/index.js</code></li> <li><a href="https://jakearchibald.com/2017/es-modules-in-browsers/">ES module</a> - <code>build/browser/index.esm.js</code></li> </ul> The library can be included in your code via either CommonJS or ES imports. ES2015 (ES6): <pre><code class="language-javascript">import * as ScanditSDK from "scandit-sdk"; </code></pre> CommonJS: <pre><code class="language-javascript">var ScanditSDK = require("scandit-sdk"); </code></pre> With ES imports it's also possible to use single components. For example: <pre><code class="language-javascript">import { Barcode, BarcodePicker, ScanSettings, configure } from "scandit-sdk"; </code></pre> <a href="#configuration" id="configuration" style="color: inherit; text-decoration: none;"> <h2>Configuration</h2> </a> The first thing that is needed to use the library is to do an initial configuration of the <code>ScanditSDK</code> object, this is required before instantiating the main library components (<code>BarcodePicker</code> and <code>Scanner</code> objects). For optimal performance, this configuration/initialization should be done as soon as possible in your application (even before scanning is actually required) to ensure needed components are preloaded and initialized ahead of time. The configuration function returns a promise and looks as follows: <pre><code class="language-javascript">ScanditSDK.configure(licenseKey, { engineLocation: "/path", }); </code></pre> The first required configuration option is a valid Scandit license key - this is necessary for the library to work and is verified at configuration time. In order to get your license key you must <a href="https://ssl.scandit.com/customers/new?p=test&source=websdk">register and login to your account</a>. The key will be available (and configurable) in your personal dashboard and is tied to your website / web application. The next (often required) optional configuration option is the location of the Scandit Data Capture library location (external WebAssembly files): <code>scandit-engine-sdk.min.js</code> and <code>scandit-engine-sdk.wasm</code>. WebAssembly requires these separate files which are loaded by our main library at runtime. They can be found inside the <code>build</code> folder in the library you either download or access via a CDN; if you download the library, these files should be put in a path that's accessible to be downloaded by the running library script. The configuration option that you provide should then point to the folder containing these files, either as a path of your website or an absolute URL (like the CDN one). By default the library will look at the root of your website. If you use a CDN to access the library, you will want to set this to <code>"https://cdn.jsdelivr.net/npm/scandit-sdk/build"</code>, <code>"https://unpkg.com/scandit-sdk/build"</code>, or similar. Please ensure that the version of the main library that you set up in the "Getting Started" section corresponds to the version of the external Scandit Data Capture library retrieved via the <code>engineLocation</code> option, either by ensuring the served files are up-to-date or the path/URL specifies a specific version. In case a common CDN is used here (jsDelivr or UNPKG) the library will automatically internally set up the correct URLs pointing directly at the files needed for the matching library version. It is highly recommended to handle the serving of these files yourself on your website/server, ensuring optimal compression, no request redirections and correct caching headers usage; thus resulting in faster loading. A configuration call could look as follows: <pre><code class="language-typescript">ScanditSDK.configure("YOUR_LICENSE_KEY_IS_NEEDED_HERE", { engineLocation: "build/", }).then(() => { // ... ready to instantiate a BarcodePicker or Scanner here }); </code></pre> Here is the same code snippet using <code>async</code>/<code>await</code>: <pre><code class="language-typescript">// inside an async function await ScanditSDK.configure("YOUR_LICENSE_KEY_IS_NEEDED_HERE", { engineLocation: "build/", }); // ... ready to instantiate a BarcodePicker or Scanner here </code></pre> Note that camera access requests are done lazily only when needed by a <code>BarcodePicker</code> (or <code>Scanner</code>) object. To make the loading process faster when scanning is actually needed, it is recommended depending on the use case to create in advance a (hidden and paused) <code>BarcodePicker</code> or <code>Scanner</code> object, to later show and unpause it when needed. You can also eagerly ask only for camera access permissions by calling the <code>ScanditSDK.CameraAccess.getCameras()</code> function. An example of this advanced usage can be found in the <code>example_background.html</code> file. More details are also given in the next section. Check the documentation for additional options available on configuration. <a href="#usage" id="usage" style="color: inherit; text-decoration: none;"> <h2>Usage</h2> </a> Once the library has been configured, there are two main ways to interact with it: via the <code>BarcodePicker</code> object, providing an easy to use high-level UI and API to setup barcode scanning via cameras, or via the <code>Scanner</code> object, providing only low level methods to process image data. In order to use the <code>BarcodePicker</code>, an HTML element must be provided to act as (parent) container for the UI. You can configure size and other styling properties/restrictions by simply setting rules on this element - the picker will fit inside it. A sample element could look as follows: <pre><code class="language-html"><div id="scandit-barcode-picker" style="max-width: 1280px; max-height: 80%;"></div> </code></pre> The <code>BarcodePicker</code> can then be created by simply passing the previous HTML element plus optional settings; this will show the UI, access the camera, initialize the Scandit Data Capture library and start scanning. JavaScript: <pre><code class="language-javascript">ScanditSDK.BarcodePicker.create(document.getElementById("scandit-barcode-picker"), { playSoundOnScan: true, vibrateOnScan: true, }).then(function (barcodePicker) { // barcodePicker is ready here to be used (rest of the tutorial code should go here) }); </code></pre> Typescript: <pre><code class="language-typescript">BarcodePicker.create(document.getElementById("scandit-barcode-picker"), { playSoundOnScan: true, vibrateOnScan: true, }).then((barcodePicker) => { // barcodePicker is ready here to be used (rest of the tutorial code should go here) }); </code></pre> By default, no symbology is enabled for recognition so nothing special will happen; we can now quickly set up <code>ScanSettings</code> to enable wanted symbologies plus other more advanced options if needed (we could and should already have done it via the previous constructor). Setting up some sample configuration looks as follows. JavaScript: <pre><code class="language-javascript">const scanSettings = new ScanditSDK.ScanSettings({ enabledSymbologies: [ScanditSDK.Barcode.Symbology.EAN8, ScanditSDK.Barcode.Symbology.EAN13], codeDuplicateFilter: 1000, // Minimum delay between duplicate results }); barcodePicker.applyScanSettings(scanSettings); </code></pre> TypeScript: <pre><code class="language-typescript">const scanSettings = new ScanSettings({ enabledSymbologies: [Barcode.Symbology.EAN8, Barcode.Symbology.EAN13], codeDuplicateFilter: 1000, // Minimum delay between duplicate results }); barcodePicker.applyScanSettings(scanSettings); </code></pre> The picker is now actively scanning the selected symbologies (detecting the same barcode a maximum of one time per second), if we later want to change the settings we just have to modify the object and apply it again to the picker. In order to react to a successful <code>scan</code> event with your code you can attach one or more listener functions to the picker. JavaScript: <pre><code class="language-javascript">barcodePicker.on("scan", (scanResult) => { alert( scanResult.barcodes.reduce((string, barcode) => { return string + `${ScanditSDK.Barcode.Symbology.toHumanizedName(barcode.symbology)}: ${barcode.data}\n`; }, "") ); }); </code></pre> TypeScript: <pre><code class="language-typescript">barcodePicker.on("scan", (scanResult) => { alert( scanResult.barcodes.reduce((string, barcode) => { return string + `${Barcode.Symbology.toHumanizedName(barcode.symbology)}: ${barcode.data}\n`; }, "") ); }); </code></pre> That's it! Please refer to the <a href="#documentation">documentation</a> for all the other available configuration options and functions, as well as more advanced <code>ScanSettings</code> and <code>Scanner</code> usage. <a href="#text-recognition-ocr-configuration" id="text-recognition-ocr-configuration" style="color: inherit; text-decoration: none;"> <h3>Text Recognition (OCR) Configuration</h3> </a> Text recognition (OCR) is available for passports and ID cards via their Machine Readable Zone (MRZ); these are also called Machine Readable Travel Documents (MRTD). Note that this functionality is disabled by default and requires specific license features in order to be usable. In order to make use of this functionality, two new and alternative sets of external Scandit Data Capture library JS/WASM (external WebAssembly) files is used: <code>scandit-engine-sdk-ocr.min.js</code>/<code>scandit-engine-sdk-ocr.wasm</code> and <code>scandit-engine-sdk-ocr-simd.min.js</code>/<code>scandit-engine-sdk-ocr-simd.wasm</code>. These files must be set up to be copied from the <code>build</code> folder and be available to be downloaded as needed, similarly to the existing set of files (nothing needs to be done when using a CDN). Depending on the dynamically detected browser features, one of the sets will be used. The following are the changes needed in order to make use of text recognition capabilities. First of all the library has to be initially configured to load the necessary OCR version of the library as follows. <pre><code class="language-javascript">ScanditSDK.configure(licenseKey, { engineLocation: "/path", loadTextRecognition: true, }); </code></pre> Then we create a sample regular expression deciding what will be recognized as text, in this case we are interested in Machine Readable Travel Documents (MRTD) text data: <pre><code class="language-javascript">const mrtdRegex = /[AIC][A-Z0-9<]{29}\n[A-Z0-9<]{30}\n[A-Z0-9<]{30}\n?|[A-Z0-9<]{36}\n[A-Z0-9<]{36}\n?|P[A-Z0-9<]{43}\n[A-Z0-9<]{44}\n?|V[A-Z0-9<]{43}\n[A-Z0-9<]{44}\n?|V[A-Z0-9<]{35}\n[A-Z0-9<]{36}\n?|[A-Z0-9<]{7}<<\n[A-Z0-9<]{30}\n[A-Z0<]{30}\n?/; </code></pre> We can now create new <code>TextRecognitionSettings</code> to configure the text recognition behaviour as follows. JavaScript: <pre><code class="language-javascript">const textRecognitionSettings = new ScanditSDK.TextRecognitionSettings({ regex: mrtdRegex, }); </code></pre> TypeScript: <pre><code class="language-typescript">const textRecognitionSettings = new TextRecognitionSettings({ regex: mrtdRegex, }); </code></pre> Afterwards, <code>ScanSettings</code> need to be set to switch from the default <code>CODE</code> recognition mode to <code>TEXT</code> and the new <code>TextRecognitionSettings</code> are also passed as follows. JavaScript: <pre><code class="language-javascript">const scanSettings = new ScanditSDK.ScanSettings({ recognitionMode: ScanditSDK.ScanSettings.RecognitionMode.TEXT, textRecognitionSettings: textRecognitionSettings, }); </code></pre> TypeScript: <pre><code class="language-typescript">const scanSettings = new ScanSettings({ recognitionMode: ScanSettings.RecognitionMode.TEXT, textRecognitionSettings: textRecognitionSettings, }); </code></pre> In order to react to obtain the new text recognition results, the <code>scan</code> event listener can be modified as follows: <pre><code class="language-javascript">barcodePicker.on("scan", (scanResult) => { alert( scanResult.texts.reduce((string, text) => { return `${<span