Scanbot SDK Cordova Plugin

⚠️ This documentation is for the version 1.x of the Scanbot SDK Cordova Plugin (cordova-plugin-scanbot-sdk@1.x)! Click here for the latest released version 2.x

Introduction

The Scanbot SDK brings scanning and document creation capabilities to your mobile apps. It contains modules which are individually licensable as license packages. For more details visit our website https://scanbot.io/sdk.html

This Cordova plugin provides implementations of Scanbot SDK for iOS and Android.

Following Package I + II functionality is covered by this plugin:

Package I

  • Camera UI with user guidance for document scanning
  • Cropping UI
  • Document Detection
  • Image Filters
  • PDF Creation
  • Barcode and QR Code Scanning

Package II

  • OCR

Requirements

Tools

  • Node.js, npm
  • Cordova CLI or PhoneGap CLI, both 6.x+ (recommended 7.x+)
  • Cordova Platforms:
  • Android SDK (API Level 16+), Platforms and Developer Tools (for Android Apps)
  • Xcode + Xcode Command Line Tools (for iOS Apps)

Cordova vs. PhoneGap

Since Adobe PhoneGap is based on Apache Cordova the Scanbot SDK Cordova Plugin is fully compatible with PhoneGap. So you can also use all features of this Plugin in your PhoneGap app.

Supported Mobile Platforms

  • Android 4.1 (API Level 16) and higher
  • iOS 8 and higher

Please note:

  • The Scanbot SDK Plugin is available only for Android and iOS
  • We don’t support rooted Android devices (custom ROMs)
  • This Plugin does not work on other platforms like Windows Phone, Desktop or Web Apps
  • Also, the Plugin does not work in a Progressive Web App (PWA)

Hardware

  • Smartphones and Tablets with a rear-facing camera with autofocus

Simulators / Emulators

While it is possible to test your App with the Scanbot SDK Plugin on simulators/emulators, we strongly recommend to use real Android/iOS devices. Depending on the emulated Camera you may not be able to test/evaluate the full functionality of the Scanbot SDK Plugin.

Serve Mode

It is not possible to test or preview the features of the Scanbot SDK Cordova Plugin within the PhoneGap Developer App.

It is also not possible to test or preview the Scanbot SDK Cordova Plugin in a desktop browser.

Or in other words, the Cordova serve mode cordova serve as well as the PhoneGap serve mode phonegap serve will not work! You have to build your app and deploy it on the target mobile device.

Example Apps

Check out our Example Apps on GitHub:

Installation

The Scanbot SDK plugin is available as npm package.

You can simply install and add it to your App by following command:

cordova plugin add cordova-plugin-scanbot-sdk

Xcode project settings for iOS

When adding a plugin to your App, Cordova automatically applies corresponding settings in the Xcode project. Unfortunately the old versions of Cordova iOS Platform cordova-ios < 4.4.0 do not support auto configuration for “Embedded Binaries” in the Xcode project file which is required by the Scanbot SDK plugin.

👍 If you are using cordova-ios@4.4.0 or higher in your project, everything should be fine after the plugin installation.

⚠️ If you are using an older version of cordova-ios, you have to apply following manual settings after the plugin installation:

  • Open the generated Xcode project file with Xcode IDE:

    <YOUR_APP_PROJECT_PATH>/platforms/ios/<YOUR_APP_NAME>.xcodeproj

  • Go to “TARGETS” settings and find the section “Embedded Binaries”. Then add the ScanbotSDK.framework to “Embedded Binaries”. The ScanbotSDK.framework is provided with the Scanbot SDK plugin. The following picture shows correct settings of ScanbotSDK.framework:

alt text

Please note and double-check: Older versions of cordova-ios will put the ScanbotSDK.framework into “Linked Frameworks and Libraries” which is wrong and will not work for the Scabot SDK plugin! The project will compile but your App will crash right after the start!

Tuning the Android Manifest

Since your application works with images it is highly recommended to add the attribute android:largeHeap="true" in the <application> element of your platforms/android/AndroidManifest.xml file. Processing images is a memory intensive task and this property will ensure your app has enough heap allocated to avoid OutOfMemoryError exceptions.

<application
  android:largeHeap="true"
  ...
</application>

Please note: Due to a potential Cordova issue (CB-13474) with the <edit-config> tag we had to remove the automatic adding of the android:largeHeap="true" attribute from the Scanbot SDK Cordova Plugin. So please add it manually.

Permissions

During the installation the plugin automatically adds all required permissions to your App. Here is a listing of those permissions just for your information:

Android (will be added in your AndroidManifest.xml file)

  • <uses-permission android:name="android.permission.CAMERA" /> - This permission is used for the camera views.
  • <uses-feature android:name="android.hardware.camera" /> - Camera hardware features.
  • <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> - Required to handle temporary files (e.g. PDF creation).
  • <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" /> - Required to handle temporary files (e.g. PDF creation).

