No Script

PhoneGap Plugin

Manatee Works provides an Adobe PhoneGap plugin for its Barcode Scanner SDK, to provide cross-platform, mobile development framework applications with the best barcode scanning experience.

 

What is Cordova and PhoneGap?

Apache Cordova is a open source platform to build Native Mobile Applicatons using HTML, CSS and JavaScript. PhoneGap is Adobe's productised implementation of Cordova. Other distributions include Ionic, Meteor, and Telerik, and are also supported by Manatee Works and its broad support for development frameworks

Manatee Works provides the PhoneGap plugin via NPM, but also as a Git repository, so both paths are viable for integration.

 

Requirements 

The system should have installed:

 

Install using CLI interface (Phonegap >6.0 and above).

*For more information about installing PhoneGap, visit PhoneGap Getting Started. *

Install PhoneGap:

$ sudo npm install -g phonegap@latest

Create your app by using the CLI interface:

phonegap create my-mw-app 

or use bundle identifiers (the MW SDK license is bound to the bundle identifier):

phonegap create my-mw-app --id "org.mwscanner.sampleapp" --name "mwbScanner"

The previous step will create a folder named my-mw-app; navigate to your newly created folder and add the platforms you wish to build:

cd my-mw-app
phonegap build android  //if you are developing an android app
phonegap build ios    //if you are developing an ios app

Add the Manatee Works plugin to the project:

phonegap plugin add manateeworks-barcodescanner-v3

or

phonegap plugin add https://github.com/manateeworks/phonegap-manateeworks-v3.git

or

phonegap plugin add LOCAL_PATH_TO_THE_FOLDER_WITH_PLUGIN (if you are adding from local folder)   

Perform initial build for each platform:

phonegap build ios
phonegap build android
phonegap build windows

License

The Manatee Works Barcode Scanner SDK requires a license to work properly. A free 30-day evaluation license may be obtained here. Be sure to select each platformsymbology, and parser your app will support.

Ater obtaining your license key(s), there are two ways to configure them within your app:

1.The MW_LICENSE_KEY variable can be added in an xml file respectively for each platform

  • For iOS you can add a row in your *.plist file, with the following format MW_LICENSE_KEY : THE_KEY_FROM_MWDN ios-plist
  • For Android you can use the AndroidManifest.xml file and the meta-data element named MW_LICENSE_KEY and place your key as value instead of KEY_FROM_MWDN android-manifest
  • For Windows (UWP) under the WindowsComponnent project you can use the Stringsen-USResources.resw file and the element named MW_LICENSE_KEY, where you can set your license in place of YOUR_LICENSE_KEY in the value section windows_resw

2. Set the key dynamically via JavaScript, more on that below.

 

Setting up your app

Add a button to index.html that will handle the call to the scanning function:

<button onClick="mwbScanner.startScanning();" style="width:80%;margin:15%;height:180px">scan</button>

The scanner is initialized with default settings. You can change these settings with the loadSettings() method.

For PhoneGap apps, we include a MWBConfig.js and include it in our index.html. It needs to be included with a script tag:

  <script type="text/javascript" src="cordova.js"></script>
  <script type="text/javascript" src="js/index.js"></script>
  <script type="text/javascript" src="js/MWBConfig.js"></script><---add it here!! ->
  <script type="text/javascript">
      app.initialize();
  </script>

First thing we need to do is setup a valid license with:

        //multi-platform keys object
        var keys = {
            'Android'   : "VALID_ANDROID_KEY",
            'iOS'       : "VALID_IOS_KEY",
            'windows'   : "VALID_WIN_10_UWP_KEY"
        };
        //resolve the key for this platform
        var key = (keys[device.platform])?keys[device.platform]:'';

        //sets your key and loads your settings
        return mwbScanner.setKey(key).then(function(response){
            if(response)
                console.log('VALID KEY');
            else
                console.log('INVALID KEY');

            return mwbScanner.loadSettings(settings)
                        .then(function(response){
                            //console.log(response); //the response is the settings array
                        })
                        .catch(function(reason){
                            console.log(reason)
                        });
        });

