Scandit logo, to the homepage

Developer Tutorial: Getting to Your First Scan

| Developers

Share

x

facebook

linkedin

How fast do you think it will take to get to your first barcode scan?

Scandit SparkScan, a development device, and the instructions below will get you there in minutes. If you want immediate satisfaction, run our JavaScript ListBuildingSample in StackBlitz now. We maintain a comprehensive set of sample applications on GitHub for all supported frameworks.

What is SparkScan? It’s our pre-built component that gives you:

  • A minimalistic UI that floats on top of any app.
  • Components built upon well-researched UX principles.
  • Core capture and image processing algorithms optimized with feedback from thousands of customers across various environments.
  • Features that solve common scanning pitfalls (think unsupported symbologies, false positives, degraded environmental conditions, and more).

This adds up to significant reductions in development time and fewer adoption risks.

Graphic showing a web-based scanner UI using the Scandit SparkScan pre-built barcode scanning component.

Before we begin

If you haven’t already signed up for Scandit’s free trial, go ahead and do that now.

Your free trial includes a 30-day license key. To create your key, go to your Scandit dashboard and follow these steps:

  1. Click Add a project.
  2. Enter a project name and purpose, then click Create project.
  3. Choose your application type and click Generate license key.

Your dashboard should look something like this:

Popup window in the Scandit dashboard displaying a license key with options to run a sample or install the SDK.
Once created, your license key can also be retrieved by clicking on your project at any time.

Before diving in, there are a few minimum requirements that you’ll need to be able to proceed:

  • GitHub account (and Git installed)
  • Suitable development environment for your chosen framework (e.g. Xcode for iOS or VS Code for React Native)

If you don’t have or don’t want to deal with the above requirements, have a look at the Scandit Express application. This solution allows you to add barcode scanning into any iOS or Android application with minimal or no coding required.

Barcode scanning quick start

Let’s start with a general overview of the steps to deploy barcode scanning regardless of which framework you’re working in.

Skip to the next section if you want a complete code walkthrough with UI customizations using the Web SDK (JavaScript).

Start your timer now:

1. Clone the samples repository

We maintain a comprehensive set of sample applications on GitHub for all supported frameworks and industry use cases.

The sample applications are sorted by framework, so you only need to clone the repository for the framework you’re working in. For example:

// Web/JavaScript
git clone https://github.com/Scandit/datacapture-web-samples.git

2. Open the sample application

You probably noticed several different sample applications in the repository. This blog walks through the ListBuildingSample, but you can use these same steps to try out the rest.

In your preferred IDE, open the ListBuildingSample directory from the cloned repository.

Navigate to the directory and file where you’ll insert the license key created earlier. This will vary depending on the framework, for example:

// Android
datacapture-android-samples/secrets.properties

// iOS 
datacapture-ios-samples/ListBuildingSample/ListBuildingSample/Extensions/DataCaptureContext+Licensed.swift

// Web/JavaScript
datacapture-web-samples/ListBuildingSample/src/app/presenter.ts

// Cordova
datacapture-cordova-samples/BarcodeCaptureSimpleSample/template_src/www/index.js

//React Native
datacapture-react-native-samples/ListBuildingSample/app/App.tsx

If you can’t find the file, search for “SCANDIT_LICENSE_KEY” in your repository.

3. Insert your license key

Jump back to the Scandit Dashboard and copy the license key you created earlier. Paste it into the file above where indicated and save the file.

4. Compile and run

You’re nearly done. All that’s left is to run the sample application from your chosen IDE. The ListBuildingSample provides a dummy app to scan into, together with a basic scanning interface, including a capture button and camera preview.

When run, the sample application looks similar to this:

User interfaces for SparkScan ListBuildingSample for JavaScript showing scanning and results screens with guidance about how to us
Once compiled and launched, you can scan away on any barcode in sight! You can also use our barcodes sample sheet to test your app out.

Now, how long did that take?

Full Web SDK walkthrough

Let’s use the Web SDK samples to walk through the process of completing your first barcode scan with SparkScan, along with a few UI customizations.

Before starting, make sure you have the latest version of Node.js installed and the datacapture-web-samples repository cloned.

1. Add the Scandit Data Capture SDK license key to your project

To run the sample application, you must add the Scandit Data Capture SDK license key to the project. In the sample app, you can do this in two ways:

Add an environment variable

  1. Open .env.example in an editor and insert your license key after SCANDIT_LICENSE_KEY=.
  2. Save and rename the file to .env.

Add programmatically

  1. Open /src/app/presenter.ts and navigate to the connect() method.
  2. Insert your license key between the quotation marks after licenseKey:.

2. Change supported symbologies

This goes for any barcode scanning library: if you don’t have the right symbologies supported and configured, your users can’t capture barcode data.

