PPBlinkID 6.12.0

Maintained by NenadMiksa, Jura Skrlec, Toni Kreso, Tomislav Cvetkovic, Milan Paradina.

You want to add pod 'PPBlinkID', '~> 6.12' similar to the following to your Podfile:

target 'MyApp' do
  pod 'PPBlinkID', '~> 6.12'
end

Then run a pod install inside your terminal, or from CocoaPods.app.

Alternatively to give it a test run, run the command:

pod try PPBlinkID

PPBlinkID 6.12.0

By
Microblink, Jurica Cerovec and Jura Skrlec

BlinkID SDK for iOS

Reimagine the way your users fill in their information with BlinkID iOS SDK. Fast, accurate and secure identity document scanning of more than 180 countries worldwide.

BlinkID is:

Fast. Real-time data extraction in less than 400ms. Way better than minutes-long form-filling.
Secure. Privacy first, always. Scanning works even if the user’s iPhone is in airplane mode, meaning personal information never touches a third-party server.
Intelligent. Machine learning models, optimized to read and parse virtually any identity document in the world, be it a Malaysian MyTentera or a Californian driver license.
Lightweight. Designed to increase your app’s usability, not weight.
What you make of it. Customize and rebrand the default UI or leave it as it is. It’s up to you.
More than just a powerful ID scanner. Powerful data extraction, coupled with powerful perks. Get a cropped document image back, spot printed identity documents or data match both sides of the ID for parity.

To see all of these features at work, download our free demo app:

Feeling ready to get going with the integration? First, make sure we support your document type ➡️ full list. And then carefully follow the guidelines below.

Updating to a newer version of the SDK? Go to our 📚 release notes to see what’s changed.

Requirements
Quick Start
Advanced BlinkID integration instructions
- Built-in overlay view controllers and overlay subviews
  - Using MBBlinkIdOverlayViewController
  - Custom overlay view controller
- Direct processing API
MBRecognizer and available recognizers
List of available recognizers
Localization
Troubleshooting
Size Report
Additional info

Requirements

SDK package contains BlinkID framework and one or more sample apps which demonstrate framework integration. The framework can be deployed in iOS 13.0 or later.

Quick Start

Getting started with BlinkID SDK

This Quick Start guide will get you up and performing OCR scanning as quickly as possible. All steps described in this guide are required for the integration.

This guide closely follows the BlinkID-Sample app in the Samples folder of this repository. We highly recommend you try to run the sample app. The sample app should compile and run on your device, and in the iOS Simulator.

The source code of the sample app can be used as the reference during the integration.

1. Initial integration steps

Using CocoaPods

Download and install/update Cocopods version 1.11.3 or newer
Since the libraries are stored on Git Large File Storage, you need to install git-lfs by running these commands:

brew install git-lfs
git lfs install

Be sure to restart your console after installing Git LFS
Note: if you already did try adding SDK using cocoapods and it's not working, first install the git-lfs and then clear you cocoapods cache. This should be sufficient to force cocoapods to clone BlinkID SDK, if it still doesn't work, try deinitializing your pods and installing them again.
Project dependencies to be managed by CocoaPods are specified in a file called Podfile. Create this file in the same directory as your Xcode project (.xcodeproj) file.
If you don't have podfile initialized run the following in your project directory.

pod init

Copy and paste the following lines into the TextEdit window:

platform :ios, '13.0'
target 'Your-App-Name' do
    pod 'PPBlinkID', '~> 6.0.0'
end

Install the dependencies in your project:

$ pod install

From now on, be sure to always open the generated Xcode workspace (.xcworkspace) instead of the project file when building your project:

open <YourProjectName>.xcworkspace

Using Carthage

BlinkID SDK is available via Carthage. Please check out Carthage documentation if you are new to Carthage.

Install Carthage. Check out Installing Carthage guide. Please make sure you have Carthage version >= 0.35.0 installed.
Create a Cartfile in the same directory where your .xcodeproj or .xcworkspace is.
Add BlinkID as a dependency to this Cartfile:

binary "https://github.com/BlinkID/blinkid-ios/blob/master/blinkid-ios.json"

