SDK Initialization | iOS 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.

Initialize

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.

In order to activate the license in the code use the +[Scanbot setLicense:] method in the Scanbot class. Execute this code as early as possible during your app's runtime, at least before using any Scanbot SDK functionality, e.g. in your application delegate's -application:didFinishLaunchingWithOptions: method.

If your license has expired, any invocation of the Scanbot SDK API will terminate your app. To prevent this you should check for license expiration during runtime by calling [Scanbot isLicenseValid]. If this method returns NO, you should disable Scanbot-SDK-using features or any user interfaces.

Example code for using the license string

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    [Scanbot setLicense:
    @"P73ZaxJ3VG08E+0sUqcbf+BPmKoCDVmWZthAS/FmYsh2I"
    "DT9AJbIKbBRfaDSzjZed4+py7suMYDq++TuzkqVc9CYwGb"
    "3VL68OhsOEpUAJ/GOdVfZnSTFvDo1JQvq54nY2+EChviwM"
    "CkBXCDO7YSMB/Rp42dlu7x3a/EFbor+PmlBpZhfdwveyWX"
    "5MasHiMzgNicdb33hVgyWgcv74NpxL1XyZkcvn7wQrzgzq"
    "JtJ63YUI6SPmTZtJB2M+0IMYeQXj1HltWX5mcohEIFPme7"
    "hU0BZB3S476QMceeL4bPCZjgu1vjL7kxKurIqmJGT6juGu"
    "kFQFJWPoccmgtJnHxI0Cg==U2NhbmJvdFNESwpuZXQuZ"
    "G9vLlBheUZvcm1TY2FubmVyRGVtbwowCjEyOA=="];

    return YES;
}

License Checks in Production Apps

If your Scanbot SDK license has expired, any call from the Scanbot SDK API will terminate your app. To prevent this you should always check for license expiration during the runtime by calling the method +[Scanbot isLicenseValid]. If this method returns NO, you should disable any usage of the Scanbot SDK functions or UI components.

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

Example code for checking the license status

if ([Scanbot isLicenseValid]) {
    // Making your call into ScanbotSDK API is safe now.
    ...
}

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

Logging

The Scanbot SDK comes with its own console logging. By default, the logging is turned on.

You can turn off logging for the Scanbot SDK by using:

[Scanbot setLoggingEnabled:NO];

This will also silence information about the Scanbot SDK license.

Image Storage

The Scanbot SDK comes with built-in image storage. You can store scanned images using either keyed or indexed storage. We provide convenient interfaces for this via the SBSDKKeyedImageStorage and SBSDKIndexedImageStorage classes.

SBSDKKeyedImageStorage is a simple thread-safe multiple-reader-single-writer key-value fashioned disk image cache class. This class manages images in a dictionary-like fashion.

SBSDKIndexedImageStorage is a simple thread-safe multiple-reader-single-writer index-based disk image cache class. This class manages images in an array-like fashion.

Both classes support JPEG (recommended) and PNG image file formats represented in SBSDKImageFileFormat Enumeration.

Both classes support encryption, so your data is stored securely. We provide built-in support for AES128 and AES256 encryption. If these algorithms do not meet your requirements you can create your own encrypter by implementing a class conforming to the SBSDKStorageCrypting protocol.

Please note

Encryption is not enabled by default.

For easier access to the device's file system, the Scanbot SDK provides a convenient helper class SBSDKStorageLocation.

Example of creating indexed image storage using SBSDKStorageLocation and built-in AES256 encrypter:

Swift

// Create a Url to the directory where you plan to store the images
let imagesDirectoryURL = SBSDKStorageLocation.applicationDocumentsFolderURL.appendingPathComponent("Images")

// Create a storage location using the Url pointing to the images directory
let storageLocation = SBSDKStorageLocation.init(baseURL: imagesDirectoryURL)

// Create encrypter with a password and the desired encryption mode
let encrypter = SBSDKAESEncrypter(password: "password_example#42", mode: .AES256)

// Create an indexed image storage using the storage location, image file format and encrypter
let imageStorage = SBSDKIndexedImageStorage(storageLocation: storageLocation,
                                            fileFormat: .JPEG,
                                            encrypter: encrypter)

Objective-C

