Microblink

PhotoPay SDK for payment slips scanning

PhotoPay SDK is a delightful component for quick and easy scanning of payment slips and payment barcodes. The SDK is powered with Microblink’s industry-proven and world leading OCR and barcode scanning technology, and offers:

  • integrated camera management
  • layered API, allowing everything from simple integration to complex UX customizations.
  • lightweight and no internet connection required
  • enteprise-level security standards
  • data parsing from payment slips and barcode standards

PhotoPay is a part of family of SDKs developed by Microblink for optical text recognition, barcode scanning, ID document scanning, payment slips and barcodes and many others.

Table of contents

Requirements

SDK package contains PhotoPay framework and one or more sample apps which demonstrate framework integration. The framework can be deployed in iOS 13.0 or later. NOTE: The SDK doesn’t contain bitcode anymore.

Quick Start

Getting started with PhotoPay 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 sets up basic Raw OCR parsing and price parsing at the same time. It closely follows the BlinkOCR-sample app. 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

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

OR

Clone this git repository:

Since

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 git@github.com:PhotoPay/photopay-ios.git

  • Copy PhotoPay.xcframework to your project folder.

  • In your Xcode project, open the Project navigator. Drag the PhotoPay.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 PhotoPay.xcframework to your project

Since

Since PhotoPay.xcframework is a dynamic framework, you also need to add it to embedded binaries section in General settings of your target.

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

Objective-C

#import <PhotoPay/PhotoPay.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.

Also, for initialization purposes, the ViewController which initiates the scan have private properties for MBPCroatiaPdf417PaymentRecognizer, so we know how to obtain result.

Swift

class ViewController: UIViewController, MBPPhotopayOverlayViewControllerDelegate  {

    var croPdf417PaymentRecognizer: MBPCroatiaPdf417PaymentRecognizer?

    override func viewDidLoad() {
        super.viewDidLoad()
    }

