Scanbot SDK for Xamarin and Xamarin.Forms

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

Requirements

  • Latest version of Microsoft Visual Studio with Xamarin Platform
  • For Xamarin.Forms projects: Xamarin.Forms v2.2+ or v3.x

Supported mobile platforms

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

Example Apps

Check out our example apps for Android and iOS on GitHub:

Getting started

Download & Installation

The Scanbot SDK is provided as NuGet packages

Install ScanbotSDK.Xamarin.Forms if your project is based on Xamarin.Forms, otherwise install ScanbotSDK.Xamarin.

You can directly install them in Visual Studio IDE. Open your App-Solution in Visual Studio, select your iOS or Android project and click on the menu item Project -> Add NuGet Packages.
Make sure nuget.org is selected as source and search for the package.

By clicking on Add Package the Scanbot SDK will be downloaded and installed into your project. Do that for both your iOS and Android projects. Also, ScanbotSDK.Xamarin.Forms must be installed in the portable app project (if one exists - not necessary if you’re using a shared project).

Android settings

Enable Multi-Dex

Android Project => Options => Android Build => General => Enable Multi-Dex

alt

ABI Settings

The Scanbot SDK uses native libraries under the hood and supports following ABIs: armeabi-v7a, arm64-v8a and x86.

Please adjust the Supported ABIs configuration in your Android project settings accordingly:

Android Project => Options => Android Build => Advanced => Supported ABIs

alt

Please note: Typically the x86 architecture can be removed for the release (production) build, since it’s used for emulators. Also, by removing the x86 architecture the size of the app package (APK) will be reduced.

Furthermore please increase the Java Heap Size value to min. 2G. For some projects it is even recommended to use 4G.

ProGuard

If you need to enable ProGuard for your Android build, please check this full list of the ProGuard rules for the Scanbot SDK.

iOS settings

You have to adjust the “Linker behavior” settings in your iOS project:

iOS Project => Options => iOS Build => Linker behavior => Change to “Link Framework SDKs Only”

Make sure to apply the settings for iPhone and iPhoneSimulator (via “Platform” drop-down) as well as for Debug and Release configurations (via “Configuration” drop-down)!

alt

You can also compare the settings to our example apps on GitHub.

Permissions

Required permissions for Android

Make sure to add these permissions in your AndroidManifest.xml file:

This permission is used for the camera views:

<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera" />

The following permissions are required for PDF creation (to handle temporary files):

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

Required permissions for iOS

Add the following properties to your Info.plist file:

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

License Key

In order to run the Scanbot SDK functionality within your production app you have to purchase and use a valid Scanbot SDK license.

Each license key is valid only for a given app 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 will terminate your app.

Example code for defining and using the license key string:

private const string licenseKey =
  "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";

// Xamarin
SBSDK.Initialize(application, licenseKey);

// Xamarin.Forms
SBSDKInitializer.Initialize(application, licenseKey);

Trial License

The Scanbot SDK will run without a license for one minute per session! To get an unrestricted “no-strings-attached” 30 day trial license, please submit the Trial License Form on our website.

Please kindly note that a trial 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.

Purchase a Production License

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

App Identifier

Every app has a unique identifier (sometimes also known as “bundle identifier” or “application ID”). Your license will be bound to this identifier. To request a trial license or purchase a production license you have to provide us the bundle identifier of your app.

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

Logging

When initializing the Scanbot SDK you can enable or disable logging of the SDK.

// Xamarin
SBSDK.Initialize(application, licenseKey, new SBSDKConfiguration { EnableLogging = true });

// Xamarin.Forms
SBSDKInitializer.Initialize(application, licenseKey, new SBSDKConfiguration { EnableLogging = true });

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

On iOS all logs are printed to the console. There will be no log files created by the Scanbot SDK.

While it may be useful for development, consider switching logging off in production builds for security and performance reasons!

Image Quality / Compression

SBSDKConfiguration has two more optional properties that specify the image storage format and compression for temporary images. Temporary images are all images created by the document scanner, cropping UI, as well as all image manipulation functions like ApplyImageFilter.

var configuration = new SBSDKConfiguration
{
  ...
  StorageImageFormat = CameraImageFormat.Jpg,
  StorageImageQuality = 80,
};

// Xamarin
SBSDK.Initialize(application, licenseKey, configuration);

// Xamarin.Forms
SBSDKInitializer.Initialize(application, licenseKey, configuration);
  • StorageImageQuality - defines the quality factor of JPEG images. The value must be between 1 and 100, where 100 means maximum quality and largest file size. The default value is 80 which is a good compromise between image file size and document legibility.
  • StorageImageFormat - CameraImageFormat.Jpg or CameraImageFormat.Png

Next Steps

Integration with Xamarin.Forms

If your project is based on Xamarin.Forms please see this page for further integration steps:

👉 Integration with Xamarin.Forms

Integration with Xamarin

For native integration with Xamarin.Android and Xamarin.iOS please follow this documentation:

👉 Integration with Xamarin.Android and Xamarin.iOS

Pitfalls and issues

👉 Pitfalls and issues

Libraries and Licenses

👉 Libraries and Licenses