High-Speed Single Scanning

What is SparkScan?

For most people integrating scanning for the first time our pre-built component SparkScan is the best and quickest place to start. It includes a pre-built scanning interface that floats on top of any native application.

This bundles multiple scanning features together and addresses many common challenges associated with scanning on smart devices.

SparkScan Quickstart Guide
Run SparkScan Samples
Learn More About SparkScan

Run SparkScan Samples

There are both simple and advanced SparkScan samples available on our Github repository.

ListBuildingSample	ReceivingSample

A simple sample that demonstrates how to populate a list of scanned barcodes using the Scandit SparkScan API.	An advanced sample that shows how to share scan data between MatrixScan Count and Spark Scan to populate an item list.

SparkScan Quick Start Guide

Add the SDK to your App

Prerequisites

The latest stable version of Xcode.
An iOS project with minimum iOS deployment target of 13.0 or higher.
A valid Scandit Data Capture SDK license key. You can sign up for a free test account at ssl.scandit.com.

Add the SDK

Add the Frameworks via CocoaPods

Add the frameworks you want to add in your Podfile. For instance, to add ScanditBarcodeCapture API add

pod 'ScanditBarcodeCapture', '~> |shortversion|'

The previous line will also download ScanditCaptureCore API, since ScanditBarcodeCapture API depends on it.

If you want to install a specific version, you can do so by specifying the version explicitly. For instance:

pod 'ScanditBarcodeCapture', '|version|'

Using a specific version is necessary when you want to install a beta version.

Add the Frameworks via Carthage

Add the frameworks you want to add in your Cartfile. For instance, to add ScanditBarcodeCapture API add

binary "https://ssl.scandit.com/sdk/download/carthage/ScanditBarcodeCapture.json"

You also need to add ScanditCaptureCore API, since ScanditBarcodeCapture API depends on it.

binary "https://ssl.scandit.com/sdk/download/carthage/ScanditCaptureCore.json"

If you want to install a specific version, you can do so by specifying the version explicitly. For instance:

binary "https://ssl.scandit.com/sdk/download/carthage/ScanditBarcodeCapture.json" == |version|

Add the Frameworks via Swift Package Manager

Add the frameworks you want to add in the Swift Packages section of your project. Add our SPM package repository:

https://github.com/Scandit/datacapture-spm

or if you prefer checking out git repositories via ssh

git@github.com:Scandit/datacapture-spm.git

You also need to add ScanditCaptureCore API, since ScanditBarcodeCapture API depends on it. Just select ScanditCaptureCore API when prompted.

If you want to install a specific version, you can do so by specifying the version explicitly when adding the Package.

Create a new project (optional)

If you do not have a Cordova project yet that you’ll use, you should create a new one.

> cordova create helloscandit --id "com.scandit.helloscandit"
> cd helloscandit
> cordova platform add [ios | android]

Add dependencies

The Scandit Data Capture SDK depends on WKWebView on iOS, so you’ll manually have to add this dependency if your project doesn’t use WKWebView yet.

> cordova plugin add cordova-plugin-wkwebview-engine

Add the Scandit Data Capture SDK via npm or GitHub repo

To add our plugins via npm or git repo, you can run these commands from your project’s root folder. In the following snippet we’re adding ScanditBarcodeCapture API

# npm package
cordova plugin add scandit-cordova-datacapture-core
cordova plugin add scandit-cordova-datacapture-barcode

# git repo
cordova plugin add https://github.com/Scandit/scandit-cordova-datacapture-core.git
cordova plugin add https://github.com/Scandit/scandit-cordova-datacapture-barcode.git

Note

For npm dependencies, you can also specify a version @<version>. For GitHub dependencies, you can also specify the version #<version>.

Add the plugin to your project

Use the Cordova CLI to add the plugin(s) to your already existing project.

First add scandit-cordova-datacapture-core plugin:

cordova plugin add <path to scandit-cordova-datacapture-core plugin>

If your project is not yet configured to use Swift on iOS, you’ll need to add the following line to your config.xml file to specify the Swift version you’d like to use:

<platform name="ios">
  ...
  <preference name="SwiftVersion" value="5" />
  ...
</platform>

Once this is done, you can continue with adding the plugin for your desired functionality, e.g. for barcode capture, add the scandit-cordova-datacapture-barcode plugin:

cordova plugin add <path to scandit-cordova-datacapture-barcode plugin>

To update plugins, make sure to follow Cordova best practices and remove the plugin before adding the new version:

