Options
All
  • Public
  • Public/Protected
  • All
Menu

Scandit Barcode Scanner SDK for the Web (Beta)

Enterprise barcode scanning performance in your browser via JavaScript and WebAssembly.

Made by Scandit

Access cameras available on the devices for video input, display a barcode picker interface, configure in-depth settings for barcode symbologies and performance, and let users easily scan barcodes in your web application.

To use this library you must possess a valid Scandit account and license key. You can register for a free trial here.

Table of Contents:

Getting Started - Web Application

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 UNPKG or jsDelivr CDN to easily include our (latest) library as follows:

<script src="https://unpkg.com/scandit-sdk"></script>
<!-- or -->
<script src="https://cdn.jsdelivr.net/npm/scandit-sdk"></script>

A specific version of the library (example for 1.3.1) can also be included with:

<script src="https://unpkg.com/scandit-sdk@1.3.1"></script>
<!-- or -->
<script src="https://cdn.jsdelivr.net/npm/scandit-sdk@1.3.1"></script>

Or download the library with npm / Yarn, save it and include it from your local files.

Via NPM:

npm install scandit-sdk --save

Via Yarn:

yarn add scandit-sdk

Include as UMD module (this is most probably what you need):

<script src="/node_modules/scandit-sdk/build/browser/index.min.js"></script>

Include as ES module:

<script type="module" src="/node_modules/scandit-sdk/build/browser/index.esm.min.js"></script>

Non-minified modules are also available if needed: just include the non-".min" file.

The library will then be accessible via the ScanditSDK object.

Getting Started - Local Development

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 Webpack, Rollup or Browserify.

Download the library with npm / Yarn.

Via NPM:

npm install scandit-sdk --save

Via Yarn:

yarn add scandit-sdk

We provide two different bundled versions of the library depending on your needs:

For reference, you also have the following browser bundles:

The library can be included in your code via either CommonJS or ES imports.

ES2015 (ES6):

import { * as ScanditSDK } from "scandit-sdk";

CommonJS:

var ScanditSDK = require("scandit-sdk");

With ES imports it's also possible to use single components. For example:

import { Barcode, BarcodePicker, ScanSettings, configure } from "scandit-sdk";

Configuration

The first thing that is needed to use the library is to do an initial configuration of the ScanditSDK object, this is required before any other function of the library can be used.

The configuration function looks as follows:

ScanditSDK.configure(licenseKey: string, {
  engineLocation: string = "/",
  preloadEngineLibrary: boolean = false,
  preloadCameras: boolean = false
})

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 register and login to your account. 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 Engine library location (external WebAssembly files): scandit-engine-sdk.min.js and scandit-engine-sdk.wasm. WebAssembly requires these separate files which are loaded by our main library at runtime. They can be found inside the build 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 the CDN to access the library, you will want to set this to "https://unpkg.com/scandit-sdk/build", "https://cdn.jsdelivr.net/npm/scandit-sdk/build", or similar.

The following configuration options lets you decide if you would like to eagerly load the external Scandit Engine library and/or the available cameras as soon as this function is called (by default they are not). The library load could take some time due to the download size and performance needed to prepare the external library, while the camera load could also take some time and ask the user for camera access permissions if needed. The required loads can be made later on via ScanditSDK.loadEngineLibrary() and ScanditSDK.CameraAccess.getCameras(), or are made later on when needed, if never done before.

A configuration call could look as follows:

ScanditSDK.configure("LICENSE_KEY_HERE", {
  engineLocation: "build/"
});

Usage

Once the library has been configured, there are two main ways to interact with it: via the BarcodePicker object, providing an easy to use high-level UI and API to setup barcode scanning via cameras, or via the Scanner object, providing only low level methods to process image data.

In order to use the BarcodePicker, 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:

<div id="scandit-barcode-picker" style="max-width: 1280px; max-height: 80%;"></div>

The BarcodePicker 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 Engine library and start scanning:

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)
});

By default, no symbology is enabled for recognition so nothing special will happen; we can now quickly set up ScanSettings to enable wanted symbologies plus other more advanced options if needed (we could also already have done it via the previous constructor). Setting up some sample configuration looks as follows:

var scanSettings = new ScanditSDK.ScanSettings({
  enabledSymbologies: ["ean8", "ean13", "upca", "upce", "code128", "code39", "code93", "itf"],
  codeDuplicateFilter: 1000
});
barcodePicker.applyScanSettings(scanSettings);

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 scan event with your code you can attach one or more listener functions to the picker:

barcodePicker.onScan(function(scanResult) {
  alert(scanResult.barcodes.reduce(function(string, barcode) {
    return string +
      ScanditSDK.Barcode.Symbology.toHumanizedName(barcode.symbology) +
      ": " + barcode.data + "\n";
  }, ""));
});

That's it!

Please refer to the documentation for all the other available configuration options and functions, as well as more advanced ScanSettings and Scanner usage.

Example Application

