PPBlinkID 6.9.2

由 NenadMiksa，Jura Skrlec，Toni Kreso，Tomislav Cvetkovic 维护。

您想将类似的代码 pod 'PPBlinkID', '~> 6.9' 添加到 Podfile 中

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

然后在终端或从 CocoaPods.app 运行 pod install

或者要测试运行，运行以下命令

pod try PPBlinkID

PPBlinkID 6.9.2

由
Microblink，Jurica Cerovec 和 Jura Skrlec

BlinkID SDK for iOS

使用 BlinkID iOS SDK 重新想象用户填写信息的方式。快速、准确、安全地扫描全球 180 多个国家的身份证明文档。

BlinkID 是

快。实时数据提取不到 400 毫秒。比填表数分钟要好得多。
安全。 优先考虑隐私，始终如此。即使用户的 iPhone 处于飞行模式，扫描也能正常工作，这意味着个人信息永远不会接触到第三方服务器。
智能。 机器学习模型，针对读取和解析世界各地的几乎任何身份证明文档进行了优化，无论是马来西亚的 MyTentera 还是加州的驾驶执照。
轻量级。 设计用于提高您的应用程序可用性，而不是增加重量。
由您定夺。 自定义和重新品牌默认 UI 或保持原样。这取决于您。
不仅仅是强大的身份扫描仪。 强大的数据提取，结合强大的福利。获取裁剪的文档图像，提示身份证明文档或数据检查身份证的两侧以确保一致性。

要查看所有这些功能的工作情况，请下载我们的免费演示应用程序

准备好开始整合了吗？首先，请确保我们支持您的文档类型 ➡️ 完整列表。然后仔细遵循以下指南。

更新到 SDK 的较新版本？前往我们的 📚 发行说明来查看有哪些变化。

要求

SDK包包含BlinkID框架和一个或多个演示框架集成的示例应用。该框架可部署在强iOS 13.0或更高版本中。

快速入门

BlinkID SDK入门指南

本快速入门指南将帮助您尽可能快地开始OCR扫描。本指南中描述的所有步骤均为集成所必需。

此指南与存储在本存储库“示例”文件夹中的BlinkID-Sample应用紧密相关。我们强烈建议您尝试运行示例应用。示例应用应在您的设备和iOS模拟器上编译并运行。

示例应用的源代码可作为集成的参考。

1. 初始集成步骤

使用CocoaPods

下载并安装/更新Cocopods版本1.11.3或更高版本
由于库存储在Git Large File Storage上，您需要通过以下命令安装git-lfs

brew install git-lfs
git lfs install

务必在安装Git LFS后重新启动您的控制台
注意：如果您已经尝试使用cocoapods添加SDK但未奏效，首先安装git-lfs并清除您的cocoapods缓存。这应该足以强制cocoapods克隆BlinkID SDK，如果仍然无效，尝试取消初始化您的pods并重新安装。
需要由CocoaPods管理的项目依赖关系在名为Podfile的文件中指定。在您的Xcode项目（.xcodeproj）文件相同的目录下创建此文件。
如果您尚未初始化podfile运行以下命令

pod init

将以下行复制并粘贴到TextEdit窗口中

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

在项目中安装依赖项

$ pod install

从现在开始，在构建您的项目时，请务必始终打开生成的Xcode工作空间（.xcworkspace），而不是项目文件

open <YourProjectName>.xcworkspace

使用Carthage

BlinkID SDK可通过Carthage获取。如果您是Carthage的新用户，请查看Carthage文档。

安装Carthage。查看安装Carthage指南。请确保您已安装Carthage版本>= 0.35.0。
在您的.xcodeproj或.xcworkspace所在目录中创建一个Cartfile。
将BlinkID添加到此Cartfile中

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

运行carthage update。
如果成功，将在您的Xcode项目的同一目录中出现一个Cartfile.resolved文件和一个Carthage目录。
将Carthage/Build/<platform>中的二进制文件拖放到您的应用程序的Xcode项目中。

使用Swift Package Manager

BlinkID SDK可用作Swift Package。如果您对Swift Package Manager不熟悉，请查看Swift Package Manager文档。

我们提供了一个公共包存储库的URL，您可以在Xcode中添加

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

选择您项目的包依赖关系选项卡
添加BlinkID Swift包存储库URL
选择Swift包版本

注意：Xcode 12中有一个已知问题，可能导致在真实iOS设备上运行时崩溃。请按照以下说明进行解决方案