Run carthage update.
If successful, a Cartfile.resolved file and a Carthage directory will appear in the same directory as your Xcode project.
Drag the binaries from Carthage/Build/<platform> into your application’s Xcode project.

Using Swift Package Manager

BlinkID SDK is available as Swift Package. Please check out Swift Package Manager documentation if you are new to Swift Package Manager.

We provide a URL to the public package repository that you can add in Xcode:

https://github.com/BlinkID/blinkid-ios

Select your project’s Package Dependencies tab:
Add the BlinkID Swift package repository URL:
Choose Swift package version

NOTE: There is a known issue in Xcode 12 that could cause crash running on real iOS device. Please follow instructions below for the workaround:

Add a new copy files phase in your application’s Build Phase
Change the copy files phase’s destination to Frameworks
Add a new run script phase script to your app’s target
Add the following script to force deep sign the frameworks with your own signing identity:

find "${CODESIGNING_FOLDER_PATH}" -name '*.framework' -print0 | while read -d $'\0' framework 
do 
    codesign --force --deep --sign "${EXPANDED_CODE_SIGN_IDENTITY}" --preserve-metadata=identifier,entitlements --timestamp=none "${framework}" 
done

Manual integration

-Download latest release (Download .zip or .tar.gz file starting with BlinkID. DO NOT download Source Code as GitHub does not fully support Git LFS)

Clone this git repository:

Since the libraries are stored on Git Large File Storage, you need to install git-lfs by running these commands:

brew install git-lfs
git lfs install

Be sure to restart your console after installing Git LFS
To clone, run the following shell command:

git clone [email protected]:BlinkID/blinkid-ios.git

Copy BlinkID.xcframework to your project folder.
In your Xcode project, open the Project navigator. Drag the BlinkID.xcframework file to your project, ideally in the Frameworks group, together with other frameworks you're using. When asked, choose "Create groups", instead of the "Create folder references" option.

Adding BlinkID.xcframework to your project

Since BlinkID.xcframework is a dynamic framework, you also need to add it to embedded binaries section in General settings of your target and choose option Embed & Sign.

Adding BlinkID.xcframework to embedded binaries

Include the additional frameworks and libraries into your project in the "Linked frameworks and libraries" section of your target settings.
- libc++.tbd
- libiconv.tbd
- libz.tbd

Adding Apple frameworks to your project

2. Referencing header file

In files in which you want to use scanning functionality place import directive.

Swift

import BlinkID

Objective-C

#import <BlinkID/BlinkID.h>

3. Initiating the scanning process

To initiate the scanning process, first decide where in your app you want to add scanning functionality. Usually, users of the scanning library have a button which, when tapped, starts the scanning process. Initialization code is then placed in touch handler for that button. Here we're listing the initialization code as it looks in a touch handler method.

Swift

class ViewController: UIViewController, MBBlinkIdOverlayViewControllerDelegate  {

    var blinkIdMultiSideRecognizer : MBBlinkIdMultiSideRecognizer?

    override func viewDidLoad() {
        super.viewDidLoad()

        MBMicroblinkSDK.shared().setLicenseResource("blinkid-license", withExtension: "txt", inSubdirectory: "", for: Bundle.main, errorCallback: block)
    }

    @IBAction func didTapScan(_ sender: AnyObject) {

        /** Create BlinkID recognizer */
        self.blinkIdMultiSideRecognizer = MBBlinkIdMultiSideRecognizer()

        /** Create BlinkID settings */
        let settings : MBBlinkIdOverlaySettings = MBBlinkIdOverlaySettings()

        /** Crate recognizer collection */
        let recognizerList = [self.blinkIdMultiSideRecognizer!]
        let recognizerCollection : MBRecognizerCollection = MBRecognizerCollection(recognizers: recognizerList)

        /** Create your overlay view controller */
        let blinkIdOverlayViewController : MBBlinkIdOverlayViewController = MBBlinkIdOverlayViewController(settings: settings, recognizerCollection: recognizerCollection, delegate: self)

        /** Create recognizer view controller with wanted overlay view controller */
        let recognizerRunneViewController : UIViewController = MBViewControllerFactory.recognizerRunnerViewController(withOverlayViewController: blinkIdOverlayViewController)

        /** Present the recognizer runner view controller. You can use other presentation methods as well (instead of presentViewController) */
        self.present(recognizerRunneViewController, animated: true, completion: nil)
    }
}

