Manatee Works Barcode Scanner SDK for Ionic

Manatee Works Barcode Scanner SDK for Ionic

Manatee Works Barcode Scanner SDK Plugin for Ionic


Manatee Works

Manatee Works

Member since 2016


iOS, Android  
4 years ago
4 years ago

Delivering simple, industrial-strength, enterprise-grade barcode scanning for today's most advanced mobile devices.

PhoneGap implementation (see below for ionic and ionic2)

Guide on how to add the Manatee Works Barcode Scanner SDK PhoneGap plugin to your project(s)

For more info, visit our website at

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

    First make sure you have the latest software required to run phoneGap apps. This means nodejs and git should be on your system. For more info about that, visit:

  2. Install PhoneGap:

    sudo npm install -g [email protected]

  3. Create your app by using CLI interface:

    ``` phonegap create my-mw-app

    //or use bundle identifiers, we bind our license with the bundle identifier!

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

  4. Previous step will create a folder named my-mw-app, navigate to your newly created folder and add the platforms you want to build with:

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

  5. Add our plugin to the project with:

    phonegap plugin add manateeworks-barcodescanner-v3 --variable MW_LICENSE_KEY=YOUR_LICENSE_KEY


    phonegap plugin add --variable MW_LICENSE_KEY=YOUR_LICENSE_KEY


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

MW_LICENSE_KEY variable is required but it can be left empty and added later in your .plist file or android manifest file. We also provide setting the key via a javaScript call.

  1. Perform initial build for each platform.

    phonegap build ios phonegap build android phonegap build wp8

Setting up your app

  1. Add a button to index.html which will handle the call to the scanning function

    html <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.

  2. For phoneGap apps we include a MWBConfig.js where this can be handled. It needs to be included with a script tag in the index.html file.


<---add it here!!


Here you can do a few things:

  • If you skipped adding your license key when installing (and on windows platform), you can set your key with setKey()

    ```html return mwbScanner.setKey('input-your-key-here').then(function(response){

esponse of the setKey action });

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

  • Configure your scanner with the desired settings - you should use loadSettings().
    Expects an array of key/value objects used to set preferences for the scanner, where the key is the name of the method used and the value is the parameters expected by that method.

    html var cc = mwbScanner.getConstants(),settings; settings = [ {'method': 'MWBsetActiveCodes', 'value' : [cc.MWB_CODE_MASK_25 | cc.MWB_CODE_MASK_39 | cc.MWB_CODE_MASK_93 | cc.MWB_CODE_MASK_128 | cc.MWB_CODE_MASK_AZTEC | cc.MWB_CODE_MASK_DM | cc.MWB_CODE_MASK_EANUPC | cc.MWB_CODE_MASK_PDF | cc.MWB_CODE_MASK_QR | cc.MWB_CODE_MASK_CODABAR | cc.MWB_CODE_MASK_11 | cc.MWB_CODE_MASK_MSI | cc.MWB_CODE_MASK_RSS | cc.MWB_CODE_MASK_MAXICODE | cc.MWB_CODE_MASK_POSTAL] } ]; //load your settings with return mwbScanner.loadSettings(settings).catch(function(reason){console.log(reason)}); ```

How to build online with

  • Copy confing.xml from project’s dir to /www
  • Add this line in www/confing.xml:

    <gap:plugin name="manateeworks-barcodescanner-v3" source="npm"/>

  • Add this code in www/index.html:


``` - Compress /www folder - Upload to - Build

How to scan an image

  • Instead of mwbScanner.startScanning() use:


``` or with custom init and callback:

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


  • 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 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


  • Example:

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

Configuration parameters

