Getting Started

If you rather like to jump into some code than to walk through a Quick Start Guide, a good starting point for development with the Anyline SDK on Cordova, is to download the Cordova GitHub Repository.

The bundle includes:

example/ - A simple Cordova example project, demonstrating how the Anyline SDK Cordova-Plugin can be used
plugin/ - The plugin that you can add to your project
README - contains setup instructions

Requirements

In order to be able to use the Anyline SDK Cordova Plugin, the following requirements have to be met:

Android

Android SDK Level >= 21
An Android device with decent camera functionality (recommended: 720p and adequate auto focus)
To be able to scan you will have to handle camera permissions (this third party plugin can help you do that).

iOS

Minimum OS version: 12.0
Minimum Cordova version: v4.3.0
Disable bitcode in your project if it enabled.
Add Camera Permissions to Info.plist

Anyline 43.0.0 is a major rewrite of the scanner architecture and brings significant improvements to scanning performance and reliability. If you are coming from an older version, be aware of some breaking changes when upgrading to this version.

The most important change concerns JSON configuration. You will have to update your config files in JSON to properly initialize Anyline for Cordova. For more information, refer to the section on Full Example as well as upgrade guides.

Cordova Quick Start Guide

In this guide, we will show you how to integrate the Anyline Cordova Plugin into your existing Cordova project.

For more information about Cordova itself, how to use plugins, etc., please refer to The Apache Cordova Website.

Keep in mind, all images are saved in the app cache directory. For performance reasons, we only provide the path as string, so we don’t have to transfer the whole image through the bridge. Please be aware, that you should not use images in the cache directory for persistent storage, but store images in a location of your choice for persistence.

Add the Anyline SDK Plugin to your Project

You can add Anyline SDK Plugin to your project by either installing it locally from anylinesdk-plugin/ folder found at Cordova GitHub Repository:

cordova plugin add PATH_TO_DIR/anylinesdk-plugin/

, or by adding the package from the npm repository:

cordova plugin add io-anyline-cordova

If you are cloning this repository you will have to install git-lfs. Use the following commands to install git-lfs.

brew install git-lfs
git lfs install

If you prefer downloading a package, use the provided zip package on releases page. Be aware that Github download zip button does not work for projects with git-lfs.

Generate an Anyline License

In order to run the Anyline SDK in your app, you require a License Key. The Guide on How To Generate a License can be found at Anyline License Key Generation.

This section focuses on how to integrate a license on Cordova.

How to identify the Application ID

The bundle identifier for your Cordova app can be found within config.xml as an attribute id under the widget tag.

<widget id="io.anyline.examples.cordova" version="3.8.1" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0">

Create your Javascript file

You can now start to create your Javascript files. Or you can build your Cordova application based on the examples provided in the Cordova Github repository. The examples are located under examples/www/js.

All of our Javascript files contains code to start a scan session calling the AnylineSDK.scan and handle both callbacks onSuccess and onError.

The following setup is just a recommendation. You can, of course, implement the Anyline plugin as you prefer.

Interfacing with the Anyline Plugin

The Anyline Cordova Plugin is like any other Cordova Plugin and can be interacted with through the Javascript interface via the exec method.

For further details please visit the Cordova Plugin Development Guide.

Initialise the SDK

To be able to scan with Anyline, you need to first have initialised the SDK with the license key.

Until this has completed successfully, attempts to use the scan method will fail. Ensure that you have appropriate handlers for the error callbacks to these function calls.

The first two parameters are success and error callbacks, giving you the information that you need to continue after the SDK is initialised.

The success callback will return either a boolean: a true or false depending on whether the SDK was successfully initialised or not. The error callback will return an error message in case something unforeseen happened during initialisation.

With the third and fourth parameter you tell the Cordova Javascript interface which plugin and method to call, in this case our Anyline Plugin referenced as AnylineSDK and the method initSdk.

cordova.exec(
    function (initWasSuccessful) {
        // handle success or failure of initialisation
    },
    function (errorMessage) {
        // handle error case
    },
    "AnylineSDK",
    "initAnylineSDK",
    ["Your license key"]
);

Create an Anyline object