iOS (will be added in your Info.plist file)

  • NSCameraUsageDescription - “Privacy - Camera Usage Description”. As value describe why your app wants to access the device’s camera.

Building iOS Production Apps / Submitting to the App Store/TestFlight

The Scanbot iOS Framework (which is included in this Cordova Plugin) contains the most used architectures (arm64, armv7, armv7s, x86_64, i386). So you can test it with all most used Devices and Simulators. But you have to remove the architectures x86_64 and i386 from the Scanbot SDK Framework before submitting your App to the App Store or TestFlight. Those architectures are for emulators and are not allowed to submit.

We provide a script for that: strip-SBSDK-Framework.sh. It can be found inside the ScanbotSDK.framework:

plugins/cordova-plugin-scanbot-sdk/src/ios/Frameworks/ScanbotSDK.framework/strip-SBSDK-Framework.sh).

This script removes the unnecessary architectures from the frameworks binary, code signs the framework and adds the crash symbols (dSYM) file to your apps archive. (And by the way: the final app size will then be significantly smaller than a debug version used during the development phase)

You will need to open the generated Xcode project and apply a few changes there. Please see the section “2.1. Step-by-step guide” in our iOS docs on how to setup this script, namely steps 7 and 8. The Xcode project is found under platforms/ios/ - look for the .xcodeproj extension. In step 8 you need to provide the path to the dSYM file. The proper path to it for Cordova projects is $(SRCROOT)/../../plugins/cordova-plugin-scanbot-sdk/src/ios/Frameworks/ScanbotSDK.framework.dSYM

Modules

  • ScanbotSdk - This module provides the Scanbot SDK functionality for image operations (e.g. filter, PDF creation, etc.)

  • ScanbotSdkUi - Provides the UI functionality like Camera UI, Cropping UI and Barcode Scanning UI.

API Reference

Getting started

Initialize SDK

ScanbotSdk.initializeSdk(successCallback, errorCallback, options)

The Scanbot SDK must be initialized before usage. Make sure to run the initialization only once per app lifetime. Call the initialization after the ‘deviceready’ event has been fired.

Callbacks:
successCallback : function(result)
  • result - Contains a simple success message as string.
errorCallback : function(error)
  • error - Contains the error message as string.

Example code for initialization:

document.addEventListener('deviceready', onDeviceReady, false);

function onDeviceReady() {
  // ...
  initScanbotSdk();
  // ...
}

function initScanbotSdk() {
  var options = {
    loggingEnabled: true,
    licenseKey: '' // optional license key (empty for trial mode)
  };
  ScanbotSdk.initializeSdk(function(result) {
    // Scanbot SDK successfully initialized
    console.log(result);
  }, function(error) {
    // Error initializing the Scanbot SDK
    console.log('Unable to initialize the Scanbot SDK: ' + error);
  }, options);
}

License Key

You can test all Scanbot SDK plugin features and develop your apps without a license. However, if you do not specify the license key when initializing the SDK, it will work in trial mode (trial period of 1 minute). To get another trial period you have to restart your app.

If this is not enough for you, contact us at sdk@scanbot.io and we’ll give you a free no strings attached trial license for a longer period. In order to run the Scanbot SDK plugin functionality within your production app you have to purchase and use a valid Scanbot SDK license.

Each license key is valid only to your apps bundle identifier. The license also defines which modules you are allowed to use. The usage of unlicensed modules will log an error to the console and terminate the app. If your license has expired any calls of the Scanbot SDK plugin will terminate your app.

Example code for defining and using the license key:

// Please note: this is just an example license key string (it's not a valid license)
var myLicenseKey =
  "fXbN2PmyqEAZ+btdkSIS36TuX2j/EE5qxVNcZMXYErbLQ" +
  "3OBnE10aOQxYI8L4UKwHiZ63jthvoFwUevttctBk0wVJ7Z" +
  "+Psz3/Ry8w7pXvfpB1o+JrnzGGcfwBnRi/5raQ2THDeokR" +
  "RB1keky2VBOFYbCfYt3Hqms5txF2z70PE/SBTMTIVuxL7q" +
  "1xcHDHclbEBriDtrHw8Pmhh9FqTg/r/4kRN/oEX37QGp+Y" +
  "3ogwIBbSmV+Cv+VuwtI31uXY3/GkyN/pSJZspIl+exwQDv" +
  "O0O1/R/oAURpfM4ydaWReRJtjW8+b1r9rUgPERguaXfcse" +
  "HlnclItgDfBHzUUFJJU/g==\nU2NhbmJvdFNESwppby5zY" +
  "2FuYm90LmRlbW8ueGFtYXJpbgoxNDg0NjExMTk5CjcxNjc" +
  "KMw==\n";
  
var options = {
  licenseKey: myLicenseKey,
  // ...
};

ScanbotSdk.initializeSdk(successCallback, errorCallback, options);

Purchase a License

You can check and purchase the Scanbot SDK licenses here: https://scanbot.io/sdk.html.