Your app’s symbologies are set through SparkScanSettings. The sample app is already configured to support EAN-13/UPC-12/UPC-A and Code 128.

To change this:

  1. Open /src/app/presenter.ts and navigate to the connect() method.
  2. Modify the call to enableSymbologies() as follows:
    this.sparkScanSettings.enableSymbologies([Symbology.EAN13UPCA, Symbology.Code128, Symbology.QR, Symbology.Code39]);

Here, we’ve added support for QR codes and Code 39.

3. Change the scanning mode

SparkScan supports two scanning modes and a UI control to switch between them:

  • Default mode: This mode shows a small camera preview to assist with aiming. Choose this for quick, close-range scans.
  • Target mode: This mode adds an aiming crosshair to the preview to help users select the barcode they wish to scan. Choose this when high precision is needed, such as when capturing one barcode from many or when barcodes are positioned far from the device.

The mode is set using SparkScanViewSettings. To set the scanning mode and disallow the user to choose:

  1. Open /src/app/presenter.ts and navigate to the connect() method.
  2. Navigate to where SparkScanViewSettings is declared: 
    this.sparkScanViewSettings = new SparkScanViewSettings();
  3. Add this line to change the scanning mode from default to target mode: 
    this.sparkScanViewSettings.defaultScanningMode = new SparkScanScanningModeTarget(SparkScanScanningBehavior.Single, SparkScanPreviewBehavior.Default);

To allow the user to toggle between scanning modes:

  1. Open /src/app/presenter.ts and navigate to the connect() method.
  2. Navigate to where SparkScanView is declared: 
    this.sparkScanView = SparkScanView.forElement(
      document.body,
      this.dataCaptureContext,
      this.sparkScan,
      this.sparkScanViewSettings
    );
  3. Add this line to make the target mode button visible to the user: 
this.sparkScanView.targetModeButtonVisible = true;

4. Customize the user interface

You can customize the SparkScan UI and UX to meet your needs, from element colors (i.e., icons, buttons, toolbar) to the size of the camera preview.

The image below shows three different examples of how colors, positions, and sizes can be customized to fit different use cases.

To change different UI elements in the sample app:

  1. Open /src/app/presenter.ts and navigate to the connect() method.
  2. Navigate to where SparkScanView is declared: 
    this.sparkScanView = SparkScanView.forElement(
      document.body,
      this.dataCaptureContext,
      this.sparkScan,
      this.sparkScanViewSettings
    );
  3. To change the color of the trigger button background and its animation (the pulsing effect shown when the scanner is active), add these lines using hex values to set different shades of blue: 
this.sparkScanView.triggerButtonExpandedColor = Color.fromHex("#123768");
this.sparkScanView.triggerButtonAnimationColor = Color.fromHex("#59D3DE");

4. To change the toolbar background color, add: 

this.sparkScanView.toolbarBackgroundColor = Color.fromHex("#01AAA7");

5. To change the size of the camera preview, navigate to where SparkScanViewSettings is declared: 

this.sparkScanViewSettings = new SparkScanViewSettings();

6. Add this line to change the camera preview from its default smaller size to a larger window:

this.sparkScanViewSettings.defaultMiniPreviewSize = SparkScanMiniPreviewSize.Expanded;

5. Add error feedback

To show an error message when scanning specific barcodes, such as those already added to an existing list, you can customize SparkScan’s error feedback prompt.

SparkScan-based app showing error feedback when scanning a barcode on an orange juice container

  1. Open /src/app/presenter.ts and navigate to the getFeedbackForBarcode() method.
  2. Change the first if statement from this: 
    if (barcode.data === "5901234123457") {
      return new SparkScanBarcodeErrorFeedback("Barcode rejected.", 60_000, Color.fromHex("#FF0000"));
    }
    to use a barcode number you have and set additional feedback like this: 
    if (barcode.data === "0059749979610") {
      return new SparkScanBarcodeErrorFeedback("Barcode is incorrect.", 60_000, Color.fromHex("#FF0000"), new Brush(Color.fromHex("#00FFFF"), Color.fromHex("#FFFFFF"),1));
    }

The method’s parameters are:

  • message: The error message to show on screen.
  • resumeCapturingDelay: The time interval after which to resume the capture process, in milliseconds.
  • visualFeedbackColor: The color to flash the screen upon scanning the wrong barcode, set using the Color class.
  • brush: The color of the solid shape laid over the barcode to indicate that it was rejected, set using the Color class.

This method includes a parameter to emit a sound and vibrate the device when called.

6. Compile and run

Run the sample application from your chosen IDE and start scanning barcodes!

Next steps

Now that you have your first scan out of the way, you can play around with the other sample applications to see some of the more advanced features in action.

We also recommend: