Skip to main content

SDK Initialization | React Native 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.

Example code for defining and using the license key:

import ScanbotSDK from 'react-native-scanbot-sdk';

// Please note: this is just an example license key string (it is not a valid license)
const 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";

const options = {
  licenseKey: myLicenseKey,
  loggingEnabled: true
}

const result = await ScanbotSDK.initializeSDK(options);

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.

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.initializeSDK(options): Promise The Scanbot SDK must be initialized before usage. Make sure to run the initialization only once per app lifetime. This should ideally be done at the earliest point in the application's lifecycle. Typically, the App.tsx file is good practice because it ensures that the Scanbot SDK is ready for use as soon as the app starts.

Example code for initialization:​

import ScanbotSDK from 'react-native-scanbot-sdk';

async function initializeSDK() {
  const options: ScanbotSdkConfiguration = {
    licenseKey: '', // Optional license key (empty for trial mode)
    loggingEnabled: true, // Consider switching logging OFF in production builds for security and performance reasons!
    storageImageFormat: 'JPG', // Optional image format - JPG or PNG. Default is JPG.
    storageImageQuality: 80, // Optional image JPG quality. Default is 80.
    storageBaseDirectory: myCustomStoragePath(), // Optional custom storage path.
    // The new and improved ML-based document detection is available from
    // ScanbotSDK react-native 4.1.0:
    documentDetectorMode: 'ML_BASED',
    // Optional file encryption configs. For more details see the section "Storage Encryption".
    fileEncryptionPassword: 'SomeSecretPa$$w0rdForFileEncryption',
    fileEncryptionMode: 'AES256'
  };
  try {
    const result = await ScanbotSDK.initializeSDK(options);
    // initialization succeeded
  } catch (err) {
    // initialization failed
  }
}

or

  useEffect(() => {
    ScanbotSDK.initializeSDK(initializationOptions)
      .then(onSuccess)
      .catch(onError);
  }, []);

Options​

export interface ScanbotSdkConfiguration {
  /** Optional boolean flag to enable logging. See the "Logging" section below. */
  loggingEnabled?: boolean;

  /** Optional boolean flag that enables Scanbot SDK Core native logging (default is false, Android only). */
  enableNativeLogging?: boolean;

  /** Your license key for the Scanbot SDK. See the "License Key" section below. */
  licenseKey?: string;

  /** Optional image quality value. It 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 recommended default value is 80 which is a good compromise between image file size and document legibility. */
  storageImageQuality?: number;

  /** Optional image format, either 'JPG' or 'PNG'. The recommended default value is 'JPG'. Please note that 'PNG' will result in larger image files! Also, the storageImageQuality value does not apply for 'PNG'. */
  storageImageFormat?: StorageImageFormat;

  /** Optional directory as file URI to override the default storage base directory of the Scanbot SDK. Refer to the section "Storage" for more details. */
  storageBaseDirectory?: string;

  /** Optional mode for document detection. */
  documentDetectorMode?: DocumentDetectorMode;

  /** Optional file encryption mode, 'AES128' or 'AES256'. */
  fileEncryptionMode?: FileEncryptionMode;

  /** Optional file encryption password. Refer to the section "Storage Encryption" for more details. */
  fileEncryptionPassword?: string;

  /** If set to `true`, Camera X will be used for the RTU-UI components (Android only). Default is `true`. */
  useCameraX?: boolean;

  /** If set to `true`, GPU Acceleration will be enabled for Barcode Scanner, Document Scanner and Generic Document Recognizer (Android only). Default is `true`. */
  allowGpuAcceleration?: boolean;

  /** Enables/disables XNNPACK acceleration for TensorFlow ML models, which provides highly optimized implementations of floating-point neural network operators (Android only) */
  allowXnnpackAcceleration?: boolean;
}

Logging​

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

const options = {
  licenseKey: myLicenseKey,
  loggingEnabled: true
}

const promise = ScanbotSDK.initializeSDK(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.

You can also see application logs in the terminal by issuing react-native log-android or react-native log-ios.

There will be no log files created by the Scanbot SDK module.

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

Image Quality / Compression​

initializeSDK can take two more optional parameters that specify the image storage format and compression for generated JPEG images, created by the Document Scanner, Cropping UI, as well as all image manipulation functions like applyImageFilter.

const options = {
  storageImageFormat: 'JPG',
  storageImageQuality: 80,
};

ScanbotSDK.initializeSDK(options);
  • 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. This parameter is optional. The default value is 80 which is a good compromise between image file size and document legibility.
  • storageImageFormat - either 'JPG' or 'PNG'. The default value is 'JPG'.

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 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.getLicenseInfo(). If the result of the isLicenseValid property returns 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!

LicenseInfo​

ScanbotSDK.getLicenseInfo(): ResultWrapper<GetLicenseInfoResult>>

export interface GetLicenseInfoResult {
  /** True if the license is valid, false otherwise */
  isLicenseValid: boolean;
  /** The license status */
  licenseStatus: LicenseStatus;
  /** The license expiration date in milliseconds */
  licenseExpirationDate: number;
}

Example code for checking the license status:​

async function() {
  const info = await ScanbotSDK.getLicenseInfo();
  if (info.isLicenseValid) {
    // Making your calls of the Scanbot SDK API is now safe.
    // e.g. startDocumentScanner(..), applyImageFilter(..), etc
  }
}

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