Scandit.BarcodeScanner

new BarcodeScanner(options?: Scandit.BarcodeScanner.ScannerOptions)

Creates a new instance of the barcode scanner with the specified options.

By default, all symbologies are disabled. To enable a symbology, it must be listed in the options under the "symbologies" key. Symbologies can either be a dictionary, or an array of symbology names. The identifiers for the different symbologies can be passed as strings directly but are also available through the Symbology object.

{
  symbologies: [ 'ean13', 'upca', Scandit.BarcodeScanner.Symbology.CODE128 ]
}

When using a dictionary, further symbology options can be specified, such as extensions to enable, used checksums etc.:

{
  symbologies: {
    'ean13': true,
    'upca': {
      extensions: ['remove_leading_zero']
    },
    Scandit.BarcodeScanner.Symbology.ITF: {
      checksums: [ 'mod10' ]
    }
  }
}
The following options are currently supported:

  • enabled: boolean indicating whether the symbology should be enabled. When using the dictionary form, enabled is automatically set to true.
  • colorInvertedEnabled: boolean indicating whether color-inverted codes of that symbology should be decoded. Default is false.
  • activeSymbolCounts: integer[] specifying the active symbol counts for the symbology.
  • extensions: string[] of extensions to be enabled for the symbology.
  • checksums: string[] of optional checksums to use for the symbology.

Depending on the symbology, some of these properties are ignored.

See Symbology Properties for details on the default active symbol counts, how it is calculated and what checksums and extensions are available.

Notes:

  • Starting the barcode scanner just after returning from the Camera is currently not recommended due to SDK limitations. If you need to start the scanner, capture an image and use the scanner again, try instead only hiding (and not stopping) the scanner, starting the image capture and resuming the scanner upon returning from the camera.
  • Using Scandit.BarcodeScanner and the barcodescanner-sdk-cordova plugin in one activity is not supported

States: The BarcodeScanner can be either in a paused or started state, otherwise it's not shown and thus does not have a state.

Battery consumption should be taken into account whenever the scanner is shown, as all devices use a significant amount of energy to power the camera. To save battery, keep the scanner in a paused state if possible or hide the scanner when not needed.

Parameters:
Name Type Attributes Description
options Scandit.BarcodeScanner.ScannerOptions <optional>

Scanner configuration

Classes

Barcode

Members

(static, readonly) Symbology :string

Enumeration of all symbologies that can be enabled and returned by the scanner.

Specify as either Scandit.BarcodeScanner.Symbology.<NAME> (e.g. Scandit.BarcodeScanner.Symbology.EAN13) or as a string (value), such as "ean13".

Type:
  • string
Properties:
Name Type Description
UNKNOWN string

Sentinel value to represent an unknown symbology. Value is "unknown".

EAN13 string

EAN-13 1D barcode symbology. Value is "ean13".

EAN8 string

EAN-8 1D barcode symbology. Value is "ean8".

UPC12 string

UPC-12/UPC-A 1D barcode symbology. Value is "upca".

UPCE string

UPC-E 1D barcode symbology. Value is "upce".

CODE11 string

Code 11 barcode symbology. Value is "code11".

CODE128 string

Code 128 1D barcode symbology, including GS1-Code128. Value is "code128".

CODE39 string

Code 39 barcode symbology. Value is "code39".

CODE93 string

Code 93 barcode symbology. Value is "code93".

CODE25 string

EAN-13 1D barcode symbology. Value is "code25".

ITF string

Interleaved-Two-of-Five (ITF) 1D barcode symbology. Value is "itf".

QR string

QR Code 2D barcode symbology. Value is "qr".

DATA_MATRIX string

Data Matrix 2D barcode symbology. Value is "data-matrix".

PDF417 string

EAN-13 1D barcode symbology. Value is "pdf417".

MSI_PLESSEY string

PDF417 barcode symbology. Value is "msi-plessey".

GS1_DATABAR string

GS1 DataBar 14 1D barcode symbology. Value is "databar".

GS1_DATABAR_LIMITED string

GS1 DataBar Limited 1D barcode symbology. Value is "databar-limited".

GS1_DATABAR_EXPANDED string

GS1 DataBar Expanded 1D barcode symbology. Value is "databar-expanded".

CODABAR string

Codabar 1D barcode symbology. Value is "codabar".

AZTEC string

Aztec Code 2D barcode symbology. Value is "aztec".

MAXICODE string

MaxiCode 2D barcode symbology. Value is "maxicode".

FIVE_DIGIT_ADD_ON string