where we replace the variables VALID_ANDROID_KEY, VALID_IOS_KEY, VALID_WIN_10_UWP_KEY with their respective values from the MWDN license section.

This method returns a promise that resolves to a boolean value that is true if the key was valid, and false in all other cases (invalid appname, invalid key etc).

Notice that after we set the key with setKey, we call another function that returns a promise, loadSettings, with a parmeter, settings, which is an array of activation calls. An example of this array is shown below:

    var mw_c =  mwbScanner.getConstants()
        , settings = [
            {'method': 'MWBsetActiveCodes', 'value' : [mw_c.MWB_CODE_MASK_DM | mw_c.MWB_CODE_MASK_39 | mw_c.MWB_CODE_MASK_93 | mw_c.MWB_CODE_MASK_QR | mw_c.MWB_CODE_MASK_128 | mw_c.MWB_CODE_MASK_PDF]},
            {"method" : 'MWBenableZoom', "value" : [true]},
            {"method" : 'MWBsetZoomLevels', "value" : [200, 400, 1]},
            {"method" : 'MWBsetOverlayMode', "value" : [mw_c.OverlayModeImage]},
            {"method" : 'MWBsetLevel', "value" : [3]}, //3 will try to scan harder than the default which is 2
            {"method" : 'MWBenableHiRes','value' : [true]}, //possible setting
            {"method" : 'MWBenableFlash','value' : [true]}, //possible setting
            {"method" : 'MWBuse60fps','value' : [true]}, //possible
            {"method" : "MWBsetScanningRect", "value" : [mw_c.MWB_CODE_MASK_25, 2, 2, 96, 96]},
            {"method" : "MWBsetScanningRect", "value" : [mw_c.MWB_CODE_MASK_39, 2, 2, 96, 96]},
            {"method" : "MWBsetScanningRect", "value" : [mw_c.MWB_CODE_MASK_93, 2, 2, 96, 96]},
            {"method" : "MWBsetScanningRect", "value" : [mw_c.MWB_CODE_MASK_128, 2, 2, 96, 96]},
            {"method" : "MWBsetScanningRect", "value" : [mw_c.MWB_CODE_MASK_AZTEC, 20, 2, 60, 96]},
            {"method" : "MWBsetScanningRect", "value" : [mw_c.MWB_CODE_MASK_DM, 20, 2, 60, 96]},
            {"method" : "MWBsetScanningRect", "value" : [mw_c.MWB_CODE_MASK_EANUPC, 2, 2, 96, 96]},
            {"method" : "MWBsetScanningRect", "value" : [mw_c.MWB_CODE_MASK_PDF, 2, 2, 96, 96]},
            {"method" : "MWBsetScanningRect", "value" : [mw_c.MWB_CODE_MASK_QR, 20, 2, 60, 96]},
            {"method" : "MWBsetScanningRect", "value" : [mw_c.MWB_CODE_MASK_RSS, 2, 2, 96, 96]},
            {"method" : "MWBsetScanningRect", "value" : [mw_c.MWB_CODE_MASK_CODABAR, 2, 2, 96, 96]},
            {"method" : "MWBsetScanningRect", "value" : [mw_c.MWB_CODE_MASK_DOTCODE, 30, 20, 40, 60]},
            {"method" : "MWBsetScanningRect", "value" : [mw_c.MWB_CODE_MASK_11, 2, 2, 96, 96]},
            {"method" : "MWBsetScanningRect", "value" : [mw_c.MWB_CODE_MASK_MSI, 2, 2, 96, 96]},
            {"method" : "MWBsetScanningRect", "value" : [mw_c.MWB_CODE_MASK_MAXICODE, 20, 2, 60, 96]},
            {"method" : "MWBsetScanningRect", "value" : [mw_c.MWB_CODE_MASK_POSTAL, 2, 2, 96, 96]},
            {"method" : "MWBsetMinLength", "value" : [mw_c.MWB_CODE_MASK_25, 5]},
            {"method" : "MWBsetMinLength", "value" : [mw_c.MWB_CODE_MASK_MSI, 5]},
            {"method" : "MWBsetMinLength", "value" : [mw_c.MWB_CODE_MASK_39, 5]},
            {"method" : "MWBsetMinLength", "value" : [mw_c.MWB_CODE_MASK_CODABAR, 5]},
            {"method" : "MWBsetMinLength", "value" : [mw_c.MWB_CODE_MASK_11, 5]},
            {"method" : 'MWBsetDirection', "value" : [mw_c.MWB_SCANDIRECTION_VERTICAL | mw_c.MWB_SCANDIRECTION_HORIZONTAL]}
        ];