To request a trial license for a longer period or purchase a production license you have to provide us the bundle identifier of your app. Please find this identifier in the config.xml file of your app project: <widget id="my.awesome.app.id" ...>

Trial Licenses

You can get a free no strings attached trial license. Please kindly note that this license can only be used in a development and staging environment. You are not allowed to publish your app to the App Store, Play Store or any 3rd party Android App Store with a trial license.

Logging

When initializing the Scanbot SDK you can enable logging of the SDK. By default logging is disabled.

var options = {
  loggingEnabled: true,
  // ...
};

ScanbotSdk.initializeSdk(successCallback, errorCallback, options);

On Android logs are printed into LogCat as well as saved on the device. You can find them in Environment.getExternalStorageDirectory()/debug_logs/[package_name]. Usually it is /sdcard/debug_logs/[package_name]. The easiest way to check the log outputs on Android is to use the Android Debug Bridge (adb). (e.g. $ adb -s <DEVICE_ID> shell "logcat")

On iOS all logs are printed to the console. Please use Xcode to check the log outputs. There will be no log files created by the Scanbot SDK plugin.

Please note: While it may be useful for development, consider switching logging OFF in production builds for security and performance reasons!

Updating the license in production apps

To renew an expired license or extend a valid license with new Scanbot SDK features, you will have to update your app in the App Store or Play Store. The expiration date and the feature list of a license are an encrypted data part of the license key string. Which means a renewal or extension of a license will cause a new license key string to be generated.

License check in production apps

If your Scanbot SDK license has expired, any call of the Scanbot SDK API will terminate your app or result in an error. To prevent this you should always check for license expiration during the runtime by calling the method ScanbotSdk.isLicenseValid(successCallback, errorCallback). If the result of the successCallback returns false, you should disable any usage of the Scanbot SDK functions or UI components in your app.

We highly recommend to implement a suitable handling of this case in your app!

ScanbotSdk.isLicenseValid(successCallback, errorCallback)

Use this function to check the current state of the license. The SDK must be initialized.

Callbacks:
successCallback : function(result)
  • result.isLicenseValid - Contains a boolean status value of the license. true means the Scanbot SDK license is valid and all features can be used normally. false means the license is not valid and any call of the Scanbot SDK API will terminate your app or result in an error.
errorCallback : function(error)
  • error - Contains the error message as string.
Example code for checking the license status:
ScanbotSdk.isLicenseValid(function(result) {
    if (result.isLicenseValid) {
      // Making your calls of the Scanbot SDK Plugin API is safe now.
      ScanbotSdkUi.startCamera(...);
    }
    else {
      // Implement a suitable handling (e.g. disable Scanbot functionality in your App)
      alert("Scanbot SDK license has expired!");
    }
}, handleErrorCallback);

Camera UI for document scanning

ScanbotSdkUi.startCamera(successCallback, errorCallback, options)

The Scanbot SDK plugin provides a ready-to-use Camera UI component for guided, automatic document scanning.

The Camera UI contains:

  • A live preview of the camera with detected polygon
  • User guidance (hints)
  • An animated shutter button, which can be used to take a picture manually
  • Toggle button for flash
  • Toggle button for auto-snapping
  • Cancel button

Use this function to start the Camera UI.

Callbacks:
successCallback : function(result)
  • result.imageFileUri - Contains a File URI of the detected document image as JPEG ('file:///...'). The document image is cropped and warped (perspective corrected) by detected polygon.
  • result.originalImageFileUri - File URI of the original full image from the camera as JPEG. Can be used for manual cropping correction via Cropping UI if the detected document image was not satisfactory.
  • result.polygon - Contains the detected polygon as array. Maybe empty if detection was not successful.
  • result.detectionResult - The Detection Result.
errorCallback : function(error)
  • error - Contains the error message as string.
Options:
var options = {
  textResBundle: {
    autosnapping_hint_do_not_move: "Don't move",
    autosnapping_hint_move_closer: "Move closer",
    autosnapping_hint_bad_angles: "Perspective",
    autosnapping_hint_bad_aspect_ratio: "Wrong aspect ratio.\n Rotate your device",
    autosnapping_hint_nothing_detected: "No document",
    autosnapping_hint_too_noisy: "Background too noisy",
    autosnapping_hint_too_dark: "Poor light"
  },
  edgeColor: '#0000ff',
  quality: 80,
  autoSnappingEnabled: true,
  autoSnappingSensitivity: 0.6,
  sampleSize: 1
};
  • options.textResBundle - Optional text resources map to localize or override user guidance hints. If no textResBundle map is provided english textes will be used as default. The example code above shows all supported text resources keys.
  • options.edgeColor - Optional color for rendered polygon edges. Hexadecimal format #RRGGBB or #AARRGGBB.
  • options.quality - Optional quality value of the output image.
  • options.autoSnappingEnabled - Optional boolean flag to set the initial value of the auto-snapping functionality. Default value is true which activates the auto-snapping. Auto-snapping can be enabled or disabled by the user via toggle button in the UI.
  • options.autoSnappingSensitivity - Optional float value to change the sensitivity factor of auto-snapping. Must be in the range 0.0…1.0. A value of 1.0 triggers automatic capturing immediately, a value of 0.0 delays the automatic by 3 seconds. The default value is 0.66 (1 sec).
  • options.sampleSize - Optional integer value to force the image decoder to subsample output images (create smaller images to save memory). For example sampleSize: 2 will return images that are 1/2 the width/height of the original. Default value is 1, which keeps the original image size. Any value < 1 is treated the same as 1.

Close Camera UI

ScanbotSdkUi.dismissCamera()

Closes the Camera UI screen if it is running. No parameters are required. The function provides no callbacks.

Cropping UI

ScanbotSdkUi.startCropping(successCallback, errorCallback, options)

The Cropping UI provides functionality for manual cropping and rotation of an image. It uses the edge detection algorithm of the Scanbot SDK and containts some smart UI elements like magnetic lines and magnifier. As input a file URI of an image must be passed. The output is a cropped and perspective corrected image as a new file. The input image file will not be modified.

Callbacks:
successCallback : function(result)
  • result.imageFileUri - File URI of the cropped image as JPEG ('file:///...').
  • result.polygon - Contains the selected polygon as array.
errorCallback : function(error)
  • error - Contains the error message as string.
Options:
var options = {
  imageFileUri: 'file:///...',
  edgeColor: '#0000ff',
  quality: 80
};
  • options.imageFileUri - Input image file URI.
  • options.edgeColor - Optional color for rendered polygon edges. Hexadecimal format #RRGGBB or #AARRGGBB.
  • options.quality - Optional quality of the output image.

Barcode and QR Code Scanning UI

ScanbotSdkUi.startBarcodeScanner(successCallback, errorCallback, options)

Opens a Scanning UI for barcodes and QR codes.

Callbacks:
successCallback : function(result)
  • result.barcodeFormat - Format of detected barcode/QR code (e.g. “CODE_128”, “EAN_13”, “QR_CODE”, etc).
  • result.textValue - Text value of detected barcode/QR code.
errorCallback : function(error)
  • error - Contains the error message as string.
Options:
var options = {
  flashEnabled: false,
  playTone: true,
  vibrate: true,
  barcodeFormats: [ScanbotSdk.BarcodeFormat.EAN_8, ScanbotSdk.BarcodeFormat.EAN_13, ScanbotSdk.BarcodeFormat.CODE_128]
};
  • options.flashEnabled - Optional flag to set the initial value of flash (torch light). By default the flash light is disabled.
  • options.playTone - Optional flag to enable or disable the beep tone on detection. By default the beep tone is enabled.
  • options.vibrate - Optional flag to enable or disable a short vibration on detection. By default the vibration is enabled. Please note that on some devices the vibration behavior can be forced by system settings.
  • options.barcodeFormats - Optional array of barcode formats to define as detection filter. By default all supported formats will be detected.

Close Barcode Scanning UI

ScanbotSdkUi.dismissBarcodeScanner()

Closes the Barcode Scanning UI screen if it is running. No parameters are required. The function provides no callbacks.

Document Detection

ScanbotSdk.documentDetection(successCallback, errorCallback, options)

The Scanbot SDK uses digital image processing algorithms to find rectangular, document like, polygons in a digital image. This function applies edge dectection and processes all image operations in a background thread. There will be no UI started. As input a file URI of an image must be passed. The output contains the Detection Result as enum and on success the cropped and perspective corrected image as a new file as well as the detected polygon. If there was no document detected the result enum provides the exact reason (noisy background, too dark, etc). The input image file will not be modified.

Callbacks:
successCallback : function(result)
  • result.imageFileUri - File URI of the detected and cropped/warped document image as JPEG ('file:///...'). Maybe null if detection was not successfull.
  • result.polygon - Contains the detected polygon as array. Maybe empty if detection was not successful.
  • result.detectionResult - The Detection Result.
errorCallback : function(error)
  • error - Contains the error message as string.
Options:
var options = {
  imageFileUri: 'file:///...',
  quality: 80
};
  • options.imageFileUri - Input image file URI.
  • options.quality - Optional quality of the output image.

Rotate Image

ScanbotSdk.rotateImage(successCallback, errorCallback, options)

Rotates an image by given degrees value. As input a file URI of the image must be passed. The output image will be a new file. The input image file will not be modified.

Callbacks:
successCallback : function(result)
  • result.imageFileUri - File URI of the rotated result image as JPEG ('file:///...').
errorCallback : function(error)
  • error - Contains the error message as string.
Options:
var options = {
  imageFileUri: 'file:///...',
  degrees: -90,
  quality: 80
};
  • options.imageFileUri - Input image file URI.
  • options.degrees - Degrees as integer value. The direction of rotation is counterclockwise if degrees value is positive (e.g. 90°), and clockwise if degrees value is negative (e.g. −90°).
  • options.quality - Optional quality of the output image.