Five-digit add-on for UPC and EAN codes. In order to scan five-digit add-on codes, at least one of these symbologies must be activated as well: EAN13, UPCA, UPCE, or EAN8 and the maximum number of codes per frame has to be set to at least 2. Value is "five-digit-add-on".

TWO_DIGIT_ADD_ON string

Two-digit add-on for UPC and EAN codes. In order to scan two-digit add-on codes, at least one of these symbologies must be activated as well: EAN13, UPCA, UPCE, or EAN8 and the maximum number of codes per frame has to be set to at least 2. Value is "two-digit-add-on".

Methods

applyScanSettings(options: Scandit.BarcodeScanner.ScannerOptions)

Applies scan settings to the barcode scanner without restarting it.

Note: applyScanSettings can not change the caseMode option of an already existing BarcodeScanner instance. If you need to change this option, you need to create a new instance of the scanner.

Parameters:
Name Type Description
options Scandit.BarcodeScanner.ScannerOptions

Scanner configuration. See Scandit.BarcodeScanner.ScannerOptions for all possibilities.

Examples
  • JavaScript
  • ES6
var scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show().start();
// ...
scanner.resize(0.5);
scanner.applyScanSettings({
  activeScanningAreaPortrait: [0, 0.48, 1, 0.04],
  activeScanningAreaLandscape: [0, 0.48, 1, 0.04]
});
let scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show().start();
// ...
scanner.resize(0.5);
scanner.applyScanSettings({
  activeScanningAreaPortrait: [0, 0.48, 1, 0.04],
  activeScanningAreaLandscape: [0, 0.48, 1, 0.04]
});

clearTextOverlay()

Removes text overlay if exists

Examples
  • JavaScript
  • ES6
var scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show();
scanner.setTextOverlay('Preparing...', 'red');
// ...
// do preparations that are needed to handle the scanned barcode, e.g. download a list of barcodes to be accepted
scanner.start();
scanner.clearTextOverlay();
let scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show();
scanner.setTextOverlay('Preparing...', 'red');
// ... // do preparations that are needed for scanning, e.g. download a list of products that will be searched
scanner.start();
scanner.clearTextOverlay();

hide(): Scandit.BarcodeScanner

Hides the scanner and camera preview. If the scanner is currently scanning it will be stopped.

Returns:
Examples
  • JavaScript
  • ES6
var scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show().start();
// ...
scanner.hide();
let scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show().start();
// ...
scanner.hide();

off(event: string, callback?: function)

Unbinds event callback. Possible events: hide, scan, show.

Parameters:
Name Type Attributes Description
event string

Event name

callback function <optional>

Event callback

Examples
  • JavaScript
  • ES6
var scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.on('scan', function(barcode) {
  console.log(barcode);
});
// ...
scanner.off('scan');
let scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.on('scan', barcode => {
  console.log(barcode);
});
// ...
scanner.off('scan');

on(event: string, callback: function)

Binds event callback. Possible events: hide, scan, show.

Parameters:
Name Type Description
event string

Event name

callback function

Event callback

Examples
  • JavaScript
  • ES6
var scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.on('scan', function(barcode) {
  console.log(barcode);
});
let scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.on('scan', barcode => {
  console.log(barcode);
});

pause(): Scandit.BarcodeScanner

Pauses the scanner.

The scanner and camera preview will continue to be visible but the scanner will no longer recognize barcodes until resume or start is called.

Returns:
Examples
  • JavaScript
  • ES6
var scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show().start();
// ...
scanner.pause();
let scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show().start();
// ...
scanner.pause();

resize(newSize: float, position?: string)

Resizes the scanner and potentially changes its position on the screen.

Note that this only resizes the visible scanner but does not change the area of the camera preview in which barcodes are recognized. If you wish to resize and change the active scanning area at the same time, use Scandit.BarcodeScanner#applyScanSettings.

Parameters:
Name Type Attributes Description
newSize float

Determines the size of the scanner. The value represents how much space will be reserved for the scanner starting from the top or bottom of the screen (depending on the position option) and can be between 0.0 and 1.0.

position string <optional>

Position of the scanner. Possible values: top, bottom

Examples
  • JavaScript
  • ES6
var scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show().start();
// ...
scanner.resize(0.5);
let scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show().start();
// ...
scanner.resize(0.5);

resume(): Scandit.BarcodeScanner

Resumes a previously paused scanner.

Returns:
Examples
  • JavaScript
  • ES6
var scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show().start();
// ...
scanner.pause();
// ...
scanner.resume();
let scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show().start();
// ...
scanner.pause();
// ...
scanner.resume();

setTextOverlay(text: string, color?: string)

Shows text overlay on the scanner camera preview

Parameters:
Name Type Attributes Description
text string

The text to display

color string <optional>

Hex color or color name.

Supported formats/values: #RRGGBB, #AARRGGBB, red, blue, green, black, white, gray, cyan, magenta, yellow, lightgray, darkgray, grey, lightgrey, darkgrey, aqua, fuschia, lime, maroon, navy, olive, purple, silver, teal.

Examples
  • JavaScript
  • ES6
var scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show().start();
scanner.setTextOverlay('Start scanning!', 'green');
let scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show().start();
scanner.setTextOverlay('Start scanning!', 'green');

show(): Scandit.BarcodeScanner

Shows the scanner and camera preview.

The scanner will start in a paused state and not immediately ready to scan. In order to start scanning after the scanner is shown, use start.

Returns:
Examples
  • JavaScript
  • ES6
var scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show().start();
let scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show().start();

start(options?: object): Scandit.BarcodeScanner

Starts scanning.

Parameters:
Name Type Attributes Description
options object <optional>
Properties
Name Type Attributes Default Description
continuous boolean <optional>
false

Whether the scanner should continuously scan or just once. If set to false the scanner will pause after the first scan. The scanner and camera preview will continue to be visible but the scanner will no longer recognize barcodes until resume or start is called.

Returns:
Examples
  • JavaScript
  • ES6
var scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show().start();
let scanner = new Scandit.BarcodeScanner({ symbologies: ['ean13'] });
scanner.show().start();

Type Definitions

ScannerOptions

BarcodeScanner configuration object

Type:
  • object
Properties:
Name Type Attributes Default Description
symbologies object <optional>
{}

Enabled symbologies (aka barcode types), which can be detected. Possible values are the members of Scandit.BarcodeScanner.Symbology. See the description of this constructor for more detailed information.

extEvents boolean <optional>
false

Whether the scan event callback should be called with the extended parameters. See the scan event for more details.

codeDuplicateFilter integer <optional>
1200

The duration of the duplicate filter in milliseconds.

  • larger than zero: barcodes with the same symbology and data are filtered out if they are decoded less than the specified milliseconds apart.
  • zero: if you do not want to filter duplicates.
  • -1: barcodes are filtered as duplicates if they match an already decoded barcode in the session.
cameraFacingPreference string <optional>
back

Determines which camera should be used (if available). Possible values: back, front.

highDensityModeEnabled boolean <optional>
false

High density mode enables phones to work at higher camera resolution, provided they support it. When enabled, phones that are able to run the video preview at 1080p (1920x1080) will use 1080p instead of the default 720p (1280x720). High density mode gives better decode ranges at the expense of processing speed and allows to decode smaller code in the near range, or codes that are further away.

activeScanningAreaPortrait float[] <optional>
[0, 0, 1, 1]

Sets the active scan area for portrait mode scanning. By default, the barcode recognition engine searches the whole image for barcodes. Use this method to define the area in which barcodes are to be scanned. The accepted format is [x, y, width, height], where all can be between 0 and 1. Example: [0, 0.48, 1, 0.04] restricts the scanning area to the scanner line.

activeScanningAreaLandscape float[] <optional>
[0, 0, 1, 1]

Sets the active scan area for landscape mode scanning. By default, the barcode recognition engine searches the whole image for barcodes. Use this method to define the area in which barcodes are to be scanned. The accepted format is [x, y, width, height], where all can be between 0 and 1. Example: [0, 0.48, 1, 0.04] restricts the scanning area to the scanner line.

scanningHotSpot float[] <optional>
[0.5,0.5]

The location in the image where barcodes are decoded with the highest priority. This variable shows a slightly different behavior depending on whether the full screen scanning is active or not. In Full screen scanning mode: Sets the location in the image which is decoded with the highest priority when multiple barcodes are present in the image. Changes the location of the spot where the barcode decoder actively scans for barcodes. X and Y can be between 0 and 1, where 0/0 corresponds to the top left corner and 1/1 to the bottom right corner.

relativeZoom float <optional>
0

The percentage of the max zoom (between 0 and 1).

maxNumberOfCodesPerFrame integer <optional>
1

Maximum number of codes to be decoded every frame. The values are clamped to the range 1 to 6.

keepCameraActive float <optional>
0.0

When the scanner is in hidden state it will keep the camera running (invisibly) for the given amount of seconds. If the scanner is started again within this time frame, this will reduce the startup time. Be aware that the device will use more battery power while the camera is running.

