Getting Started

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 your dependency to the latest minor version. If you would like to be more conservative in applying upgrades, you can change this to ~x.y.z which will only automatically upgrade to patch versions.

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. 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.

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.

The SDK needs to be initialized once with the license key, using the StrichSDK.initialize() function.

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

After the call completes successfully, the SDK is ready to use.

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.

Finally, we add BarcodeReader instance to the app. We do so by defining a host element, basically a DOM element that will contain the visual parts of the BarcodeReader, e.g. the camera stream, view finder, 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.

Before instantiating the BarcodeReader, we supply a configuration. The configuration specifies the functional and visual characteristics of the BarcodeReader. Crucially, we restrict the BarcodeReader to detect only the types of codes our application requires.

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

For a good user experience, it is crucial to restrict the types of barcodes to be detected by the BarcodeReader to only the symbologies 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 / quicker detection times.

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 the API reference for more detailed documentation).

let config = {
  // the CSS selector identifying the host element
  selector: '#scanner',
  engine: {
    // restrict to the required symbologies
    symbologies: ['code128'],
  },
  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
  }
};

Finally, we can initializing 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 also 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, e.g. by displaying a camera access will be required in th next step notice.

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 (GitHub)