Apply Image Filter

ScanbotSdk.applyImageFilter(successCallback, errorCallback, options)

Applies filter on an image. As input a file URI of the image must be passed. The output image will be a new file. The input image file will not be modified.

Callbacks:
successCallback : function(result)
  • result.imageFileUri - File URI of the result image as JPEG ('file:///...').
errorCallback : function(error)
  • error - Contains the error message as string.
Options:
var options = {
  imageFileUri: 'file:///...',
  imageFilter: ScanbotSdk.ImageFilter.BINARIZED,
  quality: 80
};
  • options.imageFileUri - Input image file URI.
  • options.imageFilter - ImageFilter enum value.
  • options.quality - Optional quality of the output image.

PDF Creation

ScanbotSdk.createPdf(successCallback, errorCallback, options)

The Scanbot SDK renders given images into a PDF document and stores it as a file. For each image a separate page is generated.

Callbacks:
successCallback : function(result)
  • result.pdfFileUri - File URI of the result file as PDF ('file:///...').
errorCallback : function(error)
  • error - Contains the error message as string.
Options:
var options = {
  images: ['file:///...', 'file:///...', 'file:///...']
};
  • options.images - Input images as an array of file URIs in proper order (image element 1 => page 1, etc).

OCR - Optical Character Recognition

The OCR feature is a part of the Scanbot SDK Package II. It is based on the Tesseract OCR Engine with some modifications and enhancements.

ScanbotSdk.getOcrConfigs(successCallback, errorCallback, options)

Use this function to get Scanbot SDK OCR properties of the current App installation.

Callbacks:
successCallback : function(result)
  • result.languageDataPath - Contains absolute file URI of the directory where to place the OCR training data files. You have to copy the corresponding *.traineddata files into this directory. The directory is a part of your App. If you uninstall the app, this directory will also be removed.
  • result.installedLanguages - Returns an array of current installed OCR languages (e.g. ["en", "fr"]). The Scanbot SDK uses the languageDataPath directory to determine installed OCR languages.
errorCallback : function(error)
  • error - Contains the error message as string.
Options:
var options = {};

No options are required for this operation.

ScanbotSdk.performOcr(successCallback, errorCallback, options)

This function takes an array of images and performs Optical Character Recognition on each of the images. As result the recognized text can be returned as plain text or a composed PDF file containing selectable and searchable text.

Callbacks:
successCallback : function(result)
  • result.plainText - Contains the recognized plain text.
  • result.pdfFileUri - File URI of the composed PDF file ('file:///...').
errorCallback : function(error)
  • error - Contains the error message as string.
Options:
var options = {
  images: ['file:///...', 'file:///...', 'file:///...'],
  languages: ['en', 'de'],
  outputFormat: ScanbotSdk.OcrOutputFormat.PDF_FILE
};
  • options.images - Input images as an array of file URIs in proper order (image element 1 => page 1, etc).
  • options.languages - An array with OCR languages of the text to be recognized (e.g. ["en", "de"]). The number of languages has an impact on the performance - the more languages, the slower the recognition process. The OCR operation will fail with an error if some of the specified languages are missing. Please use the getOcrConfigs function to make sure that desired languages are installed.
  • options.outputFormat - OcrOutputFormat enum value to specify the result.

OCR Languages and Data Files

For each desired OCR language a corresponding training data file (aka. tessdata) must be installed in the languageDataPath directory of the Scanbot SDK.

Furthermore the special data file osd.traineddata is required and must be installed. It is used for orientation and script detection.

The Scanbot SDK plugin ships with no training data files by default to keep the plugin package small in size.

Download OCR files

Please find a list of all supported languages in the Tesseract wiki.

Note: Scanbot SDK supports training data files of Tesseract version 3.0x only.

Language Codes

The Tesseract language data files are identified by a 3-letter language code. For example:

  • eng - English
  • deu - German
  • etc.

The Scanbot SDK API uses a 2-letter ISO code:

  • en - English
  • de - German
  • etc.
Example:

If you want to perform OCR with languages English and German, you have to download and install the following data files:

  • eng.traineddata - language file for English
  • deu.traineddata - language file for German
  • osd.traineddata - special data file for orientation and script detection

In the Scanbot SDK plugin then use languages: ["en", "de"].

OCR Output Format values

ScanbotSdk.OcrOutputFormat

Following output formats can be specified for OCR result:

  • OcrOutputFormat.PLAIN_TEXT - Returns the recognized text as plain text only.
  • OcrOutputFormat.PDF_FILE - Creates a composed PDF file containing selectable and searchable text.
  • OcrOutputFormat.FULL_OCR_RESULT - Full result: composed PDF file and recognized plain text.

Cleanup

ScanbotSdk.cleanup(successCallback, errorCallback, options)

By calling ths function all temporary output files generated by the Scanbot SDK plugin will be deleted.