Objective-C

@interface ViewController () <MBBlinkIdOverlayViewControllerDelegate>

@property (nonatomic, strong) MBBlinkIdMultiSideRecognizer *blinkIdMultiSideRecognizer;

@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    [MBMicroblinkSDK.sharedInstance setLicenseResource:@"blinkid-license" withExtension:@"txt" inSubdirectory:@"" for:Bundle.main errorCallback:block];
}


- (IBAction)didTapScan:(id)sender {

    /** Create BlinkID recognizer */
    self.blinkIdMultiSideRecognizer = [[MBBlinkIdMultiSideRecognizer alloc] init];

     /** Create BlinkID settings */
    MBBlinkIdOverlaySettings* settings = [[MBBlinkIdOverlaySettings alloc] init];

    /** Create recognizer collection */
    MBRecognizerCollection *recognizerCollection = [[MBRecognizerCollection alloc] initWithRecognizers:@[self.blinkIdMultiSideRecognizer]];

    /** Create your overlay view controller */
    MBBlinkIdOverlayViewController *blinkIdOverlayViewController = [[MBBlinkIdOverlayViewController alloc] initWithSettings:settings recognizerCollection:recognizerCollection delegate:self];

    /** Create recognizer view controller with wanted overlay view controller */
    UIViewController<MBRecognizerRunnerViewController>* recognizerRunnerViewController = [MBViewControllerFactory recognizerRunnerViewControllerWithOverlayViewController:blinkIdOverlayViewController];

    /** Present the recognizer runner view controller. You can use other presentation methods as well (instead of presentViewController) */
    [self presentViewController:recognizerRunnerViewController animated:YES completion:nil];

}

@end

4. License key

A valid license key is required to initialize scanning. You can request a free trial license key, after you register, at Microblink Developer Hub.

You can include the license key in your app by passing a string or a file with license key.
Note that you need to set the license key before intializing scanning. Ideally in AppDelegate or viewDidLoad before initializing any recognizers.

License key as string

You can pass the license key as a string, the following way:

Swift

MBMicroblinkSDK.shared().setLicenseKey("LICENSE-KEY", errorCallback: block)

Objective-C

[[MBMicroblinkSDK sharedInstance] setLicenseKey:@"LICENSE-KEY" errorCallback:block];

License key as file

Or you can include the license key, with the code below. Please make sure that the file that contains the license key is included in your project and is copied during Copy Bundle Resources build phase.

Swift

MBMicroblinkSDK.shared().setLicenseResource("license-key-file", withExtension: "txt", inSubdirectory: "directory-to-license-key", for: Bundle.main, errorCallback: block)

Objective-C

[[MBMicroblinkSDK sharedInstance] setLicenseResource:@"license-key-file" withExtension:@"txt" inSubdirectory:@"" forBundle:[NSBundle mainBundle] errorCallback:block];

If the licence is invalid or expired then the methods above will throw an exception.

5. Registering for scanning events

In the previous step, you instantiated MBBlinkIdOverlayViewController object with a delegate object. This object gets notified on certain events in scanning lifecycle. In this example we set it to self. The protocol which the delegate has to implement is MBBlinkIdOverlayViewControllerDelegate protocol. It is necessary to conform to that protocol. We will discuss more about protocols in Advanced integration section. You can use the following default implementation of the protocol to get you started.

Swift

func blinkIdOverlayViewControllerDidFinishScanning(_ blinkIdOverlayViewController: MBBlinkIdOverlayViewController, state: MBRecognizerResultState) {

    // this is done on background thread
    // check for valid state
    if state == .valid {

        // first, pause scanning until we process all the results
        blinkIdOverlayViewController.recognizerRunnerViewController?.pauseScanning()

        DispatchQueue.main.async(execute: {() -> Void in
            // All UI interaction needs to be done on main thread
        })
    }
}

