Getting Started | SDK Documentation

Obtaining the Library

Installing from NPM

The STRICH SDK is published as an NPM package. It can be added to your NPM project like any other package:

npm install @pixelverse/strichjs-sdk

By default, npm will add a version requirement of ^x.y.z, which will automatically update the dependency to the latest minor version every time you run npm install.

Loading STRICH from a CDN

Alternatively, you can load STRICH from a CDN like jsDeliver as an ES6 module using an import statement:

import {StrichSDK, BarcodeReader} from "https://cdn.jsdelivr.net/npm/@pixelverse/strichjs-sdk@latest";

Loading With a <script> Tag

If you can not use ES6 modules and would like to load STRICH with a <script> tag, we also provide a non-modular build flavor.

Creating a license key

To initialize the SDK, you need to obtain a license key first. License keys can be created in the Customer Portal after creating an account and starting the free 30-day trial.

License keys are restricted to one or more application URLs (the scope of the license). So if your scanning app will be available at https://app.example.com and you have staging and development environments, you need to add those URLs to the license key when creating it. You can also create separate license keys if you already have a mechanism for injecting per-environment configurations.

Please note that HTTPS is required. Web browsers only allow access to the camera feed for secure origins. For more information on how to serve from a secure origin during development, please refer to the Deployment Guide.

Initializing the SDK

The SDK needs to be initialized once with the license key created previously by calling StrichSDK.initialize(). When the Promise resolves successfully, the SDK is ready to use.

StrichSDK.initialize('eyJhbGciOiJIUzI1NiIsInR...')
    .then(() => console.log('STRICH SDK initialized'));

We recommend doing SDK initialization early, before the user expects to see the barcode scanning screen, for instance during the rest of your app initialization. SDK initialization is asynchronous and requires internet connectivity, except for Enterprise licenses which support offline operation.

Choosing the Integration

As of version 1.6.0 of the SDK, we now support two kinds of integrations:

BarcodeReader: An embeddable barcode reader that you control. You supply a container in your app UI and are in charge of managing the BarcodeReader. Allows full flexibility in designing your scanning experience.
PopupScanner: An out-of-the-box scanning experience presented in a modal dialog. Perfect for simple scanning use cases that do not require a lot of customization. No changes to your app UI are necessary. Scan barcodes with a single line of code.

The remainder of this guide will focus on the BarcodeReader integration. Please refer to the PopupScanner documentation if you want to explore that integration, or if you want to quickly verify that the SDK is working.

Integrating the BarcodeReader

Defining the Host Element

We need to provide the BarcodeReader with a place to live. We do so by defining a host element – a DOM element that will contain the UI, i.e. the camera feed, view finder, camera controls, etc.

Example: Vertical Layout with BarcodeReader on Top

A typical scanning app has a vertical layout with the scanner on top, results below and an action bar at the bottom.

<div style="display: flex; flex-direction: column">
  <div id="scanner" style="position: relative; height: 240px">
    <!-- BarcodeReader will be instantiated here - position:relative is required! -->
  </div>
  <div class="results">
    <!-- Display scanned results -->
  </div>
  <div class="actions">
    <!-- Action buttons, e.g. Save, Send, Cancel, etc. -->
  </div>
</div>

Here, the host element is a div with ID scanner, so we can refer to it via the CSS selector #scanner.

Creating a Configuration

Before we can create the BarcodeReader, we need to create a configuration – an object that specifies the functional and visual characteristics of the BarcodeReader.

For a good scanning experience, it is important to restrict the types of barcodes to be detected by the BarcodeReader to only the ones you need. STRICH will automatically set the region of interest (the area where barcodes are detected) to something appropriate for selected barcode types.

Example: Configuration for Code 128 Barcodes

In the example below, we only look for Code 128 barcodes. We also set a duplicateInterval of 2.5 seconds, avoiding repeated scans of the same code over a short time frame.

let config = {
  // the CSS selector identifying the host element
  selector: '#scanner',
  engine: {
    // restrict to the required symbologies
    symbologies: ['code128'],
    // filter duplicate results
    duplicateInterval: 2500
  }
};

Initializing the BarcodeReader

Initializing the BarcodeReader is a two-step process: the configuration is passed to the constructor, then the initialize() method is called, which will request access to the camera.

Barcode recognition starts once you call the start() method. To receive barcode detections in your app code, provide a callback using the detected property. The BarcodeReader will invoke this callback whenever barcodes are detected.

Example: Initializing and Starting a BarcodeReader

new BarcodeReader(config).initialize()
  .then(result => {

    // initialization successful, store BarcodeReader for later
    this.barcodeReader = result;

    // register handler for code detections
    this.barcodeReader.detected = (detections) => {
      // .. do something with the scanned codes
    };

    // start reading barcodes!
    return this.barcodeReader.start();
  })
  .catch(error => {
    // initialization failed (error message displayed in BarcodeReader)
  });

Camera Access

Initialization requires camera access, which is gated through a browser prompt. It is usually a good idea to make the user aware of this prior to initializing the BarcodeReader, for example by displaying a camera access will be required in the next step notice.

The SDK provides utility functions for determining the current camera permission state and whether the device actually has a camera.

Destroying the BarcodeReader

When you are done with BarcodeReader, it needs to be released by calling the destroy method.

Testing on a Smartphone

STRICH is optimized for barcode scanning in web apps running on smartphones. It is very important to always test your app on actual smartphones.

During development, you are probably running your app locally on your desktop or laptop. When accessing your app from a smartphone on the same network, you might have to do some extra work to set up SSL, as camera access only works if the app is hosted via HTTPS or is accessed via localhost, a secure context.

Please refer to the Deployment Guide for more information about how to expose your app via HTTPS during development.

Next Steps

You are now ready to scan barcodes in your web app. For further advice, check out these additional resources.

API Reference – explore the SDK and its features with our reference documentation.
Deployment Guide – What to know when taking your app live.
Best Practices for Barcode Scanning Apps – Observing these practices ensures a good scanning experience for your users.
Sample code repositories on Github