iProov 生物识别 iOS SDK v12.2.2

iProov 生物识别 iOS SDK 使您能够将 iProov 集成到您的 iOS 应用程序中。我们还有 Android SDK、Xamarin SDK、Flutter SDK、React Native SDK 和 Web SDK。

• iOS 13.0 及以上版本
• Xcode 15.0.1 及以上版本

该框架是用 Swift 5.5 编写的，我们建议使用 Swift 进行最简单和最清晰的集成。但是，也可以使用我们的 Objective-C API 从 Objective-C 应用程序中调用 iProov，该 API 提供了一个 Objective-C 友好的 API 来调用 Swift 代码。

iProov 生物识别 SDK 包括以下第三方代码

• GPUImage2 的一个分支版本，源自 GPUImage2
• Expression
• CryptoExportImportManager
• SwiftProtobuf
• TrustKit
• Starscream

这些依赖项已打包并编译到 SDK 中，这无需任何操作，仅供参考和许可目的。

iProov SDK 支持模块稳定性。 这样做的好处是，对于 Swift 编译器的每个新版本，无需重新编译 SDK。

框架包通过此仓库提供，其中包含以下内容

• README.md - 本文档！
• Example - 使用 iProov 的基本示例项目，用 Swift 编写并使用 CocoaPods。
• iProov.xcframework - XCFramework 格式的 iProov 框架。如果您没有使用依赖项管理器，则可以手动将其添加到您的项目中。
• iProov.framework - iProov 框架，作为一个适用于设备和模拟器的“fat”动态框架。（如果由于某种原因无法使用 XCFramework 版本，则可以使用此版本。）
• iProovAPIClient.podspec & iProovAPIClient - 与 iOS API 客户端相关的文件。
• iProov.podspec - CocoaPods 所需。您无需对此文件执行任何操作。
• resources - 包含您可能会觉得有用的其他开发资源的目录。
• iProovTargets - 包含虚拟文件的目录，SPM 所需。
• carthage - 包含 Carthage 支持所需文件的目录。

如果您已在使用旧版本的 iProov 生物识别 SDK，请查阅升级指南，以获取有关如何升级应用程序的详细信息。

您可以通过在 iProov Portal 上注册来获得 API 凭据。

通过 CocoaPods、Swift Package Manager 和 Carthage 支持与您的应用程序集成。 您也可以在 Xcode 中手动安装 SDK，而无需使用任何依赖项管理器（不建议这样做）。 我们建议使用 CocoaPods 以获得最简单和最灵活的安装。

注意：SDK 以 XCFramework 的形式分发，因此您需要使用 CocoaPods 1.9.0 或更高版本。

1. 如果您的项目尚未在使用 CocoaPods，请首先运行 sudo gem install cocoapods，然后运行 pod init。（有关安装 CocoaPods 的更多信息，请点击此处。）

2. 将以下内容添加到您的 Podfile（在 target 部分内）

   pod 'iProov'

3. 运行 pod install。

1. 在 Xcode 菜单栏中选择 File → Add Packages…。

2. 使用以下 URL 搜索 iProov SDK 程序包

   https://github.com/iProov/ios
   

3. 将依赖项规则设置为直至下一个主版本，并输入 12.2.2 作为下限。

4. 单击添加程序包以将 iProov SDK 添加到您的 Xcode 项目，然后再次单击以确认。

如果愿意，您可以按如下所示通过您的 Package.swift 文件添加 iProov

.package(
	name: "iProov",
	url: "https://github.com/iProov/ios.git",
	.upToNextMajor(from: "12.2.2")
),

然后将 iProov 添加到您希望使用 iProov 的任何目标的 dependencies 数组中。

注意：强烈建议您使用 Carthage v0.38.0 或更高版本，该版本完全支持预构建的 XCFramework。但是，仍然支持旧版本的 Carthage（但您必须使用传统的通用/"fat"框架代替）。

1. 将以下内容添加到您的 Cartfile

   binary "https://raw.githubusercontent.com/iProov/ios/master/carthage/IProov.json"
   