You can create an object, holding all your callbacks and configuration files.

All the following functions and fields can be simply added to your object.

if (anyline === undefined) {
  var anyline = {};
}
anyline.barcode = {
    ...
    scan: function (type) {
        ...
        var options = this.barcodeConfig;
        ...
        cordova.exec(this.onResult, this.onError, "AnylineSDK", "scan", [options]);
    }
}

cordova.exec takes the following parameters:

onResult: a function called when scanning succeeds; the scan result object is passed to the function as a parameter
onError: a function called scanning ends with an error or when the session is canceled; the error message is passed to the function as a parameter
AnylineSDK: to indicate that the method call is directed to anylinesdk-plugin
scan: calls the scan method
config: a Javascript object containing the Anyline view configuration

Add the callback functions

The Anyline SDK Cordova Plugin provides requires two callback functions: onResult and onError.

onResult(result)

This function is called once the scan was successfully performed.

The returned result object is a JSON object containing all the scanned values.

onResult: function (result) {
  var barcodeResult = result.barcodeResult.value; // "00283.11"
}

More information about the result type can be found here.

onError(error)

This function is called if an error occurred or the user canceled the scanning.

The returned error object is a String, providing the error message.

onError: function (error) {
  // called if an error occurred or the user canceled the scanning
  if (error == "Canceled") {
    // user has canceled the operation
    console.log("Scanning was canceled");
    return;
  }
  alert(error);
}

Add the View

The View Configuration defines the look & feel of your scanning application. More information can be found here: Anyline View Configuration.

barcodeConfig: {
    "viewPluginConfig": {
      "pluginConfig": {
        "id": "barcode",
        "barcodeConfig": {
          "parseAAMVA": false,
          "barcodeFormats": [
            "ALL"
          ]
        },
        "cancelOnResult": true,
        "startScanDelay": 1500
      },
      "cutoutConfig": {
        "animation": "none",
        "maxWidthPercent": "70%",
        "maxHeightPercent": "70%",
        "alignment": "center",
        "ratioFromSize": {
          "width": 3,
          "height": 2
        },
        "offset": {
          "x": 0,
          "y": 0
        },
        "cropOffset": {
          "x": 0,
          "y": 0
        },
        "cropPadding": {
          "x": 0,
          "y": 0
        },
        "cornerRadius": 4,
        "strokeColor": "0099ff",
        "strokeWidth": 2,
        "outerColor": "000000",
        "feedbackStrokeColor": "0099FF",
        "outerAlpha": 0.3
      },
      "scanFeedbackConfig": {
        "style": "none",
        "strokeWidth": 0,
        "strokeColor": "0099FF",
        "fillColor": "330099FF",
        "beepOnResult": false,
        "vibrateOnResult": false,
        "blinkAnimationOnResult": false
      }
    },
    "options": {}
  }

iOS Done Button Configuration

On iOS, it is possible to configure the appearance of the Done button by providing additional parameters:

"options": {
  "doneButtonConfig": {
    "title": "OK",
    "type": "rect",
    "cornerRadius": 0,
    "textColor": "FFFFFF",
    "textColorHighlighted": "CCCCCC",
    "fontSize": 33,
    "fontName": "HelveticaNeue",
    "positionXAlignment": "center",
    "positionYAlignment": "bottom",
    "offset": {
      "x": 0,
      "y": -88
    }
  }
}

For more information on how to configure the Done button, refer to Advanced Topics

Full Example

/*
 * Anyline Cordova Plugin
 * anyline.barcode.js
 *
 * Copyright (c) 2023 Anyline GmbH
 */