You can have a look at the example.html file for a (almost) ready to use webpage using the library. A valid license key must be inserted replacing "YOUR_LICENSE_KEY_IS_NEEDED_HERE"; you then only need to serve the folder containing it for it to run. Note that it depends on the build folder contents.

You can use your own tools, or the following proposed simple way to quickly set up a local server.

Globally install the http-server JavaScript package.

Via NPM:

npm install http-server -g

Via Yarn:

yarn global add http-server

Run the new package from the folder containing example.html with:

http-server

Please note that this simple server will not compress files thus resulting in slower loading times than normal.

Finally, access the webpage via your favourite (and supported) browser at http://127.0.0.1:8080/example.html!

Browser Support and Requirements

Due to the advanced features required and some limitations imposed by operating systems, only the browsers listed below are able to correctly use this library.

The following is a list of the main required browser features together with links to updated support statistics:

This results in the current browser compatibility list:

  • Desktop
    • Chrome 57+
    • Firefox 52+ (except ESR 52)
    • Opera 44+
    • Safari 11+
    • Edge 16+
  • Mobile - Android
    • Chrome 59+
    • Firefox 55+
  • Mobile - iOS
    • Safari 11+

Important Notes

  • HTTPS deployment

    You must serve your final web application / website via HTTPS: due to browser security restrictions, camera access is only granted if that's the case; this is not needed for local IP addresses during development.

  • WASM file format

    Please make sure that your webserver serves the scandit-engine-sdk.wasm file with Content-Type: binary/octet-stream (it should be the default), failure to do so will result in some browsers failing to execute the external library.

  • Cookies for device identification

    For licensing purposes we use cookies to assign and store/retrieve completely random device IDs of end users of the library. This may change in the future, but currently it cannot be disabled.

  • Analytics data

    Our Scandit Engine library makes several different requests at initialization and during usage of the scanning library to our servers, in order to store and provide analytics data about the usage of the SDK. This request/information is the same as what we collect for other SDKs.

  • License key

    A Scandit license key for this particular library is required. The license key is verified at runtime with each library usage and is linked/limited to your specified domain names to prevent abuse. Local addresses and private IPs are also allowed for testing independently from the domain name restriction in a valid license.

  • Camera performance

    On desktop or Android devices, the Chrome browser provides more advanced camera controls and results in better performance than other browsers. At the moment, it is also the only browser to support manual camera focus operations (via tapping the screen) and mobile torch toggling, where available. More browsers are expected to support these advanced features soon.

  • Scanning performance

    The performance of the scanner depends on the device and camera being used. Nonetheless for optimal speed/quality, please keep in mind the following guidelines/tips:

    • Enable only the symbologies you really need to scan (1D code scanning is usually faster than 2D code scanning, only having 1D codes enabled is faster).
    • Only increase the maximum amount of codes per single frame from the default of 1 if it's really needed.
    • If possible, restrict the scanning search area to be less than the default full frame.
    • Depending on your use case, it might be worth to enable Full HD video quality, resulting in slower frame processing times but higher resolution recognition.
  • Library performance

    In order to provide the best possible experience in your web application, please follow these guidelines to guarantee optimal performance of this library:

    • Ensure the JavaScript assets and the scandit-engine-sdk.min.js and scandit-engine-sdk.wasm files are served compressed and with caching enabled by your web server.
    • Re-use BarcodePicker objects whenever possible by hiding and showing them instead of destroying and recreating them: each object needs to load and initialize the external library on creation.
    • If possible, create a (hidden and paused) BarcodePicker in the background and simply resume scanning by switching its visibility to "show" when needed, instead of creating it on the fly to provide instant scanning capabilities.
    • Remember to use destroy() methods on the Scanner or BarcodePicker objects when they are not needed anymore, before they are automatically garbage collected by JavaScript. This will ensure all needed resources are correctly cleaned up.
    • Camera permissions can be asked to the user in advance via this library or other external methods to ensure a more fluid experience depending on the situation. Remember that usually these permissions are stored forever and need only to be asked once.
  • Scandit logo

    In accordance with our license terms, the Scandit logo displayed in the bottom right corner of the barcode picker must be displayed and cannot be hidden by any method. Workarounds are not allowed.

Documentation

An updated in-depth documentation of all of the libraries' specifications and functionalities can be generated/found in the docs folder or can also be accessed online at https://docs.scandit.com/stable/web.