2. 在您的根 Carthage 目录中创建以下名为 carthage.sh 的脚本

   # carthage.sh
   # Usage example: ./carthage.sh build --platform iOS
   
   set -euo pipefail
    
   xcconfig=$(mktemp /tmp/static.xcconfig.XXXXXX)
   trap 'rm -f "$xcconfig"' INT TERM HUP EXIT
   
   if [[ "$@" != *'--use-xcframeworks'* ]]; then
   	# See https://github.com/Carthage/Carthage/blob/master/Documentation/Xcode12Workaround.md for further details
   
   	CURRENT_XCODE_VERSION="$(xcodebuild -version | grep "Xcode" | cut -d' ' -f2 | cut -d'.' -f1)00"
   	CURRENT_XCODE_BUILD=$(xcodebuild -version | grep "Build version" | cut -d' ' -f3)
   
   	echo "EXCLUDED_ARCHS__EFFECTIVE_PLATFORM_SUFFIX_simulator__NATIVE_ARCH_64_BIT_x86_64__XCODE_${CURRENT_XCODE_VERSION}__BUILD_${CURRENT_XCODE_BUILD} = arm64 arm64e armv7 armv7s armv6 armv8" >> $xcconfig
   	echo 'EXCLUDED_ARCHS__EFFECTIVE_PLATFORM_SUFFIX_simulator__NATIVE_ARCH_64_BIT_x86_64__XCODE_'${CURRENT_XCODE_VERSION}' = $(EXCLUDED_ARCHS__EFFECTIVE_PLATFORM_SUFFIX_simulator__NATIVE_ARCH_64_BIT_x86_64__XCODE_$(XCODE_VERSION_MAJOR)__BUILD_$(XCODE_PRODUCT_BUILD_VERSION))' >> $xcconfig
   	echo 'EXCLUDED_ARCHS = $(inherited) $(EXCLUDED_ARCHS__EFFECTIVE_PLATFORM_SUFFIX_$(EFFECTIVE_PLATFORM_SUFFIX)__NATIVE_ARCH_64_BIT_$(NATIVE_ARCH_64_BIT)__XCODE_$(XCODE_VERSION_MAJOR))' >> $xcconfig
   fi
   
   echo 'BUILD_LIBRARY_FOR_DISTRIBUTION=YES' >> $xcconfig
   
   export XCODE_XCCONFIG_FILE="$xcconfig"
   carthage "$@"

   此脚本包含一个重要的解决方法。 构建通用（“fat”）框架时，它会确保在 Apple Silicon Mac 上构建时，不会将重复的体系结构 lipo'd 到同一框架中，这符合 官方 Carthage 解决方法（请注意，该文档指的是 Xcode 12，但也适用于 Xcode 13 和 14）。

3. 使脚本可执行

   chmod +x carthage.sh

4. 您现在必须使用 ./carthage.sh 而不是 carthage 来构建依赖项。

   Carthage 0.38.0 及以上版本（使用 XCFramework）

   ./carthage.sh update --use-xcframeworks --platform ios

   Carthage 0.37.0 及以下版本（使用通用框架）

   ./carthage.sh update --platform ios

5. 以通常的方式将构建的 .framework/.xcframework 文件从 Carthage/Build 文件夹添加到您的项目中。

   仅适用于 Carthage 0.37.0 及以下版本

   您应按照 此处 的其他说明，在运行您的应用/提交到 App Store 之前，从您的通用二进制文件中删除模拟器体系结构。

1. 在 Xcode 中选择您的项目。

2. 选择您的应用目标。

3. 选择 General 标签，然后向下滚动到 Frameworks, Libraries, and Embedded Content。

4. 从 release assets 添加 iProov.xcframework。

   注意：请确保添加 .xcframework 文件，而不是 .framework 文件。

5. 在 Embed 列下，确保设置了 Embed & Sign。

所有需要访问摄像头的 iOS 应用程序都必须请求用户的许可，并在 Info.plist 中指定此信息。

将 NSCameraUsageDescription 条目添加到您的应用程序的 Info.plist 中，并说明您的应用程序需要访问摄像头的原因（例如，“为了使用 iProov 来验证您的身份。”）

iProov 使用 Genuine Presence™ 技术来远程确认用户的身份； 确保用户是正确的人、真实的人，并且他们正在立即进行身份验证。 使用我们获得专利的 Flashmark™ 解决方案，iProov 可确保准确的在线身份验证。

在能够启动 iProov 之前，您需要获取一个针对 iProov 的令牌。 有 2 种不同的令牌类型

• 一个 verify 令牌 - 用于登录现有用户
• 一个 enrol 令牌 - 用于注册新用户

