Documentation

Getting Started

We've tried to make adding barcode scanning to your website as easy as possible. At a high level, these are the steps you'll need to follow:

  1. Create an account.
  2. Create a scanner.
  3. Include our JavaScript file on your page.
  4. Open the scanner from a button click or other means.

On this page, we'll cover everything you need to know.

  • We'll cover advanced topics further down as well.

Create Your Account

All you need is an email address and a password to create an account. We will send you a welcome email with a link to verify your account. Once you've done that, you're ready to go.

These are things we won't do:

  • Send you email about anything other than information about BarcodeScanner.io, especially as it pertains to your account.
  • Share your information with anyone else.

Create a Scanner

Once you're logged in, you'll see a menu option called "My Scanners" under the "My Account" heading. On this page you can create new barcode scanners or edit the scanners you've already made. Click on the "Create New Scanner" button to begin creating a new scanner.

At the top of the scanner editor, you'll notice an option to "Toggle Help". This will display captions below each field with further information to help you.

When your scanner is set up the way you want it, click "Save" to return to your list of scanners.


Now let's call attention to the options you'll see next to each scanner in your list.

Opens the scanner editor and allow you to make changes.

Shows you the scanner ID as well as the code that you need to deploy the scanner.

Launches the scanner so you can see what it looks like. This load will not count against your quota.

Shows you a graph with recent load and scan statistics for this scanner.

Deletes the scanner after asking you to confirm.

Choosing a Library

At the moment, there are two scanner libaries to choose from when creating a scanner, ZXing and the Barcode Detection API. The first, ZXing, is an open source library that allows you to scan many different types of barcodes and should work on most devices. The second, Barcode Detection API, is actually a built-in feature in some browsers.

ZXing

Pros

  • Supports many barcode formats
  • Works well across many browsers
  • Generally good, reliable scanning with most formats
  • Good performance

Cons

  • Seems to struggle with some formats, such as UPC, unless conditions are perfect.
Barcode Detection API

Pros

  • Provides excellent detection
  • Excellent performance

Cons

  • Not supported on all browsers
  • All formats not supported in all implementations (must check).
Our Recommendation
  • Experiment and choose the right library for your use case.
  • Use code to determine which scanner to use based on browser capabilities, scanning requirements. See examples.

Deploying a Scanner

On any page where you will use a scanner, you need to include our JavaScript library by inserting the following code somewhere on your page.

<script id="BarcodeScannerIOScript" src="https://barcodescanner.io/js/BarcodeScannerIO.min.js" data-api-key="[API_KEY]"></script>
Replace [API_KEY] with your actual 32-character API key, which can be found on the "Profile" page under your account or by clicking on the "show code" icon next to any of your scanners.
Launching a scanner is done through a call to the BarcodeScannerIO library, specifically by calling either the "openScanner" or "openWindowScanner" methods. We'll talk more about the difference between those later.
BarcodeScannerIO.openScanner('[SCANNER_ID]')
Replace [SCANNER_ID] with your actual 32-character scanner ID, which can be found by clicking on the "show code" icon next to any of your scanners.
In this slightly more complete example, we attach the scanner to a button and tell it to populate the "serialNumber" field with scanned data.
<input type="text" id="serialNumber">
<button type="button" 
	onclick="BarcodeScannerIO.openScanner('[SCANNER_ID]', '#serialNumber')">
	Scan
</button>

Camera Permissions

When a scanner is launched and attemps to access the camera, the browser will validate that the user has already been given camera permission or will prompt the user to grant it.

There are two types of scanner available in the library. The first is opened by calling the openScanner method. This scanner opens in an iframe on an overlay. It provides a smooth experience in that it becomes part of the current page. However, this also means that the hosting site (your site) must use a secure connection (https). Permission to access the camera must also be granted to your site.

The second type of scanner is opened by calling the openWindowScanner method and opens in a popup window. It provides a similar experience but through an external window. A potential drawback to this method is that popup may be blocked by the browser. The potential benefits are that the scanner can be used on non-secure sites (http) and that permission to access the camera must be granted to barcodescanner.io.

BarcodeScannerIO API

After including our JavaScript in your page, an object variable named BarcodeScannerIO will be created that contains the following properties, methods, and events.

Properties

BarcodeScannerIO uses the following user properties. These properties are not meant to be addressable or read directly. Instead, they are set through the init method or through options when the scanner is opened.

  • apiKey
  • Type: String
    This is your API key, found on the profile page in your account. It is normally set as an attribute in the script tag, but it can be set here as well.
  • caption
  • Type: String
    This is the caption that will appear in the scanner window.
  • elementToPopulate
  • Type: String or Element
    Either an element or a query selector string.
  • scanCompleteCallback
  • Type: Function
    Function to be called with the result of a scan.
  • scanCanceledCallback
  • Type: Function
    Function to be called if the scan is canceled.
  • noCameraFoundCallback
  • Type: Function
    Function to call if no camera is found.
  • noCameraPermissionCallback
  • Type: Function
    Function to be called if the site cannot gain access to the camera.

Methods

  • init( options )
  • options
    Type: object
    Default options for all scanners (see properties above). Options can also be set when using one of the openScanner methods.
  • openScanner( scannerId [, element | selector | function | options] )
  • Opens the scanner in an iframe on a screen overlay. Camera permissions must be granted for the hosting website. Additionally, most browsers will also require a secure connection (https).
    scannerId
    Type: String
    The ID of the scanner to be opened.


    element
    Type: Element
    Element to populate with result of scan.
    selector
    Type: Selector
    A string representing a selector to identify the element to be populated with the result of the scan, such as "#textField".
    function
    Type: Function
    Function that will be called after a successful scan.
    options
    Type: Object
    An object containing properties that will be set for this scanner instance.
    The scannerId is always required. Any number of successive arguments may be included and will be evaluated according to their type.
  • openWindowScanner( scannerId [, element | selector | function | options] )
  • Opens the scanner in a a popup window. Camera permissions must be granted for barcodescanner.io. The hosting site will not require a secure connection (https). Popup blockers may keep window from opening.
    scannerId
    Type: String
    The ID of the scanner to be opened.


    element
    Type: Element
    Element to populate with result of scan.
    selector
    Type: Selector
    A string representing a selector to identify the element to be populated with the result of the scan, such as "#textField".
    function
    Type: Function
    Function that will be called after a successful scan.
    options
    Type: Object
    An object containing properties that will be set for this scanner instance.
    The scannerId is always required. Any number of successive arguments may be included and will be evaluated according to their type.

Event Callbacks

  • scanCompleteCallback(result)
  • result
    Type: object
    Example: {text: "123456", libResult: {...}}

    The result object will contain two properties, text and libResult. The text property will contain the text read from the barcode. The libResult will contain the raw result returned by the scanner library (ZXing).
  • scanCanceledCallback(void)
  • Called when a scan is canceled.
  • noCameraFoundCallback(void)
  • Called when no cameras are found. This may also occur if the openScanner method is called from a non-secure site (http).
  • noCameraPermissionCallback(void)
  • Called when the user has denied access to the camera.