Getting Started

A step-by-step guide on how to integrate the STRICH SDK into your app and get started with barcode scanning.

Installing from NPM

The STRICH SDK is published as an NPM package. It can be added to your project like any other NPM 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. As barcode scanning is typically a critical function in an app, we recommend to a more conservative approach: either use ~x.y.z which will automatically apply minor version upgrades (patches) or x.y.z to pin an exact version.

Loading STRICH from a CDN

Alternatively, you can load STRICH from a CDN like jsDeliver as an ES6 module (JavaScript import keyword):

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

Or if you prefer to include the library via a <script> tag, you may use the non-modular flavor:

<script src="https://cdn.jsdelivr.net/npm/@pixelverse/strichjs-sdk@latest/dist/strich-noesm.js"></script>

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.

License keys are restricted to one or more application URLs (the scope of the license). So if for example your scanning app will be available at https://myapp.example.com and https://myapp-staging.example.com, you need to add those two URLs as the scope of the license key when creating it. You may 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.

Loopback and private IP address ranges such as localhost/127.0.0.1 and 192.168.x.y which are often used during development need not be specified. These are automatically included in the license key.

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.

Defining the host element

Finally, we add a BarcodeReader instance to the app. We do so by defining a host element, a DOM element that will contain the BarcodeReader UI, e.g. the camera stream, view finder, camera controls, etc. The host element needs to have position: relative positioning.

A typical scanning app has a vertical layout with the scanner on top, results below and 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 -->
  </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 the div with ID scanner, so we can refer to it via the CSS selector #scanner. The host element should not change its size during regular operation, and its selector should only match a single element.

Supplying a configuration

Before instantiating the BarcodeReader, we need to create a configuration. The configuration defines the functional and visual characteristics of the BarcodeReader instances.

For a good user experience, it is crucial to restrict the types of barcodes to be detected by the BarcodeReader to only the symbologies (barcode types) used in your process, and configure the active area to be appropriate for the layout of your app and the type of code to be detected. Fewer types of codes being searched in a smaller area lead to faster processing and quicker detection times.

You can find the supported symbologies in the API reference. Some symbologies like Code 128 support variable lengths and may require you to specify a minLen and/or maxLen for very short or very long barcodes. Instead of providing just the name of the symbology, you may also provide an object containing these values.

In the example below, we restrict the BarcodeReader to only look for Code 128 barcodes, and only look for them along a horizontal, bar-shaped area in the center of the host element (check out th API Reference for more detailed documentation). We also set a duplicateInterval of 750ms, 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: 750
  },
  locator: {
    regionOfInterest: {
      // restrict active area to a horizontal bar in the center
      left: 0.05,
      right: 0.05,
      top: 0.35,
      bottom: 0.35
    }
  },
  feedback: {
    // get audio and vibration feedback for scans
    audio: true,
    vibration: true
  }
};

Initializing the BarcodeReader

Finally, we can initialize the BarcodeReader by creating a BarcodeReader instance and passing the previously created configuration to the constructor.

Upon successful initialization, a handler for code detections must be installed. The handler is where you decide what should happen when a barcode is scanned.

The BarcodeReader instance should be retained by your application, so you can later call destroy it when it is no longer needed, or pause/resume scanning between user interactions. It is also possible to temporarily hide and then show the scanner again, without losing camera access.

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

Initialization requires camera access, which is acquired 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.

Next steps

You should now be ready to scan barcodes in your web app. For more information regarding the aforementioned steps, or more detailed sample code, check out our other resources:

API Reference
Sample code repository on GitHub

Last modified: 27 August 2024