Get Started

In this guide you will learn step-by-step how to add Smart Label Capture to your application.

The general steps are:

• Create a component to handle the capture process
• Initialize the Data Capture Context
• Initialize the Label Capture Mode
• Implement a listener to handle captured labels
• Visualize the scan process
• Start the camera
• Provide feedback

Prerequisites

Before starting with adding a capture mode, make sure that you have a valid Scandit Data Capture SDK license key and that you added the necessary dependencies. If you have not done that yet, check out this guide.

tip

You can retrieve your Scandit Data Capture SDK license key by signing in to your account Dashboard.

Module Overview

The modules that need to be included in your project depend on the features you want to use:

Module	NPM Package	Required for Feature
ScanditCaptureCore	@scandit/web-datacapture-core	Always required
ScanditBarcodeCapture	@scandit/web-datacapture-barcode	Always required
ScanditLabelCapture	@scandit/web-datacapture-label	Always required
ScanditLabelCaptureText	@scandit/web-datacapture-label	Required for capturing arbitrary texts
ScanditPriceLabel	@scandit/web-datacapture-label	Required for capturing price texts

Initialize the Data Capture Context

The first step to add capture capabilities to your application is to create a new Data Capture Context with a valid Scandit Data Capture SDK license key.

    const context = await DataCaptureContext.forLicenseKey("-- ENTER YOUR SCANDIT LICENSE KEY HERE --",{
      libraryLocation: new URL("library/engine/", document.baseURI).toString(),
      moduleLoaders: [barcodeCaptureLoader()], // module for capture mode e.g. [barcodeCaptureLoader()],
    });

    const dataCaptureView = new DataCaptureView();
    // #root element should be present in .html document
    dataCaptureView.connectToElement(document.getElementById("root"));

    await dataCaptureView.setContext(context);

Initialize the Label Capture Mode

The main entry point for the Label Capture Mode is the LabelCapture object.

It is configured through LabelCaptureSettings and allows you to register one or more listeners that get informed whenever a new frame has been processed.

import { Symbology } from "scandit-cordova-datacapture-barcode";
import {
  CustomBarcode,
  ExpiryDateText,
  ImeiOneBarcode,
  ImeiTwoBarcode,
  LabelCapture,
  LabelCaptureSettings,
  LabelDateComponentFormat,
  LabelDateFormat,
  LabelDefinition,
  SerialNumberBarcode,
  TotalPriceText,
  UnitPriceText,
  WeightText,
} from "scandit-cordova-datacapture-label";

// Create a label definition for an ISOF (In-Store Order Fulfillment) label.
// This label type typically includes a barcode, price fields, expiry date, and weight.
const isofLabel = new LabelDefinition("ISOF Label");

// Add a barcode field that expects an EAN-13 or UPC-A barcode.
const barcodeField = CustomBarcode.initWithNameAndSymbology("Barcode", Symbology.EAN13UPCA);
barcodeField.optional = false;
isofLabel.addField(barcodeField);

// Add a total price text field.
const totalPriceField = new TotalPriceText("Total Price");
totalPriceField.optional = false;
isofLabel.addField(totalPriceField);

// Add a unit price text field.
const unitPriceField = new UnitPriceText("Unit Price");
unitPriceField.optional = false;
isofLabel.addField(unitPriceField);

// Add an expiry date text field with a specific date format (Month-Day-Year).
const expiryDateField = new ExpiryDateText("Expiry Date");
expiryDateField.optional = false;
expiryDateField.labelDateFormat = new LabelDateFormat(LabelDateComponentFormat.MDY, false);
isofLabel.addField(expiryDateField);

// Add a weight text field.
const weightField = new WeightText("Weight");
weightField.optional = false;
isofLabel.addField(weightField);

// Create a label definition for a smart device label.
// This label type is commonly found on electronic devices and includes IMEI numbers and serial numbers.
const smartDeviceLabel = new LabelDefinition("Smart Device Label");

// Add an IMEI barcode field (first IMEI number).
const imeiField = ImeiOneBarcode.initWithNameAndSymbology("IMEI", Symbology.Code128);
imeiField.optional = false;
smartDeviceLabel.addField(imeiField);

// Add a second IMEI barcode field (for dual-SIM devices).
const imei2Field = ImeiTwoBarcode.initWithNameAndSymbology("IMEI2", Symbology.Code128);
imei2Field.optional = false;
smartDeviceLabel.addField(imei2Field);

// Add a serial number barcode field.
const serialNumberField = SerialNumberBarcode.initWithNameAndSymbology("Serial Number", Symbology.Code128);
serialNumberField.optional = false;
smartDeviceLabel.addField(serialNumberField);

// Add a custom barcode field for EID (Electronic ID).
const eidField = CustomBarcode.initWithNameAndSymbology("EID", Symbology.Code128);
eidField.optional = false;
smartDeviceLabel.addField(eidField);

// Create the label capture settings from the label definitions.
const settings = LabelCaptureSettings.settingsFromLabelDefinitions(
  [isofLabel, smartDeviceLabel],
  null // Optional properties
);

// Create the label capture mode with the settings.
const labelCapture = new LabelCapture(settings);

// Add the mode to the data capture context created earlier.
dataCaptureContext.addMode(labelCapture);

Implement a Listener to Handle Captured Labels

To get informed whenever a new label has been recognized, add a LabelCaptureListener through LabelCapture.addListener() and implement the listener methods to suit your application's needs.

First conform to the LabelCaptureListener interface. Here is an example of how to implement a listener that processes the captured labels based on the label capture settings defined above.

import { Feedback } from "scandit-cordova-datacapture-core";
import { LabelCaptureListener } from "scandit-cordova-datacapture-label";

// Create a listener to handle captured labels.
const labelCaptureListener = {
    // Called for every processed frame. Check session.capturedLabels for results.
    didUpdateSession: (labelCapture, session) => {
        // Early return if no label has been captured in this frame.
        if (session.capturedLabels.length === 0) {
            return;
        }

        // Process each captured label.
        session.capturedLabels.forEach((capturedLabel) => {
            const fields = capturedLabel.fields;

            // Access the barcode field by its name (as defined in the label definition).
            // The barcode property contains the scanned barcode data.
            const barcodeField = fields.find((field) => field.name === "Barcode");
            const barcodeData = barcodeField?.barcode?.data;

            // Access the expiry date field. Use the text property for OCR-captured text,
            // or the asDate() method to get a parsed LabelDateResult.
            const expiryDateField = fields.find((field) => field.name === "Expiry Date");
            const expiryDateText = expiryDateField?.text;
            const expiryDateResult = expiryDateField?.asDate();

            // Handle the captured data as needed, for example:
            // - Update your app's state
            // - Navigate to a results screen
            // - Send data to your backend
            console.log("Barcode:", barcodeData);
            console.log("Expiry Date:", expiryDateText);
        });

        // Disable label capture to prevent capturing the same labels multiple times.
        // Re-enable it when you're ready to scan again.
        labelCapture.isEnabled = false;

        // Emit feedback to indicate a successful scan.
        // See the Feedback section for customization options.
        Feedback.defaultFeedback.emit();
    }
};

// Register the listener with the label capture mode.
labelCapture.addListener(labelCaptureListener);

Visualize the Scan Process

The capture process can be visualized by adding a DataCaptureView to your view hierarchy. The view controls the UI elements, such as the viewfinder and overlays, that are shown to visualize captured labels.

To visualize the results of Label Capture, you can choose between two overlays, LabelCaptureBasicOverlay and LabelCaptureAdvancedOverlay.

Here is an example of how to add a LabelCaptureBasicOverlay to the DataCaptureView.

import { RectangularViewfinder, RectangularViewfinderStyle } from "scandit-cordova-datacapture-core";
import { LabelCaptureBasicOverlay } from "scandit-cordova-datacapture-label";

// Create the overlay for the label capture mode created earlier.
const overlay = new LabelCaptureBasicOverlay(labelCapture);

// Add the overlay to the data capture view.
dataCaptureView.addOverlay(overlay);

// Optionally, add a viewfinder to guide users through the capture process.
const viewfinder = new RectangularViewfinder(RectangularViewfinderStyle.Square);
overlay.viewfinder = viewfinder;

tip

See the Advanced Configurations section for more information about how to customize the appearance of the overlays and how to use the advanced overlay to display arbitrary views such as text views, icons or images.

Start the Camera

You need to also create the Camera:

import { Camera, FrameSourceState } from "scandit-cordova-datacapture-core";
import { LabelCapture } from "scandit-cordova-datacapture-label";

// Get the default camera (usually the back-facing camera).
const camera = Camera.default;

// Set the camera as the frame source for the data capture context.
await dataCaptureContext.setFrameSource(camera);

// Use the recommended camera settings for label capture.
const cameraSettings = LabelCapture.createRecommendedCameraSettings();

// Depending on the use case, further camera settings adjustments can be made here.
await camera.applySettings(cameraSettings);

Once the Camera, DataCaptureContext, DataCaptureView and LabelCapture are initialized, you can switch on the camera to start capturing labels.

Typically, this is done once the view becomes active and the user granted permission to use the camera, or once the user presses continue scanning after handling a previous scan.

// Turn on the camera to start capturing labels.
await camera.switchToDesiredState(FrameSourceState.On);

Please refer to the available sample apps for detailed examples of camera permission handling and view lifecycle management.

Provide Feedback

Smart Label Capture provides customizable feedback, emitted automatically when a label is recognized and successfully processed, configurable via LabelCapture.feedback.

You can use the default feedback, or configure your own sound or vibration.

tip

If you already have a Feedback instance implemented in your application, remove it to avoid double feedback.

import { LabelCaptureFeedback } from "scandit-cordova-datacapture-label";

// Get the default feedback configuration.
const feedback = LabelCaptureFeedback.defaultFeedback;

// Assign the feedback to the label capture mode.
labelCapture.feedback = feedback;

note

Audio feedback is only played if the device is not muted.