Deprecation warning

Please note that this is outdated documentation for an older release of the Scandit Barcode Scanner SDK.

We encourage you to migrate to 6.x and take advantage of our latest / advanced features and improved performance.

You'll find the updated documentation at: Data Capture SDK Documentation for Cordova

CordovaPlugin Class Reference

Instance Methods

(void) - scan
 
(void) - cancel
 
(void) - pause
 
(void) - resume
 
(void) - stop
 
(void) - start
 
(void) - resize
 
(void) - torch
 

Detailed Description

phonegap/cordova plugin that acquires camera frames, shows scan user interface and decodes barcodes in the camera frames.

Example (minimal) usage:

Set up the Scandit SDK in your javascript code by providing two callback functions and a call to cordova.exec.

The parameter listing below shows all the customization options of the Scandit SDK. They are listed in the dictionary that follows the app key (see example below). All parameters are optional.

function success(resultArray) {
alert("Scanned " + resultArray[0] + " code: " + resultArray[1]);
}
function failure(error) {
alert("Failed: " + error);
}
function scan() {
cordova.exec(success, failure, "ScanditSDK", "scan",
["ENTER YOUR APP KEY HERE",
{"beep": true,
"ean13" : true,
"qr" : false}]);
}
Since
1.0.0

Copyright Scandit AG

Method Documentation

- (void) scan

Configures and starts the scanner.

You invoke the plugin's scan function through the cordova.exec function the following way:

cordova.exec(success, failure, "ScanditSDK", "scan",
["ENTER YOUR APP KEY HERE",
{"beep": true,
"ean13" : true,
"qr" : false}]);

Parameters of the exec function to invoke the plugin's scan function

Parameters
successfunction to be called when barcode is decoded (or user enters a string in the search bar). The function is called with an array containing two strings. The first string is the content of the barcode, the second string is the symbology of the barcode. The symbology is one of the following strings: "EAN8", "EAN13", "UPC12", "UPCE", "CODE128", "GS1-128", "CODE39", "CODE93", "ITF", "MSI", "CODABAR", "GS1-DATABAR", "GS1-DATABAR-EXPANDED", "QR", "GS1-QR", "DATAMATRIX", "GS1-DATAMATRIX", "PDF417", "TWO-DIGIT-ADD-ON", "FIVE-DIGIT-ADD-ON", "AZTEC".
failurefunction to be called when user cancels
pluginthe plugin name: "ScanditSDK"
pluginMethodthe method name: "scan"
parametersAn array of parameters. The first object has to be the Scandit app key whic is available from your Scandit Account. The second object is an optional dictionary which can contain any of the parameters described below.

The following parameters are optional and are specified as part of a json dictionary as shown in the example above.

Camera Configuration

Parameters
preferFrontCameraboolean to use the front camera when a device has two cameras (default is false).

Orientation Configuration

Parameters
orientationsstring for which orientations are allowed for the iOS scanner (under Android the orientations have to be set in the Manifest where the ScanditSDKActivity is defined). This only works if the scanner is shown in full screen mode and does not work if margins are set. Legal values: portrait, portraitUpsideDown, landscapeLeft, landscapeRight. Example: "landscapeRight,landscapeLeft". Default is the same as set in the app settings.

Scanner Behavior and Presentation

Parameters
continuousModeboolean to enable continous mode. If a barcode is scanned, the scanner is not dismissed and the user is able to continue scanning until he presses "Cancel" or the plugins cancel function is called. Default is false.
portraitMarginsstring to set left/top/right/bottom margins (in resolution independent pixels) for the scanner in portrait orientation. Settings margins will start the scanner in a subview on top of Cordova's webview and not in its own view controller. Use this parameter to make the scanner smaller than fullscreen and show your own content along with the scanner. Default is "0/0/0/0" (fullscreen).
landscapeMarginsstring to set left/top/right/bottom margins (in resolution independent pixels) for the scanner in landscape orientation. Settings margins will start the scanner in a subview on top of Cordova's webview and not in its own view controller. Use this parameter to make the scanner smaller than fullscreen and show your own content along with the scanner. Default is "0/0/0/0" (fullscreen).
pausedboolean to start the scanner in a paused state instead of already scanning. Default is false.

Symbology Selection

Parameters
1DScanningboolean to enable all 1D symbologies are enabled. Deprecated - enable symbologies individually instead.
2DScanningboolean to enable all 2D symbologies are enabled. Deprecated - enable symbologies individually instead.
ean13AndUpc12boolean to enable/disable EAN13 and UPC12 decoding. Default is true.
ean8boolean to enable/disable EAN8 decoding. Default is true.
upceboolean to enable/disable UPCE decoding. Default is true.
code39boolean to enable/disable CODE39 decoding. Default is true.
code128boolean to enable/disable CODE128 decoding. Default is true.
itfboolean to enable/disable Interleaved-Two-of-Five (ITF) decoding. Default is true.
gs1DataBarboolean to enable/disable GS1 DataBar decoding. Default is false.
gs1DataBarExpandedboolean to enable/disable GS1 DataBar Expanded decoding. Default is false.
codabarboolean to enable/disable Codabar decoding. Default is false.
qrboolean to enable/disable QR decoding. Default is true.
dataMatrixboolean to enable/disable Datamatrix decoding. Default is true.
pdf417boolean to enable/disable PDF417 decoding. Default is true.
aztecboolean to enable/disable Aztec decoding. Default is false.
msiPlesseyboolean to enable/disable MSIPlessey decoding. Default is false.
msiPlesseyChecksumTypestring enum to set the type of checksum that is expected of the MSI Plessey codes. Legal values are: "none", "mod10", "mod11", "mod1010", "mod1110". Default is "mod10".

Barcode Decoder Configuration

Parameters
inverseRecognitionboolean to enable/disable white on black Data Matrix and QR code decoding. Default is false.
microDataMatrixboolean to enable/disable tiny Data Matrix decoder. Default is false.
force2dboolean to force running 2D decoder even when detector does not detect 2D code presence. Default is false.
scanningHotSpotstring of the location in the image where the barcodes are decoded with the highest priority. The hotspot coordinates are passed in the format "x/y" where x and y are floats between 0 and 1 where "0/0" corresponds to the top left corner and "1/1" to the bottom right corner. Default is "0.5/0.5".
scanningHotSpotHeightfloat height of the area where barcodes are decoded in the camera image. The area is centered around the location set through the "scanningHotSpot" parameter. The height is relative to the screen and has to be between 0.0 and 0.5. If no hot spot height is set, barcodes everywhere in the image are decoded.
codeDuplicateFilterinteger duration of the duplicate filter in milliseconds. When set to a value larger than zero, barcodes with the same symbology and data are filtered out if they are decoded less than the given milliseconds apart. Set this value to zero if you do not want to filter duplicates. When set to -1 barcodes are filtered as duplicates if they match an already decoded barcode in the session (A session ends with a call to cancel or stop or a successful scan in non-continuous mode). (see native SBSScanSettings:codeDuplicateFilter)

Sound Configuration

Parameters
beepboolean to enable/disable the sound played when a code was recognized. Default is true.
vibrateboolean to enable/disable the vibration when a code was recognized. Default is true.

Torch Configuration

Parameters
torchboolean to enable/disable the torch toggle button for all devices that support a torch. Default is true.
torchButtonPositionAndSizestring position at which the button to enable the torch is drawn. The position is passed in the format "0.05/0.05/40/40" (x/y/width/height). The X and Y coordinates are relative to the screen size, which means they have to be between 0 and 1.
torchButtonMarginsAndSizestring position at which the button to enable the torch is drawn. The position is passed in the format "15/15/40/40" (leftMargin/topMargin/width/height). All values are in resolution independent pixels.

Camera Switch Configuration

Parameters
cameraSwitchVisibilitystring enum to set when the camera switch button is visible for devices that have more than one camera. Values are: "never", "tablet", "always". Default is "never".
cameraSwitchButtonPositionAndSizestring position at which the button to switch the camera is drawn. The position is passed in the format "0.05/0.05/40/40" (inverseX/y/width/height). The inverse X (distance from right side instead of left) and Y coordinates are relative to the screen size, which means they have to be between 0 and 1.
cameraSwitchButtonMarginsAndSizestring position at which the button to switch the camera is drawn. The position is passed in the format "15/15/40/40" (leftMargin/topMargin/width/height). All values are in resolution independent pixels.

Searchbar Configuration

Parameters
searchBarboolean to show or hide the search bar at the top of the screen. Default is false.
searchBarActionButtonCaptionstring to set caption of the "Go" button.
searchBarCancelButtonCaptionstring to set caption of the "Cancel" button.
searchBarPlaceholderTextstring placeholder text:, e.g. "Scan barcode or enter it here".
minSearchBarBarcodeLengthinteger minimum size a barcode in the search bar has to have to be valid.
maxSearchBarBarcodeLengthinteger maximum size a barcode in the search bar can have to be valid.

Toolbar Configuration

Parameters
toolBarButtonCaptionstring to set the caption of the tool bar's "Cancel" button.

Viewfinder Configuration

Parameters
guiStylestring to set the style of the viewfinder. Can be one of "default" or "laser".
viewfinderSizestring to set the size of the viewfinder. The size is passed in the format "0.9/0.4/0.6/0.4" (width/height/landscapeWidth/landscapeHeight) where all lengths are relative to the screen size.
viewfinderColorstring to set the color of the viewfinder. Default is "FFFFFF".
viewfinderDecodedColorstring to set the color of the viewfinder when the code has been recognized. Default is "3AC1CD".

Analytics Configuration

Parameters
deviceNamestring to set a device name that identifies this device when looking at analytics tools. Sends a request to the server to set this as soon as a connection is available.
- (void) cancel

Cancels the scanning.

You invoke the plugin's cancel function through the cordova.exec function the following way:

cordova.exec(success, failure, "ScanditSDK", "cancel", []);

Parameters of the exec function to invoke the plugin's cancel function

Parameters
successThere is no failure callback: null
failureThere is no failure callback: null
pluginThe plugin name: "ScanditSDK"
pluginMethodThe method name: "cancel"
parametersAn empty array.
- (void) pause

Pauses the scanning while the video feed continues to run.

You invoke the plugin's pause function through the cordova.exec function the following way:

cordova.exec(success, failure, "ScanditSDK", "pause", []);

Parameters of the exec function to invoke the plugin's pause function

Parameters
successThere is no failure callback: null
failureThere is no failure callback: null
pluginThe plugin name: "ScanditSDK"
pluginMethodThe method name: "pause"
parametersAn empty array.
- (void) resume (success) 
(failure) 
(parameters)   

Resumes the scanning after pause was called.

You invoke the plugin's cancel function through the cordova.exec function the following way:

cordova.exec(success, failure, "ScanditSDK", "resume", []);

Parameters of the exec function to invoke the plugin's Resume function

Parameters
successThere is no failure callback: null
failureThere is no failure callback: null
pluginThe plugin name: "ScanditSDK"
pluginMethodThe method name: "resume"
parametersAn empty array
- (void) stop

Stops the scanning and also freezes the video feed.

You invoke the plugin's stop function through the cordova.exec function the following way:

cordova.exec(success, failure, "ScanditSDK", "stop", []);

Parameters of the exec function to invoke the plugin's cancel function

Parameters
successThere is no failure callback: null
failureThere is no failure callback: null
pluginThe plugin name: "ScanditSDK"
pluginMethodThe method name: "stop"
parametersAn empty array.
- (void) start

Restarts the scanning after stop or pause were called.

You invoke the plugin's start function through the cordova.exec function the following way:

cordova.exec(success, failure, "ScanditSDK", "start", []);

Parameters of the exec function to invoke the plugin's start function

Parameters
successThere is no failure callback: null
failureThere is no failure callback: null
pluginThe plugin name: "ScanditSDK"
pluginMethodThe method name: "start"
parametersAn empty array.
- (void) resize

Configures and starts the scanner.

You invoke the plugin's scan function through the cordova.exec function the following way:

cordova.exec(null, null, "ScanditSDK", "resize", [{"beep": false}]);

Parameters of the exec function to invoke the plugin's scan function

Parameters
successThere is no failure callback: null
failureThere is no failure callback: null
pluginThe plugin name: "ScanditSDK"
pluginMethodThe method name: "resize"
parametersAn array of parameters. The first and only object is an optional dictionary which can contain any of the parameters described below.

The following parameters are optional and are specified as part of a json dictionary as shown in the example above.

Camera Configuration

Parameters
preferFrontCameraboolean to use the front camera when a device has two cameras (default is false).

Orientation Configuration