func blinkIdOverlayViewControllerDidTapClose(_ blinkIdOverlayViewController: MBBlinkIdOverlayViewController) {
    // Your action on cancel
}

Objective-C

- (void)blinkIdOverlayViewControllerDidFinishScanning:(MBBlinkIdOverlayViewController *)blinkIdOverlayViewController state:(MBRecognizerResultState)state {

    // this is done on background thread
    // check for valid state
    if (state == MBRecognizerResultStateValid) {

        // first, pause scanning until we process all the results
        [blinkIdOverlayViewController.recognizerRunnerViewController pauseScanning];

        dispatch_async(dispatch_get_main_queue(), ^{
            // All UI interaction needs to be done on main thread
        });
    }
}

- (void)blinkIdOverlayViewControllerDidTapClose:(nonnull MBBlinkIdOverlayViewController *)blinkIdOverlayViewController {
    // Your action on cancel
}

Advanced BlinkID integration instructions

This section covers more advanced details of BlinkID integration.

First part will cover the possible customizations when using UI provided by the SDK.
Second part will describe how to embed MBRecognizerRunnerViewController's delegates into your UIViewController with the goal of creating a custom UI for scanning, while still using camera management capabilites of the SDK.
Third part will describe how to use the MBRecognizerRunner (Direct API) for recognition directly from UIImage without the need of camera or to recognize camera frames that are obtained by custom camera management.
Fourth part will describe recognizer concept and available recognizers.

Built-in overlay view controllers and overlay subviews

Within BlinkID SDK there are several built-in overlay view controllers and scanning subview overlays that you can use to perform scanning.

Using `MBBlinkIdOverlayViewController`

MBBlinkIdOverlayViewController implements new UI for scanning identity documents, which is optimally designed to be used with new MBBlinkIdSingleSideRecognizer and MBBlinkIdMultiSideRecognizer. The new MBBlinkIdOverlayViewController implements several new features:

clear indication for searching phase, when BlinkID is searching for an ID document
clear progress indication, when BlinkID is busy with OCR and data extraction
clear message when the document is not supported
visual indications when the user needs to place the document closer to the camera
when MBBlinkIdMultiSideRecognizer is used, visual indication that the data from the front side of the document doesn't match the data on the back side of the document.

The new UI allows the user to scan the document at an any angle, in any orientation. We recommend forcing landscape orientation if you scan barcodes on the back side, because in that orientation success rate will be higher.
To force the UI in landscape mode, use the following instructions:

Swift

let settings = MBBlinkIdOverlaySettings()
settings.autorotateOverlay = true
settings.supportedOrientations = UIInterfaceOrientationMask.landscape

Objective-C

MBBlinkIdOverlaySettings *settings = [[MBBlinkIdOverlaySettings alloc] init];
settings.autorotateOverlay = YES;
settings.supportedOrientations = UIInterfaceOrientationMaskLandscape;

It has MBBlinkIdOverlayViewControllerDelegate delegate which can be used out-of-the-box to perform scanning using the default UI. Here is an example how to use and initialize MBBlinkIdOverlayViewController:

Swift

/** Create your overlay view controller */
let blinkIdOverlayViewController : MBBlinkIdOverlayViewController = MBBlinkIdOverlayViewController(settings: blinkIdSettings, recognizerCollection: recognizerCollection, delegate: self)

/** Create recognizer view controller with wanted overlay view controller */
let recognizerRunneViewController : UIViewController = MBViewControllerFactory.recognizerRunnerViewController(withOverlayViewController: blinkIdOverlayViewController)

/** Present the recognizer runner view controller. You can use other presentation methods as well (instead of presentViewController) */
self.present(recognizerRunneViewController, animated: true, completion: nil)

Objective-C

MBBlinkIdOverlayViewController *overlayVC = [[MBBlinkIdOverlayViewController alloc] initWithSettings:settings recognizerCollection: recognizerCollection delegate:self];
UIViewController<MBRecognizerRunnerViewController>* recognizerRunnerViewController = [MBViewControllerFactory recognizerRunnerViewControllerWithOverlayViewController:overlayVC];