在您的应用程序的构建阶段中添加一个新的复制文件阶段
将复制文件阶段的目标更改为框架
向您的应用程序目标添加一个新的运行脚本阶段脚本来添加以下脚本强制以您自己的签名身份深度签名框架
以下是强制以您自己的签名身份深度签名框架的脚本

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

手动集成

-下载最新版本（下载以BlinkID开头的.zip或.tar.gz文件。不要下载源代码，因为GitHub不完全支持Git LFS）

或

克隆此git存储库

由于库存储在Git Large File Storage上，您需要通过以下命令安装git-lfs

brew install git-lfs
git lfs install

务必在安装Git LFS后重新启动您的控制台
要克隆，请运行以下shell命令

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

将BlinkID.xcframework复制到您的项目文件夹。
在您的Xcode项目中，打开项目导航器。将BlinkID.xcframework文件拖放到您的项目中，最佳情况下在Framework组内，与其他您正在使用的框架一起。当被询问时，选择“创建组”，而不是“创建文件夹引用”选项。

Adding BlinkID.xcframework to your project

由于BlinkID.xcframework是一个动态框架，您还需要将其添加到您的目标“常规设置”中的嵌入式二进制部分，并选择选项嵌入式 & 签名。

Adding BlinkID.xcframework to embedded binaries

在您的目标设置中的“链接框架和库”部分，将额外的框架和库包含到您的项目中。
- libc++.tbd
- libiconv.tbd
- libz.tbd

Adding Apple frameworks to your project

2. 引用头文件

在需要使用扫描功能的文件中放置导入指令。

Swift

import BlinkID

Objective-C

#import <BlinkID/BlinkID.h>

3. 启动扫描过程

要启动扫描过程，首先决定在您的应用中希望在何处添加扫描功能。通常，扫描库的用户有一个按钮，点击该按钮将启动扫描过程。然后初始化代码放置在该按钮的触摸处理程序中。以下是初始化代码在触摸处理程序方法中的格式。

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. 许可证密钥

初始化扫描需要有效的许可证密钥。在注册后，您可以在Microblink开发者中心请求一个免费试用许可证密钥。

您可以通过传递包含许可证密钥的字符串或文件来将许可证密钥包含到您的应用中。
注意您需要在初始化扫描之前设置许可证密钥。理想情况下，在AppDelegate或viewDidLoad中初始化任何识别器之前。

许可证密钥（字符串形式）

您可以通过以下方式将许可证密钥作为字符串传递

Swift

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

Objective-C

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

许可证密钥（文件形式）

或者，您可以使用以下代码将许可证密钥包含在内。请确保包含许可证密钥的文件已包含在您的项目中，并在复制包资源构建阶段中进行复制。

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];

如果许可证无效或已过期，则上述方法将抛出异常。

5. 注册扫描事件

在上一个步骤中，您使用具有委托对象的MBBlinkIdOverlayViewController 对象。当扫描生命周期发生特定事件时，该对象会收到通知。在本例中，我们将它设置为 self。委托必须实现的是MBBlinkIdOverlayViewControllerDelegate 协议。需要遵守此协议。我们将在高级集成部分中讨论更多关于协议的内容。您可以使用以下协议的默认实现作为起点。

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
}

高级BlinkID集成说明

本部分涵盖了BlinkID集成的更多高级细节。

第一部分将介绍在使用SDK提供的UI时可能的定制。
第二部分将描述如何将MBRecognizerRunnerViewController's delegates嵌入到您的UIViewController中，以创建自定义UI进行扫描，同时仍然使用SDK的相机管理功能。
第三部分将描述如何使用MBRecognizerRunner（直接API）从UIImage中直接进行识别，而无需使用相机或识别由自定义相机管理获得的相机帧。
第四部分将描述识别器概念和可用识别器。

内置覆盖视图控制器和覆盖子视图

BlinkID SDK 中包含几个内置的叠加视图控制器和扫描子视图叠加，您可以使用它们来进行扫描。

使用 `MBBlinkIdOverlayViewController`

MBBlinkIdOverlayViewController 实现了用于扫描身份证件的新用户界面，该界面针对与新 MBBlinkIdSingleSideRecognizer 和 MBBlinkIdMultiSideRecognizer 的配合使用进行了优化设计。新的 MBBlinkIdOverlayViewController 实现了多个新特性

BlinkID 搜索身份证件阶段的清晰指示
BlinkID 正在忙于OCR和数据提取时的清晰进度指示
不支持文档时的清晰消息
当用户需要将文档靠近相机时，提供视觉指示
当使用 MBBlinkIdMultiSideRecognizer 时，如果文档正面和背面的数据不匹配，提供视觉指示。

新的用户界面允许用户以任意角度、任何方向扫描文档。我们建议在扫描背面条码时强制 landscape 方向，因为在这种方向下成功率更高。
要强制使用 landscape 模式，请按照以下说明操作

Swift

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

Objective-C

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

它具有 MBBlinkIdOverlayViewControllerDelegate 代理，它可以直接使用默认用户界面执行扫描。以下是如何使用和初始化 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];

如您所见，在初始化 MBBlinkIdOverlayViewController 时，我们发送代理属性为 self。要获取结果，我们需要遵守 MBBlinkIdOverlayViewControllerDelegate 协议。

定制外观

SDK 通过使用 UI 主题提供了自定义一些界面方面功能的能力。通过定义应用程序中的主题以覆盖 SDK 中的主题，屏幕可以被定制以符合您的应用程序的外观和感觉。每种主题必须扩展 SDK 中相应的基础主题，如以下各节所述。

BlinkID Overlay 主题

BlinkIDOverlayTheme

BlinkIDOverlayThemeSuccess

要定制 MBBlinkIdOverlayViewController，请使用 MBBlinkIdOverlayTheme 类来定制外观。您可以通过向 MBBlinkIdOverlayTheme 提供希望的属性来定制上图所示标注的元素

准星
- reticleErrorColor - 更改自定义错误UIColor
指令
- instructionsFont - 设置自定义UIFont
- instructionsTextColor - 设置自定义UIColor
- instructionsCornerRadius - 设置自定义圆角
闪光灯警告
- flashlightWarningFont - 设置自定义UIFont
- flashlightWarningBackgroundColor - 设置自定义背景UIColor
- flashlightWarningTextColor - 设置自定义文字UIColor
- flashlightWarningCornerRadius - 设置自定义圆角
卡片图标
- frontCardImage - 在翻转时更改卡片正面图片
- backCardImage - 在翻转时更改卡片背面图片
成功图标
- successScanningImage - 更改成功扫描的图片
- successFlashColor - 更改成功扫描时的闪光颜色

自定义叠加视图控制器

请检查我们的示例以获取自定义叠加视图控制器的实现。

叠加视图控制器是所有叠加视图的抽象类。

其责任是提供有意义且有用的用户界面供用户交互。

用户需要允许的典型操作包括

以直观且有意义的方式指导用户通过扫描过程。这通常通过显示“视口”，用户需要放置扫描对象来实现
取消扫描的方式，通常使用“取消”或“后退”按钮
一种打开和关闭灯光（即“手电筒”）按钮的方法

BlinkID SDK始终为每个特定的用途提供自己的默认实现 Overlay View Controller。您的实现应该尽可能模仿默认实现，因为它经过与最终用户的彻底测试。此外，它还与底层扫描技术非常匹配。

例如，在用户将设备的相机放置在预期能够成功扫描的物体的上方后，扫描技术通常会非常快地给出结果。这意味着扫描进度栏对用户并不是特别有用。用户的大部分时间都花在正确调整设备的摄像头位置上。这只是一个例子，它展示了默认相机叠加视图背后的谨慎决策。

1. 子类化

要使用您自己的叠加视图与Microblink的相机视图一起使用，您必须首先将MBCustomOverlayViewController子类化，并实现符合所需协议的叠加行为。

2. 协议

共有七个MBRecognizerRunnerViewController协议。

七个RecognizerRunnerViewController协议有：

在viewDidLoad中，可以在recognizerRunnerViewController属性的MBOverlayViewController上完成其他协议确认，例如

Swift和Objective-C

self.scanningRecognizerRunnerViewControllerDelegate = self;

3. 初始化

在Quick Start指南中说明了如何使用默认的叠加视图控制器。现在，您可以将默认视图控制器与您的CustomOverlayViewController实现交换

Swift

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

Objective-C

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

直接处理API

本指南将简要说明如何使用BlinkID SDK处理UIImage对象，而不启动摄像头视频捕获。

使用此功能，您可以解决各种用例，例如
——在相册中识别图像上的文本
——拍摄高分辨率照片并将其发送到处理
——在电子邮件中的图像上扫描条形码等