This is an array of key/value objects used to set preferences for the scanner. The key is the name of the method and the value is the parameters (passed as an array) expected by that method.

How to scan an image

Instead of mwbScanner.startScanning() use:

mwbScanner.scanImage(URI);

or with a custom init and callback:

mwbScanner.scanImage(URI,function(result){
    //custom callback 
});

Params:

URI                     - the path to the image
callback                - custom callback function

How to scan in partial screen view

Instead of mwbScanner.startScanning() use:

mwbScanner.startScanning(x, y, width, height);

or with a custom init and callback:

mwbScanner.startScanning(function(result){
//custom callback
}, x, y, width, height);

Params:

x, y, width, height     - rectangle of the view in percentages relative to the screen size
callback  - result callback

TODO: ADD HOW TO SET PARAMS WITH SETTINGS CALLS

Example:

 Scan fullscreen  -  mwbScanner.startScanning()
 Scan in view     -  mwbScanner.startScanning(0,4,100,50)
 Pause/Resume     -  mwbScanner.togglePauseResume()
 Close            -  mwbScanner.closeScanner()
 Flash            -  mwbScanner.toggleFlash()
 Zoom             -  mwbScanner.toggleZoom()

Configuration parameters

@name "MWBsetActiveCodes"  Sets active or inactive status of decoder types     
@param[in]  activeCodes   ORed bit flags (MWB_CODE_MASK_...) of decoder types to be activated.


  @n       MWB_CODE_MASK_NONE
  @n       MWB_CODE_MASK_QR
  @n       MWB_CODE_MASK_DM
  @n       MWB_CODE_MASK_RSS
  @n       MWB_CODE_MASK_39
  @n       MWB_CODE_MASK_EANUPC
  @n       MWB_CODE_MASK_128
  @n       MWB_CODE_MASK_PDF
  @n       MWB_CODE_MASK_AZTEC
  @n       MWB_CODE_MASK_25
  @n       MWB_CODE_MASK_93
  @n       MWB_CODE_MASK_CODABAR
  @n       MWB_CODE_MASK_DOTCODE
  @n       MWB_CODE_MASK_11
  @n       MWB_CODE_MASK_MSI
  @n       MWB_CODE_MASK_MAXICODE
  @n       MWB_CODE_MASK_POSTAL
  @n       MWB_CODE_MASK_ALL   

CodeMask constants are available for all codeMask variables

@name "MWBsetActiveSubcodes"  Set active subcodes for given code group flag.  Subcodes under some decoder type are all activated by default.

@param[in]  codeMask    Single decoder type/group (MWB_CODE_MASK_...)
@param[in]  subMask     ORed bit flags of requested decoder subtypes (MWB_SUBC_MASK_)

@name "MWBsetFlags"   Sets active or inactive status of decoder types    
@param[in]   codeMask   Single decoder type (MWB_CODE_MASK_...)
@param[in]   flags      ORed bit mask of selected decoder type options (MWB_FLAG_...)

@name "MWBsetMinLength" configures minimum result length for decoder type specified in codeMask.
@param[in]   codeMask   Single decoder type (MWB_CODE_MASK_...)
@param[in]   minLength  Minimum result length for selected decoder type

