The Popup Scanner

Introduction

Introduced in version 1.6.0 of the SDK, PopupScanner is a pre-built modal scanning dialog that you can integrate into your app with just a single line of code. The entire UI and management of the underlying BarcodeReader is taken care of for you.

It is intended for use cases where tight integration with the host app UX and custom styling is less important.

Example: Scanning a serial number barcode using PopupScanner

Scanning Barcodes

To scan barcodes, call the PopupScanner.scan() method and supply a PopupConfiguration as the argument. The SDK needs to be in an initialized state.

Scanning is an asynchronous operation that returns a Promise, and should be awaited using the await operator. The method returns as soon as a matching barcode is read, and returns undefined in case the user dismissed the dialog without scanning a barcode.

Example: Scanning Code 128 barcodes using PopupScanner

// invoke PopupScanner, restrict to Code 128 symbology
let barcodes = await PopupScanner.scan({ symbologies: ['code128'] });
if (barcodes) {
    // process the scanned barcode value
    handleBarcodeScan(barcodes[0].data);
} else {
    // handle user cancellation...
}

The Popup Scanner is a semi-translucent dialog that pops up over your app’s UI. There's a small margin on all sides so it is clear that the popup is shown in the context of your app.

Title Area

The title area is used for user guidance — we recommend using something specific to the use case as the text, like Scan serial number or Scan document ID. The default text is Scan Barcode and is localized based on the browser’s locale. For further customization, a background color matching your app’s color palette can be set.

Active Area

The active area or region of interest is bordered by a rectangle. Its dimensions are set automatically based on the configured 1D and 2D symbologies.

Cancel Button

The cancel button dismisses the dialog, without scanning a barcode. This causes the PopupScanner.scan() to return undefined. The default text is Cancel and is localized based on the browser’s locale. The text and the button background color can be overridden from their defaults.

Sample Configuration

The following snippet illustrates the full extent of customization that can be achieved through PopupConfiguration.

// A fully customized popup scanner configuration, for illustration
const popupCfg = {

    /**
     * The symbologies to recognize. Here we use Code 128 with a
     * length of 15...17 characters and QR codes */
     */
    symbologies: [{ name:'code128', 'minLen':15, 'maxLen':17}, 'qr'],
    
    /**
     * Overrides for textual elements
     */
    labels: {
        title: 'Scan IMEI Number',
        cancel: 'Abort Scanning'
    },
    
    /**
     * Overrides for background colors.
     */
    style: {
        cancelButtonBackgroundColor: 'rgba(1,0,0,0.5)',
        cancelButtonColor: 'rgb(1,1,1)',
        titleBackgroundColor: 'rgb(0,0,0)',
        titleColor: 'rgb(1,1,1)',
    },
    
    /**
     * Choose full-hd for dense 2D or long 1D codes, otherwise hd
     * is fine.
     */
    resolution: 'hd',
    
    /**
     * Configure audible and haptic feedback.
     */
    feedback: {
         audio: true,
         vibration: true
    },
    
    /**
     * Custom code to further validate barcodes.
     * Here we check against a regular expression.
     */
    detectionHandler: (detections) => {
        return detections.some(d => d.data.match('\d{15,17}'));
    }

}

Sample Code

A vanilla JavaScript sample is available on Github illustrating how to use PopupScanner for filling form inputs.

Requirements

PopupScanner requires browser support for the <dialog> element, a modern Web API which has been widely available since early 2022.

Last modified: 27 November 2024