Skip to main content

SDK Initialization | Flutter Document Scanner

License Key​

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

Each license key is valid only for a given app bundle identifier. You will be unable to use any of the SDK features if the license key is corrupted, expired, or invalid in any other way.

Trial License​

The Scanbot SDK will run without a license for one minute per session! To get a free, "no-strings-attached" 7-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​

To get pricing information and purchase a production license for the Scanbot SDK please request a quote.

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.

For Android: Please see the applicationId in the app-level build.gradle file of your android project:

defaultConfig {
    ...
    applicationId "io.scanbot.example.app.flutter"
}

For iOS: In Xcode see the Bundle Identifier in the "General" settings tab of your project.

Initialization​

Free Developer Support

We provide free "no-strings-attached" developer support for the implementation & testing of the Scanbot SDK. If you encounter technical issues with integrating the Scanbot SDK or need advice on choosing the appropriate framework or features, please visit our Support Page.

ScanbotSdk.initScanbotSdk(config) ScanbotSDK must be initialized before usage!

The following configuration options can be passed on initialization:

Options:​
import 'package:scanbot_sdk/scanbot_sdk.dart';
import 'package:scanbot_sdk/scanbot_sdk_models.dart';
import 'package:scanbot_sdk/json/common_data.dart';

var config = ScanbotSdkConfig(
  licenseKey: "<YOUR_SCANBOT_SDK_LICENSE_KEY>",
  loggingEnabled: true,
  imageFormat: ImageFormat.JPG,
  imageQuality: 80,
  storageBaseDirectory: "file:///some/optional/custom-storage-dir/",
  documentDetectorMode: DocumentDetectorMode.ML_BASED,
  licenseErrorHandler: (status, feature) {
    print("status: $status, feature $feature");
  },
);

ScanbotSdk.initScanbotSdk(config);
  • licenseKey: Your license key for the Scanbot SDK.
  • loggingEnabled: Optional logging flag.
  • imageFormat: Optional image format value.
  • imageQuality: Optional image quality value.
  • storageBaseDirectory: Optional parameter for overriding the default storage directory as a file URI of the Scanbot Barcode Scanner SDK.
  • encryptionParameters: Optional parameter for Configuration class for AES encryption.
  • useCameraX: Optional flag to enable the usage of CameraX Android APIs of the Ready to Use UI components under the hood (Android only).
  • allowGpuAcceleration: Optional flag to enable GPU acceleration for TensorFlow ML models (Android only).
  • allowXnnpackAcceleration: Optional flag allows control of whether the XNN pack optimizations should be used (Android only).
  • documentDetectorMode: Optional document detector mode.
    • DocumentDetectorMode.EDGE_BASED - default implementation, based on classical edge detection approach
    • DocumentDetectorMode.ML_BASED - new Machine Learning based approach (requires iOS 11.2+)
  • licenseErrorHandler : Callback function to get info about problems with license key or specific feature that is not available for usage.

Example code for initialization:

import 'package:scanbot_sdk/scanbot_sdk.dart';
import 'package:scanbot_sdk/scanbot_sdk_models.dart';
import 'package:scanbot_sdk/common_data.dart';

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() {
      // Please note: this is just an example license key string (it is not a valid license)
      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";
      var config = ScanbotSdkConfig(
          licenseKey: licenseKey,
          imageFormat: ImageFormat.JPG,
          imageQuality: 80,
          loggingEnabled: true,
          encryptionParameters : EncryptionParameters(password: "password",
                                                      mode: FileEncryptionMode.AES256));
      ScanbotSdk.initScanbotSdk(config);
    });
    return _MyAppState();
  }
}

Image Quality / Compression​

The initializeSdk function can take some optional parameters that specify the image storage format and compression for generated Page images. Page images are all images created by the Ready-To-Use UI Components (like Document Scanner, Cropping UI, etc), as well as all image manipulation functions working with Page objects as input (like applyImageFilterOnPage, detectDocumentOnPage, etc).

import 'package:scanbot_sdk/scanbot_sdk.dart';
import 'package:scanbot_sdk/scanbot_sdk_models.dart';
import 'package:scanbot_sdk/common_data.dart';

var config = ScanbotSdkConfig(
   imageFormat: ImageFormat.JPG,
   imageQuality: 80,
);

ScanbotSdk.initScanbotSdk(config);
  • imageQuality - 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.
  • imageFormat - either JPG or PNG. The default value is JPG.

Updating License Key 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 contained in an encrypted data part of the license key string. This 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.getLicenseStatus(). If the result of await returns result.isLicenseValid == false, you should disable any usage of the Scanbot SDK functions or UI components in your app.

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

ScanbotSdk.getLicenseStatus()​

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

var result = await ScanbotSdk.getLicenseStatus();
if (result.isLicenseValid) {
  // Making your calls of the Scanbot SDK Plugin API is now safe.
  // e.g. start the Document Scanner
} else {
  // Implement a suitable handling (e.g. disable Scanbot functionality in your App)
  showAlert("Scanbot SDK license has expired! Please install the latest app update.");
}
  • 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.

Logging​

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

import 'package:scanbot_sdk/scanbot_sdk.dart';
import 'package:scanbot_sdk/scanbot_sdk_models.dart';

var config = ScanbotSdkConfig(
  loggingEnabled: true,
  // ...
);
ScanbotSdk.initScanbotSdk(config);

On Android logs are printed into LogCat as well as saved on the device. 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!

Want to scan longer than one minute?

Generate your free "no-strings-attached" Trial License and properly test the Scanbot SDK.

Get your free Trial License

What do you think of this documentation?

On this page

Scroll to top