Skip to main content

Get Started

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

The general steps are:

  • Include the ScanditBarcodeCapture library and its dependencies to your project, if any.
  • Create a new DataCaptureContext instance, initialized with your license key.
  • Create a BarcodeCaptureSettings and enable the BarcodeSymbologies you want to read in your application.
  • Create a new BarcodeCaptureMode instance and initialize it with the settings created above.
  • Register a BarcodeCaptureListener to receive scan events. Process the successful scans according to your application’s needs, e.g. by looking up information in a database. After a successful scan, decide whether more codes will be scanned, or the scanning process should be stopped.
  • Obtain a Camera instance and set it as the frame source on the data capture context.
  • Display the camera preview by creating a DataCaptureView.
  • If displaying a preview, optionally create a new BarcodeCaptureOverlay and add it to DataCaptureView for a better visual feedback.

1. Obtain a Scandit License Key​

A valid Scandit Data Capture SDK license key is required enable any capture mode. Sign into your Scandit account and create a new Scandit license key or copy an existing one.

tip

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

For new projects, create a new cross-platform license key. Depending on the type of license key, it may require entering an iOS Bundle ID and/or Android App ID. If these values are not identical between platforms, the Bundle ID and App ID can both be entered separated by a comma.

2. Download the Scandit SDK​

Add the Scandit SDK dependencies to your current project. Lean more about the installation requirements.

npm i scandit-react-native-datacapture-core scandit-react-native-datacapture-barcode

3. Create 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.

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.

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'

4. Configure the Barcode Scanning Behavior​

BarcodeCapture is one of the DataCaptureMode options within the Scandit SDK which scans individual barcodes.

This mode is attached to a DataCaptureContext and configured by applying the BarcodeCaptureSettings. Then, attaching the BarcodeCaptureListener will provide new Barcode values when recognized.

For this tutorial, we will setup barcode scanning for a small list of different barcode types, called a Symbology. The list of symbologies to enable is highly application specific.

Each additional Symbology may reduce recognition speed, therefore only enable the symbologies your application requires.

const settings = new BarcodeCaptureSettings();
settings.codeDuplicateFilter = 300; // optionally add a 300ms timeout between scanning identical barcodes
settings.enableSymbologies([
	Symbology.Code128,
	Symbology.Code39,
	Symbology.QR,
	Symbology.EAN8,
	Symbology.UPCE,
	Symbology.EAN13UPCA,
]);

// Create a BarcodeCapture instance with the BarcodeCaptureSettings applied.
const barcodeCapture = new BarcodeCapture(settings);
context.addMode(barcodeCapture);

If you are not disabling barcode capture immediately after having scanned the first code, consider setting the BarcodeCaptureSettings.codeDuplicateFilter to around 500 or even -1 if you do not want codes to be scanned more than once.

5. Register the Barcode Capture Listener​

To get informed whenever a new code has been recognized, add a BarcodeCaptureListener through BarcodeCapture.addListener() and implement the listener methods to suit your application’s needs.

First implement the BarcodeCaptureListener interface. For example:

const barcodeCaptureListener: BarcodeCaptureListener = {
	didScan: async (
		barcodeCapture: BarcodeCapture,
		session: BarcodeCaptureSession,
		getFrameData: () => Promise<FrameData>
	) => {
		const barcode = session.newlyRecognizedBarcode;
		// Do something with the barcodes
	},
};

// Add the BarcodeCaptureListener to the BarcodeCapture mode.
barcodeCapture.addListener(barcodeCaptureListener);

Rejecting Barcodes​

To prevent scanning unwanted codes, you can reject them by adding the desired logic to the didScan method. This will prevent the barcode from being added to the session and will not trigger the didUpdateSession method.

The example below will only scan barcodes beginning with the digits 09 and ignore all others, using a transparent brush to distinguish a rejected barcode from a recognized one:

if (!barcode.data?.startsWith('09:')) {
	overlay.brush = Brush.transparent;
	return;
}

Use the Built-in Camera​

The DataCaptureContext supports using different frame sources to perform recognition on. Most applications will use the built-in camera of the device, e.g. the world-facing camera of a device. The remainder of this tutorial will assume that you use the built-in camera.

important

In iOS, the user must explicitly grant permission for each app to access cameras. Your app needs to provide static messages to display to the user when the system asks for camera permission. To do that include the NSCameraUsageDescription key in your app’s Info.plist file.

important

In Android, the user must explicitly grant permission for each app to access cameras. Your app needs to declare the use of the Camera permission in the AndroidManifest.xml file and request it at runtime so the user can grant or deny the permission. To do that follow the guidelines from Request app permissions to request the android.permission.CAMERA permission.

When using the built-in camera there are recommended settings for each capture mode. These should be used to achieve the best performance and user experience for the respective mode. The following couple of lines show how to get the recommended settings and create the camera from it:

const cameraSettings = BarcodeCapture.recommendedCameraSettings;
// cameraSettings.preferredResolution = VideoResolution.FullHD; // or adjust default camera settings

const camera = Camera.withSettings(cameraSettings);

// Attaches the Camera object as FrameSource to the DataCaptureContext
context.setFrameSource(camera);

... // Setup the BarcodeCaptureMode, BarcodeCaptureListener, etc.

camera.switchToDesiredState(FrameSourceState.On);

The FrameSource for the DataCaptureContext configurable by calling DataCaptureContext.setFrameSource():

The camera is off by default. To turn it on, call FrameSource.switchToDesiredState() with a value of FrameSourceState.On.

Use a Capture View to Visualize the Scan Process​

When using the built-in camera as frame source, you will typically want to display the camera preview on the screen together with UI elements that guide the user through the capturing process. To do that, add a DataCaptureView to your view hierarchy:

<DataCaptureView context={this.dataCaptureContext} ref={this.viewRef}>

To visualize the results of barcode scanning, the following overlay can be added:

const overlay = BarcodeCaptureOverlay.withBarcodeCaptureForView(
	barcodeCapture,
	view
);

Disabling Barcode Capture​

To disable barcode capture, for instance as a consequence of a barcode being recognized, set BarcodeCapture.isEnabled to false.

The effect is immediate: no more frames will be processed after the change. However, if a frame is currently being processed, this frame will be completely processed and deliver any results/callbacks to the registered listeners. Note that disabling the capture mode does not stop the camera, the camera continues to stream frames until it is turned off.