iProov 提供 Genuine Presence Assurance™ 技术（也称为“Dynamic Liveness”）和 Liveness Assurance™ 技术（也称为“Express Liveness”）

• Genuine Presence Assurance 验证在线远程用户是正确的人、真实的人，并且他们正在立即进行身份验证，以进行访问控制和安全性。
• Liveness Assurance 验证远程在线用户是正确的人和真实的人，以进行访问控制和安全性。

请查阅我们的 REST API 文档，以获取有关如何生成令牌的详细信息。

警告：在生产应用中，您应始终通过服务器到服务器的调用安全地获取令牌。为了节省您为测试 demo/PoC 应用而设置服务器的麻烦，我们提供了 Swift 示例代码，用于通过我们的开源 iOS API 客户端，使用 iProov API v2 获取令牌。您应确保在投入生产之前迁移到服务器到服务器的调用，并且不要忘记使用您的生产 API 密钥和密钥！

获得令牌后，您可以简单地调用 IProov.launch()

import iProov

let token = "{{ your token here }}"
let streamingURLString = "wss://eu.rp.secure.iproov.me/ws" // Substitute as appropriate

guard let streamingURL = URL(string: streamingURLString) else {
    // handle your URL error
}

IProov.launch(streamingURL: streamingURL, token: token) { status in

    switch status {
    case .connecting:
        // The SDK is connecting to the server. You should provide an indeterminate progress indicator
        // to let the user know that the connection is taking place.

    case .connected:
        // The SDK has connected, and the iProov user interface will now be displayed. You should hide
        // any progress indication at this point.

    case let .processing(progress, message):
        // The scan has completed, and the SDK will update your app with the progress of streaming
        // to the server and authenticating the user.
        // This will be called multiple times as the progress updates.

    case let .success(result):
        // The user was successfully verified/enrolled and the token has been validated.
        // You can access the following properties:
        let frame: UIImage? = result.frame // This is a deprecated feature and will be nil.

    case let .failure(result):
        // The user was not successfully verified/enrolled, as their identity could not be verified,
        // or there was another issue with their verification/enrollment.
        // You can access the following properties:
        let reason: FailureReason = result.reason // A reason of why the claim failed
        let feedbackCode: String = reason.feedbackCode // A code referring to the failure reason (see list below)
        let localizedDescription: String = result.localizedDescription // A human-readable suggestion about what to do to get to a successful claim
        let frame: UIImage? = result.frame // This is a deprecated feature and will be nil.

    case let .canceled(canceler):
        // Either:
        //
        // (a) The user canceled iProov by pressing the close button, or sending the
        // app to the background (canceler will be .user), or
        //
        // (b) You canceled iProov by calling cancel() on the SDK (canceler will be .integration) - see cancelation below.

    case let .error(error):
        // The user was not successfully verified/enrolled due to an error (e.g. lost internet connection)
        // along with an `iProovError` with more information about the error (NSError in Objective-C).
        // It will be called once, or never.

    @unknown default:
        // Reserved for future usage.
        break
    }
}

警告：您永远不应将 iProov 用作本地身份验证方法。 这意味着

• 您不能依赖于成功返回的结果来证明用户已成功通过身份验证或注册（恶意的用户有可能在本地操纵 iProov 流程）。您可以将成功回调视为提示您的应用程序更新 UI 等，但在执行任何经过身份验证的用户操作之前，您必须始终独立地在服务器端验证令牌（使用 /validate API 调用）。

• 成功和失败结果中返回的 frame 是一项已弃用的功能，将为 nil。 如果您出于任何原因需要将图像上传到您的系统中（例如，面部匹配、图像分析、用户个人资料图像等），您应该通过服务器到服务器的 /validate API 调用安全地检索此图像。

在正常情况下，用户将控制 iProov 扫描的完成，即他们将完成扫描，或使用关闭按钮取消。 在某些情况下，您（集成者）可能希望以编程方式取消 iProov 扫描，例如为了响应超时或应用程序中条件的变化。

要取消 iProov SDK，您首先需要保存对 iProov 会话的引用（从 IProov.launch() 返回），然后您可以在其上调用 cancel()。

let session = IProov.launch(...)

DispatchQueue.main.asyncAfter(deadline: .now() + 10) { // Example - cancel the session after 10 sec
    session.cancel() // Will return true if the session was successfully canceled
}

您可以通过在启动 iProov 时传入 Options 引用并设置任何这些值来自定义 iProov 会话

