捕获 SDK for iOS

BlinkID Capture iOS SDK 以用户友好的方式让您能够自动捕获身份证件的高质量图像。SDK 为您提供校正后的文档图像，确保提取文档文本或验证文档真实性的成功率很高。

用户被引导避免反光、模糊的图像、灯光明暗不均、手在文档上或倾斜过多。SDK 能够识别身份证件是单面（如护照）还是双面（如驾照），并在需要时提示用户扫描文档背面。

在结果中，您可以获取裁剪、透视校正的文档图像以及原始框架。这些可以根据您的应用需求进行处理。SDK 轻量级，可轻松集成到您的移动应用和设计中。

目录

• 需求
• 快速入门
  • 熟悉 Capture SDK
    • 手动集成
    • 使用 Swift 包管理器
    • 使用 Cocoapods
  • 引用头文件
  • 启动捕获流程
  • 许可证密钥
  • 注册捕获事件
• 自定义外观和 UX
• 本地化
• 使用直接 API 完全自定义 UX（高级）
  • AnalyzerRunner
• 故障排除
• Capture SDK 大小
• 更多信息

需求

SDK 软件包包含 Capture 框架和演示框架集成的示例应用程序。该框架可在 iOS 13.0 或更高版本中部署。该框架支持 Swift 和 Objective-C 项目。**注意**：SDK 不包含位代码。

快速入门

熟悉 Capture SDK

本快速入门指南将帮助您迅速开始文档捕获。本指南中描述的所有步骤都是集成所必需的。

本指南紧密遵循本存储库中“Samples”文件夹中的 CaptureSample 应用程序。我们强烈建议您尝试运行该示例应用程序。示例应用程序应可在您的设备上编译和运行。

示例应用程序的源代码可以在集成期间作为参考使用。

手动集成

下载 最新版本（下载 Capture.xcframework.zip 文件或克隆此存储库）。

• 将 CaptureUX.xcframework 和 CaptureCore.xcframework 复制到您的项目文件夹。

• 在您的 Xcode 项目中，打开 Project navigator。将 CaptureUX.xcframework 和 CaptureCore.xcframework 文件拖到您的项目中，最佳位置是在 Frameworks 组中，与其他您正在使用的框架一起。当被问及时，选择“创建分组”，而不是“创建文件夹参考”选项。

• 由于 CaptureUX.xcframework 和 CaptureCore.xcframework 是动态框架，您还需要在目标的一般设置中将它们添加到嵌入式二进制文件部分，并选择“嵌入并签名”选项。

• 将附加框架和库包含到您的项目中，在目标设置的“链接框架和库”部分。

  • libc++.tbd
  • libz.tbd

使用 Swift 包管理器

Capture SDK 作为 Swift 包 提供。如果您是 Swift 包管理器的新手，请查阅 Swift 包管理器文档。

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

CaptureUX

https://github.com/BlinkID/capture-ux-sp

CaptureCore

https://github.com/BlinkID/capture-core-sp

使用 Cocoapods

Capture SDK 作为 Cocoapods 包 提供。
我们为每个框架提供了 podspecs。需要在 CocoaPods 中管理的项目依赖项指定在名为 Podfile 的文件中。在您的 Xcode 项目文件（.xcodeproj）相同的目录中创建此文件。

如果没有初始化 podfile，请在您的项目目录中运行以下命令。

pod init

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

platform :ios, '13.0'
target 'Your-App-Name' do
    pod 'MBCaptureCore', '~> 1.1.0'
    pod 'MBCaptureUX', '~> 1.1.0'
end

• 在您的项目中安装依赖项

$ pod install

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

open <YourProjectName>.xcworkspace

引用头文件

在您想使用 SDK 功能的文件中放置导入指令。

Swift

import CaptureCore
import CaptureUX

Objective-C

#import <CaptureCore/CaptureCore.h>
#import <CaptureUX/CaptureUX>

初始化捕获过程

要初始化捕获过程，首先决定在您的应用中添加捕获功能的位置。通常，捕获库的用户有一个按钮，当点击该按钮时，会启动扫描过程。然后，将初始化代码放置在该按钮的 touch 处理程序中。以下是我们列出在 touch 处理程序方法中初始化代码的方式。

class ViewController: UIViewController {

    var captureVC: MBICCaptureViewController?
    var settings: MBICCaptureSettings?

    @IBAction func startCapture(_ sender: Any) {
        settings = MBICCaptureSettings()
        captureVC = MBICCaptureViewController(captureSettings: settings!)
        captureVC?.delegate = self
        captureVC?.modalPresentationStyle = .fullScreen

        present(imageCaptureVC!, animated: true)
    }
}