DirectAPI-sample演示应用程序将展示UIImagePickerController以拍摄高分辨率照片，然后使用Direct处理API与BlinkID SDK一起处理它以获取扫描结果。

Direct处理API由MBRecognizerRunner处理。这是一个处理图像的类。它还有一个与MBRecognizerRunnerViewController一样的协议。
开发者可以选择遵守哪个协议

在示例中，我们遵守了MBScanningRecognizerRunnerDelegate协议。

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

现在您已经了解了如何实现Direct处理API。

本质上，此API包含两个步骤

扫描器的初始化。
为每个UIImage或CMSampleBufferRef调用- (void)processImage:(MBImage *)image;方法。

使用Direct API进行`NSString`识别（解析）

一些识别器支持从NSString中进行识别。它们可以通过Direct API用于解析提供的NSString并返回数据，就像它们用于输入图像时一样。当在NSString上执行识别时，不需要OCR。输入的NSString用于与OCR输出相同的方式识别图像。
String识别可以以与图像识别相同的方式进行。
唯一的区别是用户应该在MBRecognizerRunner上调用- (void)processString:(NSString *)string;。

理解DirectAPI的状态机

DirectAPI的RecognizerRunner单例是一个状态机，可以处于3种状态之一：OFFLINE、READY和WORKING。

当你获取RecognizerRunner单例的引用时，它将在OFFLINE状态下。
你可以通过调用initWithRecognizerCollection:方法来初始化RecognizerRunner。如果在RecognizerRunner不在OFFLINE状态下调用initialize方法，你会得到IllegalStateException。
初始化成功后，RecognizerRunner将移动到READY状态。现在你可以调用任何recognize*方法。
当你开始使用任何recognize*方法启动识别时，RecognizerRunner将移动到WORKING状态。如果在RecognizerRunner不在READY状态下尝试调用这些方法，你会得到IllegalStateException。
识别是在后台线程上执行的，所以可以从UI线程安全地调用所有的RecognizerRunner方法。
当识别完成时，RecognizerRunner首先回到READY状态，然后调用提供的MBScanningRecognizerRunnerDelegate的recognizerRunner(_ :, didFinishScanningWith:)方法。
请注意，MBScanningRecognizerRunnerDelegate的recognizerRunner(_ :, didFinishScanningWith:)方法将在后台处理线程上被调用，因此请确保不要在此回调中执行UI操作。还请注意，直到recognizerRunner(_ :, didFinishScanningWith:)方法完成，RecognizerRunner不会对另一张图片或字符串进行识别，即使是在过渡到READY状态后立即调用了recognize*方法。这是为了保证在recognizerRunner(_ :, didFinishScanningWith:)方法使用时，与RecognizerRunner相关联的识别器的结果不会被修改。
通过调用resetState方法，RecognizerRunner单例将释放其所有内部资源。请注意，即使调用过resetState，如果resetState被调用时有正在进行的工作，你仍然可能会收到recognizerRunner(_ :, didFinishScanningWith:)事件。
可以在RecognizerRunner单例的任何状态下调用resetState方法。

在`RecognizerRunnerView`激活时使用DirectAPI

既RecognizerRunnerView又RecognizerRunner使用同一个内部单例，该单例管理原生代码。这个单例处理原生库的初始化和终止以及将识别器传播到原生库。可以同时使用RecognizerRunnerView和RecognizerRunner，因为内部单例将确保正确的同步和正确的识别设置。如果你在使用RecognizerRunner与RecognizerRunnerView结合时遇到问题，请告诉我们！

在结合识别器中使用Direct API

当你使用组合识别器且需要文档两侧的图像时，你需要多次调用RecognizerRunner.recognize*。首先使用文档第一侧的图像调用它，直到读取完毕，然后使用第二侧的图像。组合识别器会自动切换到第二侧扫描，在成功读取第一侧后。当第一侧扫描完成后得到通知，你需要在MBRecognizerRunnerMetadataDelegates中设置MBFirstSideFinishedRecognizerRunnerDelegate。如果你不需要该信息，例如，每份文档两侧只有一个图像时，不要设置MBFirstSideFinishedRecognizerRunnerDelegate，并在第二侧图像被处理后检查MBScanningRecognizerRunnerDelegate.recognizerRunner(_ :, didFinishScanningWith:)中的RecognitionSuccessType。

`MBRecognizer`和可用的识别器

`MBRecognizer`的概念

MBRecognizer 是 SDK 中处理的基本单元。其主要目的是处理图像并从中提取有意义的信息。正如您稍后看到的，SDK 有许多不同用途的 MBRecognizer 对象。

