Step-by-step instructions for getting your scanning app up and running using STRICH SDK.
Installing from NPM
The STRICH SDK is published as an NPM package. It can be added to your project like any other NPM package:
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.
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.
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.
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
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.
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.
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.
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.
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: