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	Required for Feature
ScanditCaptureCore	Always required
ScanditBarcodeCapture	Always required
ScanditLabelCapture	Always required
ScanditLabelCaptureText	Required for capturing arbitrary texts
ScanditPriceLabel	Required for capturing price texts

Create a Component to Handle the Capture Process

To start capturing labels, you need to setup and configure the Data Capture Context, Camera, and Label Capture Mode.

You can then add a DataCaptureView to your view hierarchy to display the camera preview on the screen together with UI elements that guide the user through the capture process.

You can create a component that initializes all the necessary objects and adds the DataCaptureView to the view hierarchy.

import { DataCaptureView } from "scandit-react-native-datacapture-core"

export const YourDataCaptureView = (props: Props) => {
  const { /* ... */ } = props

  const dataCaptureViewRef = useRef<DataCaptureView>(null)

  const [dataCaptureContext] = // see Data Capture Context section
  const camera = // see Camera section

  const labelCapture = useMemo<LabelCapture>(() => {
    // Initialize as described in the Label Capture Mode section
  }, [dataCaptureContext])
  
  const labelCaptureListener = useMemo<LabelCaptureListener>(() => ({
    // Implement a listener as described in the Implement a Listener section
  }), [onLabelCaptured])
  
  const labelCaptureOverlay = useMemo<LabelCaptureBasicOverlay>(() => {
    // Initialize the overlay as described in the Visualize the Scan Process section
  }, [labelCapture])


  // Add listener to the LabelCapture mode
  useEffect(() => {
    labelCapture.addListener(labelCaptureListener)
    return () => {
      labelCapture.removeListener(labelCaptureListener)
    }
  }, [labelCapture, labelCaptureListener])
  
  // Add the overlay to the DataCaptureView
  useEffect(() => {
    const dataCaptureView = dataCaptureViewRef.current
    dataCaptureView?.addOverlay(basicOverlay)
    return () => {
      dataCaptureView?.removeOverlay(basicOverlay)
    }
  }, [basicOverlay, basicOverlayListener])

  // Subscribe to the AppState and start/stop the camera 
  // as described in the Start the Camera section

  return (
    <View style={[
      styles.container,
    ]}>
      <DataCaptureView
        context={dataCaptureContext}
        ref={dataCaptureViewRef}
      />
    </View>
  )
}

Initialize the Data Capture Context

The first step to enable any data capture mode is to create a new DataCaptureContext. The DataCaptureContext handles licensing and a valid Scandit Data Capture SDK license key must be passed during initialization to activate scanning.

tip

If an error message appears on screen after initialization, review the Context Status Codes to learn more about the specific reason.

If the app uses only a single scanning mode, create a single DataCaptureContext within the scanner component.

TypeScript

const context = useMemo(() => {
	return DataCaptureContext.initialize('-- ENTER YOUR SCANDIT LICENSE KEY HERE --');
}, []);

JavaScript

const context = useMemo(() => {
	return DataCaptureContext.initialize('-- ENTER YOUR SCANDIT LICENSE KEY HERE --');
}, []);

If the app uses multiple scanning modes, create the DataCaptureContext as a singleton instance and import it into each scanner component.

TypeScript

import { DataCaptureContext } from 'scandit-react-native-datacapture-core';

DataCaptureContext.initialize('-- ENTER YOUR SCANDIT LICENSE KEY HERE --');

export default DataCaptureContext.instance;

import dataCaptureContext from 'path/to/DataCaptureContext'

JavaScript

import { DataCaptureContext } from 'scandit-react-native-datacapture-core';

DataCaptureContext.initialize('-- ENTER YOUR SCANDIT LICENSE KEY HERE --');

export default DataCaptureContext.instance;

import dataCaptureContext from 'path/to/DataCaptureContext'

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 { useMemo } from 'react';
import { Symbology } from 'scandit-react-native-datacapture-barcode';
import {
  CustomBarcode,
  ExpiryDateText,
  LabelCapture,
  LabelCaptureSettings,
  LabelDefinition,
} from 'scandit-react-native-datacapture-label';

const labelCapture = useMemo<LabelCapture>(() => {
  // Create a barcode field with the expected symbologies.
  const barcodeField = CustomBarcode.initWithNameAndSymbologies('Barcode', [
    Symbology.EAN13UPCA,
    Symbology.Code128,
  ]);
  barcodeField.optional = false;

  // Create an expiry date text field using the ExpiryDateText preset.
  const expiryDateField = new ExpiryDateText('Expiry Date');
  expiryDateField.optional = true;

  // Create a label definition with the fields created above.
  const labelDefinition = new LabelDefinition('Product Label');
  labelDefinition.fields = [barcodeField, expiryDateField];

  // Create the label capture settings from the label definition.
  const settings = LabelCaptureSettings.settingsFromLabelDefinitions([labelDefinition], {});

  // 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);
  
  return labelCapture;
}, [dataCaptureContext]);

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.

Remember to add and remove listeners as described in the Create Component section.

import { useMemo } from 'react';
import { Feedback } from 'scandit-react-native-datacapture-core';
import { LabelCaptureListener } from 'scandit-react-native-datacapture-label';

const labelCaptureListener = useMemo<LabelCaptureListener>(() => ({
  didUpdateSession: (labelCapture, session) => {
    // The session update callback is called for every processed frame.
    // Early return if no label has been captured.
    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();
  }
}), []);

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. Remember to add and remove overlays from the data capture view as described in the Create Component section.

import { useMemo } from 'react';
import { RectangularViewfinder, RectangularViewfinderStyle } from 'scandit-react-native-datacapture-core';
import { LabelCaptureBasicOverlay } from 'scandit-react-native-datacapture-label';

const labelCaptureOverlay = useMemo<LabelCaptureBasicOverlay>(() => {
  // Create the overlay for the label capture mode created earlier.
  const overlay = new LabelCaptureBasicOverlay(labelCapture);
  
  // Optionally, add a viewfinder to guide users through the capture process.
  const viewfinder = new RectangularViewfinder(RectangularViewfinderStyle.Square);
  overlay.viewfinder = viewfinder;
  
  return overlay;
}, [labelCapture]);

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 Android views such as text views, icons or images.

Start the Camera

You need to also create the Camera:

import { Camera, FrameSourceState } from 'scandit-react-native-datacapture-core';
import { LabelCapture } from 'scandit-react-native-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.
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.
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

Label Capture doesn’t emit feedback (sound or vibration) by default when a new label is recognized, as it may be that the label is not complete and you choose to ignore it and wait for the next recognition.

However, we provide a Feedback class that you can use to emit feedback when a label is recognized and successfully processed.

Here, we use the default Feedback, but you may configure it with your own sound or vibration.

import { Feedback } from 'scandit-react-native-datacapture-core';

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

After creating the feedback, you can emit it on successful scans with feedback.emit(). See the LabelCaptureListener implementation above for more information.

note

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