每个 MBRecognizer 都有一个 MBRecognizerResult 对象，其中包含从图像中提取的数据。MBRecognizerResult 对象是相应 MBRecognizer 对象的成员，其生命周期与其父 MBRecognizer 对象的周期绑定。如果您需要您的 MBRecognizerResult 对象比其父 MBRecognizer 对象存活时间更长，您必须通过调用它的 copy 方法来制作一份副本。

当 MBRecognizer 对象工作时，它改变了其内部状态和结果。MBRecognizer 对象的 MBRecognizerResult 总是处于 Empty 状态。当相应的 MBRecognizer 对象对给定图像执行识别时，其 MBRecognizerResult 可以保持 Empty 状态（如果 MBRecognizer 执行识别失败），转换到 Uncertain 状态（如果 MBRecognizer 执行识别，但没有提取所有必要信息）或转换到 Valid 状态（如果 MBRecognizer 执行识别并从图像中成功提取所有必要信息）。

一旦给定的 MBRecognizerCollection 中的 MBRecognizer 对象的 MBRecognizerResult 在传递给 MBRecognizerRunner 或 MBRecognizerRunnerViewController 后变为 Valid 状态，onScanningFinished 回调将在执行后台处理的同一线程上被调用，您将有机会检查您的每个 MBRecognizer 对象的 MBRecognizerResult 以查看哪个已转换为 Valid 状态。

一旦 onScanningFinished 方法结束，MBRecognizerRunnerViewController 将继续使用相同的 MBRecognizer 对象处理新的相机帧，除非处于暂停状态。处理续集或重新启动识别将修改或重置所有 MBRecognizer 对象的 MBRecognizerResult。在启用内置活动时，一旦调用 onScanningFinished，内置活动将暂停 MBRecognizerRunnerViewController 并开始完成活动，同时保存具有活动 MBRecognizer 的 MBRecognizerCollection。

`MBRecognizerCollection` 概念

MBRecognizerCollection 是 MBRecognizer 对象的包装器，它包含一个 MBRecognizer 对象数组，可以用来将 MBRecognizer 对象提供给 MBRecognizerRunner 或 MBRecognizerRunnerViewController 进行处理。

MBRecognizerCollection 总是使用包含需要准备进行识别的 MBRecognizer 对象的数组 [[MBRecognizerCollection alloc] initWithRecognizers:recognizers] 构建（即，它们的属性必须已经调整）。

MBRecognizerCollection 管理识别过程中的一系列 MBRecognizer 对象。当新的图像到达时，它首先由链中的第一个 MBRecognizer 处理，然后是第二个，以此类推，直到某个 MBRecognizer 对象的 MBRecognizerResult 的状态变为 Valid 或链中的所有 MBRecognizer 对象都被调用（没有一个得到 Valid 状态）。

您无法更改链中 MBRecognizer 对象的顺序——无论您以何种顺序将 MBRecognizer 对象提供给 MBRecognizerCollection，它们内部按照能提供最佳性能和准确性的方式排序。此外，为了让 SDK 以最有效的方式对所有 MBRecognizer 对象进行排序，确保识别链中没有同一类型的多个 MBRecognizer。如果尝试这样做，将导致应用程序崩溃。

可用识别器列表

本节将列出所有在 BlinkID SDK 中可用的 MBRecognizer 对象，它们的用途以及如何使用它们以获得最佳性能和用户体验的建议。

帧捕获识别器

MBFrameGrabberRecognizer 是 SDK 中最简单的识别器，因为它不处理提供的图像，而是仅将其返回给其 onFrameAvailable。它的结果永远不会从空状态改变。

此识别器非常适合用 MBRecognizerRunnerViewController 简单捕获摄像头帧。请注意，发送给 onFrameAvailable 的 MBImage 是临时的，其内部缓冲区仅在 onFrameAvailable 方法执行期间有效——该方法结束时，所有内部缓冲区都将丢弃 MBImage 对象。如果您需要存储 MBImage 对象以便稍后使用，您必须通过调用 copy 来创建其副本。

成功帧捕获识别器

MBSuccessFrameGrabberRecognizer 是一种特殊的 MBecognizer，它包装另一个 MBRecognizer 并在处理图像时冒充它。但是，当被冒充的 MBRecognizer 将其 MBRecognizerResult 变为 Valid 状态时，MBSuccessFrameGrabberRecognizer 将捕获图像并将其保存到其自己的 MBSuccessFrameGrabberRecognizerResult 对象中。