cordova plugin remove <id of the plugin being updated>
cordova plugin add <local path, id or GitHub repo url of the plugin being updated>

Get a License Key

Sign up or Sign in to your Scandit account
Create a project
Create a license key by specifying your bundle ID

If you have a paid subscription, please reach out to support@scandit.com if you need a new license key.

Additional Information

Remember that, if you want to use the camera as the frame source for barcode, text and label capture, you need to set the “Privacy - Camera Usage Description” field in the Info.plist file.

Get Started With SparkScan

In this guide you will learn step by step how to add SparkScan to your application.

Roughly, the steps are:

Create a new Data Capture Context instance.
Configure the Spark Scan Mode.
Create the SparkScanView with the desired settings and bind it to the application’s lifecycle.
Register the listener to be informed when new barcodes are scanned and update your data whenever this event occurs.

1. Create a New Data Capture Context Instance

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.

self.context = DataCaptureContext(licenseKey: "-- ENTER YOUR SCANDIT LICENSE KEY HERE --")

2. Configure the SparkScan Mode

The SparkScan Mode is configured through SparkScanSettings and allows you to register one or more listeners that are informed whenever a new barcode is scanned.

For this tutorial, we will set up SparkScan for scanning EAN13 codes. Change this to the correct symbologies for your use case (for example, Code 128, Code 39…).

let settings = SparkScanSettings()
settings.set(symbology: .ean13UPCA, enabled: true)
sparkScan.apply(settings, completionHandler: nil)

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

let sparkScan = SparkScan(settings: settings)

3. Setup the Spark Scan View

The SparkScan built-in user interface includes the camera preview and scanning UI elements. These guide the user through the scanning process.

The SparkScanView appearance can be customized through SparkScanViewSettings.

let viewSettings = SparkScanViewSettings()
// setup the desired appearance settings by updating the fields in the object above

By adding a SparkScanView, the scanning interface (camera preview and scanning UI elements) will be added automatically to your application.

Add a SparkScanView to your view hierarchy:

Construct a new SparkScan view. The SparkScan view is automatically added to the provided parentView:

let sparkScanView = SparkScanView(parentView: view, context: context, sparkScan: sparkScan, settings: viewSettings)

Additionally, make sure to call SDCSparkScanView.prepareScanning and SDCSparkScanView.stopScanning in your UIViewController’s viewWillAppear <https://developer.apple.com/documentation/uikit/uiviewcontroller/1621510-viewwillappear> and viewWillDisappear callbacks, to make sure that start up time is optimal and scanning is stopped when the app is going in the background.

override func viewWillAppear(animated: Bool) {
    super.viewWillAppear(animated)
    sparkScanView.prepareScanning()
}

override func viewWillDisappear(animated: Bool) {
    super.viewWillDisappear(animated)
    sparkScanView.stopScanning()
}

4. Register the Listener to Be Informed When a New Barcode Is Scanned

To keep track of the barcodes that have been scanned, implement the SDCSparkScanListener protocol and register the listener to the SparkScan mode.

// Register self as a listener to monitor the spark scan session.
sparkScan.addListener(self)

SDCSparkScanListener.sparkScan:didScanInSession:frameData: is called when a new barcode has been scanned. This result can be retrieved from the first object in the provided barcodes list: SDCSparkScanSession.newlyRecognizedBarcodes. Please note that this list only contains one barcode entry. When a barcode is scanned, it is possible to emit a sound and a visual feedback via SDCSparkScanView.emitFeedback:.

extension ViewController: SparkScanListener {
    func sparkScan(_ sparkScan: SparkScan,
                      didScanIn session: SparkScanSession,
                      frameData: FrameData?) {
        // Gather the recognized barcode
        let barcode = session.newlyRecognizedBarcodes.first
        // This method is invoked from a recognition internal thread.
        // Dispatch to the main thread to update the internal barcode list.
        DispatchQueue.main.async {
            // Update the internal list and the UI with the barcode retrieved above
            self.latestBarcode = barcode

            // Emit sound and vibration feedback
            self.sparkScanView.emitFeedback(SparkScanViewSuccessFeedback())

            // Handle the barcode
        }
    }
}

Learn More About SparkScan

UI overview

The SparkScan’s UI is minimal, meant to be overlayed on top of any application without the need to adapt the existing app - while offering the best user experience.

Three main elements compose the UI:


Mini preview: A small camera preview screen giving a visual confirmation while aiming at the code. This is placed in the top right corner, where the phone camera is located. Its size depends on the scanning mode enabled.	Trigger button: A large-sized floating button that users can drag up and down to position it in the most convenient and ergonomic place. This eliminates the need to look at the screen to trigger scanning.	Settings Toolbar: A quick-access toolbar that includes controls of settings (like the torch, haptics feedback etc.), scan modes (like switching to continuous scanning, enabling the target mode etc,) and more. More info on the scanning modes in the following section.

NOTE: Additional UI elements are available for developers to use if their app logic requires displaying errors or additional feedback while scanning. More information in Customisation and advanced capabilities.

Scanning Modes Supported

SparkScan offers different scanning modes, to optimally fit different use-cases and user preferences.

These modes change the workflow and the way the user scans the barcodes.
They can be toggled manually by the end users, or set a priori by the developer.

SparkScan offers two scanning modes:

Default mode: Ideal for close-range and fast paced scanning. This mode will display a small camera preview to aid with aiming.
Target mode: Ideal for scanning scenarios where precision is important. This mode will display a big camera preview with a target to precisely select the barcode to scan. This is useful when multiple barcodes are in view. As this mode allows you to choose the zoom level, it is also ideal for long-range scanning (e.g. to scan a label at the bottom shelf).

And two scanning behaviors:

Single scan: the user needs to trigger the scanner every time to scan a barcode. This allows for a more controlled scanning.
Continuous scan: Scan barcodes consecutively. The user needs to trigger the scanner once and barcodes will be scanned without any further interaction before each scan. This allows for a smoother experience when multiple barcodes need to be scanned consecutively.


Scanning Mode: Default.	Scanning Mode: Default.	Scanning Mode: Target.
Scanning Behavior: Single Scan.	Scanning Behavior: Continuous Scan.	Scanning Behavior: Single Scan.

NOTE: By default, scanning modes and scanning behaviors can be toggled by the end user acting on the setting toolbar - to allow for the maximum flexibility.
Developers can always change the initial configuration of the scanner or select a specific configuration removing the possibility to toggle it.
More information in Customisation and advanced capabilities.

Workflow Description

When SparkScan is started, the UI presents just the trigger button, collapsed on the side.
To start scanning, the user can:
- swipe to open the button, then tap on it.
- tap on the collapsed trigger button.


Swipe and tap to start the scanner.	Tap to start the scanner.

When the scanner is active, the mini preview becomes visible.
Depending on the scanning mode enabled, the workflow will behave differently:
- In Single Scan, upon scan the user will receive audio/haptic feedback confirming the scan, and the mini preview will display the scanned barcode for a small amount of time. The scanner will need to be restarted to scan a new code.
- In Continuous Scan, upon scan the user will receive audio/haptic feedback confirming the scan. The mini preview keeps showing the camera preview, ready to scan a new code.


Single Scan.	Continuous Scan.

Upon completing the scanning process (or to interact with the customer app layer), the user can tap in any area outside the trigger button and the mini preview. This collapses the scanner button back to the side, going back to the initial state.

Collapse the SparkScan UI.

Supported Devices

Runs on iOS and Android devices.

Supported Symbologies

SparkScan supports all of the major symbologies listed here: Barcode Symbologies except DotCode, MaxiCode and postal codes (KIX, RM4SCC, LAPA 4SC and USPS Intelligent Mail).

If you are not familiar with the symbologies that are relevant for your use case, you can use capture presets that are tailored for different verticals (e.g. retail, logistics, etc.).

For more symbology specific information, please refer to this link.

Customisation and advanced capabilities

SparkScan offers an out-of-the-box experience optimized for efficiency and a frictionless worker experience. This experience has been crafted after many user testing and with the product knowledge gained in the many years of Scandit.
While this out-of-the-box experience will suit most use-cases, we understand there are some special cases in which some configuration is still needed.
In this page, we collect the main customization and advanced settings you may need to customize SparkScan to obtain the best experience possible.

Advanced capabilities

Hold-to-scan gesture

In addition to the standard tap-to-scan interaction, in which the users tap the trigger button to enable the scanner, users can hold down the scan button to perform a hold-to-scan interaction. In this case, regardless of the scanning behavior (whether is Single Mode or Continuous Mode), the scanner will be active (scanning barcodes) as long as the button is pressed.

Developers can disable this gesture via SDCSparkScanViewSettings.holdToScanEnabled.

EXAMPLE: to create a workflow in which only Single Scan is possible, developers will need to:

