Skip to main content

Getting started with the Web Barcode Scanner SDK's Classic UI

Opening the scanner​

To open the Barcode Scanner, simply call the relevant SDK function with the configuration object:

const scanner = await scanbotSDK.createBarcodeScanner(configuration);

You should store the barcode scanner object in a globally accessible location, as additional barcode scanner actions are functions of that object.

Disposing of the scanner​

The Barcode Scanner should also be properly disposed of when it has detected and processed the relevant barcodes:

dispose(): void;

The scanner object​

To improve the handling scanner results, the Scanbot SDK offers the following convenience functions to pause and resume detection while you are processing the data on your side:

scanner.resumeDetection(): void;
scanner.pauseDetection(): void;
scanner.isDetectionPaused(): boolean;

Switching between the front and rear camera​

scanner.swapCameraFacing(force?: boolean): void;

swapCameraFacing(true) indicates that only the swapped camera (e.g., the front camera) is acceptable. If the swapped camera is not available, or the user declines the permission to use that camera, the media request will fail.

warning

Firefox on Android: Due to current Firefox browser limitations, we highly recommend checking the running browser and disabling this feature for Firebox browsers.

Switching to a specific available camera​

scanner.fetchAvailableCameras(): Promise<CameraInfo[]>;
scanner.switchCamera(deviceId: string, mirrored?: boolean): void;
scanner.getActiveCameraInfo(): CameraInfo | undefined;
interface CameraInfo {
    deviceId: string;
    label: string;
    facingMode?: CameraFacingMode;
    supportsTorchControl?: boolean;
}

type CameraFacingMode = 'front' | 'back' | 'unknown';

You can search for available cameras on the running browser by using the fetchAvailableCameras method of a scanner.

You can retrieve the label, device ID, and the camera facing mode information of the active camera of a scanner by using the getActiveCameraInfo method.

You can also switch to another available camera by utilizing its device ID with the switchCamera method.

// There can be no cameras available, so check if cameras is not null
const cameras = await scanner.fetchAvailableCameras()
// Current camera info can be unavailable, so check if currentCameraInfo is not null
const currentCameraInfo = scanner.getActiveCameraInfo();
const cameraIndex = cameras.findIndex((cameraInfo) => {
    return cameraInfo.deviceId == currentCameraInfo.deviceId;
});
const newCameraIndex = (cameraIndex + 1) % (cameras.length);
scanner.switchCamera(cameras[newCameraIndex].deviceId);

Controlling the torch (flashlight)​

On some mobile devices, the browser can control the torch (flashlight). Check scanner.getActiveCameraInfo().supportsTorchControl to see if the browser can control the torch for the currently active camera. If true, you can control the torch by using the setTorchState method of the scanner.

scanner.setTorchState(state: boolean): Promise<void>;
info

On Android devices, only Chrome supports torch control. Starting with iOS 17.4, all supported browsers on iOS offer torch control functionality.

Configuration​

The Barcode Scanner takes an instance of BarcodeScannerViewConfiguration as its argument. This is your main object for configuration options, styling and receiving the results.

    let scanner;
    const configuration = {
        //  The `id` of the containing HTML element where the Barcode Scanner will be initialized.
        containerId: 'scanner',
        onBarcodesDetected: (result: BarcodeScannerResultWithSize) => {
            // If you're happy with the result, dispose the scanner right away
            scanner.dispose();
            // Otherwise the scanner will continue scanning and delivering results
            const format = result.barcodes[0].format // The barcode's symbology
            const text = result.barcodes[0].text // The text value of the barcode
            // ...
        }
    }
    scanner = await scanbotSDK.createBarcodeScanner(configuration);

BarcodeScannerViewConfiguration requires the following parameters:

  • containerId: The id of the containing HTML element where the Barcode Scanner will be initialized. Please note: In order to not disturb your layout, the scanner will attempt to not change the size of your container. Therefore, please remember to set an appropriate size on your container, e.g., use <div id="scanner" style="height: 100dvh; width: 100dvw;"></div>.
  • onBarcodesDetected: Your callback for receiving detection results.

BarcodeScannerViewConfiguration also inherits the following optional base properties:

  • videoConstraints: The desired video resolution. Optional, defaults to 1920x1080.
  • mirrored: Whether the screen should be mirrored. Useful when using a user-facing camera. false by default.
  • preferredCamera: Camera label or camera device ID. If not available, a default camera is used as a fallback.
  • onError: Callback when something went wrong.