@interface ViewController()<MBICCaptureViewControllerDelegate> {

@property (nonatomic) MBICCaptureViewController *captureVC;
@property (nonatomic) MBICCaptureSettings * settings;

@end

@implementation ViewController

- (void) startCapture:(UIButton *)sender {
    self.settings = [[MBICCaptureSettings alloc] init];
    self.captureVC = [[MBICCaptureViewController alloc] initWithCaptureSettings: self.settings];
    self.captureVC.delegate = self;
    self.captureVC.modalPresentationStyle = UIModalPresentationFullScreen;

    [self presentViewController:captureVC animated:YES completion:nil];
}

@end

}

许可证密钥

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

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

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

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

Swift

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

Objective-C

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

许可证密钥（文件形式）

或您可以使用以下代码将许可证密钥包含到其中。请确保包含许可证密钥的文件已包含到您的项目中，并且在 复制包资源 构建设置期间已复制。

Swift

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

Objective-C

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

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

注册捕获事件

要获取捕获结果，您需要遵循 MBICCaptureViewControllerDelegate 协议。

extension ViewController: MBICCaptureViewControllerDelegate

@interface ViewController : UIViewController<MBICCaptureViewControllerDelegate>

实现必需的方法并获取结果

captureViewController(captureViewController: MBICCaptureViewController, didFinishCaptureWithResult analyserResult: MBICAnalyserResult)

- (void)captureViewController:(nonnull MBICCaptureViewController *)captureViewController didFinishCaptureWithResult:(nonnull MBICAnalyserResult *)analyserResult

定制外观和 UX

SDK 提供了使用 UI 主题来定制一些 UI 方面的能力。通过定义来自 SDK 的主题的应用程序主题，可以将屏幕定制以适应您应用的样式和感觉。每个主题都必须扩展 SDK 中的相应基本主题，如以下章节所述。定制支持暗黑色模式。

CaptureViewController 主题

要定制 MBICCaptureViewController，在初始化 MBICCaptureViewController 时使用 MBICCaptureViewControllerTheme 在 MBICCaptureSettings 中，以自定义外观。您可以通过为 MBICCaptureViewControllerTheme 提供所需的属性来自定义上图上的标记元素。

• captureOnboardingAlertViewTitleTextColor

  • messageTextColor - 设置自定义 UIColor
  • messageFont - 设置自定义 UIFont
  • titleTextColor - 设置自定义 UIColor
  • titleFont - 设置自定义 UIFont
  • doneButtonTextColor - 设置自定义 UIColor
  • 完成按钮文本字体 - 设置自定义 UIFont

• 捕获教程视图

  • 动作按钮关闭文本颜色 - 设置自定义 UIColor
  • 动作按钮关闭字体 - 设置自定义 UIFont
  • 动作按钮下一个文本颜色 - 设置自定义 UIColor
  • 动作按钮下一个字体 - 设置自定义 UIFont
  • titleTextColor - 设置自定义 UIColor
  • 标题文字字体 - 设置自定义 UIColor
  • messageTextColor - 设置自定义 UIColor
  • 消息字体 - 设置自定义 UIColor
  • 页面控制颜色 - 设置自定义 UIColor

• 捕获状态视图

  • 字体 - 设置自定义 UIFont
  • 圆角 - 设置自定义圆角

• 捕获成功扫描

  • 图片 - 更改成功扫描图片

• 捕获工具提示

  • 背景颜色 - 设置自定义 UIColor
  • 文字颜色 - 设置自定义 UIColor
  • 圆角 - 设置自定义圆角

• 捕获帮助按钮

  • 图片 - 更改帮助按钮图片

• 捕获瞄准器

  • 瞄准器错误颜色 - 更改自定义错误 UIColor

• 捕获torch

  • torch开启图片 - 更改自定义开启图片
  • torch关闭图片 - 更改自定义关闭图片

• 捕获剪辑视图

  • 正面文档图像 - 正面翻转图像
  • 背面文档图像 - 正面翻转图像

• 捕获手电筒警告/相机手电筒警告

  • 字体 - 设置自定义 UIFont
  • 背景颜色 - 设置自定义 UIColor
  • 文字颜色 - 设置自定义 UIColor
  • 圆角 - 设置自定义圆角

本地化

SDK 支持英语。

如果您希望我们支持附加语言或有翻译错误，请通过 help.microblink.com 联系我们。

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

例如，在我们想要更改 "扫描文档的正面" 文本到 "扫描文档的正面" 在 BlinkID 示例项目中。以下步骤将是这样：

• 在 Capture.xcframework 内的 en.strings 文件中找到翻译键
• 通过使用 "Strings File" 模板在项目中添加新的文件 MyTranslations.strings
• 在 MyTranslations.string 打开时，在文件检查器中点击 "本地化…" 按钮并选择英语
• 将翻译键 "mbic_scan_the_front_side" 和值 "扫描文档的正面" 添加到 MyTranslations.strings
• 最后，在 AppDelegate.swift 的方法 application(_:, didFinishLaunchingWithOptions:) 中添加 MBICCaptureUISDK.shared().customLocalizationFileName = "MyTranslations"

此外，您可以直接在框架中更改我们的 .strings 文件。转到 Capture.framework 并进行替换。