hide the single/continuous toggle via SDCSparkScanView.scanningBehaviorButtonVisible.
disable the hold-to-scan gesture via SDCSparkScanViewSettings.holdToScanEnabled.

Control the Scanner through a Hardware Button

Allowing the end user to control the scanner with hardware buttons can be useful if your users typically wear gloves. It can also improve ergonomics in some workflows.

SparkScan offers a built-in API to let you do this via SDCSparkScanViewSettings.hardwareTriggerEnabled.

Trigger the Error State

You may want to introduce logic in your app to show an error message when scanning specific barcodes (e.g. barcodes already added to the list, barcodes from the wrong lot etc.). SparkScan offers a built-in error state you can easily set to trigger an error feedback prompt to the user. You will be able to customize:

The text message
The timeout of the error message: the scanner will be paused for the specified amount of time, but the user can quickly restart the scanning process by tapping the trigger button
The color of the flashing screen upon scan. You can enable or disable the visual feedback via SDCSparkScanViewSettings.visualFeedbackEnabled and you can control the color via SDCSparkScanViewFeedback.
The color of the highlight for the scanned barcode.

An error example is here reported:

self.sparkScanView.emitFeedback(SparkScanViewErrorFeedback(message: "This code should not have been scanned", resumeCapturingDelay: 6, visualFeedbackColor: UIColor.red))

NOTE: you can have different error states triggered by different logic conditions. For example you can trigger an error state when a wrong barcode is scanned, and another one when a duplicate barcode is scanned. These errors can show different colors and have different timeouts.

NOTE: a high timeout (e.g. >10s) typically requires the users to interact with the UI to start scanning again. This is a good choice when you want to interrupt the scanning workflow (e.g. because a wrong barcode is scanned and some actions need to be performed). A small timeout (e.g. <2s) could allow the user to scan again without having to interact with the app, just momentarily pausing the workflow to acknowledge that a “special” barcode has been scanned.


	In this example, a first error is triggered when a “duplicate” barcode is scanned (in blue) - stopping the scanner for 2s. Users do not need to restart the scanner manually, as the timeout is limited. A second error is triggered when an “error” barcode is scanned, with a long timeout (60s) that requires the user to trigger the scanner again.

Increase the precision of your scanning workflow

In scenarios where numerous barcodes are close together or in crowded environments, accurately selecting the right barcode can be difficult. To address this challenge, a new workflow that incorporates an aimer in the camera preview is recommended so that users can precisely target and scan intended barcodes.

As a developer you can select two different SparkScan workflow by picking a SDCSparkScanScanningPrecision value:

DEFAULT
ACCURACY

Depending on the selection, the behavior of the preview will be different.

Default workflow VS Accuracy workflow.

DEFAULT: the standard workflow for use cases in which the accurate selection of a barcode (e.g. long range scanning or many barcode close together) is occasional.

Preview only visible when scanning (hidden otherwise).
Two scanning modes:
- Default mode: Mini preview without aimer (barcodes can be scanned anywhere in the mini-preview).
- Target mode: big preview with an aimer to precisely scan barcodes far away or close together.

ACCURACY: the workflow for use cases where you mainly want to select a barcode (among many) or you need to look through the preview at all times (to ensure the right scan).

Preview always visible, scanning only active when tapping/holding the trigger button
Two scanning modes:
- Default Mode: Mini preview with an aimer, only scanning aimed barcodes to increase precision
- Expanded mode: big preview with an aimer in case you want to be more precise or you need to zoom in.

Accuracy mode example.

Customization

Customize colors and texts

All texts (guidance inside the trigger button and hints’ messages), colors and opacity of the SparkScan UI elements (trigger button, setting toolbar, toasts) can be customized to match the desired language and color scheme.

Please refer to SDCSparkScanView for the full list of available parameters.

Move the trigger button to the upper part of the screen

The trigger button can only slide up and down on the bottom part of the screen, where it is easy to reach with the finger that holds the smartphone. This reserves space for the large camera preview on the top part of the screen in the target mode.
By default, the trigger button can be moved up and down in the bottom part of the screen - where is ergonomically reachable by the finger holding the smartphone. This also leaves the space for the big camera preview in the target mode.

If the trigger button blocks part of your application, you might want to move the scan button to the upper part of the screen. You can do this by using the SDCSparkScanViewSettings.ignoreDragLimits option.

Effect of the ignoreDragLimits option.


Standard toolbar.	Toolbar with advanced modes icons shown.


Default icons shown.	Only two icons left.