if (anyline === undefined) {
  var anyline = {};
}
anyline.barcode = {
  onResult: function (result) {
    changeLoadingState(false);
    // this is called with result of the barcode module
    // the result is a string containing the barcode
    var resultStr = "";
    if (result.barcodeResult) {
      resultStr = result.barcodeResult.value;
    }
    insertScanResult(result, resultStr);
  },

  onError: function (error) {
    changeLoadingState(false);
    // called if an error occurred or the user canceled the scanning
    if (error == "Canceled") {
      // when user has canceled
      // this can be used as an indicator that the user finished the scanning if canclelOnResult is false
      console.log("Barcode scanning canceled");
      return;
    }
    alert(error);
  },

  scan: function (type) {
    // start the barcode scanning
    // pass the success and error callbacks, as well as the license key and the config to the plugin
    // see http://documentation.anyline.io/#anyline-config for config details
    // and http://documentation.anyline.io/#barcode for barcode module details

    if (localStorage.getItem("hasStartedAnyline") === 'true') {
      return;
    }
    changeLoadingState(true);

    var options = this.barcodeConfig;

    cordova.exec(this.onResult, this.onError, "AnylineSDK", "scan", [options]);
  },

  barcodeConfig: {
    "viewPluginConfig": {
      "pluginConfig": {
        "id": "barcode",
        "barcodeConfig": {
          "parseAAMVA": false,
          "barcodeFormats": [
            "ALL"
          ]
        },
        "cancelOnResult": true,
        "startScanDelay": 1500
      },
      "cutoutConfig": {
        "animation": "none",
        "maxWidthPercent": "70%",
        "maxHeightPercent": "70%",
        "alignment": "center",
        "ratioFromSize": {
          "width": 3,
          "height": 2
        },
        "offset": {
          "x": 0,
          "y": 0
        },
        "cropOffset": {
          "x": 0,
          "y": 0
        },
        "cropPadding": {
          "x": 0,
          "y": 0
        },
        "cornerRadius": 4,
        "strokeColor": "0099ff",
        "strokeWidth": 2,
        "outerColor": "000000",
        "feedbackStrokeColor": "0099FF",
        "outerAlpha": 0.3
      },
      "scanFeedbackConfig": {
        "style": "none",
        "strokeWidth": 0,
        "strokeColor": "0099FF",
        "fillColor": "330099FF",
        "beepOnResult": false,
        "vibrateOnResult": false,
        "blinkAnimationOnResult": false
      }
    },
    "options": {
      "doneButtonConfig": {
        "title": "OK",
        "type": "rect",
        "cornerRadius": 0,
        "textColor": "FFFFFF",
        "textColorHighlighted": "CCCCCC",
        "fontSize": 33,
        "fontName": "HelveticaNeue",
        "positionXAlignment": "center",
        "positionYAlignment": "bottom",
        "offset": {
          "x": 0,
          "y": -88
        }
      }
    }
  },

  barcodePDF417Config: {
    "viewPluginConfig": {
      "pluginConfig": {
        "id": "barcode_pdf417_aamva",
        "barcodeConfig": {
          "barcodeFormats": [
            "PDF_417"
          ],
          "parseAAMVA": true
        },
        "cancelOnResult": true
      },
      "cutoutConfig": {
        "animation": "none",
        "maxWidthPercent": "75%",
        "maxHeightPercent": "50%",
        "width": 0,
        "alignment": "center",
        "ratioFromSize": {
          "width": 4,
          "height": 1
        },
        "offset": {
          "x": 0,
          "y": 0
        },
        "cropOffset": {
          "x": 0,
          "y": 0
        },
        "cropPadding": {
          "x": 0,
          "y": 0
        },
        "cornerRadius": 4,
        "strokeColor": "0099ff",
        "strokeWidth": 2,
        "outerColor": "000000",
        "feedbackStrokeColor": "0099FF",
        "outerAlpha": 0.3
      },
      "scanFeedbackConfig": {
        "style": "animated_rect",
        "strokeWidth": 2,
        "strokeColor": "000000",
        "fillColor": "330099FF",
        "beepOnResult": false,
        "vibrateOnResult": false,
        "blinkAnimationOnResult": false
      }
    },
    "options": {
      "doneButtonConfig": {
        "title": "OK",
        "type": "rect",
        "cornerRadius": 0,
        "textColor": "FFFFFF",
        "textColorHighlighted": "CCCCCC",
        "fontSize": 33,
        "fontName": "HelveticaNeue",
        "positionXAlignment": "center",
        "positionYAlignment": "bottom",
        "offset": {
          "x": 0,
          "y": -88
        }
      }
    }
  }
};