    @IBAction func didTapScan(_ sender: AnyObject) {

        let settings = MBPPhotopayOverlaySettings()
        croPdf417PaymentRecognizer = MBPCroatiaPdf417PaymentRecognizer()

        let recognizerList = [self.croPdf417PaymentRecognizer!]
        let recognizerCollection = MBPRecognizerCollection(recognizers: recognizerList)

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

        /** Create recognizer view controller with wanted overlay view controller */
        let recognizerRunnerViewController: UIViewController = MBPViewControllerFactory.recognizerRunnerViewController(withOverlayViewController: photopayOverlayViewController)

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

Objective-C

@interface ViewController () <MBPPhotopayOverlayViewControllerDelegate>

@property (nonatomic, strong) MBPCroatiaPdf417PaymentRecognizer *croPdf417PaymentRecognizer;

@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
}


- (IBAction)didTapScan:(id)sender {

    MBPPhotopayOverlaySettings* settings = [[MBPPhotopayOverlaySettings alloc] init];

    self.croPdf417PaymentRecognizer = [[MBPCroatiaPdf417PaymentRecognizer  alloc] init];

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

    MBPPhotopayOverlayViewController *overlayVC = [[MBPPhotopayOverlayViewController alloc] initWithSettings:settings recognizerCollection:recognizerCollection delegate:self];
    UIViewController<MBPRecognizerRunnerViewController>* recognizerRunnerViewController = [MBPViewControllerFactory 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];

}

@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

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

Objective-C

[[MBPMicroblinkSDK 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

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

Objective-C

[[MBPMicroblinkSDK sharedInstance] setLicenseResource:@"license-key-file" withExtension:@"key" 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 MBPPhotopayOverlayViewController 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 MBPPhotopayOverlayViewControllerDelegate 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 photopayOverlayViewControllerDidFinishScanning(_ photopayOverlayViewController: MBPPhotopayOverlayViewController, state: MBPRecognizerResultState) {

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

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

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

func photopayOverlayViewControllerDidTapClose(_ photopayOverlayViewController: MBPPhotopayOverlayViewController) {
    // Your action on cancel
}

Objective-C

- (void)photopayOverlayViewControllerDidFinishScanning:(MBPPhotopayOverlayViewController *)photopayOverlayViewController state:(MBPRecognizerResultState)state {

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

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

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

- (void)photopayOverlayViewControllerDidTapClose:(MBPPhotopayOverlayViewController *)photopayOverlayViewController {
    // Your action on cancel
}

Advanced PhotoPay integration instructions

This section covers more advanced details of PhotoPay integration.

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

Built-in overlay view controllers and overlay subviews

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

Using MBPBarcodeOverlayViewController

MBPBarcodeOverlayViewController is overlay view controller best suited for performing scanning of various barcodes. It has MBPBarcodeOverlayViewControllerDelegate 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 MBPBarcodeOverlayViewController:

Swift

/** Create your overlay view controller */
let barcodeOverlayViewController : MBPBarcodeOverlayViewController = MBPBarcodeOverlayViewController(settings: barcodeSettings, recognizerCollection: recognizerCollection, delegate: self)

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

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

MBPBarcodeOverlayViewController *overlayVC = [[MBPBarcodeOverlayViewController alloc] initWithSettings:settings recognizerCollection: recognizerCollection delegate:self];
UIViewController<MBPRecognizerRunnerViewController>* recognizerRunnerViewController = [MBPViewControllerFactory 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 MBPBarcodeOverlayViewController, we are sending delegate property as self. To get results, we need to conform to MBPBarcodeOverlayViewControllerDelegate protocol.

Using MBPFieldByFieldOverlayViewController

MBPFieldByFieldOverlayViewController is overlay view controller best suited for performing scanning of various payment slips and barcodes with field of view. It has MBPFieldByFieldOverlayViewControllerDelegate 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 MBPFieldByFieldOverlayViewController:

Swift

/** Create your overlay view controller */
let fieldByFieldOverlayViewController : MBPFieldByFieldOverlayViewController = MBPFieldByFieldOverlayViewController(settings: fieldByFieldOverlaySettings, recognizerCollection: recognizerCollection, delegate: self)

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

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

MBPFieldByFieldOverlayViewController *overlayVC = [[MBPFieldByFieldOverlayViewController alloc] initWithSettings:settings recognizerCollection: recognizerCollection delegate:self];
UIViewController<MBPRecognizerRunnerViewController>* recognizerRunnerViewController = [MBPViewControllerFactory 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 MBPFieldByFieldOverlayViewController, we are sending delegate property as self. To get results, we need to conform to MBPFieldByFieldOverlayViewControllerDelegate protocol.

Using MBPPhotopayOverlayViewController

MBPPhotopayOverlayViewController is overlay view controller best suited for performing scanning of various payment slips and barcodes. It has MBPPhotopayOverlayViewControllerDelegate 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 MBPPhotopayOverlayViewController:

Swift

/** Create your overlay view controller */
let photopayOverlayViewController : MBPPhotopayOverlayViewController = MBPPhotopayOverlayViewController(settings: photopayOverlaySttings, recognizerCollection: recognizerCollection, delegate: self)

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

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

MBPPhotopayOverlayViewController *overlayVC = [[MBPPhotopayOverlayViewController alloc] initWithSettings:settings recognizerCollection: recognizerCollection delegate:self];
UIViewController<MBPRecognizerRunnerViewController>* recognizerRunnerViewController = [MBPViewControllerFactory 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 MBPPhotopayOverlayViewController, we are sending delegate property as self. To get results, we need to conform to MBPPhotopayOverlayViewControllerDelegate protocol.

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.

Its 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

PhotoPay 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 MBPCustomOverlayViewController and implement the overlay behaviour conforming wanted protocols.

2. Protocols

There are five MBPRecognizerRunnerViewController protocols and one overlay protocol MBPPhotoPayOverlayViewControllerDelegate.

Five RecognizerRunnerViewController protocols are:

In viewDidLoad, other protocol conformation can be done and it’s done on recognizerRunnerViewController property of MBPOverlayViewController, 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 = MBPViewControllerFactory.recognizerRunnerViewController(withOverlayViewController: CustomOverlayViewController)

Objective-C

UIViewController<MBPRecognizerRunnerViewController>* recognizerRunnerViewController = [MBPViewControllerFactory recognizerRunnerViewControllerWithOverlayViewController:CustomOverlayViewController];

Direct processing API

This guide will in short present you how to process UIImage objects with PhotoPay 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 PhotoPay SDK to get scanning results using Direct processing API.

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

In example, we are conforming to MBPScanningRecognizerRunnerDelegate protocol.

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

func setupRecognizerRunner() {
    var recognizers = [MBPRecognizer]()
    pdf417Recognizer = MBPPdf417Recognizer()
    recognizers.append(pdf417Recognizer!)
    let recognizerCollection = MBPRecognizerCollection(recognizers: recognizers)
    recognizerRunner = MBPRecognizerRunner(recognizerCollection: recognizerCollection)
    recognizerRunner?.scanningRecognizerRunnerDelegate = self
}

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

func recognizerRunner(_ recognizerRunner: MBPRecognizerRunner, didFinishScanningWith state: MBPRecognizerResultState) {
    if blinkInputRecognizer.result.resultState == MBPRecognizerResultStateValid {
        // Handle result
    }
}

Objective-C

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

    self.pdf417Recognizer = [[MBPPdf417Recognizer alloc] init];

    [recognizers addObject: self.pdf417Recognizer];

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

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

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

- (void)recognizerRunner:(nonnull MBPRecognizerRunner *)recognizerRunner didFinishScanningWithState:(MBPRecognizerResultState)state {
    if (self.blinkInputRecognizer.result.resultState == MBPRecognizerResultStateValid) {
        // 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:(MBPImage *)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 MBPRecognizerRunner.

MBPRecognizer and available recognizers

The MBPRecognizer concept

The MBPRecognizer 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 MBPRecognizer objects that have various purposes.

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

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

As soon as one MBPRecognizer object’s MBPRecognizerResult within MBPRecognizerCollection given to MBPRecognizerRunner or MBPRecognizerRunnerViewController 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 MBPRecognizer objects’ MBPRecognizerResult to see which one has moved to Valid state.

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

MBPRecognizerCollection concept

The MBPRecognizerCollection is is wrapper around MBPRecognizer objects that has array of MBPRecognizer objects that can be used to give MBPRecognizer objects to MBPRecognizerRunner or MBPRecognizerRunnerViewController for processing.

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

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

You cannot change the order of the MBPRecognizer objects within the chain - no matter the order in which you give MBPRecognizer objects to MBPRecognizerCollection, they are internally ordered in a way that provides best possible performance and accuracy. Also, in order for SDK to be able to order MBPRecognizer objects in recognition chain in a best way possible, it is not allowed to have multiple instances of MBPRecognizer 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 MBPRecognizer objects that are available within PhotoPay SDK, their purpose and recommendations how they should be used to get best performance and user experience.

Frame Grabber Recognizer

The MBPFrameGrabberRecognizer 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 MBPRecognizerRunnerViewController. Note that MBPImage 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 MBPImage object are disposed. If you need to store MBPImage object for later use, you must create a copy of it by calling copy.

Success Frame Grabber Recognizer

The MBPSuccessFrameGrabberRecognizer is a special MBPecognizer that wraps some other MBPRecognizer and impersonates it while processing the image. However, when the MBPRecognizer being impersonated changes its MBPRecognizerResult into Valid state, the MBPSuccessFrameGrabberRecognizer captures the image and saves it into its own MBPSuccessFrameGrabberRecognizerResult object.

Since MBPSuccessFrameGrabberRecognizer impersonates its slave MBPRecognizer object, it is not possible to give both concrete MBPRecognizer object and MBPSuccessFrameGrabberRecognizer that wraps it to same MBPRecognizerCollection - doing so will have the same result as if you have given two instances of same MBPRecognizer type to the MBPRecognizerCollection - 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 MBPRecognizer object at the time its MBPRecognizerResult became Valid. When that happens, MBPSuccessFrameGrabberRecognizer's MBPSuccessFrameGrabberRecognizerResult will also become Valid and will contain described image.

PDF417 recognizer

The MBPPdf417Recognizer is recognizer specialised for scanning PDF417 2D barcodes. This recognizer can recognize only PDF417 2D barcodes - for recognition of other barcodes, please refer to BarcodeRecognizer.

This recognizer can be used in any overlay view controller, but it works best with the MBPBarcodeOverlayViewController, which has UI best suited for barcode scanning.

Barcode recognizer

The MBPBarcodeRecognizer is recognizer specialised for scanning various types of barcodes. This recognizer should be your first choice when scanning barcodes as it supports lots of barcode symbologies, including the PDF417 2D barcodes, thus making PDF417 recognizer possibly redundant, which was kept only for its simplicity.

You can enable multiple barcode symbologies within this recognizer, however keep in mind that enabling more barcode symbologies affect scanning performance - the more barcode symbologies are enabled, the slower the overall recognition performance. Also, keep in mind that some simple barcode symbologies that lack proper redundancy, such as Code 39, can be recognized within more complex barcodes, especially 2D barcodes, like PDF417.

This recognizer can be used in any overlay view controller, but it works best with the MBPBarcodeOverlayViewController, which has UI best suited for barcode scanning.

BlinkInput recognizer

The MBPBlinkInputRecognizer is generic OCR recognizer used for scanning segments which enables specifying MBPProcessors that will be used for scanning. Most commonly used MBPProcessor within this recognizer is MBPParserGroupProcessor) that activates all MBPParsers in the group to extract data of interest from the OCR result.

This recognizer can be used in any context. It is used internally in the implementation of the provided MBPFieldByFieldOverlayViewController.

MBPProcessors are explained in The Processor concept section and you can find more about MBPParsers in The Parser concept section.

PhotoPay recognizers by countries

Austria

The MBPAustriaQrCodePaymentRecognizer is recognizer specialised for scanning Austrian payment QR codes, such as Stuzza codes.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

The MBPAustriaSlipRecognizer is recognizer specialised for scanning Austrian payment slips.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

Belgium

The MBPBelgiumSlipRecognizer is recognizer specialised for scanning Belgian payment slips.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

Croatia

The MBPCroatiaPdf417PaymentRecognizer is recognizer specialised for scanning Croatia payment Pdf417 codes.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

The MBPCroatiaQrCodePaymentRecognizer is recognizer specialised for scanning Croatia payment QR codes.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

The MBPCroatiaSlipRecognizer is recognizer specialised for scanning Croatia payment slips.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

Czechia

The MBPCzechiaQrCodeRecognizer is recognizer specialised for scanning Czech payment QR codes.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

The MBPCzechiaSlipRecognizer is recognizer specialised for scanning Czech payment slips.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

Germany

The MBPGermanyQrCodePaymentRecognizer is recognizer specialised for scanning German payment QR codes.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

The MBPGermanySlipRecognizer is recognizer specialised for scanning German payment slips.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

Hungary

The MBPHungarySlipRecognizer is recognizer specialised for scanning Hungarian payment slips - white and yellow.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

Kosovo

The MBPKosovoSlipRecognizer is recognizer specialised for scanning Kosovo payment slips.

This recognizer can be used in any overlay view controller, but it works best with the MBPFieldOfViewOverlayViewController, which has UI best suited for payment slip and barcode scanning.

The MBPKosovoCode128PaymentRecognizer is recognizer specialised for scanning code 128 barcodes found on Kosovo payment slips.

This recognizer can be used in any overlay view controller, but it works best with the MBPFieldOfViewOverlayViewController, which has UI best suited for payment slip and barcode scanning.

Netherlands

The MBPNetherlandsSlipRecognizer is recognizer specialised for scanning Dutch payment slips.

This recognizer can be used in any overlay view controller, but it works best with the MBPFieldOfViewOverlayViewController, which has UI best suited for payment slip and barcode scanning.

SEPA

The MBPSepaQrCodePaymentRecognizer is recognizer specialised for scanning SEPA QR codes.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

Serbia

The MBPSerbiaQrCodeRecognizer is recognizer specialised for scanning Serbian QR payment barcodes.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

The MBPSerbiaPdf417Recognizer is recognizer specialised for scanning Serbian PDF 417 payment barcodes.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

Slovakia

The MBPSlovakiaCode128PaymentRecognizer is recognizer specialised for scanning Slovakian CODE 128 payment barcodes.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

The MBPSlovakiaDataMatrixPaymentRecognizer is recognizer specialised for scanning Slovakian Data Matrix payment barcodes.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

The MBPSlovakiaQrCodeRecognizer is recognizer specialised for scanning Slovakian QR payment barcodes.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

The MBPSlovakiaSlipRecognizer is recognizer specialised for scanning Slovakian payment slips.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

Slovenia

The MBPSloveniaSlipRecognizer is recognizer specialised for scanning Slovenian UPN payment slips.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

The MBPSloveniaQrCodePaymentRecognizer is recognizer specialised for scanning Slovenian QR payment barcodes.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

Switzerland

The MBPSwitzerlandQrCodePaymentRecognizer is recognizer specialised for scanning Swiss payment QR codes, such as Stuzza codes.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

The MBPSwitzerlandSlipRecognizer is recognizer specialised for scanning Swiss payment slips.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

United Kingdom

The MBPUnitedKingdomQrCodePaymentRecognizer is recognizer specialised for scanning UK payment QR codes.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

The MBPUnitedKingdomSlipRecognizer is recognizer specialised for scanning UK payment slips.

This recognizer can be used in any overlay view controller, but it works best with the MBPPhotopayOverlayViewController, which has UI best suited for payment slip and barcode scanning.

MBPProcessor and MBPParser

The MBPProcessors and MBPParsers are standard processing units within PhotoPay SDK used for data extraction from the input images. Unlike the MBPRecognizer, MBPProcessor and MBPParser are not stand-alone processing units. MBPProcessor is always used within MBPRecognizer and MBPParser is used within appropriate MBPProcessor to extract data from the OCR result.

The MBPProcessor concept

MBPProcessor is a processing unit used within some Recognizer which supports processors. It process the input image prepared by the enclosing Recognizer in the way that is characteristic to the implementation of the concrete MBPProcessor.

MBPProcessor architecture is similar to MBPRecognizer architecture described in The Recognizer concept section. Each instance also has associated inner MBPRecognizerResult object whose lifetime is bound to the lifetime of its parent MBPProcessor object and it is updated while MBPProcessor works. If you need your MBPRecognizerResult object to outlive its parent MBPProcessor object, you must make a copy of it by calling its method copy.

It also has its internal state and while it is in the working state during recognition process, it is not allowed to tweak MBPProcessor object’s properties.

To support common use cases, there are several different MBPProcessor implementations available. They are listed in the next section.

List of available processors

This section will give a list of MBPProcessor types that are available within PhotoPay SDK and their purpose.

Image Return Processor

The MBPImageReturnProcessor is used for obtaining input images. It simply saves the input image and makes it available after the scanning is done.

The appearance of the input image depends on the context in which MBPImageReturnProcessor is used. For example, when it is used within MBPBlinkInputRecognizer, simply the raw image of the scanning region is processed. When it is used within the Templating API, input image is dewarped (cropped and rotated).

The image is returned as the raw MBPImage type. Also, processor can be configured to encode saved image to JPEG.

Parser Group Processor

The MBPParserGroupProcessor is the type of the processor that performs the OCR (Optical Character Recognition) on the input image and lets all the parsers within the group to extract data from the OCR result. The concept of MBPParser is described in the next section.

Before performing the OCR, the best possible OCR engine options are calculated by combining engine options needed by each MBPParser from the group. For example, if one parser expects and produces result from uppercase characters and other parser extracts data from digits, both uppercase characters and digits must be added to the list of allowed characters that can appear in the OCR result. This is a simplified explanation because OCR engine options contain many parameters which are combined by the MBPParserGroupProcessor.

Because of that, if multiple parsers and multiple parser group processors are used during the scan, it is very important to group parsers carefully.

Let’s see this on an example: assume that we have two parsers at our disposal: MBPAmountParser and MBPEmailParser. MBPAmountParser knows how to extract amount’s from OCR result and requires from OCR only to recognize digits, periods and commas and ignore letters. On the other hand, MBPEmailParser knows how to extract e-mails from OCR result and requires from OCR to recognize letters, digits, ‘@’ characters and periods, but not commas.

If we put both MBPAmountParser and MBPEmailParser into the same MBPParserGroupProcessor, the merged OCR engine settings will require recognition of all letters, all digits, ‘@’ character, both period and comma. Such OCR result will contain all characters for MBPEmailParser to properly parse e-mail, but might confuse MBPAmountParser if OCR misclassifies some characters into digits.

If we put MBPAmountParser in one MBPParserGroupProcessor and MBPEmailParser in another MBPParserGroupProcessor, OCR will be performed for each parser group independently, thus preventing the MBPAmountParser confusion, but two OCR passes of the image will be performed, which can have a performance impact.

MBPParserGroupProcessor is most commonly used MBPProcessor. It is used whenever the OCR is needed. After the OCR is performed and all parsers are run, parsed results can be obtained through parser objects that are enclosed in the group. MBPParserGroupProcessor instance also has associated inner MBPParserGroupProcessorResult whose state is updated during processing and its property ocrLayout can be used to obtain the raw MBPOcrLayout that was used for parsing data.

Take note that MBPOcrLayout is available only if it is allowed by the PhotoPay SDK license key. MBPOcrLayout structure contains information about all recognized characters and their positions on the image. To prevent someone to abuse that, obtaining of the MBPOcrLayout structure is allowed only by the premium license keys.

The MBPParser concept

MBPParser is a class of objects that are used to extract structured data from the raw OCR result. It must be used within MBPParserGroupProcessor which is responsible for performing the OCR, so MBPParser is not stand-alone processing unit.

Like MBPRecognizer and all other processing units, each MBPParser instance has associated inner MBPRecognizerResult object whose lifetime is bound to the lifetime of its parent MBPParser object and it is updated while MBPParser works. When parsing is done MBPParserResult can be used for obtaining extracted data. If you need your MBPParserResult object to outlive its parent MBPParser object, you must make a copy of it by calling its method copy.

It also has its internal state and while it is in the working state during recognition process, it is not allowed to tweak MBPParser object’s properties.

There are a lot of different MBPParsers for extracting most common fields which appear on various documents. Also, most of them can be adjusted for specific use cases. For all other custom data fields, there is RegexParser available which can be configured with the arbitrary regular expression.

List of available parsers

Amount Parser

MBPAmountParser is used for extracting amounts from the OCR result.

Date Parser

MBPDateParser is used for extracting dates in various formats from the OCR result.

IBAN Parser

MBPIbanParser is used for extracting IBAN (International Bank Account Number) from the OCR result.

Raw Parser

MBPRawParser is used for obtaining string version of raw OCR result, without performing any smart parsing operations.

Regex Parser

MBPRegexParser is used for extracting OCR result content which is in accordance with the given regular expression. Regular expression parsing is not performed with java’s regex engine. Instead, it is performed with custom regular expression engine.

Other parsers

There are also other specialized parsers. You can see a list of all o them here.

Troubleshooting

Integration problems

In case of problems with integration of the SDK, first make sure that you have tried integrating it into Xcode by following integration instructions.

If you have followed Xcode integration instructions and are still having integration problems, please contact us at help.microblink.com.

SDK problems

In case of problems with using the SDK, you should do as follows:

Licencing problems

If you are getting “invalid licence key” error or having other licence-related problems (e.g. some feature is not enabled that should be or there is a watermark on top of camera), first check the console. All licence-related problems are logged to error log so it is easy to determine what went wrong.

When you have determine what is the licence-relate problem or you simply do not understand the log, you should contact us help.microblink.com. When contacting us, please make sure you provide following information:

  • exact Bundle ID of your app (from your info.plist file)
  • licence that is causing problems
  • please stress out that you are reporting problem related to iOS version of PhotoPay SDK
  • if unsure about the problem, you should also provide excerpt from console containing licence error

Other problems

If you are having problems with scanning certain items, undesired behaviour on specific device(s), crashes inside PhotoPay SDK or anything unmentioned, please do as follows:

  • Contact us at help.microblink.com describing your problem and provide following information:
    • log file obtained in previous step
    • high resolution scan/photo of the item that you are trying to scan
    • information about device that you are using
    • please stress out that you are reporting problem related to iOS version of PhotoPay SDK

Frequently asked questions and known problems

Here is a list of frequently asked questions and solutions for them and also a list of known problems in the SDK and how to work around them.

In demo everything worked, but after switching to production license I get NSError with MBPMicroblinkSDKRecognizerErrorDomain and MBPRecognizerFailedToInitalize code as soon as I construct specific MBPRecognizer object

Each license key contains information about which features are allowed to use and which are not. This NSError indicates that your production license does not allow using of specific MBPRecognizer object. You should contact support to check if provided licence is OK and that it really contains all features that you have purchased.

I get NSError with MBPMicroblinkSDKRecognizerErrorDomain and MBPRecognizerFailedToInitalize code with trial license key

Whenever you construct any MBPRecognizer object or, a check whether license allows using that object will be performed. If license is not set prior constructing that object, you will get NSError with MBPMicroblinkSDKRecognizerErrorDomain and MBPRecognizerFailedToInitalize code. We recommend setting license as early as possible in your app.

In my didFinish callback I have the result inside my MBPRecognizer, but when scanning activity finishes, the result is gone

This usually happens when using MBPRecognizerRunnerViewController and forgetting to pause the MBPRecognizerRunnerViewController in your didFinish callback. Then, as soon as didFinish happens, the result is mutated or reset by additional processing that MBPRecognizer performs in the time between end of your didFinish callback and actual finishing of the scanning activity. For more information about statefulness of the MBPRecognizer objects, check this section.

Disable logging

Logging can be disabled by calling disableMicroblinkLogging method on MBPLogger instance.

Additional info

Complete API reference can be found here.

For any other questions, feel free to contact us at help.microblink.com.