Capture SDK for iOS

BlinkID Capture iOS SDK允许您以用户友好的方式自动捕捉身份证件的高清图像。该SDK为您提供了一个校正后的文件图像，确保文本提取或验证文件有效性的成功率很高。

用户被引导避免眩光、模糊的图像、不良的照明条件、手指覆盖文件或倾斜过多。SDK能够识别文件是单面（例如护照）还是双面（例如驾驶证）并提示用户在需要时扫描文件的背面。

在结果中，您可以获取裁剪、透视校正的文件图像以及原始框架。这些图像可以在您的应用中以任何需要的方式进行处理。该SDK轻量且易于集成到您的移动应用中，并与您的设计融为一体。

目录

• 需求
• 快速入门
  • 从Capture SDK开始
    • 手动集成
    • 使用Swift Package Manager
    • 使用CocoaPods
  • 引用头文件
  • 启动捕捉过程
  • 许可证密钥
  • 为捕捉事件进行注册
• 自定义外观和UX
• 本地化
• 使用直接API完全自定义UX（高级）
  • The AnalyzerRunner
• 故障排除
• Capture SDK大小
• 附加信息

需求

SDK包包含Capture框架和一个或多个演示应用，这些应用演示了框架集成。该框架可以部署在iOS 13.0或更高版本。该框架支持Swift和Objective-C项目。注意：SDK不包含位码。

快速入门

从Capture SDK开始

本快速入门指南将帮助您尽快完成文件捕捉。本指南中描述的所有步骤都是集成所必需的。

本指南与存储库中 Samples 文件夹中的 CaptureSample 应用紧密相关。我们强烈建议您尝试运行这个示例应用。该示例应用应该能够在您的设备上编译和运行。

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

手动集成

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

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

• 在Xcode项目中，打开项目导航器。将CaptureUX.xcframework和CaptureCore.xcframework文件拖到项目中，最好在框架组中，与其他您正在使用的框架一起使用。当被询问时，选择“创建组”，而不是“创建文件夹引用”选项。

• 由于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 以 Cocopods 包 的形式提供。
我们为每个框架提供 podspec 文件。要由 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>

启动捕获过程

要启动捕获过程，首先决定在您的应用中添加捕获功能的位置。通常，捕获库的用户有一个按钮，点击该按钮会启动扫描过程。初始化代码随后放置在该按钮的触摸处理器。以下是将初始化代码作为触摸处理器方法中显示的方式。

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

文件形式的许可证密钥

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

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 时在 MBICCaptureSettings 中使用 MBICCaptureViewControllerTheme 以定制外观。您可以通过向 MBICCaptureViewControllerTheme 提供所需属性来自定义屏幕截图上标记的元素。

• captureOnboardingAlertViewTitleTextColor

  • messageTextColor - 设置自定义 UIColor
  • messageFont - 设置自定义 UIFont
  • titleTextColor - 设置自定义 UIColor
  • titleFont - 设置自定义 UIFont
  • doneButtonTextColor - 设置自定义 UIColor
  • doneButtonTextFont - 设置自定义 UIFont

• captureTutorialView

  • actionButtonCloseTextColor - 设置自定义 UIColor
  • actionButtonCloseFont.- 设置自定义 UIFont
  • actionButtonNextTextColor - 设置自定义 UIColor
  • actionButtonNextFont - 设置自定义 UIFont
  • titleTextColor - 设置自定义 UIColor
  • titleTextFont - 设置自定义 UIColor
  • messageTextColor - 设置自定义 UIColor
  • messageFont - 设置自定义 UIColor
  • pageControlColor - 设置自定义 UIColor

• captureStatusView

  • font - 设置自定义 UIFont
  • cornerRadius - 设置自定义圆角半径

• captureSuccesScan

  • image - 更改成功扫描图像

• captureTooltip

  • backgroundColor - 设置自定义 UIColor
  • textColor - 设置自定义 UIColor
  • cornerRadius - 设置自定义圆角半径

• captureHelpButton

  • image - 更改帮助按钮图像

• captureReticle

  • reticleErrorColor - 更改自定义错误 UIColor

• captureTorch

  • torchOnImage - 更改自定义开启图像
  • torchOffImage - 更改自定义关闭图像

• captureClipView

  • firstSideDocumentImage - 第一面翻转图像
  • secondSideDocumentImage - 第一面翻转图像

• captureFlashlightWarning/cameraTorchWarning

  • font - 设置自定义 UIFont
  • backgroundColor - 设置自定义 UIColor
  • textColor - 设置自定义 UIColor
  • cornerRadius - 设置自定义圆角半径

本地化

该 SDK 支持 英语 语言。

如果您希望我们支持其他语言或报告错误的翻译，请联系我们 help.microblink.com。

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

例如，假设我们想在 BlinkID 示例项目中将文本 "Scan the front side of a document" 更改为 "Scan the front side"。以下是步骤：

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

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

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

当使用 直接 API 时，您负责准备输入图像流（或静态图像）进行分析，并根据 SDK 的图像反馈从头开始构建一个完全定制的 UX。

直接 API 提供了更多的灵活性，但是需要更大的集成工作量。例如，如果您需要一个相机，您将负责相机管理和显示实时用户指南。

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

为 Direct API 添加 Capture SDK 依赖

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

MBCCAnalyzerRunner

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

就像在默认 UX 中一样，您可以使用所需的 MBCCAnalyzerSettings 配置 MBCCAnalyzerRunner。您可以在分析过程中任何时候更新设置。

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 集成问题，首先请确保您已按照以下 集成说明 尝试将其集成到 Xcode 中。

如果您已按照 Xcode 集成说明 进行操作，但仍存在集成问题，请通过 help.microblink.com 联系我们。

SDK 问题

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

许可证问题

如果您收到 "无效的许可证密钥" 错误或其他许可证相关的问题（例如，某些应启用的功能未启用或相机顶部有水印），请首先检查控制台。所有与许可证相关的问题都记录在错误日志中，因此很容易确定出错的原因。

当您确定是何种许可证相关问题或您简单不知道日志内容时，您应通过 help.microblink.com 联系我们。在联系我们时，请确保您提供以下信息

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

其他问题

如果您在使用扫描特定物品、特定设备上的不良行为、Capture SDK 内部的崩溃或其他未提及的问题时遇到问题，请按照以下操作

• 通过 help.microblink.com 描述您的问题，并以下列信息提供
  • 上一步骤中获得的日志文件
  • 您尝试扫描的物品的高分辨率扫描/照片
  • 您所使用设备的详细信息
  • 请强调您正在报告与 iOS 版本的 Capture SDK 相关的问题

Capture SDK 的大小

Capture 是一个非常轻量级的 SDK。压缩大小仅为 2.1MB。SDK 大小计算是通过 在 Xcode 中创建 App 大小报告 来完成的，一个带 SDK 的，一个不带 SDK 的。
以下是为 iPhone 的 SDK App 大小报告

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

未压缩的大小等同于设备上安装的应用程序的大小，压缩的大小是您应用程序的下载大小。
您可以通过以下链接找到 应用程序大小报告：这里。

附加信息

完整的API参考可以在以下位置找到

• CaptureUX
• CaptureCore

如果您有其他任何问题，请随时通过help.microblink.com与我们联系。