@name "MWBsetDirection" 
@param[in]   direction   ORed bit mask of direction modes given with MWB_SCANDIRECTION_... bit-masks
@n     MWB_SCANDIRECTION_HORIZONTAL - horizontal lines
@n     MWB_SCANDIRECTION_VERTICAL - vertical lines
@n     MWB_SCANDIRECTION_OMNI - omnidirectional lines
@n     MWB_SCANDIRECTION_AUTODETECT - enables BarcodeScanners autodetection of barcode direction

@name "MWBsetScanningRect"
Sets the scanning rectangle
Parameters are interpreted as percentage of image dimensions, i.e. ranges are 0 - 100 for all parameters.
@param[in]   codeMask    Single decoder type selector (MWB_CODE_MASK_...)
@param[in]   left        X coordinate of left edge (percentage)
@param[in]   top         Y coordinate of top edge (percentage)
@param[in]   width       Rectangle witdh (x axis) (percentage)
@param[in]   height      Rectangle height (y axis) (percentage)

@name "MWBsetLevel"
Effort level of the scanner values can be 
@param[in]   level     1,2,3,4 and 5
example : [{"method":"setLevel" : "value" : [3]}]    

@name "MWBsetInterfaceOrientation"
Sets prefered User Interface orientation of scanner screen
@param[in]   orientation
@n     OrientationPortrait    
@n     OrientationLandscapeLeft
@n     OrientationLandscapeRight
default is OrientationPortrait

@name "MWBsetOverlayMode"
@param[in]    OverlayMode
@n  OverlayModeNone     No overlay is displayed
@n  OverlayModeMW       Use MW Dynamic Viewfinder with blinking line
@n  OverlayModeImage    Show image on top of camera preview
example : [{"method":"MWBsetOverlayMode" : "value" : [mw_c.OverlayModeImage]}]    

@name "MWBresizePartialScanner"
Resizes partial scanner dimensions. If usePartialScanner is true the scanner will open in a window with these dimensions
@param[in]   left      X coordinate of left edge (percentage)
@param[in]   top       Y coordinate of top edge (percentage)
@param[in]   width     Rectangle witdh (x axis) (percentage)
@param[in]   height    Rectangle height (y axis) (percentage)
example : [{"method":"MWBresizePartialScanner" : "value" : [0,0,50,50]}]    

@name "MWBusePartialScanner"
Boolean value that opens a partial scanner if set true
@param[in]   bool               true/false
example : [{"method":"MWBusePartialScanner" : "value" : [true]}]

@name "MWBsetActiveParser"
Set active parser types
@param[in]    ActiveParser    ORed values
@n      MWP_PARSER_MASK_NONE
@n      MWP_PARSER_MASK_AUTO
@n      MWP_PARSER_MASK_GS1
@n      MWP_PARSER_MASK_IUID
@n      MWP_PARSER_MASK_ISBT
@n      MWP_PARSER_MASK_AAMVA
@n      MWP_PARSER_MASK_HIBC
@n      MWP_PARSER_MASK_SCM    
example : [{"method":"MWBsetActiveParser" : "value" : [mw_c.MWP_PARSER_MASK_GS1 | mw_c.MWP_PARSER_MASK_IUID]}]

//additional settings:

@name "MWBsetBlinkingLineVisible"
Set blinking line visible
Default value is true
@param[in]  visible
example : [{"method" : "MWBsetBlinkingLineVisible" : "value" : [true]}]

@name "MWBsetPauseMode"
What happens when the scanner is paused
Default value is PM_PAUSE
@param[in]  pauseMode
@n  PM_NONE             - Nothing happens
@n  PM_PAUSE            - Blinking lines are replaced with a pause view
@n  PM_STOP_BLINKING    - Blinking lines stop blinking
example : [{"method" : "MWBsetPauseMode" : "value" : [mw_c.PM_STOP_BLINKING]}]

@name "MWBenableHiRes"
Enable or disable high resolution scanning. It is recommended to enable it when target barcodes
are of high density or small footprint. If device does not support high resolution param will be ignored
Default value is true (enabled)
@param[in]  enableHiRes
example : [{"method" : "MWBenableHiRes" : "value" : [true]}]

