Single Scanning

Get Started With Barcode Capture

In this guide you will learn step by step how to add barcode capture to your application. Roughly, the steps are:

• Include the ScanditBarcodeCapture library and its dependencies to your project, if any.

• Create a new data capture context instance, initialized with your license key.

• Create a barcode capture settings and enable the barcode symbologies you want to read in your application.

• Create a new barcode capture mode instance and initialize it with the settings created above.

• Register a barcode capture listener 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 data capture view.

• If displaying a preview, optionally create a new overlay and add it to data capture view for a better visual 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.

Note

You can retrieve your Scandit Data Capture SDK license key, by signing in to your account at ssl.scandit.com/dashboard/sign-in.

Initialize the barcode plugin

Warning

Without initializing the barcode plugin, runtime crashes will occur. However, you don’t have to initialize the core plugin, as initializing the barcode plugin already does that for you, as presented in the snippet below.

Before accessing anything of the Scandit Data Capture SDK functionality. You have to initialize the barcode plugin.

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await ScanditFlutterDataCaptureBarcode.initialize();
  runApp(MyApp());
}

Internal dependencies

Some of the Scandit Data Capture SDK modules depend on others to work:

Module	Dependencies
scandit-flutter-datacapture-core	No dependencies
scandit-flutter-datacapture-barcode	scandit-flutter-datacapture-core
scandit-flutter-datacapture-parser	scandit-flutter-datacapture-core
scandit-flutter-datacapture-text	scandit-flutter-datacapture-core
scandit-flutter-datacapture-id	scandit-flutter-datacapture-core scandit-flutter-datacapture-text (VIZ documents)

Create the Data Capture Context

The first step to add capture capabilities to your application is to create a new data capture context. The context expects a valid Scandit Data Capture SDK license key during construction.

var context = DataCaptureContext.forLicenseKey("-- ENTER YOUR SCANDIT LICENSE KEY HERE --");

Configure the Barcode Scanning Behavior

Barcode scanning is orchestrated by the BarcodeCapture data capture mode. This class is the main entry point for scanning barcodes. It is configured through BarcodeCaptureSettings and allows to register one or more listeners that will get informed whenever new codes have been recognized.

For this tutorial, we will setup barcode scanning for a small list of different barcode types, called symbologies. The list of symbologies to enable is highly application specific. We recommend that you only enable the list of symbologies your application requires.

var settings = BarcodeCaptureSettings()
  ..enableSymbologies({
    Symbology.code128,
    Symbology.code39,
    Symbology.qr,
    Symbology.ean8,
    Symbology.upce,
    Symbology.ean13Upca
  });

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.

Next, create a BarcodeCapture instance with the settings initialized in the previous step:

var barcodeCapture = BarcodeCapture.forContext(context, settings);

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:

@override
void didScan(BarcodeCapture barcodeCapture, BarcodeCaptureSession session) {
  var recognizedBarcodes = session.newlyRecognizedBarcodes;
  // Do something with the barcodes.
}

Then add the listener:

barcodeCapture.addListener(this);

Use the Built-in Camera

The data capture context 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:

var cameraSettings = BarcodeCapture.recommendedCameraSettings;

// Depending on the use case further camera settings adjustments can be made here.

  var camera = Camera.defaultCamera..applySettings(cameraSettings);

Because the frame source is configurable, the data capture context must be told which frame source to use. This is done with a call to DataCaptureContext.setFrameSource():

context.setFrameSource(camera);

The camera is off by default and must be turned on. This is done by calling FrameSource.switchToDesiredState() with a value of FrameSourceState.on:

camera.switchToDesiredState(FrameSourceState.on);

There is a separate guide for more advanced camera functionality.

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:

var dataCaptureView = DataCaptureView.forContext(dataCaptureContext);
// Add the dataCaptureView to your widget tree

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

var overlay = BarcodeCaptureOverlay.withBarcodeCaptureForView(barcodeCapture, dataCaptureView);

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.

What’s next?

To dive further into the Scandit Data Capture SDK we recommend the following articles:

• Barcode Symbologies

• Configure Which Barcodes Are Read

• Advanced Topics

Configure Which Barcodes Are Read

In this guide you will learn how to configure a barcode based capture mode (BarcodeCapture and BarcodeTracking) to read the barcodes that you need it to read. The available symbol count range, checksum, extensions, etc. for all symbologies are listed in Symbology Properties

Before you start…

To get the most out of this guide, we recommend that you have read the following articles:

• Add the SDK to Your App

• Get Started With Barcode Capture

• Barcode Symbologies

Enable the Symbologies You Want to Read