由于 MBSuccessFrameGrabberRecognizer 模仿其从属 MBRecognizer 对象，因此不能将具体的 MBRecognizer 对象以及封装它的 MBSuccessFrameGrabberRecognizer 同时放入同一 MBRecognizerCollection 中 - 这样做会导致与向 MBRecognizerCollection 提供两个相同的 MBRecognizer 类型实例相同的结果 - 这将导致您的应用程序崩溃。

此识别器最适合以下用例：您需要在某个 MBRecognizer 对象的处理图像处于 MBRecognizerResult 为 Valid 状态时捕获该图像。发生这种情况时，MBSuccessFrameGrabberRecognizer 的 MBSuccessFrameGrabberRecognizerResult 也将变为 Valid，并将包含所描述的图像。

BlinkID 识别器

除非具体识别器有其他说明，此列表中的单个边 BlinkID 识别器可适用于任何上下文，但它们与具有适合文档扫描的绝佳 UI 的 MBDocumentOverlayViewController 一起表现最佳。

组合识别器 应与 MBDocumentVerificationOverlayViewController 一起使用，它管理单个相机开孔中多张文档边的扫描，并指导用户进行扫描过程。某些组合识别器支持扫描多种文档类型，但一次只能扫描一种文档类型。

机器可读旅行文件识别器

用于扫描和从各种机器可读旅行文件（例如身份证和护照）的机器可读区域（MRZ）中提取数据的 MBMrtdRecognizer。此识别器不受特定国家的限制，但可以配置为仅返回符合 MBMrzFilter 定义的某些标准的的数据。

您可以在本节开始处找到有关使用上下文的信息。

机器可读旅行文件组合识别器

MBMrtdCombinedRecognizer 扫描整个文档图像和面部图像（通常 MRZ 位于文档背面，而面部图像位于正面）之后的机器可读区域（MRZ）。内部，它首先使用 MBDocumentFaceRecognizer 获取完整的文档图像和面部图像作为第一步，然后使用 MBMrtdRecognizer 扫描 MRZ。

您可以在本节开始处找到有关使用上下文的信息。

护照识别器

用于扫描和从各种护照文件的机器可读区域（MRZ）中提取数据的 MBPassportRecognizer。此识别器还会从护照中返回面部图像。

您可以在本节开始处找到有关使用上下文的信息。

签证识别器

用于扫描和从各种签证文件的机器可读区域（MRZ）中提取数据的 MBVisaRecognizer。此识别器还会从签证文档中返回面部图像。

您可以在本节开始处找到有关使用上下文的信息。

身份证条码识别器

用于从各种身份证中扫描条码的 MBIdBarcodeRecognizer。请查阅此文件以查看支持的文档类型列表。

您可以在本节开始处找到有关使用上下文的信息。

文档面部识别器

MBDocumentFaceRecognizer 是一种特殊的识别器，它只返回扫描文档的面部图像和全文档图像。它不提取姓名、姓氏等文档字段。这种通用识别器可以在特定文档类型不支持的情况下用于获取文档图像。

您可以在本节开始处找到有关使用上下文的信息。

BlinkID 识别器

MBBlinkIdSingleSideRecognizer 用于扫描并从支持的文档正面提取数据。
您可以在 此处 找到当前支持文档的列表。
我们将继续通过在未来添加对新文档类型的支持来扩展此识别器。星标此存储库以保持更新。

BlinkID 组合识别器

使用 MBBlinkIdMultiSideRecognizer 扫描支持的文档的两侧。首先，它会扫描并从正面提取数据，然后扫描并从背面条形码提取数据，最后将两侧的结果合并。BlinkIDCombinedRecognizer 还执行数据匹配，如果从正面捕获的数据与背面条形码中的数据匹配，则返回一个标志。
您可以在 此处 找到当前支持文档的列表。
我们将继续通过在未来添加对新文档类型的支持来扩展此识别器。星标此存储库以保持更新。

本地化

SDK 已在以下语言中进行本地化：阿拉伯语、简体中文、繁体中文、克罗地亚语、捷克语、荷兰语、菲律宾语、法语、德语、希伯来语、匈牙利语、印度尼西亚语、意大利语、马来语、葡萄牙语、罗马尼亚语、斯洛伐克语、斯洛文尼亚语、西班牙语、泰语、越南语。