使用 Direct API（高级）实现完全自定义 UX

在使用 Direct API 时，您负责准备输入图像流（或静态图像）以进行分析，并根据 SDK 的逐图像反馈从头开始构建完全自定义的用户界面。

Direct API 提供了更多灵活性，但需要显著更大的集成努力。例如，如果您需要一个相机，您将负责相机管理和显示实时用户引导。

请查看我们的 Direct API 示例应用 了解实现方法。

为 Direct API 添加 Capture SDK 依赖项

对于 Direct API，您只需要 Capture SDK 核心库： CaptureCore，不需要 CaptureUX。

MBCCAnalyzerRunner

对于 Direct API 集成，请使用 MBCCAnalyzerRunner。它是一个单例对象，这意味着一次只能捕获一个文档。

与默认 UX 一样，您可以配置 MBCCAnalyzerRunner 以希望使用的 MBCCAnalyzerSettings。在分析过程中随时更新设置是允许的。

AnalyzerRunner.settings = AnalyzerSettings(
    // set supported options
)

在开始分析下一个文档时，请确保分析器已重置到初始状态。

MBCCAnalyzerRunner.shared().reset()

[MBCCAnalyzerRunner sharedInstance] reset];

在分析过程中以及分析完成后，可以通过 MBCCFrameAnalysisResult 获取当前结果。

分析完成后，不需要再使用 MBCCAnalyzerRunner 时，请确保终止它以释放处理分配的内存。

MBCCAnalyzerRunner.shared().terminate()

[MBCCAnalyzerRunner sharedInstance] terminate]

终止后，可以稍后再次使用 MBCCAnalyzerRunner。只需开始为下一个文档输入帧。

分析图像流

当你从流中获得大量图像时，例如摄像头流或预录制的视频
，使用MBCCAnalyzerRunner analyzeStreamImage方法。

预计您将多次调用此方法以分析单个文档，并且所有已分析的图像都考虑用于构建最终结果。

对于每个帧，didAnalyzeFrameWithResult代表作为MBCCFrameAnalysisResult返回的所有相关信息，该信息可用于引导用户通过扫描过程并给出实时反馈
。

当MBCCFrameAnalysisResult captureState变为MBCCCaptureStateDocumentCaptured时，这意味着已成功捕获文档，您可以使用此结果作为最终的捕获结果。为了立即将分析器重置为其初始状态并避免进一步的结果更改，您可以使用MBCCAnalyzerRunner.shared().detachResult()。

分析少量图像（通常是单个或两个）

当你有要分析的固定数量图像时，例如（或少数）用于文件的正面
和另一侧（或几个）用于文件的反面，使用MBCCAnalyzerRunner analyzeImage，这是针对单个图像分析优化的。

确保您已设置适当的设置以启用从单个图像捕获文档侧面

MBCCAnalyzerRunner.shared().settings.captureStrategy = .singleFrame

[MBCCAnalyzerRunner sharedInstance].settings.captureStrategy = MBCCCaptureStrategySingleFrame

故障排除

集成问题

如果SDK集成出现问题，请首先确保您已按照集成说明将SDK集成到Xcode中。

如果您已按照Xcode集成说明进行操作并且仍然有集成问题，请联系我们help.microblink.com。

SDK问题

如果使用SDK出现问题，您应该这样做

许可证问题

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

当你确定什么问题或你只是不理解日志，你应该联系我们help.microblink.com。在联系我们时，请确保您提供以下信息

• 您的应用程序的精确Bundle ID（来自您的info.plist文件）
• 导致问题的许可证
• 强调您正在报告与Capture SDK iOS版本相关的问题
• 如果您不确定问题，还请提供包含许可证错误的控制台摘录

其他问题

如果您在使用某些物品扫描时遇到问题，特定设备上的不受欢迎的行为，Capture SDK内部崩溃或任何未提及的事情，请按以下方式操作

• 在我们的help.microblink.com上联系我们，描述您的问题，并提供以下信息
  • 上一步中获得的日志文件
  • 您试图扫描的物品的高分辨率扫描/照片
  • 有关您使用的设备的信息
  • 强调您正在报告与Capture SDK iOS版本相关的问题

Capture SDK大小

Capture是一个非常轻量级的SDK。压缩大小仅为2.1MB。SDK大小计算是通过使用Xcode创建应用程序大小报告完成的，一个是带有SDK的，一个是不带SDK的。
以下是iPhone的SDK 应用程序大小报告。

大小	应用程序+按需资源大小	应用程序大小
压缩	2.1 MB	2.1 MB
未压缩	3.1 MB	3.1 MB

未压缩的大小等同于设备上已安装应用程序的大小，而压缩大小是您的应用程序的下载大小。
您可以在这里找到《应用大小报告》。

附加信息

完整的API参考可以在

• CaptureUX
• CaptureCore

对于任何其他问题，请随时通过help.microblink.com联系我们。