选项名称	描述	默认值
filter	调整用于人脸预览的滤镜。请参阅下文以获取更多详细信息。	LineDrawingFilter()
stringsBundle	应该从中检索字符串的应用程序包。	nil
stringsTable	应该从中检索字符串的应用程序表。	nil
titleTextColor	标题的文本颜色。	.white
closeButtonTintColor	应用于关闭按钮的着色颜色。	.white
closeButtonImage	用于关闭按钮的图像。
title	在屏幕顶部显示的标题文本。	nil
font	用于标题和提示的字体的名称。	"HelveticaNeue-Medium"
logoImage	放置在标题旁边的徽标。	nil
promptTextColor	提示文本的颜色。	.white
promptBackgroundColor	提示背景的颜色。	.black.withAlphaComponent(0.8)
promptRoundedCorners	提示是否具有圆角 (true) 或直角 (false)。	true
disableExteriorEffects	是否应禁用椭圆外部的模糊和渐晕效果。	false
presentationDelegate	用于呈现和关闭 iProov UI 的自定义逻辑。 详情请参见下文。	DefaultPresentationDelegate()
surroundColor	应用于椭圆外部区域的颜色。	.black.withAlphaComponent(0.4)
headerBackgroundColor	标题栏的颜色。	nil
certificates	要作为字符串传递的证书（证书的 Subject Public Key Info 的 SHA-256 哈希）。 详情请参见下文。	iProov 服务器证书
timeout	应用于 WebSocket 连接的网络超时。	10 (秒)
viewDelegate	接收 UI 状态更新的可选委托。 详情请参见下文。	nil

SDK 支持两种不同的相机滤镜

LineDrawingFilter 是 iProov 传统的 "canny" 滤镜，有 3 种样式：.shaded（默认）、.classic 和 .vibrant。

foregroundColor 和 backgroundColor 也可以自定义。

示例

options.filter = Options.LineDrawingFilter(style: .vibrant,
                                           foregroundColor: UIColor.black,
                                           backgroundColor: UIColor.white)

NaturalFilter 提供更直接的用户面部可视化效果，有 2 种样式：.clear（默认）和 .blur。

示例

options.filter = Options.NaturalFilter(style: .clear)

注意：NaturalFilter 仅适用于 Liveness Assurance 声明。 尝试将 NaturalFilter 用于 Genuine Presence Assurance 声明将导致错误。

如果 disableExteriorEffects 设置为 true，则 filter 不能设置为 NaturalFilter.Style.blur。 这种选项组合将导致错误。

默认情况下，iProov SDK 锁定到 *.rp.secure.iproov.me 使用的 iProov 服务器证书。

如果您使用自己的反向代理，则需要更新锁定配置以锁定到您自己的证书。

证书应作为 String 数组传递，其中 String 是证书的 Subject Public Key Info 的 base64 编码的 SHA-256 哈希。 您可以按如下方式加载证书

options.certificates = ["O8qZKEXWWkMPISIpvB7DUow++JzIW2g+k9z3U/l5V94="]

要从 .crt 文件获取 Subject Public Key Info，请使用以下命令

$ openssl x509  -in cert.crt -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

要从 .der 文件获取 Subject Public Key Info，请使用以下命令

$ openssl x509 -inform der -in cert.der -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

当传递多个证书时，只要服务器与任何证书匹配，就允许连接。 锁定是针对证书的公钥执行的。

您还可以通过传递一个空数组来完全禁用证书锁定

options.certificates = []

警告：永远不要在生产应用程序中禁用证书锁定！

GPA 特定的选项可以在 Options.genuinePresenceAssurance 下设置

LA 特定的选项可以在 Options.livenessAssurance 下设置

默认情况下，启动 SDK 后，它将获取对应用程序委托窗口的 rootViewController 的引用，然后遍历视图控制器堆栈以找到最顶层的视图控制器，然后从堆栈中最顶层的视图控制器中 present() iProov 的视图控制器作为模态视图控制器。

这可能并不总是理想的行为；例如，您可能希望将 iProov 作为基于 UINavigationController 的流程的一部分呈现。 因此，也可以设置 options.presentationDelegate 属性，该属性允许您通过遵循 IProovPresentationDelegate 协议来覆盖 iProov 视图控制器的呈现/关闭行为

extension MyViewController: IProovPresentationDelegate {