FAQ

  • How big is the library?

    The main library is currently about 55kb (minified, gzipped), while the external Scandit Engine library is around 850kb (gzipped). Keep in mind that you will not need to wait for these files to download to display your webpage / web application, they can be downloaded and prepared in the background without affecting the rest of the application (the Scandit Engine library is also always downloaded and prepared asynchronously in a separate thread).

  • Why is only Safari supported on iOS?

    This is (for now) a limitation imposed by Apple, which doesn't yet allow any external browser using WKWebView from accessing device cameras, see this discussion.

  • How well are barcodes recognized?

    This obviously depends from the specifics of the camera being used, but in general the performance of this library is slightly inferior to what is provided by Scandit's native SDKs. Currently it's not possible to (efficiently) use WebGL instructions inside WebWorkers, meaning no advanced GPU control and functions can be provided to our library. The situation will also improve over time as more of the features present in the native SDK are implemented/enabled and as browsers allow more control over the GPU and camera.

  • Does the library require network access?

    The scanning of barcodes doesn't require network access and is executed completely on the client in the browser. Our engine however needs network access at configuration time to verify license keys and will also attempt to send additional requests afterwards for data analytics purposes (linked to your license key).

  • Why can I see network requests with a 409 error response in the browser's debugger?

    That is normal behaviour and won't affect final users in any way: it's our Scandit Engine library contacting our servers for verification for a device that is already registered and thus is allowed to use the library with the given license key. Note that it's not a JavaScript error but just a network response result that is displayed by Chrome by default in the debugger view (when set to show network responses).

  • Why can I sometimes see "Intervention" messages about blocked vibrate calls in the browser's debugger?

    That is normal behaviour and won't affect final users in any way: some browsers won't allow vibration requests to be called by our library if the user hasn't first touched/clicked the page, and will block these calls (outside from normal JavaScript code execution).

  • Why does my BarcodePicker/Scanner not work/start?

    Please ensure that you correctly configured the library via the ScanditSDK.configure function call before using the objects provided. More specifically check that in its arguments:

    • You provided a valid license key (any domain name restriction will work for local testing).
    • You configured the engineLocation setting appropriately for your folder/deployment structure.

Support

For questions or support please use the form you can find here or send us an email to support@scandit.com.

Project Commands

If you want to work on this project, the following is a list of the most useful npm / Yarn commands you can run in this project (here shown with Yarn).

We suggest you use yarn instead of npm to handle project dependencies to make use of the existing yarn.lock file.

Start developing (watch task for build and tests):

yarn watch

Build and create all output modules:

yarn build

Lint with type checking:

yarn lint

Run unit tests and check coverage:

yarn unit

Generate documentation:

yarn docs

Show all available commands:

yarn info

Versioning and Changelog

We use SemVer for versioning. A log of the project's releases over time with their features and changes can be found in the CHANGELOG.md file.

Built With

Authors

  • Lorenzo W√∂lckner (Scandit)

License

This project is licensed under a custom license - see the LICENSE file for details.

Index

Functions

configure

  • configure(licenseKey: string, __namedParameters?: object): Promise<void>
  • Initialize and configure the Scandit Barcode Scanner SDK library. This function must be called as first thing before using any other function of the library.

    Depending on parameters, device features and user permissions for camera access, any of the following errors could be the rejected result of the returned promise:

    • NoLicenseKeyError
    • UnsupportedBrowserError
    • PermissionDeniedError
    • NotAllowedError
    • NotFoundError
    • AbortError
    • NotReadableError
    • InternalError

    If the external Scandit Engine library is not loaded now, it can later be loaded via loadEngineLibrary, or it will be downloaded and prepared automatically when needed by other objects/functions.

    If the cameras are not accessed now, they can later be loaded via CameraAccess.getCameras, or they will be accessed automatically when needed by other objects/functions.

    Parameters

    • licenseKey: string

      The Scandit license key to be used by the library.

    • Default value __namedParameters: object = {}
      • engineLocation: string

        Default = "/"
        The location of the folder containing the external scandit-engine-sdk.min.js and scandit-engine-sdk.wasm files (external Scandit Engine library). By default they are retrieved from the root of the web application. Can be a full URL to folder or an absolute folder path.

      • preloadCameras: boolean

        Default = false
        Whether to eagerly request access (if needed) and access available cameras with this call.

      • preloadEngineLibrary: boolean

        Default = false
        Whether to eagerly download and prepare the external Scandit Engine library with this call.

    Returns Promise<void>

    A promise resolving when the library has loaded and the available cameras are loaded (if selected).

loadEngineLibrary

  • loadEngineLibrary(): Promise<void>
  • Download and prepare in memory the external Scandit Engine library. If this method isn't called manually the library will be automatically loaded the first time it's required by another of this library's components.

    Returns Promise<void>

    A promise resolving when the external Scandit Engine library has been loaded and is ready.

Legend

  • Module
  • Object literal
  • Variable
  • Function
  • Function with type parameter
  • Index signature
  • Type alias
  • Enumeration
  • Enumeration member
  • Property
  • Method
  • Interface
  • Interface with type parameter
  • Constructor
  • Property
  • Method
  • Index signature
  • Class
  • Class with type parameter
  • Constructor
  • Property
  • Method
  • Accessor
  • Index signature
  • Inherited constructor
  • Inherited property
  • Inherited method
  • Inherited accessor
  • Protected property
  • Protected method
  • Protected accessor
  • Private property
  • Private method
  • Private accessor
  • Static property
  • Static method

Generated using TypeDoc