caseMode boolean <optional>
false

Whether the scanner should be running in caseMode. To use the external Scandit Case with the barcode scanner running in Flow, set this to true. When the scanner is running in caseMode, it's shown without the camera stream. While the scanner is actively scanning (either by calling start/resume or pushing the physical button), the device's LED is turned on the power the case's aimer.

matrixScanEnabled boolean <optional>

Enables matrix scanning which allows you to know the location of all localized codes. If enabled you should set ui.guiStyle to 'matrix_scan'.

ui Scandit.BarcodeScanner.ScannerOptionsUi <optional>

UI configuration object

Examples
  • JavaScript
  • ES6
var scanner = new Scandit.BarcodeScanner({
  symbologies: ['ean13', 'upca'],
  activeScanningAreaPortrait: [0, 0.48, 1, 0.04],
  activeScanningAreaLandscape: [0, 0.48, 1, 0.04]
});
let scanner = new Scandit.BarcodeScanner({
  symbologies: ['ean13', 'upca'],
  activeScanningAreaPortrait: [0, 0.48, 1, 0.04],
  activeScanningAreaLandscape: [0, 0.48, 1, 0.04]
});

ScannerOptionsUi

BarcodeScanner UI configuration object

Type:
  • object
Properties:
Name Type Attributes Default Description
size float <optional>
1.0

Determines the size of the scanner. The value represents how much space will be reserved for the scanner starting from the top or bottom of the screen (depending on the position option) and can be between 0.0 and 1.0.

position string <optional>
top

Position of the scanner. Possible values: top, bottom.

guiStyle string <optional>
laser

Style of the overlaying GUI. Possible values: 'default', 'laser', 'locations_only', 'matrix_scan'

viewfinderDimension float[] <optional>
[0.9, 0.4, 0.6, 0.4]

Dimension of the viewfinder when guiStyle is 'default' or 'locations_only'

viewfinderColor string <optional>
"#FFFFFF"

The color of the viewfinder in its default state.

viewfinderColor string <optional>
"#39c1cc"

The color of the viewfinder when it highlights a recognized code.

manualInputEnabled boolean <optional>
true

Can be used to enable manual input for the scanner.

manualInputPlaceholder string <optional>
null

If manual input enabled, it can be used to overwrite the default text placeholder.

torchEnabled boolean <optional>
true

Determines if the torch button should be visible on the scanner.

cameraSwitchVisibility string <optional>
never

Determines if the scanner should have a user option to switch between front and back camera. Possible values: never, always, tablet.

vibrationEnabled boolean <optional>
true

Determines if each scan should be confirmed with a device vibration.

soundEnabled boolean <optional>
true

Determines if each scan should be confirmed with a beep sound.

Examples
  • JavaScript
  • ES6
var scanner = new Scandit.BarcodeScanner({
  symbologies: ['ean13', 'upca'],
  ui: {
    size: 0.5,
    position: 'top'
  }
});
let scanner = new Scandit.BarcodeScanner({
  symbologies: ['ean13', 'upca'],
  ui: {
    size: 0.5,
    position: 'top'
  }
});

Events

hide

Scanner hide event

scan

Scanner scan event.

Callbacks for this event are called with either normal or extended events which can be turned on through options.extEvents of the barcode scanner's constructor.

Extended events are recommended if you want to scan multiple codes at the same time or if you are scanning gs1 codes, as the gs1 data carrier flag is only available through the extended events.

Examples
With extEvents set to false the callback is called with two arguments, the first contains the data of the barcode, the second a string to identify the symbology.
  • JavaScript
  • ES6
scanner.on('scan', function(barcode, symbology) {
  console.log(symbology + ": " + barcode);
  scanner.pause(); // Pause if in continuous mode and no more codes should be scanned.
});
scanner.on('scan', (barcode, symbology) => {
  console.log(`${symbology}:${barcode}`);
  scanner.pause(); // Pause if in continuous mode and no more codes should be scanned.
});
With extEvents set to true the callback is called with an array of Barcodes. The array contains all codes that have been recognized in the same frame.
  • JavaScript
  • ES6
scanner.on('scan', function(barcodes) {
  console.log(barcodes[0].symbology + ": " + barcodes[0].data);
  scanner.pause(); // Pause if in continuous mode and no more codes should be scanned.
});
scanner.on('scan', barcodes => {
  console.log(`${barcodes[0].symbology}:${barcodes[0].data}`);
  scanner.pause(); // Pause if in continuous mode and no more codes should be scanned.
});

show

Scanner show event