    func present(iProovViewController: UIViewController, completion: (() -> Void)?) {
        // How should we present the iProov view controller?
    }

    func dismiss(iProovViewController: UIViewController, completion: (() -> Void)?) {
        // How should we dismiss the iProov view controller once it's done?
    }

}

警告：使用此功能时，您必须遵循以下几个重要规则

1. 能力越大，责任越大！ iProov 视图控制器需要完全覆盖整个屏幕才能正常工作。 不要尝试以仅占据屏幕一部分或被其他视图遮挡的方式向用户呈现视图控制器。 您还必须确保视图控制器在关闭后完全从用户的视图中移除。

2. 为了避免保留循环的风险，Options 仅保存对演示委托的 weak 引用。 确保您的演示委托在 iProov 捕获会话的整个生命周期内被保留，否则可能会导致流程缺陷。

注意：以上定义的默认 UI 选项已验证符合 WCAG 2.1 AA 可访问性标准。 更改这些值可能会导致不符合指南。

如果您想从 iProov SDK 接收 UI 状态更新，您可以将符合 IProovViewDelegate 协议类型的对象设置为 options.viewDelegate。

示例

extension MyViewController: IProovViewDelegate {
    func willPresentIProovView() {
    	// Called before the iProov user interface is presented.
    }

    func didPresentIProovView() {
    	// Called when the iProov user interface is presented.
    }

    func didDismissIProovView() {
    	// Called when the iProov user interface is dismissed.
    }
}

let myViewController = MyViewController()
options.viewDelegate = myViewController

SDK 支持以下语言

• 英语 - en
• 荷兰语 - nl
• 法语 - fr
• 德语 - de
• 意大利语 - it
• 葡萄牙语 - pt
• 葡萄牙语（巴西）- pt-BR
• 西班牙语 - es
• 西班牙语（哥伦比亚）- es-CO
• 威尔士语 - cy-GB

您可以从您的应用程序自定义字符串或将它们本地化为其他语言。 有关更多详细信息，请参阅我们的 本地化指南。

当用户的身份无法验证时，会发生失败。 失败意味着服务器已成功接收并处理捕获，并返回了结果。 关键是，这与错误不同，在错误中，由于系统故障，捕获本身失败了。

通过回调中的 .failure(reason) 枚举案例捕获失败。 reason 是一个枚举，其中包含用户无法被验证/注册的原因，它具有以下属性

• feedbackCode - 反馈代码的字符串表示形式。

• localizedDescription - 您应该将其呈现给用户，因为它可能会为用户提供有用的提示，以增加他们下次成功使用 iProov 的机会。

可用的反馈代码如下

Key: ✅ = 将被返回, ❌ = 将不会被返回,⚠️= 将来可能会被返回

这些不是正在执行的测试的指示，而只是是否报告失败原因。

当由于技术问题或阻止捕获完成的用户操作而无法完成捕获时，会发生错误。

通过回调中的 .error(error) 枚举案例捕获错误。 error 参数以 IProovError 的形式提供 iProov 流程失败的原因。

iProov iOS API 客户端 是一个简单的包装器，用于 iProov REST API v2，用 Swift 编写，并使用 Alamofire 在演示/PoC 应用程序中使用。

有关更多详细信息，请参阅安装文档。 也可以使用此 repo 中的 iProovAPIClient 文件夹集成 APIClient，但这将在下一个主要版本中删除。

对于开箱即用且使用 iProov API 客户端的简单 iProov 体验，请查看 示例项目。

1. 确保您已安装 CocoaPods，然后从 Example 目录运行 pod install 以安装所需的依赖项。

2. 将 Credentials.example.swift 重命名为 Credentials.swift，并使用您的基本 URL、API 密钥和密钥更新它。 您可以从 iProov 门户获取这些凭据。

3. 打开 Example.xcworkspace。

4. 现在您可以构建和运行项目。 请注意，您只能在真实设备上启动 iProov； 它在模拟器中不起作用。

警告：示例项目使用 iOS API 客户端 直接在设备上获取令牌，这本质上是不安全的。 iProov 的生产实现应始终通过服务器到服务器的调用安全地获取令牌。

您可以在我们的 常见问题解答 或我们的其他 Wiki 页面中找到您的问题答案。

请参阅 文档中心 以获取详细的 实施指南、术语表和 API 参考。

如需进一步帮助集成 iProov 生物识别 SDK，请联系 support@iproov.com。