Callbacks:
successCallback : function(result)
  • result - Contains a simple success message as string.
errorCallback : function(error)
  • error - Contains the error message as string.
Options:
var options = {};

No options are required for this operation.

File Handling & Storage Concept

The Scanbot SDK plugin works with file URIs. That means all input and output files (images, PDFs, etc) are identified by a file URI. Please note that a file URI is not just a file path : "file:///some/file/path/.." vs. "/some/file/path/.."

Examples of valid file URIs:

  • On Android: file:///storage/emulated/0/Android/data/my.awesome.app/cache/sbsdk-temp/ce8de3c4-3c96-4ce1-b285-483d01e1dc9a.jpg

  • On iOS: file:///var/mobile/Containers/Data/Application/D2BF9FB2-1024-4418-99B2-3709AB2C171E/Documents/sbsdk-temp/05719BF8-63DB-4C8A-9A57-25B233AED33C.jpg

All output files generated by the Scanbot SDK plugin are a kind of temporary files. We recommend to copy, move or delete the files you get from callbacks to a appropriate storage place.

There is no automatic file clean mechanism in the plugin, because only your App can decide when is the perfect time to remove a file.

To avoid storage space issues caused by temporary files please implement a suitable hook for the cleanup function in your App.

Detection Result values

ScanbotSdk.DetectionResult

  • DetectionResult.OK - Document detection was successful. The detected contour looks like a valid document.
  • DetectionResult.OK_BUT_BAD_ANGLES - Document was detected, but the perspective is not perfect.
  • DetectionResult.OK_BUT_BAD_ASPECT_RATIO - Document was detected, but it has a wrong rotation relatively to the camera sensor.
  • DetectionResult.OK_BUT_TOO_SMALL - Document was detected, but it doesn’t fill the most best area in the image rect.
  • DetectionResult.ERROR_TOO_DARK - Document was not found, most likely because of bad lightning conditions.
  • DetectionResult.ERROR_TOO_NOISY - Document was not found, most likely because there is too much background noise (maybe too many other objects on the table, or background texture is not monotonic).
  • DetectionResult.ERROR_NOTHING_DETECTED - No document was found.

Image Filter values

ScanbotSdk.ImageFilter

Supported image filters:

  • ImageFilter.COLOR_ENHANCED - Color-enhancement filter
  • ImageFilter.GRAYSCALE - Grayscale filter
  • ImageFilter.BINARIZED - Black & White filter
  • ImageFilter.COLOR_DOCUMENT - MagicColor filter

Polygon

The Scanbot SDK polygon is a list with 4 float points (one for each corner). Each point has coordinates in range [0..1], representing position relative to image size. For instance, if a point has the coordinates (0.5, 0.5), it means that it is located exactly in the center of the image.

Example code of a detected polygon as JSON result:

"polygon": [
    {"y":0.046, "x":0.13066667},
    {"y":0.035, "x":0.91066664},
    {"y":0.92, "x":0.9346667},
    {"y":0.916, "x":0.10666667}
]

Image Quality / Compression

The quality parameter defines the quality factor of the JPEG output image. The value must be in a range of 1-100, where 100 means the least quality loss.

This parameter is optional. The default value used by the Scanbot SDK Plugin is 95.

Barcode Format

The following barcode formats are currently supported.

Android

1D barcodes
  • EAN_13
  • EAN_8
  • UPC_A
  • UPC_E
  • CODE_39
  • CODE_93
  • CODE_128
  • ITF (Interleaved 2 of 5)
  • CODABAR
2D barcodes
  • QR_CODE
  • DATA_MATRIX
  • AZTEC
  • PDF_417

iOS

1D barcodes
  • EAN_13
  • EAN_8
  • UPC_E
  • CODE_39
  • CODE_93
  • CODE_128
  • ITF (Interleaved 2 of 5)
2D barcodes
  • QR_CODE
  • DATA_MATRIX
  • AZTEC
  • PDF_417

All values are provided as string constants in ScanbotSdk.BarcodeFormat.*.

UI Customization

Colors

The most customizable colors can be passed as an optional JSON argument in the corresponding JS function call. Please see the description of the UI functions startCamera and startCropping.

Image Resources

All image resources (icons, buttons, etc) can be replaced in the platforms directory of your app:

  • iOS: *./platforms/ios//Resources/*
  • Android: ./platforms/android/res/

Release history for version 1.x