/** Present the recognizer runner view controller. You can use other presentation methods as well (instead of presentViewController) */
[self presentViewController:recognizerRunnerViewController animated:YES completion:nil];

As you can see, when initializing MBBlinkIdOverlayViewController, we are sending delegate property as self. To get results, we need to conform to MBBlinkIdOverlayViewControllerDelegate protocol.

Customizing the look

The SDK comes with the ability to customize some aspects of the UI by using the UI theming. The screens can be customized to fit your app’s look and feel by defining themes in your application that override themes from the SDK. Each theme must extend the corresponding base theme from the SDK, as described in the following sections.

BlinkID Overlay Theme

BlinkIDOverlayTheme

BlinkIDOverlayThemeSuccess

To customize MBBlinkIdOverlayViewController, use MBBlinkIdOverlayTheme class to customize your look. You can customise elements labeled on the screenshot above by providing wanted properties to MBBlinkIdOverlayTheme:

reticle
- reticleErrorColor - change custom error UIColor
instructions
- instructionsFont - set custom UIFont
- instructionsTextColor - set custom UIColor
- instructionsCornerRadius - set custom corner radius
flashlightWarning
- flashlightWarningFont - set custom UIFont
- flashlightWarningBackgroundColor - set custom background UIColor
- flashlightWarningTextColor - set custom text UIColor
- flashlightWarningCornerRadius - set custom corner radius
cardIcon
- frontCardImage - change front card image on flip
- backCardImage - change back card image on flip
successIcon
- successScanningImage - change success scan image
- successFlashColor - change flash color on success scanning

Custom overlay view controller

Please check our Samples for custom implementation of overlay view controller.

Overlay View Controller is an abstract class for all overlay views.

It's responsibility is to provide meaningful and useful interface for the user to interact with.

Typical actions which need to be allowed to the user are:

intuitive and meaniningful way to guide the user through scanning process. This is usually done by presenting a "viewfinder" in which the user need to place the scanned object
a way to cancel the scanning, typically with a "cancel" or "back" button
a way to power on and off the light (i.e. "torch") button

BlinkID SDK always provides it's own default implementation of the Overlay View Controller for every specific use. Your implementation should closely mimic the default implementation as it's the result of thorough testing with end users. Also, it closely matches the underlying scanning technology.

For example, the scanning technology usually gives results very fast after the user places the device's camera in the expected way above the scanned object. This means a progress bar for the scan is not particularly useful to the user. The majority of time the user spends on positioning the device's camera correctly. That's just an example which demonstrates careful decision making behind default camera overlay view.

1. Subclassing

To use your custom overlay with Microblink's camera view, you must first subclass MBCustomOverlayViewController and implement the overlay behaviour conforming wanted protocols.

2. Protocols

There are seven MBRecognizerRunnerViewController protocols.

Seven RecognizerRunnerViewController protocols are:

In viewDidLoad, other protocol conformation can be done and it's done on recognizerRunnerViewController property of MBOverlayViewController, for example:

Swift and Objective-C

self.scanningRecognizerRunnerViewControllerDelegate = self;

3. Initialization

In Quick Start guide it is shown how to use a default overlay view controller. You can now swap default view controller with your implementation of CustomOverlayViewController

Swift

let recognizerRunnerViewController : UIViewController = MBViewControllerFactory.recognizerRunnerViewController(withOverlayViewController: CustomOverlayViewController)

Objective-C

UIViewController<MBRecognizerRunnerViewController>* recognizerRunnerViewController = [MBViewControllerFactory recognizerRunnerViewControllerWithOverlayViewController:CustomOverlayViewController];

Direct processing API

This guide will in short present you how to process UIImage objects with BlinkID SDK, without starting the camera video capture.

With this feature you can solve various use cases like:
- recognizing text on images in Camera roll
- taking full resolution photo and sending it to processing
- scanning barcodes on images in e-mail etc.