如果您想让我们支持其他语言或报告翻译错误，请通过 help.microblink.com 联系我们。

如果您想自己添加额外的语言或更改现有翻译，您需要设置 MBMicroblinkApp 对象上的 customLocalizationFileName 属性为您的字符串文件名。

例如，假设我们想在 BlinkID 样本项目中将文本“扫描文档的正面”更改为“扫描文档的正面”。以下是步骤

在 BlinkID.framework 中的 en.strings 文件中找到翻译密钥
使用“字符串文件”模板将新文件 MyTranslations.strings 添加到项目中
打开 MyTranslations.strings，在文件检查器中单击“本地化…”按钮并选择英语
将翻译密钥 "blinkid_generic_message" 和值 "Scan the front side" 添加到 MyTranslations.strings
最后，在 AppDelegate.swift 中的 application(_:didFinishLaunchingWithOptions:) 方法中添加 MBMicroblinkApp.instance()?.customLocalizationFileName = "MyTranslations"

故障排除

集成问题

在 SDK 集成遇到问题的情祝下，首先确保您已按照集成说明将其集成到 Xcode 中。

如果您已遵循 Xcode 集成说明并且仍然遇到集成问题，请通过 help.microblink.com 联系我们。

SDK 问题

在使用 SDK 时遇到问题，您应采取以下措施

许可问题

如果您收到“无效许可证密钥”错误或遇到其他许可证相关的问题（例如某些功能未启用或相机上出现水印），请首先检查控制台。所有与许可证相关的问题都记录在错误日志中，因此可以轻松确定发生了什么。

当您确定了许可证相关的问题或您根本不理解日志时，您应通过 help.microblink.com 联系我们。在联系我们时，请确保您提供以下信息

您的应用确切的项目包标识符（来自您的 info.plist 文件）
导致问题的许可证
请强调您报告的是与 iOS 版本 BlinkID SDK 相关的问题
如果您不确定问题所在，也应提供包含许可错误的控制台截屏

其他问题

如果您在扫描特定项目、特定设备（组）中出现不期望的行为、BlinkID SDK 内部崩溃或未提及的其他问题，请按照以下步骤操作

请通过 help.microblink.com 联系我们，描述您的问题并提供以下信息
- 上一步获取的日志文件
- 您试图扫描的项目的超高分辨率扫描/照片
- 您正在使用的设备信息
- 请强调您报告的是与 iOS 版本 BlinkID SDK 相关的问题

常见问题及已知问题

以下是常见问题及其解决方案的列表，以及 SDK 中的已知问题及其解决方案。

在演示版本中一切正常，但当我切换到生产许可证后，当我构建特定的 `MBRecognizer` 对象时，我立即收到一个具有 `MBMicroblinkSDKRecognizerErrorDomain` 和 `MBRecognizerFailedToInitalize` 代码的 `NSError`

每个许可证密钥都包含有关哪些功能可使用以及哪些不可使用的相关信息。此 NSError 指示您的生产许可证不允许使用特定的 MBRecognizer 对象。您应联系支持检查所提供的许可证是否 okay，并且它确实包含您所购买的所有功能。

使用试用许可证密钥时，我会收到一个具有 `MBMicroblinkSDKRecognizerErrorDomain` 和 `MBRecognizerFailedToInitalize` 代码的 `NSError`

每次构建任何 MBRecognizer 对象或检查许可证是否允许使用该对象时，都会执行检查。如果您在构建该对象之前未设置许可证，您将收到一个具有 MBMicroblinkSDKRecognizerErrorDomain 和 MBRecognizerFailedToInitalize 代码的 NSError。我们建议尽早将在您的应用中设置许可证。

armv7 架构上的未定义符号

请确保您像在快速入门中所示那样，将您的应用与应用程序图标和 Accelerate 框架链接。
如果您正在使用 Cocoapods，请确保在安装 pods 之前已安装 git-lfs。如果您仍然收到此错误，请转到项目文件夹并执行命令 git-lfs pull。

armv7 设备上的崩溃

如果启用了位码，SDK 在 armv7 设备上崩溃。我们正在努力解决这个问题。

在我的 `didFinish` 回调中，我在我的 `MBRecognizer` 内部有结果，但当扫描活动结束时，结果消失了

这种情况通常发生在使用 MBRecognizerRunnerViewController 并且忘记在您的 didFinish 回调中暂停 MBRecognizerRunnerViewController 的情况下。然后，一发生 didFinish，结果就被 MBRecognizer 在您的 didFinish 回调和扫描活动实际完成之间的额外处理所更改或重置。有关 MBRecognizer 对象的状态信息，请参阅本节。