1.7.0
  • Android:
    • Under the hood: Upgraded the native Scanbot Android SDK to v1.33.0
    • Added native libs for arm64-v8a. ⚠️ Please note: In August 2019, Google Play Store will require that new apps and app updates with native libraries provide 64-bit versions in addition to their 32-bit versions https://android-developers.googleblog.com/2017/12/improving-app-security-and-performance.html. We strongly recommend to upgrade the Scanbot SDK Plugin to the latest version to benefit from the full support of arm64-v8a libs.
    • Upgraded Google Support Libs to v27 (e.g. com.android.support:appcompat-v7:27.1.1, etc)
    • Improvement in Camera UI: Replaced the user guidance Toast messages with a TextView (provides smoother updates of the hints).
    • Bugfix: Minor fixes and improvements in Camera UI and Cropping UI
    • Min requirements changed: cordova-android@6.4.0 or higher is required now.
  • iOS:
    • Under the hood: Upgraded the native Scanbot iOS SDK to v1.6.0
    • Added dSYM files (ScanbotSDK.framework.dSYM) of the Scanbot iOS SDK into the npm package. dSYM files contain the debug symbols and can be used for services like Crashlytics. (also see the section Buildingi OS Production Apps…)
1.6.0
  • Android:
    • Improvement: Added support for latest version of Cordova Android platform cordova-android@7.x+
1.5.0
  • Android & iOS:
    • Feature: Barcode and QR code Scanner
  • Android:
    • Under the hood: Upgraded the native Scanbot Android SDK to v1.26.7
  • iOS:
    • Under the hood: Upgraded the native Scanbot iOS SDK to v1.5.6
1.4.1
  • Android & iOS:
    • Bugfix: Error handling in Cropping UI.
1.4.0
  • Android:
    • Under the hood: Upgraded the native Scanbot Android SDK to v1.26.5
    • Feature: Detection result details in Camera UI callback (detectionResult and polygon)
    • Improvement: Optimized auto snapping sensitivity / timings
    • Improvement: Optimized Scanbot SDK license check and error handling (added Java exceptions with human readable messages)
    • Bugfix: Various fixes in Cropping UI
  • iOS:
    • Feature: Detection result details in Camera UI callback (detectionResult and polygon)
    • Bugfix: Fixed the names of returned DetectionResult constants according to documentation
    • Bugfix: Added support for the user guidance hint "autosnapping_hint_bad_aspect_ratio" in Camera UI
1.3.1
  • Android
    • Improvement: Better compatibility with other 3rd-party plugins.
    • Workaround: Temporary removed the android:largeHeap="true" attribute due to a potential Cordova issue (CB-13474) with the <edit-config> tag. Please add the attribute android:largeHeap="true" manually in the <application> element of AndroidManifest.xml file.
1.3.0
  • Android & iOS:
    • Feature: Image rotation functionality in Cropping UI
    • Feature: New API function rotateImage()
    • Feature: New API function isLicenseValid()
    • Feature: New image filter ImageFilter.COLOR_DOCUMENT
  • Android:
    • Under the hood: Upgraded the native Scanbot Android SDK to v1.25.1
  • iOS:
    • Under the hood: Upgraded the native Scanbot iOS SDK to v1.4.7
    • Bugfix: Fixed initial screen orientation in Camera UI
1.2.5
  • Android:
    • Improvement: Optimized Camera UI behaviour
1.2.4
  • Android:
    • Bugfix: User guidance messages are closed after leaving Camera screen
1.2.3
  • iOS:
    • Bugfix: Fixed Camera UI dismiss behaviour
1.2.2
  • Android:
    • Improvement: Added android:largeHeap="true" application attribute in AndroidManifest.xml by default
    • Under the hood: Upgraded the native Scanbot Android SDK to v1.23.3
1.2.1
  • Android:
    • Bugfix: Fixed a crash in Camera UI when resuming the App (fix in the native Scanbot Android SDK)
    • Bugfix: Fixed an issue with the flash light in Camera UI on some devices (fix in the native Scanbot Android SDK)
    • Under the hood: Upgraded the native Scanbot Android SDK to v1.22.6
  • iOS:
    • Bugfix: Fixed a bug in Cropping UI where sometimes the polygon handles were not visible (fix in the native Scanbot iOS SDK)
    • Under the hood: Upgraded the native Scanbot iOS SDK to v1.4.3
1.2.0
  • Android & iOS
    • Feature: OCR functionality
    • Feature: Auto-snapping toggle button in Camera UI
    • Feature: New parameters for Camera UI: autoSnappingEnabled, autoSnappingSensitivity, sampleSize
  • Android
    • Improvement: Continuous focus mode in Camera UI (improves scan performance & quality)
    • Under the hood: Upgraded the native Scanbot Android SDK to v1.22.3
  • iOS
    • Under the hood: Upgraded the native Scanbot iOS SDK to v1.4.2
1.1.1
  • Android:
    • Bugfix: Autorotating images based on image orientation value in Camera UI (relevant for most Samsung devices).
1.1.0
  • Android:
    • Feature: quality parameter in Scanbot SDK functions: Camera UI, Cropping UI, documentDetection, applyImageFilter
  • iOS:
    • Feature: quality parameter in Scanbot SDK functions: Camera UI, Cropping UI, documentDetection, applyImageFilter
    • Bugfix: originalImageFileUri in Camera UI callback had no file
1.0.1
  • Android:
    • Bugfix: OutOfMemoryError in Camera UI (Camera Activity)