DirectAPI-sample demo app here will present UIImagePickerController for taking full resolution photos, and then process it with BlinkID SDK to get scanning results using Direct processing API.

Direct processing API is handled with MBRecognizerRunner. That is a class that handles processing of images. It also has protocols as MBRecognizerRunnerViewController.
Developer can choose which protocol to conform:

In example, we are conforming to MBScanningRecognizerRunnerDelegate protocol.

Swift

func setupRecognizerRunner() {
    var recognizers = [MBRecognizer]()
    recognizer = MBBlinkIdMultiSideRecognizer()
    recognizers.append(recognizer!)
    let recognizerCollection = MBRecognizerCollection(recognizers: recognizers)
    recognizerRunner = MBRecognizerRunner(recognizerCollection: recognizerCollection)
    recognizerRunner?.scanningRecognizerRunnerDelegate = self
}

func processImageRunner(_ originalImage: UIImage) {
    var image: MBImage? = nil
    if let anImage = originalImage {
        image = MBImage(uiImage: anImage)
    }
    image?.cameraFrame = true
    image?.orientation = MBProcessingOrientation.left
    let _serialQueue = DispatchQueue(label: "com.microblink.DirectAPI-sample-swift")
    _serialQueue.async(execute: {() -> Void in
        self.recognizerRunner?.processImage(image!)
    })
}

func recognizerRunner(_ recognizerRunner: MBRecognizerRunner, didFinishScanningWith state: MBRecognizerResultState) {
    if blinkInputRecognizer.result.resultState == MBRecognizerResultStateValid {
        // Handle result
    }
}

Objective-C

- (void)setupRecognizerRunner {
    NSMutableArray<MBRecognizer *> *recognizers = [[NSMutableArray alloc] init];

    self.recognizer = [[MBBlinkIdMultiSideRecognizer alloc] init];

    [recognizers addObject: self.recognizer];

    MBRecognizerCollection *recognizerCollection = [[MBRecognizerCollection alloc] initWithRecognizers:recognizers];

    self.recognizerRunner = [[MBRecognizerRunner alloc] initWithRecognizerCollection:recognizerCollection];
    self.recognizerRunner.scanningRecognizerRunnerDelegate = self;
}

- (void)processImageRunner:(UIImage *)originalImage {
    MBImage *image = [MBImage imageWithUIImage:originalImage];
    image.cameraFrame = YES;
    image.orientation = MBProcessingOrientationLeft;
    dispatch_queue_t _serialQueue = dispatch_queue_create("com.microblink.DirectAPI-sample", DISPATCH_QUEUE_SERIAL);
    dispatch_async(_serialQueue, ^{
        [self.recognizerRunner processImage:image];
    });
}

- (void)recognizerRunner:(nonnull MBRecognizerRunner *)recognizerRunner didFinishScanningWithState:(MBRecognizerResultState)state {
    if (self.blinkInputRecognizer.result.resultState == MBRecognizerResultStateValid) {
        // Handle result
    }
}

Now you've seen how to implement the Direct processing API.

In essence, this API consists of two steps:

Initialization of the scanner.
Call of - (void)processImage:(MBImage *)image; method for each UIImage or CMSampleBufferRef you have.

Using Direct API for `NSString` recognition (parsing)

Some recognizers support recognition from NSString. They can be used through Direct API to parse given NSString and return data just like when they are used on an input image. When recognition is performed on NSString, there is no need for the OCR. Input NSString is used in the same way as the OCR output is used when image is being recognized.
Recognition from String can be performed in the same way as recognition from image.
The only difference is that user should call - (void)processString:(NSString *)string; on MBRecognizerRunner.

Understanding DirectAPI's state machine

DirectAPI's RecognizerRunner singleton is a state machine that can be in one of 3 states: OFFLINE, READY and WORKING.

When you obtain the reference to RecognizerRunner singleton, it will be in OFFLINE state.
You can initialize RecognizerRunner by calling initinitWithRecognizerCollection:) method. If you call initialize method while RecognizerRunner is not in OFFLINE state, you will get IllegalStateException.
After successful initialization, RecognizerRunner will move to READY state. Now you can call any of the recognize* methods.
When starting recognition with any of the recognize* methods, RecognizerRunner will move to WORKING state. If you attempt to call these methods while RecognizerRunner is not in READY state, you will get IllegalStateException
Recognition is performed on background thread so it is safe to call all RecognizerRunner's methods from UI thread
When recognition is finished, RecognizerRunner first moves back to READY state and then calls the recognizerRunner(_ :, didFinishScanningWith:) method of the provided MBScanningRecognizerRunnerDelegate.
Please note that MBScanningRecognizerRunnerDelegate's recognizerRunner(_ :, didFinishScanningWith:) method will be called on background processing thread, so make sure you do not perform UI operations in this callback. Also note that until the recognizerRunner(_ :, didFinishScanningWith:) method completes, RecognizerRunner will not perform recognition of another image or string, even if any of the recognize* methods have been called just after transitioning to READY state. This is to ensure that results of the recognizers associated with RecognizerRunner are not modified while possibly being used within recognizerRunner(_ :, didFinishScanningWith:) method.
By calling resetState method, RecognizerRunner singleton will release all its internal resources. Note that even after calling resetState you might receive recognizerRunner(_ :, didFinishScanningWith:) event if there was work in progress when resetState was called.
resetState method can be called from any RecognizerRunner singleton's state

Using DirectAPI while `RecognizerRunnerView` is active

Both RecognizerRunnerView and RecognizerRunner use the same internal singleton that manages native code. This singleton handles initialization and termination of native library and propagating recognizers to native library. It is possible to use RecognizerRunnerView and RecognizerRunner together, as internal singleton will make sure correct synchronization and correct recognition settings are used. If you run into problems while using RecognizerRunner in combination with RecognizerRunnerView, let us know!

Using Direct API with combined recognizers

When you are using combined recognizer and images of both document sides are required, you need to call RecognizerRunner.recognize* multiple times. Call it first with the images of the first side of the document, until it is read, and then with the images of the second side. The combined recognizer automatically switches to second side scanning, after it has successfully read the first side. To be notified when the first side scanning is completed, you have to set the MBFirstSideFinishedRecognizerRunnerDelegate through MBRecognizerRunnerMetadataDelegates. If you don't need that information, e.g. when you have only one image for each document side, don't set the MBFirstSideFinishedRecognizerRunnerDelegate and check the RecognitionSuccessType in MBScanningRecognizerRunnerDelegate.recognizerRunner(_ :, didFinishScanningWith:), after the second side image has been processed.

`MBRecognizer` and available recognizers

The `MBRecognizer` concept

The MBRecognizer is the basic unit of processing within the SDK. Its main purpose is to process the image and extract meaningful information from it. As you will see later, the SDK has lots of different MBRecognizer objects that have various purposes.

Each MBRecognizer has a MBRecognizerResult object, which contains the data that was extracted from the image. The MBRecognizerResult object is a member of corresponding MBRecognizer object its lifetime is bound to the lifetime of its parent MBRecognizer object. If you need your MBRecognizerResult object to outlive its parent MBRecognizer object, you must make a copy of it by calling its method copy.

While MBRecognizer object works, it changes its internal state and its result. The MBRecognizer object's MBRecognizerResult always starts in Empty state. When corresponding MBRecognizer object performs the recognition of given image, its MBRecognizerResult can either stay in Empty state (in case MBRecognizerfailed to perform recognition), move to Uncertain state (in case MBRecognizer performed the recognition, but not all mandatory information was extracted) or move to Valid state (in case MBRecognizer performed recognition and all mandatory information was successfully extracted from the image).

As soon as one MBRecognizer object's MBRecognizerResult within MBRecognizerCollection given to MBRecognizerRunner or MBRecognizerRunnerViewController changes to Valid state, the onScanningFinished callback will be invoked on same thread that performs the background processing and you will have the opportunity to inspect each of your MBRecognizer objects' MBRecognizerResult to see which one has moved to Valid state.

