iProov 生物识别 iOS SDK v10.3.0

简介

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

要求

iOS 11.0 及以上
Xcode 13.0 及以上

此框架是用 Swift 5.5 编写的，我们建议使用 Swift 以实现最简单、最纯粹的集成，但是，您也可以使用我们的 Objective-C API 从 Objective-C 应用中调用 iProov，该 API 提供了针对 Objective-C 的 API 来调用 Swift 代码。

依赖关系

iProov 生物识别 SDK 依赖于 Starscream。如果在以下列出的任何依赖管理器中安装，这个依赖关系将被自动包含。

SDK 还包含以下第三方代码

这些依赖关系已被纳入 SDK 并编译在内，这不需要采取任何行动，仅提供信息和授权目的。

模块稳定性

iProov SDK 支持模块稳定性。其优势在于 SDK 不必因 Swift 编译器的每个新版本而重新编译。

因此，SDK 是通过启用 "为分发构建库" 构建设置来构建的，这意味着它的依赖关系也必须启用此设置构建。因此，您必须确保为 CocoaPods 和 Carthage 都设置了此设置（有关详细信息，请参阅安装文档）。

仓库内容

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

README.md - 此文档！
示例 - 使用 iProov 的基本示例项目，使用 Swift 编写，并使用 CocoaPods。
iProov.xcframework - 以 XCFramework 格式提供的 iProov 框架。如果您不使用依赖管理器，可以手动将其添加到项目中。
iProov.framework - 作为“肥”动态框架提供的 iProov 框架，适用于设备和模拟器。（如果您因任何原因无法使用 XCFramework 版本，可以使用此版本。）
iProovAPIClient.podspec & iProovAPIClient - 与 iOS API 客户端有关的文件。
iProov.podspec - 由 CocoaPods 所需。您无需对此文件进行任何操作。
resources - 包含您可能认为有帮助的额外开发资源的目录。
iProovTargets - 包含占位符文件，用于支持 SPM。
carthage - 包含支持 Carthage 所需的文件。

从早期版本升级

如果您已经使用 iProov 生物识别 SDK 的旧版本，请查阅升级指南，了解如何升级您的应用的详细信息。

注册

您可以通过在 iProov 门户上注册来获取 API 凭证。

安装

您可以通过 CocoaPods、Swift Package Manager 和 Carthage 将其集成到您的应用中。您还可以在不使用任何依赖管理器的情况下手动在 Xcode 中安装 SDK（我们不推荐这样做）。我们建议您使用 CocoaPods，因为它易于安装且最具灵活性。

CocoaPods

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

如果您在项目中尚未使用 CocoaPods，请首先运行 sudo gem install cocoapods，然后运行 pod init。（有关安装 CocoaPods 的更多信息，请点击这里。）
请在 Podfile 的目标部分添加以下内容
```
pod 'iProov'
```

请在 Podfile 的底部添加以下内容

post_install do |installer|
  installer.pods_project.targets.each do |target|
    if ['iProov', 'Starscream'].include? target.name
      target.build_configurations.each do |config|
          config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
      end
    end
  end
end

运行 pod install。

Swift 包管理器

注意：如果您的应用程序已对 Starscream 有现有依赖项，您必须删除该现有依赖项并使用 iProov 提供的版本，或者应该避免通过 SPM 安装 iProov，而是使用其他安装方法。

通过 Xcode 安装

在 Xcode 菜单栏中选择 文件 → 添加包…。
使用以下 URL 搜索 iProov SDK 包
```
https://github.com/iProov/ios
```
将 依赖关系规则 设置为 直到下一个主要版本，并将 10.3.0 作为下限输入。
单击 添加包 将 iProov SDK 添加到您的 Xcode 项目中，然后再次单击以确认。

通过Package.swift安装

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

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

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

Carthage

Note: 强烈建议使用Carthage v0.38.0或更高版本，它完全支持预构建的XCFrameworks，但是仍然支持Carthage的较旧版本（但是您必须使用传统的通用/"fat" frameworks）。

将以下内容添加到您的Cartfile中

binary "https://raw.githubusercontent.com/iProov/ios/master/carthage/IProov.json"
github "daltoniam/Starscream" >= 4.0.0

在您的root 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") frameworks时，确保在Apple Silicon Mac上构建时，重复架构不会在同一个框架中lipo（根据官方Carthage的解决方案（请注意，该文档引用的是Xcode 12，但也适用于Xcode 13和14））。
确保Starscream框架带有启用BUILD_LIBRARY_FOR_DISTRIBUTION设置的构建。

将脚本设置为可执行
```
chmod +x carthage.sh
```
现在您必须使用./carthage.sh而不是carthage来构建依赖项。

Carthage 0.38.0及以上（使用XCFrameworks）
```
./carthage.sh update --use-xcframeworks --platform ios
```
Carthage 0.37.0及以下（使用通用框架）
```
./carthage.sh update --platform ios
```
将来自Carthage/Build文件夹中构建的.framework/.xcframework文件以通常方式添加到项目中。