// Create a Url pointing to the directory where you plan to store the images
NSURL *imagesDirectoryURL = [[SBSDKStorageLocation applicationDocumentsFolderURL]
                                URLByAppendingPathComponent:@"Images"];

// Create a storage location using the Url pointing to the images directory
SBSDKStorageLocation *storageLocation = [[SBSDKStorageLocation alloc] initWithBaseURL:imagesDirectoryURL];

// Create encrypter with a password and the desired encryption mode
SBSDKAESEncrypter *encrypter = [[SBSDKAESEncrypter alloc] initWithPassword:@"password_example#42"
                                                                      mode:SBSDKAESEncrypterModeAES256];

// Create an indexed image storage using the storage location, image file format and encrypter
SBSDKIndexedImageStorage *imageStorage = [[SBSDKIndexedImageStorage alloc] initWithStorageLocation:storageLocation
                                                                                        fileFormat:SBSDKImageFileFormatJPEG
                                                                                         encrypter:encrypter];

Examples of some basic operations on Indexed Image storage:

Swift

// In the example we are using temporary image storage
guard let imageStorage = SBSDKIndexedImageStorage.temporary else { return }

// Create an image
guard let image = UIImage(named: "testImage") else { return }

// Create an index
let index: Int = 0

// Get the image at index
let storedImage = imageStorage.image(at: index)

// Add an image to storage
let isAdded = imageStorage.add(image)

// Insert an image at index
let isInserted = imageStorage.insert(image, at: index)

// Remove the image at index
imageStorage.removeImage(at: index)

// Move an image from index to index
// Create a new index to move the image to
let newIndex: Int = 1
let isMoved = imageStorage.moveImage(from: index, to: newIndex)

// Replace an image at index with another image
// Create an image to replace a stored one
guard let newImage = UIImage(named: "newTestImage") else { return }
let isReplaced = imageStorage.replaceImage(at: index, with: newImage)

Objective-C

// In the example we are using temporary image storage
SBSDKIndexedImageStorage *imageStorage = [SBSDKIndexedImageStorage temporary];

// Create an image
UIImage *image = [UIImage imageNamed:@"testImage"];

// Create an index
NSInteger index = 0;

// Get the image at index
UIImage *storedImage = [imageStorage imageAtIndex:index];

// Add an image to storage
BOOL isAdded = [imageStorage addImage:image];

// Insert an image at index
BOOL isInserted = [imageStorage insertImage:image atIndex:index];

// Remove the image at index
[imageStorage removeImageAtIndex:index];

// Move an image from index to index
// Create a new index to move the image to
NSInteger newIndex = 1;
BOOL isMoved = [imageStorage moveImageFromIndex:index toIndex:newIndex];

// Replace an image at index with another image
// Create an image to replace a stored one
UIImage *newImage = [UIImage imageNamed:@"newTestImage"];
BOOL isReplaced = [imageStorage replaceImageAtIndex:index withImage:newImage];

Examples of some basic operations on Keyed Image storage:

Swift

// Create an image storage using storage location, in the example we are using a temporary location
let imageStorage = SBSDKKeyedImageStorage()

// Create an image
guard let image = UIImage(named: "testImage") else { return }

// Create a key
let key = "testKey"

// Set an image for key
imageStorage?.set(image: image, for: key)

// Get the image for key
let storedImage = imageStorage?.image(for: key)

// Remove the image for key
imageStorage?.removeImage(for: key)

// Remove images for keys matching a prefix
// Create a prefix
let prefix = "test"
imageStorage?.removeImages(matchingPrefix: prefix)

Objective-C

// Create an image storage using storage location, in the example we are using a temporary location
SBSDKKeyedImageStorage *imageStorage = [[SBSDKKeyedImageStorage alloc] initWithStorageLocation:[SBSDKStorageLocation temporary]];

// Create an image
UIImage *image = [UIImage imageNamed:@"testImage"];

// Create a key
NSString *key = @"testKey";

// Set an image for key
[imageStorage setImage:image forKey:key];

// Get the image for key
UIImage *storedImage = [imageStorage imageForKey:key];

// Remove the image for key
[imageStorage removeImageForKey:key];

// Remove images for keys matching prefix
// Create a prefix
NSString *prefix = @"test";
[imageStorage removeImagesForKeysMatchingPrefix:prefix];

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?

What can we do to improve it? Please be as detailed as you like.

---