The type of a barcode is referred to as its symbology, e.g QR Code or Code 128. To enable scanning of a particular barcode, its symbology must be enabled. This is done through calling BarcodeCaptureSettings.enableSymbology() on the BarcodeCaptureSettings and then applying the settings to the barcode capture instance. Similarly, for barcode tracking (MatrixScan), the barcode’s symbology must be enabled by calling BarcodeTrackingSettings.enableSymbology() on the BarcodeTrackingSettings and then applying the settings to the barcode tracking instance.

If you already know the names of the symbologies you want to scan/read, take a look at the list of symbologies supported by the Scandit Data Capture SDK. If you are unsure what the symbology of your barcode is, use the Scandit Demo App available in the iOS App Store or Android Play Store. After you have installed the app, select the “Any Code” mode and scan the codes you are interested in. The name of the symbology will appear on the result screen.

The following lines of code show you how to enable scanning Code 128 codes for barcode capture:

var settings = BarcodeCaptureSettings()
  ..enableSymbology(Symbology.code128, true);

Configure the Active Symbol Count

Barcode symbologies such as Code 128, Code 39, Code 93 or Interleaved Two of Five can store variable-length data. As an example, Code 39 can be used to store a string anywhere from 1 up to around 40-50 symbols. There is no fixed upper limit, though there are practical limitations to the code’s length for it to still be conveniently readable by barcode scanners. For performance reasons, the Scandit Data Capture SDK limits the possible symbol range for variable-length symbologies. If you want to read codes that are shorter/longer than the specified default range or you want to tailor your app to only read codes of a certain length, you need to change the active symbol count of the symbology to accommodate the data length you want to use in your application.

The below lines of code show how to change the active symbol count for Code 128 to read codes with 6, 7 and 8 symbols.

var settings = BarcodeCaptureSettings();
var symbologySettings = settings.settingsForSymbology(Symbology.code128);
symbologySettings.activeSymbolCounts = {6, 7, 8};

How to Calculate the Active Symbol Count

Calculating the active symbol count is symbology-specific as each symbology has a different symbol definition. To understand what a symbology’s default active symbol count range is and to learn how to compute the active symbol count for a particular symbology, consult the documentation on symbology properties. As an alternative, you can also use the Scandit Demo App in the iOS App Store, or Android Play Store. After you have installed the app, select the “Any Code” mode and scan the codes you are interested in. The active symbol count will appear on the result screen.

Read Bright-on-Dark Barcodes

Most barcodes are printed using dark ink on a bright background. Some symbologies allow the colors to be inverted and can also be printed using bright ink on a dark background. This is not possible for all symbologies as it could lead to false reads when the symbology is not designed for this use case. Which symbologies allow color inversion can be seen in the documentation on symbology properties. When you enable a symbology as described above, only dark-on-bright codes are enabled (see SymbologySettings.isEnabled). When you also want to read bright-on-dark codes, color-inverted reading for that symbology must also be enabled (see SymbologySettings.isColorInvertedEnabled:

var settings = BarcodeCaptureSettings();
var symbologySettings = settings.getSymbologySettings(Symbology.code128);
symbologySettings.isColorInvertedEnabled = true;

Enforce Checksums

Some symbologies have a mandatory checksum that will always be enforced while others only have optional checksums. Enforcing an optional checksum will reduce false positives as an additional check can be performed. When enabling a checksum you have to make sure that the data of your codes contains the calculated checksum otherwise the codes will be discarded as they checksum doesn’t match. All available checksums per symbology can be found in the documentation on symbology properties. You can enforce a specific checksum by setting it through SymbologySettings.checksums:

var settings = BarcodeCaptureSettings();
var symbologySettings = settings.settingsForSymbology(Symbology.code39)
  ..checksums = {Checksum.mod43};

Enable Symbology-Specific Extensions

Some symbologies allow further configuration. These configuration options are available as symbology extensions that can be enabled/disabled for each symbology individually. Some of the extensions affect how the data in the code is formatted, others allow to enable more relaxed recognition modes that are disabled by default to eliminate false reads. All available extensions per symbology and a description of what they do can be found in the documentation on symbology properties.

To enable/disable a symbology extension, use SymbologySettings.setExtensionEnabled().

var settings = BarcodeCaptureSettings();
var symbologySettings = settings.settingsForSymbology(Symbology.code39)
  ..setExtensionEnabled("full_ascii", enabled: true);

What’s next?

To dive further into the Scandit Data Capture SDK we recommend the following articles:

• Symbology Properties

• Scan Add-On/Extension Codes

• Scan Composite Codes

• Optimize Scanning Performance