仅限Carthage 0.37.0及以下

您应该遵循这里的额外说明，在运行您的应用/提交到App Store之前从通用二进制文件中删除模拟器架构。

手动安装

在 Xcode 中选择您的项目。
选择您的应用程序目标。
选择“通用”选项卡，然后向下滚动到“框架、库和嵌入内容”。
从以下发布资产中添加以下文件
- iProov.xcframework
- Starscream.xcframework
注意: 确保添加 .xcframework 文件，而不是 .framework 文件。
在“嵌入”列下，确保所有框架都设置为“嵌入并签名”。

添加 `NSCameraUsageDescription`

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

在您的应用程序的 Info.plist 中添加 NSCameraUsageDescription 条目，并描述您的应用程序为何需要访问摄像头（例如，“为了通过 iProov 验证您的身份。”）

开始使用

获取令牌

在启动 iProov 之前，您需要获取一个用于 iProov 的令牌。存在两种不同类型的令牌

一个验证令牌 - 用于登录现有用户
一个注册令牌 - 用于注册新用户

iProov 提供了 genuine-presence-assurance™ 技术和 liveness-assurance™ 技术

真实现场保证 验证在线远程用户是否为正确人员，真实人员，并且他们在当前进行身份验证，用于访问控制和安全性。
活动性保证 验证远程在线用户是否为正确的人员，真实人员，用于访问控制和安全性。

请参阅我们的REST API 文档获取生成令牌的详细信息。

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

启动 SDK

一旦您获取了令牌，只需调用 IProov.launch()

import iProov

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

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 // An optional image containing a single frame of the user, if enabled for your service provider (see important security info below)

    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 failureCode: String = reason.failureCode // 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 // An optional image containing a single frame of the user, if enabled for your service provider (see important security info below)

    case .cancelled(canceller):
        // Either:
        //
        // (a) The user cancelled iProov by pressing the close button, or sending the
        // app to the background (canceller will be .user), or
        //
        // (b) You cancelled iProov by calling cancel() on the SDK (canceller will be .app) - see cancellation 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应仅用于UI/UX目的。如果您需要上传图片到您的系统（例如人脸匹配、图像分析、用户个人资料图片等），您应通过服务间/validate API调用安全地检索。

取消SDK

在正常情况下，用户将控制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 cancelled
}

选项