``` @name "setActiveCodes" Sets active or inactive status of decoder types

CodeMask constants are available for all codeMask variables

@name "setActiveSubcodes" 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 (MWBCODEMASK...) @param[in] subMask ORed bit flags of requested decoder subtypes (MWBSUBCMASK)

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

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

@name "setDirection" @param[in] direction ORed bit mask of direction modes given with MWBSCANDIRECTION... bit-masks @n MWBSCANDIRECTIONHORIZONTAL - horizontal lines @n MWBSCANDIRECTIONVERTICAL - vertical lines @n MWBSCANDIRECTIONOMNI - omnidirectional lines @n MWBSCANDIRECTIONAUTODETECT - enables BarcodeScanner's autodetection of barcode direction

@name "setScanningRect" 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 (MWBCODEMASK_...) @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 "setLevel" Effort level of the scanner values can be @param[in] level 1,2,3,4 and 5 example : [{"method":"setLevel" : "value" : [3]}]

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

@name "setOverlayMode" @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":"setOverlayMode" : "value" : [cc.OverlayModeImage]}]

@name "resizePartialScanner" 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":"resizePartialScanner" : "value" : [0,0,50,50]}]

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

example : [{"method":"setActiveParser" : "value" : [cc.MWPPARSERMASKGS1 | cc.MWPPARSERMASKIUID]}] ```

IONIC 1 Implementation

Manateeworks barcode scanner can be loaded as an ionic plugin, which uses cordova, so every phonegap plugin could run as an ionic plugin with little to none change. Most of the changes are in the configuration files, due to how the projects are organized in ionic (or even ionic2)

Just like phonegap,

  1. First we ensure we have nodejs installed and latest ionic and cordova see ( for more:

    npm install -g cordova ionic //depending on your OS, this could very well be: sudo npm install -g cordova ionic

    if it's already installed, updating is done with:

    npm update -g cordova ionic //or sudo npm update -g cordova ionic

  2. Then we create an ionic app (similar to the phonegap process, where we created an app, here we start one). Currently ionic is using v2, and ionic v1 may be completely retired, but for the purpose of clarity we provide these steps to getting an ionic v1 app running.

    ionic start -a "Manateeworks Barcode Scanner Ionic App" mwbScanner blank -i com.ionic.manateeworks --v1 cd mwbScanner ionic plugin add manateeworks-barcodescanner-v3 --variable MW_LICENSE_KEY=YOUR_LICENSE_KEY

    ionic plugin add --variable MW_LICENSE_KEY=YOUR_LICENSE_KEY

    ionic plugin add LOCAL_PATH_TO_THE_FOLDER_WITH_PLUGIN --variable MW_LICENSE_KEY=YOUR_LICENSE_KEY (if you are adding from local folder)

  3. In the platforms www folder (for example if you are developing for ios)


    there are example files named exactly like the files you need to change to get the app started.

*app.js* should be replaced with the one in *js/app.js* and *index.html* should be replaced with the *index.html* of your app, to get you started.

Ionic 2

Step 1 is the same as ionic, so:

ionic start myMwApp blank --v2 cd myMwApp ionic plugin add manateeworks-barcodescanner-v3

which will create an ionic 2 blank app. This will create a slightly different project structure than phonegap and ionic 1.

App development in ionic2 is a little different, due to the fact that angularJS2 is used, so project structure is quite different than regular phonegap, or ionic1 (which uses angularJS).

If you are building for ionic 2 this is not news to you so we will presume that you are familiarized with the structure of your app. We will modify the files in the /src folder, if you followed the instructions you should have

/src/pages/home folder

We want to modify the home.html file, and add a button and a text input (which will show the result) and the home.ts file which will handle that control of the scanner. These files have been copied in the examples folder that we provide with the plugin. Copy the files to your /src/pages/home folder.

Important thing to notice is the addition of the

declare var mwbScanner:any;

this is done, to stop ionic2 from complaining about scanner missing. The scanner variable becomes available after the cordova plugins load, so in order to "import" it to our component controller, we define it as a variable that can receive any value.

Since manateeworks-barcodescanner plugin is essentially a phonegap plugin, naturally we use a callback to show results. But we also return a promise, which is more an ionic2 way. To disable the default callback we do:


Then to show results from a scan we simply do

mwbScanner.startScanning().then(function(response){ console.log('show the result here'); console.log(response); //actual example in home.ts is different });

Build for your platform

ionic build ios

And run your app.