提交应用至 App Store 时的不受支持的架构

BlinkID.framework 是一个动态框架，其中包含设备仿真器上的所有架构的切片。如果您打算提取 .ipa 文件以进行 ad hoc 分发，您将需要预处理框架以删除仿真器架构。

理想解决方案是在嵌入框架构建阶段之后添加一个构建阶段，该阶段从嵌入框架中删除未使用的切片。

此构建步骤基于以下内容： http://ikennd.ac/blog/2015/02/stripping-unwanted-architectures-from-dynamic-libraries-in-xcode/

APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"

# This script loops through the frameworks embedded in the application and
# removes unused architectures.
find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"

EXTRACTED_ARCHS=()

for ARCH in $ARCHS
do
echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done

echo "Merging extracted architectures: ${ARCHS}"
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"

echo "Replacing original executable with thinned version"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"

done

禁用日志记录

可以通过在MBLogger实例上调用disableMicroblinkLogging方法来禁用日志记录。

大小报告

我们提供的BlinkID SDK完整大小报告基于我们的BlinkID-sample-Swift样例项目。您可以在这里查看。

附加信息

完整的API参考可以在这里找到。

如果您有任何其他疑问，请随时联系help.microblink.com。

PPBlinkID 6.9.2

PPBlinkID 6.9.2

PPBlinkID 6.9.2

BlinkID SDK for iOS

目录

要求

快速入门

BlinkID SDK入门指南

1. 初始集成步骤

使用CocoaPods

使用Carthage

使用Swift Package Manager

手动集成

2. 引用头文件

3. 启动扫描过程

4. 许可证密钥

许可证密钥（字符串形式）

许可证密钥（文件形式）

5. 注册扫描事件

高级BlinkID集成说明

内置覆盖视图控制器和覆盖子视图

使用 MBBlinkIdOverlayViewController

定制外观

BlinkID Overlay 主题

自定义叠加视图控制器

1. 子类化

2. 协议

3. 初始化

直接处理API

使用Direct API进行NSString识别（解析）

理解DirectAPI的状态机

在RecognizerRunnerView激活时使用DirectAPI

在结合识别器中使用Direct API

MBRecognizer和可用的识别器

MBRecognizer的概念

MBRecognizerCollection 概念

可用识别器列表

帧捕获识别器

成功帧捕获识别器

BlinkID 识别器

机器可读旅行文件识别器

机器可读旅行文件组合识别器

护照识别器

签证识别器

身份证条码识别器

文档面部识别器

BlinkID 识别器

BlinkID 组合识别器

本地化

故障排除

集成问题

SDK 问题

许可问题

其他问题

常见问题及已知问题

在演示版本中一切正常，但当我切换到生产许可证后，当我构建特定的 MBRecognizer 对象时，我立即收到一个具有 MBMicroblinkSDKRecognizerErrorDomain 和 MBRecognizerFailedToInitalize 代码的 NSError

使用试用许可证密钥时，我会收到一个具有 MBMicroblinkSDKRecognizerErrorDomain 和 MBRecognizerFailedToInitalize 代码的 NSError

armv7 架构上的未定义符号

armv7 设备上的崩溃

在我的 didFinish 回调中，我在我的 MBRecognizer 内部有结果，但当扫描活动结束时，结果消失了

提交应用至 App Store 时的不受支持的架构

禁用日志记录

大小报告

附加信息

使用 `MBBlinkIdOverlayViewController`

使用Direct API进行`NSString`识别（解析）

在`RecognizerRunnerView`激活时使用DirectAPI

`MBRecognizer`和可用的识别器

`MBRecognizer`的概念

`MBRecognizerCollection` 概念

在演示版本中一切正常，但当我切换到生产许可证后，当我构建特定的 `MBRecognizer` 对象时，我立即收到一个具有 `MBMicroblinkSDKRecognizerErrorDomain` 和 `MBRecognizerFailedToInitalize` 代码的 `NSError`

使用试用许可证密钥时，我会收到一个具有 `MBMicroblinkSDKRecognizerErrorDomain` 和 `MBRecognizerFailedToInitalize` 代码的 `NSError`

在我的 `didFinish` 回调中，我在我的 `MBRecognizer` 内部有结果，但当扫描活动结束时，结果消失了