@name "MWBenableFlash"
Enable or disable flash toggle button on scanning screen. If device does not support flash mode
button will be hidden regardles of param
Default value is true (enabled)
@param[in]  enableFlash
example : [{"method" : "MWBenableFlash" : "value" : [true]}]

@name "MWBturnFlashOn"
Set default state of flash (torch) when scanner activity is started
Default value is false (disabled)
@param[in]  flashOn
example : [{"method" : "MWBturnFlashOn" : "value" : [false]}]

@name "MWBtoggleFlash"
Toggle on/off flash state
example : [{"method" : "MWBtoggleFlash" : "value" : []}]

@name "MWBenableZoom"
Enable or disable zoom button on scanning screen. If device does not support zoom,
button will be hidden regardles of param. Zoom is not supported on Windows Phone 8
as there is no zooming api available!
Default value is true (enabled)
@param[in]  enableZoom
example : [{"method" : "MWBenableZoom" : "value" : [true]}]

@name "MWBsetZoomLevels"
Set two desired zoom levels in percentage and initial level. Set first two params to zero for default
levels. On iOS, first zoom level is set to maximum non-interpolated level available on device, and
second is double of first level. On Android, default first zoom is 150% and second is 300%. Zoom is
not supported on Windows Phone 8 as there is no zooming api available! On Windows 10 UWP phone devices,
default values are half the maximum device supported zoom level for the first zoom and maxinum device
supported zoom level for the second zoom. Zoom levels are scalars, so values are expected to be in 
the [1, max] range, for example 1.0 (no zoom) and 4.0 (400% zoom).
Initial zoom level can be 0 (100% - non zoomed), 1 (zoomLevel1) or 2 (zoomLevel2). Default is 0.
@param[in]  zoomLevel1
@param[in]  zoomLevel2
@param[in]  initialZoomLevel
example : [{"method" : "MWBsetZoomLevels" : "value" : [150, 300, 0]}] //android
example : [{"method" : "MWBsetZoomLevels" : "value" : [2.0, 4.0, 0]}] //windows uwp

@name "MWBtoggleZoom"
Toggle on/off zoom state
example : [{"method" : "MWBtoggleZoom" : "value" : []}]

@name "MWBsetMaxThreads"
Set maximum threads to be used for decoding. Value will be limited to maximum available CPU cores.
Default is 4 (will trim to max available value). Set to 1 to disable multi-threaded decoding
@param[in]  maxThreads
example : [{"method" : "MWBsetMaxThreads" : "value" : [2]}]

@name "MWBcloseScannerOnDecode"
Enable/disable continuous scanning. If 'shouldClose' is 'false', result callback will be performed and
scanner will be paused. The User can call 'resumeScanning' to continue scanning, or 'closeScanner'
for closing the scanner. Default is 'true'.
Function is not available on WP8 and UWP due to the technical limitations.
@param[in]  shouldClose
example : [{"method" : "MWBcloseScannerOnDecode" : "value" : [true]}]

@name "MWBresumeScanning"
Resume scanning. Use this method if already using MWBcloseScannerOnDecode(false).
Function is not available on WP8 and UWP due to the technical limitations.
example : [{"method" : "MWBresumeScanning" : "value" : []}]

@name "MWBcloseScanner"
Close scanner. Use this method if already using MWBcloseScannerOnDecode(false).
Function is not available on WP8 due to the technical limitations.
example : [{"method" : "MWBcloseScanner" : "value" : []}]

@name "MWBuse60fps"
Use 60 fps when available.
Function is only available on iOS.
Default value is false
@param[in]  use
example : [{"method" : "MWBuse60fps" : "value" : [false]}]

@name "MWBscanImage"
Scan image.
imageURI - path to the image to be scanned.
@param[in]  imageURI
example : [{"method" : "MWBscanImage" : "value" : ['image.jpg']}]

@name "MWBsetParam"
Set custom decoder param id / value pair for decoder type specified in a codeMask.
@param[in]  codeMask                Single decoder type (MWB_CODE_MASK_...)
@param[in]  paramId                 ID of param
@param[in]  paramValue              Integer value of param
example : [{"method" : "MWBsetParam" : "value" : [codeMask, paramId, paramValue]}]