As soon as onScanningFinished method ends, the MBRecognizerRunnerViewController will continue processing new camera frames with same MBRecognizer objects, unless paused. Continuation of processing or reset recognition will modify or reset all MBRecognizer objects's MBRecognizerResult. When using built-in activities, as soon as onScanningFinished is invoked, built-in activity pauses the MBRecognizerRunnerViewController and starts finishing the activity, while saving the MBRecognizerCollection with active MBRecognizer.

`MBRecognizerCollection` concept

The MBRecognizerCollection is is wrapper around MBRecognizer objects that has array of MBRecognizer objects that can be used to give MBRecognizer objects to MBRecognizerRunner or MBRecognizerRunnerViewController for processing.

The MBRecognizerCollection is always constructed with array [[MBRecognizerCollection alloc] initWithRecognizers:recognizers] of MBRecognizer objects that need to be prepared for recognition (i.e. their properties must be tweaked already).

The MBRecognizerCollection manages a chain of MBRecognizer objects within the recognition process. When a new image arrives, it is processed by the first MBRecognizer in chain, then by the second and so on, iterating until a MBRecognizer object's MBRecognizerResult changes its state to Valid or all of the MBRecognizer objects in chain were invoked (none getting a Valid result state).

You cannot change the order of the MBRecognizer objects within the chain - no matter the order in which you give MBRecognizer objects to MBRecognizerCollection, they are internally ordered in a way that provides best possible performance and accuracy. Also, in order for SDK to be able to order MBRecognizer objects in recognition chain in a best way possible, it is not allowed to have multiple instances of MBRecognizer objects of the same type within the chain. Attempting to do so will crash your application.

List of available recognizers

This section will give a list of all MBRecognizer objects that are available within BlinkID SDK, their purpose and recommendations how they should be used to get best performance and user experience.

Frame Grabber Recognizer

The MBFrameGrabberRecognizer is the simplest recognizer in SDK, as it does not perform any processing on the given image, instead it just returns that image back to its onFrameAvailable. Its result never changes state from empty.

This recognizer is best for easy capturing of camera frames with MBRecognizerRunnerViewController. Note that MBImage sent to onFrameAvailable are temporary and their internal buffers all valid only until the onFrameAvailable method is executing - as soon as method ends, all internal buffers of MBImage object are disposed. If you need to store MBImage object for later use, you must create a copy of it by calling copy.

Success Frame Grabber Recognizer

The MBSuccessFrameGrabberRecognizer is a special MBecognizer that wraps some other MBRecognizer and impersonates it while processing the image. However, when the MBRecognizer being impersonated changes its MBRecognizerResult into Valid state, the MBSuccessFrameGrabberRecognizer captures the image and saves it into its own MBSuccessFrameGrabberRecognizerResult object.

Since MBSuccessFrameGrabberRecognizer impersonates its slave MBRecognizer object, it is not possible to give both concrete MBRecognizer object and MBSuccessFrameGrabberRecognizer that wraps it to same MBRecognizerCollection - doing so will have the same result as if you have given two instances of same MBRecognizer type to the MBRecognizerCollection - it will crash your application.

This recognizer is best for use cases when you need to capture the exact image that was being processed by some other MBRecognizer object at the time its MBRecognizerResult became Valid. When that happens, MBSuccessFrameGrabberRecognizer's MBSuccessFrameGrabberRecognizerResult will also become Valid and will contain described image.

BlinkID recognizers

Unless stated otherwise for concrete recognizer, single side BlinkID recognizes from this list can be used in any context, but they work best with the MBDocumentOverlayViewController, which has UI best suited for document scanning.

Combined recognizers should be used with MBDocumentVerificationOverlayViewController which manages scanning of multiple document sides in the single camera opening and guides the user through the scanning process. Some combined recognizers support scanning of multiple document types, but only one document type can be scanned at a time.

Machine Readable Travel Document recognizer

The MBMrtdRecognizer is used for scanning and data extraction from the Machine Readable Zone (MRZ) of the various Machine Readable Travel Documents (MRTDs) like ID cards and passports. This recognizer is not bound to the specific country, but it can be configured to only return data that match some criteria defined by the MBMrzFilter.