您可以通过在启动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`	用于SSL固定所使用的证书。关于详细信息，请参阅以下内容。	iProov Server证书
`timeout`	用于WebSocket连接的网络超时。	`10`（秒）

过滤选项

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

`LineDrawingFilter`

LineDrawingFilter是iProov传统的“Canny”滤镜，有3种风格可供选择：.shaded（默认）、.classic和.vibrant。

foregroundColor和backgroundColor也可以进行自定义。

示例

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

`NaturalFilter`

NaturalFilter提供了更直观的用户面部可视化，有两种风格可供选择：.clear（默认）和.blur。

示例

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

注意: NaturalFilter仅适用于存在性保证要求。尝试将NaturalFilter用于真实存在性保证要求将会导致错误。

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

证书固定

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

如果您正在使用自己的反向代理，则需要更新固定配置，以便将证书固定到您自己的证书上。

证书应以 Data 数组的形式传递，其中包含 DER 编码的 X.509 证书。您可以将以下命令从您的应用程序包中加载 DER 编码的证书：

options.certificates = [try! Data(contentsOf: URL(fileURLWithPath: Bundle.main.path(forResource: "certificate", ofType: "der")!))]

将 .crt 文件转换为 .der，请使用以下命令

$ openssl x509 -in cert.crt -outform der -out cert.der

当传递多个证书时，只要服务器匹配证书中的任何一个，则允许连接。固定是对证书的公钥进行的。

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

options.certificates = []

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

真实存在性保证选项

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

选项名称	描述	默认值
`notReadyOvalStrokeColor`	在 GPA "未就绪" 状态下椭圆描边的颜色。	`.white`
`readyOvalStrokeColor`	GPA "就绪" 状态下椭圆描边的颜色。	#01AC41
`maxYaw`（已弃用）	用户面部可接受的最大偏航值。	`-1`（禁用）
`maxRoll`（已弃用）	用户面部可接受的最大翻滚值。	`-1`（禁用）
`maxPitch`（已弃用）	用户面部可接受的最大俯仰值。	`-1`（禁用）

* 这些选项用于实现姿态控制，该选项已被弃用，并在未来的 SDK 版本中删除。值以归一化单位（0 到 1）提供，其中 -1 表示禁用。这些选项不应用于一般用途；如果您想使用此功能，请联系 iProov 以获得更多信息。

活体确认选项

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

选项名称	描述	默认值
`ovalStrokeColor`	LA扫描期间椭圆轮廓的颜色。	`.white`
`completedOvalStrokeColor`	LA扫描完成后椭圆轮廓的颜色。	#01AC41

自定义 `IProovPresentationDelegate`

默认情况下，当启动SDK时，它将获取应用代理的窗口的 rootViewController 的引用，然后遍历视图控制器栈以找到最顶部的视图控制器，然后从栈中的最顶部视图控制器以模态视图控制器的方式调用 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?
    }

}

警告：使用此功能时，您必须遵守一些重要的规则

权力越大，责任越大！iProov 视图控制器需要整个屏幕的全面覆盖才能正常工作。不要尝试以只占用屏幕部分的方式展示您视图控制器给用户，或使其被其他视图遮挡。您还必须确保在关闭时完全将视图控制器从用户视图中移除。

为了避免保留循环的风险，Options 仅持有您展示代理的 weak 引用。确保您的展示代理在 iProov 捕捉会话的生命周期内被保留，否则可能会导致流程出错。

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

本地化

SDK支持以下语言

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

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

处理失败和错误

失败

当用户的身份无法验证时，会发生失败。失败意味着捕获已被服务器成功接收和处理，并返回了结果。重要的是，这不同于错误，错误是由于系统错误而导致捕获失败。

失败通过回调中的.failure(reason)枚举情况进行捕获。reason是一个枚举，表示用户无法验证/注册的原因，具有以下属性

feedbackCode - 反馈代码的字符串表示形式。
localizedDescription - 您应该将此信息展示给用户，因为这可能为用户提供有关如何最大限度地增加下次 iProoving 成功率的提示。

真正的存在保证

真正的存在保证声明中可用的失败原因如下

枚举值	`localizedDescription`（英语）
`未知`	再次尝试
`移动过多`	保持静止
`太亮`	移动到更暗的地方
`太暗`	移动到更亮的地方
`人脸对齐错误`	将人脸保持在椭圆形内
`眼睛闭上`	保持你的眼睛睁开
`人脸太远`	将人脸移近屏幕
`人脸太近`	将人脸移远屏幕
`戴眼镜`	取下眼镜
`人脸被遮挡`	取下任何遮住人脸的物品
`用户超时`	再次尝试
`不支持`	设备不支持

活跃性保证

活跃性保证声明中可用的失败原因如下

枚举值	`localizedDescription`（英语）
`未知`	再次尝试
`用户超时`	再次尝试
`不支持`	设备不支持

错误

发生错误是因为由于技术问题或用户操作导致的捕获无法完成。

错误通过回调中的 .error(error) 枚举情况捕获。 error 参数提供了 iProov 处理失败的原因，作为 IProovError。

枚举值	描述
`captureAlreadyActive`	现有的 iProov 捕获已经开始。在开始新的捕获之前，请等待当前捕获完成。
`cameraPermissionDenied`	当提示时，用户拒绝了访问摄像头的权限。您应指导用户通过设置重新启用摄像头访问。
`networkError(String?)`	发生视频流处理错误。相关字符串（如果可用）将包含关于错误的更多信息。
`serverError(String?)`	服务器端错误/令牌失效。相关字符串（如有）将包含有关错误的更多信息。
`unexpectedError(String)`	发生了意外且无法恢复的错误。相关字符串将包含有关错误的更多信息。这些错误应报告给iProov以进行进一步调查。

API客户端

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

有关详细信息，请参阅iProovAPIClient文件夹中的文档。

示例项目

要获取一个简单易用的iProov体验，您可以查看示例项目。

安装

请确保您已安装CocoaPods，然后从示例目录运行pod install以安装所需的依赖项。
将Credentials.example.swift重命名为Credentials.swift，并使用您的基URL、API密钥和秘密更新它。您可以从iProov Portal获取这些凭据。
打开Example.xcworkspace。
现在您可以为项目构建和运行。请注意，您只能在真实设备上启动iProov；它无法在模拟器中工作。

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

帮助与支持

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

有关详细信息，请参阅文档中心中的实现指南、术语表和API参考。

如需进一步帮助集成iProov生物识别SDK，请联系[email protected]。

iProov 12.0.0

iProov 12.0.0

iProov 12.0.0

iProov 生物识别 iOS SDK v10.3.0

简介

要求

依赖关系

模块稳定性

仓库内容

从早期版本升级

注册

安装

CocoaPods

Swift 包管理器

通过 Xcode 安装

通过Package.swift安装

Carthage

手动安装

添加 NSCameraUsageDescription

开始使用

获取令牌

启动 SDK

取消SDK

选项

过滤选项

LineDrawingFilter

NaturalFilter

证书固定

真实存在性保证选项

活体确认选项

自定义 IProovPresentationDelegate

本地化

处理失败和错误

失败

真正的存在保证

活跃性保证

错误

API客户端

示例项目

安装

帮助与支持

添加 `NSCameraUsageDescription`

`LineDrawingFilter`

`NaturalFilter`

自定义 `IProovPresentationDelegate`