@name "MWBtogglePauseResume"
Pause/unpause scanner view
example : [{"method" : "MWBtogglePauseResume" : "value" : []}]

@name "MWBduplicateCodeDelay"
Ignore result if scanned the same code in continuous scanning mode
@param[in]  delay         Time interval between 2 scan results with the same result.code in milliseconds
example : [{"method" : "MWBduplicateCodeDelay" : "value" : [1000]}]

@name "MWBuseAutoRect"
Use auto generated full screen scanning rectangle, or use user defined scanning rectangles
@param[in]  useAutoRect   Whether or not to use auto generated full screen scanning rectangle
Default value is true
example : [{"method" : "MWBuseAutoRect" : "value" : [true]}]

@name "MWBuseFrontCamera"
Use front facing camera
@param[in]  useFrontCamera   Whether or not to use front facing camera
Default value is false
example : [{"method" : "MWBuseFrontCamera" : "value" : [false]}]

Windows (UWP) specifics

Requirements

  • Visual Studio with Universal Windows App Development Tools
  • MWBarcodeLibUniversal SDK W10 extension (You can download it from here, and then install 10.0MWBCameraDemoMWBarcodeLibUniversalSDK.vsix)

Post-build settings (required)

  • In the solution explorer, set the project CordovaApp.Windows10 (Universal Windows) as the startup project.
  • In this project’s directory, open the file package.windows10.appxmanifest and in the capabilities tab, check Webcam from the list.
  • On some devices, there might be a problem with deployment and starting the scanner that can be fixed by removing the following line from the index.html file.
<meta http-equiv="Content-Security-Policy" content="default-src * 'unsafe-inline'; style-src 'self' 'unsafe-inline'; media-src *" />

Functionalities

  • The function scanImage() requires image files to be placed in the www folder.
  • The usage of front camera is currently not available.

Performance

The camera capture and preview are implemented in JavaScript on the web side. Windows doesn't seem to support non-native implementation well, and this results in lower frame rates than hardware available. This can be improved by using a lower camera resolution (480p instead of the default 720p), which can be set with the method MWBenableHiRes and false as value. Some devices with slower processors could further improve their frame rate by reducing the number of cores the decoder uses (default is all), by using the method MWBsetMaxThreads with a value lower than all CPU cores but not lower than 1.

Examples

We've added a minimum set of files that you need to replace, to help you setup your app as soon as possible (FOR TESTING PURPOSES).

examples.zip

Also there are a few demo apps that we provide implementing the Ionic platform, which uses AngularJs as it's JS framework. 

Ionic 1 Demo App

Ionic 2 Demo App

2017-03-29
2017-04-11
https://manateeworks.com/phonegap
PhoneGap barcode scanner integration
ManateeWorks
info@manateeworks.com
Mobile apps need to be increasingly more engaging to succeed. Manatee Works can help. Our mobile barcode scanner SDK is available on all major mobile development platforms.
ManateeWorks

Barcode Scanner SDK Features and Capabilities

Developing practical applications is challenging. That’s why we've developed a straight-forward barcode scanner software development kit (SDK) that boasts the most powerful scanning experience available for integration. It offers developers a simple, flexible, dynamic decoding experience, while still allowing for maximum control and flexibility over the user experience (UX). The Manatee Works Barcode Scanner SDK was built BY developers FOR developers... with the goal of making all your applications practical.

As a tool developed with the retail, manufacturing, government, healthcare, commercial services, and transportation industries in mind, our scanning solutions are built around efficiency for the end-user, as well as simplicity for the application developer. We understand that the enterprise is continually looking for opportunities to increase efficiency. Therefore, we have developed the ultimate single-handed scanning solution aimed at maximizing every promise of a return on investment.

ManateeWorksinfo@manateeworks.com
Mobile apps need to be increasingly more engaging to succeed. Manatee Works can help. Our mobile barcode scanner SDK is available on all major mobile development platforms.
ManateeWorks