In addition, the Barcode Scanner has the following configurable options:

  • showFinder: Optional boolean to determine if the scanner should start with the viewfinder rectangle enabled.
  • captureDelay: The delay between receiving detection results, in milliseconds. Defaults to 1000.
  • scannerConfiguration: The parameters for barcode detection. Optional, defaults to new BarcodeScannerConfiguration(). See the API documentation for a description of all the fields.

By default, the most common barcode types are enabled. However, the scanning speed increases if you only specify the barcode formats you are interested in:

scannerConfiguration: {
    barcodeFormatConfigurations: [
        new ScanbotSDK.Config.BarcodeFormatCommonConfiguration({formats: ["QR_CODE", "PDF_417"]}),
    ]
}

The result of onBarcodesDetected is a BarcodeScannerResultWithSize object. See the API documentation for a description of all its fields.

Styling​

Viewfinder-based scanners all have the following two top-level configuration properties:

finder?: ViewFinderConfiguration;
userGuidance?: UserGuidanceConfiguration;

Viewfinder​

The finder property controls the styling of the background and the hole. Its style property can be of either FinderCorneredStyle or FinderStrokedStyle (defaults to FinderCorneredStyle).

Both of them have the following properties and default values:

/** Color of the viewfinder corner's outlines. @defaultValue "#FFFFFFFF"; */
public strokeColor: string = "#FFFFFFFF";
/** Width of the viewfinder corner's outlines. @defaultValue 3.0; */
public strokeWidth: number = 3.0;
/** Radius of the viewfinder's corners.        @defaultValue 10.0; */
public cornerRadius: number = 10.0;

If you're configuring the scanner from a JSON object, be sure to include the type name:

finder: {
    style: {
        _type: "FinderStrokedStyle",
    }
},

The finder's size and position can be controlled via the minimumInsets and preferredHeight properties. If you set minimumInsets, the finder will be placed at the specified minimum distance from the edges of the screen:

.minimumInsets = { top: 0, left: 100, right: 100, bottom: 0 };

Alternatively, if you prefer to keep the finder at the center of the screen, you can set the preferredHeight property to increase or decrease the size of the finder. This will preserve the default or custom aspectRatio values:

.preferredHeight = 50;

Your entire finder configuration object might look something like this:

const config = {
    ...
    finder: {
        visible: true,
        style: {
            _type: "FinderStrokedStyle",
            cornerRadius: 50,
            strokeColor: "green",
            strokeWidth: 5,
        },
        aspectRatio: {
            width: 16,
            height: 9,
        },
        overlayColor: "rgba(0, 0, 0, 0.5)",
    } as ViewFinderConfiguration
};

Alternatively, you can configure the object line by line:

config.finder!.style._type = "FinderStrokedStyle";
config.finder!.style.cornerRadius = 20;
...

User guidance​

The userGuidance property is for styling the hint text below the finder window and has the following options:

    /** Whether the user guidance is visible. @defaultValue true; */
    public visible: boolean = true;
    /** Title of the user guidance. @defaultValue new StyledText({ "color": "?sbColorOnPrimary" }); */
    public title: StyledText = new StyledText({ "color": "?sbColorOnPrimary" });
    /** Background style used for the user guidance.
    public background: BackgroundStyle = new BackgroundStyle({ "strokeColor": "#00000000", "fillColor": "?sbColorSurfaceLow" });

Your entire userGuidance configuration object might look something like this:

const config = {
    ...
    userGuidance: {
        visible: true,
        title: {
            text: "Scan item",
            color: "white",
        },
        background: {
            strokeColor: "green",
            fillColor: "rgba(0, 255, 0, 0.2)",
        }
    } as UserGuidanceConfiguration
};

Alternatively, you can also configure the object line by line:

config.userGuidance!.title.text = "Scan item";
config.userGuidance!.title.color = "white";
...

Manual data parsing​

Besides scanning barcodes and parsing the results, it is also possible to parse any given string containing structured data using the parseBarcodeDocument method:

const result = await sdk.parseBarcodeDocument(['GS1'], "(01)03453120000011(17)191125(10)ABCD1234");

Want to scan longer than one minute?

Generate a free trial license to test the Scanbot SDK thoroughly.

Get free trial license

On this page