1.0.0
  • First release version
  • Added customization options for colors in UI functions startCamera and startCropping
  • Fixed some image resource issues
0.9.2
  • First beta preview.

Libraries and Licenses


Scanbot SDK for iOS uses the following Open Source libraries:


OpenCV 3.1
----------
Copyright © 2014, Itseez. All rights reserved.
This library is distributed under the terms of the following license: http://opencv.org/license.html.


G8Tesseract
-----------
Copyright @ 2014 Daniele Galiotto. https://github.com/gali8/Tesseract-OCR-iOS
This library is distributed under the terms of a MIT License (https://github.com/gali8/Tesseract-OCR-iOS/blob/master/LICENSE.md).


Tesseract 3.04 modified by doo GmbH
-----------------------------------
Tesseract, maintained by Google (http://code.google.com/p/tesseract-ocr/),
is distributed under the Apache 2.0 license (see http://www.apache.org/licenses/LICENSE-2.0).


Leptonica 1.72
--------------
Copyright @ 2001-2015, Leptonica, (http://leptonica.org),
is distributed under a Creative Commons Attribution 3.0 United States License (see http://creativecommons.org/licenses/by/3.0/us/).


OpenSSL 1.0.2d
--------------
Copyright @ 1998-2011 The OpenSSL Project. All rights reserved. (https://www.openssl.org)
This library is distributed under the terms of the following license: https://github.com/openssl/openssl/blob/master/LICENSE





Scanbot SDK for Android uses the following Open Source libraries:

CWAC-Camera
-----------
Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


Dagger 2
--------
Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


Android PDF Writer
------------------
Android PDF Writer (APW) is a simple Java library to generate simple PDF documents in Google's Android devices released under the BSD license.

This software includes several classes from the Android Open Source Project

Copyright 2010 The Android Open Source Project

Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


commons-lang
------------
Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


commons-io
----------
Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


commons-codec
-------------
Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


IntelliJ Annotations
--------------------
Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


Guava: Google Core Libraries For Java
-------------------------------------
Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


Dagger Compiler
---------------
Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.



Tesseract-ocr
-------------
Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.



ZXing
-----
Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.



BoringSSL
---------

OpenSSL License
---------------

====================================================================
Copyright (c) 1998-2011 The OpenSSL Project.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in
   the documentation and/or other materials provided with the
   distribution.

3. All advertising materials mentioning features or use of this
   software must display the following acknowledgment:
   "This product includes software developed by the OpenSSL Project
   for use in the OpenSSL Toolkit. (http://www.openssl.org/)"

4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
   endorse or promote products derived from this software without
   prior written permission. For written permission, please contact
   openssl-core@openssl.org.

5. Products derived from this software may not be called "OpenSSL"
   nor may "OpenSSL" appear in their names without prior written
   permission of the OpenSSL Project.

6. Redistributions of any form whatsoever must retain the following
   acknowledgment:
   "This product includes software developed by the OpenSSL Project
   for use in the OpenSSL Toolkit (http://www.openssl.org/)"

THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.
====================================================================

This product includes cryptographic software written by Eric Young
(eay@cryptsoft.com).  This product includes software written by Tim
Hudson (tjh@cryptsoft.com).



Original SSLeay License
-----------------------

Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
All rights reserved.

This package is an SSL implementation written
by Eric Young (eay@cryptsoft.com).
The implementation was written so as to conform with Netscapes SSL.

This library is free for commercial and non-commercial use as long as
the following conditions are aheared to.  The following conditions
apply to all code found in this distribution, be it the RC4, RSA,
lhash, DES, etc., code; not just the SSL code.  The SSL documentation
included with this distribution is covered by the same copyright terms
except that the holder is Tim Hudson (tjh@cryptsoft.com).

Copyright remains Eric Young's, and as such any Copyright notices in
the code are not to be removed.
If this package is used in a product, Eric Young should be given attribution
as the author of the parts of the library used.
This can be in the form of a textual message at program startup or
in documentation (online or textual) provided with the package.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software
   must display the following acknowledgement:
   "This product includes cryptographic software written by
    Eric Young (eay@cryptsoft.com)"
   The word 'cryptographic' can be left out if the rouines from the library
   being used are not cryptographic related :-).
4. If you include any Windows specific code (or a derivative thereof) from
   the apps directory (application code) you must include an acknowledgement:
   "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"

THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

The licence and distribution terms for any publically available version or
derivative of this code cannot be changed.  i.e. this code cannot simply be
copied and put under another distribution licence
[including the GNU Public Licence.]



ISC license used for completely new code in BoringSSL:

Copyright (c) 2015, Google Inc.

Permission to use, copy, modify, and/or distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. */


Some files from Intel carry the following license:

Copyright (c) 2012, Intel Corporation

All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

*  Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

*  Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the
   distribution.

*  Neither the name of the Intel Corporation nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.


THIS SOFTWARE IS PROVIDED BY INTEL CORPORATION ""AS IS"" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INTEL CORPORATION OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.