Parameters
orientationsstring for which orientations are allowed for the iOS scanner (under Android the orientations have to be set in the Manifest where the ScanditSDKActivity is defined). This only works if the scanner is shown in full screen mode and does not work if margins are set. Legal values: portrait, portraitUpsideDown, landscapeLeft, landscapeRight. Example: "landscapeRight,landscapeLeft". Default is the same as set in the app settings.

Scanner Behavior and Presentation

Parameters
animationDurationfloat to set the animation duration for the change in margins. Default is 0.0.
portraitMarginsstring to set left/top/right/bottom margins (in resolution independent pixels) for the scanner in portrait orientation. Settings margins will start the scanner in a subview on top of Cordova's webview and not in its own view controller. Use this parameter to make the scanner smaller than fullscreen and show your own content along with the scanner. Default is "0/0/0/0" (fullscreen).
landscapeMarginsstring to set left/top/right/bottom margins (in resolution independent pixels) for the scanner in landscape orientation. Settings margins will start the scanner in a subview on top of Cordova's webview and not in its own view controller. Use this parameter to make the scanner smaller than fullscreen and show your own content along with the scanner. Default is "0/0/0/0" (fullscreen).

Barcode Decoder Configuration

Parameters
scanningHotSpotstring of the location in the image where the barcodes are decoded with the highest priority. The hotspot coordinates are passed in the format "x/y" where x and y are floats between 0 and 1 where "0/0" corresponds to the top left corner and "1/1" to the bottom right corner. Default is "0.5/0.5".
scanningHotSpotHeightfloat height of the area where barcodes are decoded in the camera image. The area is centered around the location set through the "scanningHotSpot" parameter. The height is relative to the screen and has to be between 0.0 and 0.5. If no hot spot height is set, barcodes everywhere in the image are decoded.

Sound Configuration

Parameters
beepboolean to enable/disable the sound played when a code was recognized. Default is true.
vibrateboolean to enable/disable the vibration when a code was recognized. Default is true.

Torch Configuration

Parameters
torchboolean to enable/disable the torch toggle button for all devices that support a torch. Default is true.
torchButtonPositionAndSizestring position at which the button to enable the torch is drawn. The position is passed in the format "0.05/0.05/40/40" (x/y/width/height). The X and Y coordinates are relative to the screen size, which means they have to be between 0 and 1.

Camera Switch Configuration

Parameters
cameraSwitchVisibilitystring enum to set when the camera switch button is visible for devices that have more than one camera. Values are: "never", "tablet", "always". Default is "never".
cameraSwitchButtonPositionAndSizestring position at which the button to switch the camera is drawn. The position is passed in the format "0.05/0.05/40/40" (inverseX/y/width/height). The inverse X (distance from right side instead of left) and Y coordinates are relative to the screen size, which means they have to be between 0 and 1.

Searchbar Configuration

Parameters
searchBarboolean to show or hide the search bar at the top of the screen. Default is false.
searchBarActionButtonCaptionstring to set caption of the "Go" button.
searchBarCancelButtonCaptionstring to set caption of the "Cancel" button.
searchBarPlaceholderTextstring placeholder text:, e.g. "Scan barcode or enter it here".
minSearchBarBarcodeLengthinteger minimum size a barcode in the search bar has to have to be valid.
maxSearchBarBarcodeLengthinteger maximum size a barcode in the search bar can have to be valid.

Viewfinder Configuration

Parameters
viewfinderSizestring to set the size of the viewfinder. The size is passed in the format "0.9/0.4/0.6/0.4" (width/height/landscapeWidth/landscapeHeight) where all lengths are relative to the screen size.
viewfinderColorstring to set the color of the viewfinder. Default is "FFFFFF".
viewfinderDecodedColorstring to set the color of the viewfinder when the code has been recognized. Default is "3AC1CD".
- (void) torch

Turns the torch on or off once the scanner is running.

You invoke the plugin's torch function through the cordova.exec function the following way:

cordova.exec(null, null, "ScanditSDK", "torch", [true]);

Parameters of the exec function to invoke the plugin's torch function

Parameters
successThere is no failure callback: null
failureThere is no failure callback: null
pluginThe plugin name: "ScanditSDK"
pluginMethodThe method name: "torch"
parametersAn array containing one boolean to say whether the torch should be on or off.