如何使用刷脸认证提供的iOS客户端SDK进行iOS客户端接入

刷脸认证提供iOS客户端SDK，帮助您在业务应用（App）中实现刷脸认证功能。您可通过刷脸认证的服务端认证初始化接口，获取刷脸认证唯一标识CertifyId，并使用CertifyId唤起刷脸认证客户端SDK。本文将结合示例代码进行iOS客户端接入的详细说明。

前提条件

刷脸认证应用必须运行在iOS 9.0及以上版本的系统上。
您的业务应用必须采用Objective C++或Swift集成金融级实人认证服务。

说明

iOS接入不支持模拟器模式调试。

配置开发环境

在info.plist中配置摄像头权限请求。
在Xcode的编译设置中关闭Enable Bitcode选项。
在Xcode编译设置的Linking > Other Linker Flags中，添加设置-ObjC。
如果您的工程设置了-force_load选项，则需要加入-force_load <framework path>/AliyunOSSiOS，命令之间以空格隔开，例如-ObjC -force_load <framework path>/AliyunOSSiOS。

配置依赖

下载iOS SDK。
该SDK为framework包。您需要在Xcode添加Link Binary With Libraries、SDK中的12个包和额外系统库依赖。

解压下载的SDK包，并在解压的文件夹中执行以下命令提取所有的framework到Products目录。

for i in $(ls *.tgz);do tar xvf $i;done

SDK中的包：

AliyunFaceAuthFacade.framework
APBToygerFacade.framework
APPSecuritySDK.framework
BioAuthEngine.framework
deviceiOS.framework
DTFIdentityManager.framework
DTFUtility.framework
MultiFactorFacade.framework
OCRDetectSDKForTech.framework
ToygerNative.framework
ToygerService.framework

系统库依赖：

CoreGraphics.framework
Accelerate.framework
SystemConfiguration.framework
AssetsLibrary.framework
CoreTelephony.framework
QuartzCore.framework
CoreFoundation.framework
CoreLocation.framework
ImageIO.framework
CoreMedia.framework
CoreMotion.framework
AVFoundation.framework
WebKit.framework
libresolv.tbd
libz.tbd
libc++.tbd
libc++.1.tbd
libc++abi.tbd
AudioToolbox.framework
CFNetwork.framework
MobileCoreServices.framework
libz.1.2.8.tbd
AdSupport.framework
ReplayKit.framework

拷贝资源文件

选择TARGETS，单击Build Phases页签，在Copy Bundle Resources中添加以下bundle：

APBToygerFacade.bundle：位于APBToygerFacade.framework中。
ToygerService.bundle：位于ToygerService.framework中。
OCRXMedia.bundle：位于OCRDetectSDKForTech.framework中。
BioAuthEngine.bundle：位于BioAuthEngine.framework中。
MultiFactorFacade.bundle：位于MultiFactorFacade.framework中。
APBToygerFacadeSuitable.bundle：位于APBToygerFacade.framework中。

调用SDK

引入头文件。

命令如下：

#import <AliyunFaceAuthFacade/AliyunFaceAuthFacade.h>

初始化SDK。
说明
为了提升用户体验并为刷脸认证准备一些必备的数据，iOS客户端需要初始化SDK。您可以在调用appDelegate函数时（如下列代码所示）放置初始化SDK代码。您也可以在获取metaInfo数据前（如步骤3所示）放置初始化SDK代码。
appDelegate函数调用，示例代码：
```
- (BOOL)application:(UIApplication)application didFinishLaunchingWithOptions:(NSDictionary)launchOptions {
    [AliyunFaceAuthFacade initSDK];// 初始化SDK。
}
```
IPv6网络初始化，示例代码如下：
```
- (BOOL)application:(UIApplication)application didFinishLaunchingWithOptions:(NSDictionary)launchOptions {
    [AliyunFaceAuthFacade initIPv6];// 初始化SDK。
}
```
获取metaInfo数据。
示例代码如下：
```
[AliyunFaceAuthFacade initSDK];// 初始化SDK，如果已经在appDelegate函数中调用过，此处无需再重复调用。
[AliyunFaceAuthFacade getMetaInfo];
```
IPv6网络初始化，示例代码如下：
```
[AliyunFaceAuthFacade initIPv6];// 初始化SDK，如果已经在appDelegate函数中调用过，此处无需再重复调用。
[AliyunFaceAuthFacade getMetaInfo];
```
说明
返回值类型是NSDictionary，您的服务端需要将其转换为JSON字符串。调用服务端发起认证请求接口时，在入参metaInfo中传入该值。关于发起认证请求的具体操作，请参见发起认证请求。

调用SDK开始认证。

示例代码如下：

[AliyunFaceAuthFacade verifyWith:certifyId extParams:extParams onCompletion:^(ZIMResponse *response) {}];

参数说明如下表所示。

名称

类型

描述

certifyId

NSString

您可以通过服务端发起申请请求接口获取该参数。关于发起认证请求的具体操作，请参见发起认证请求。

extParams

NSDictionary

通过以下代码传入当前viewController，用于展现网络加载和presentViewController。

[extParams setValue:self forKey:@"currentCtr"];

如需设置OCR的下一步按钮的颜色，在extParams中添加按钮的正常颜色和按钮按下时的颜色。代码示例如下：

[extParams setValue:@"00FF00" forKey:ZIM_EXT_PARAMS_KEY_OCR_BOTTOM_BUTTON_COLOR];
[extParams setValue:@"0000FF" forKey:PARAMS_KEY_OCR_BOTTOM_BUTTON_CLICKED_COLZIM_EXT_OR];

如需设置扫脸时的圆圈颜色，在extParams中添加圆圈颜色。代码示例如下：
```
[extParams setValue:@"FF0000" forKey:ZIM_EXT_PARAMS_KEY_OCR_FACE_CIRCLE_COLOR];
```
如需返回本地视频，在extParams中添加returnVideo，并且设置值为true。代码示例如下：
```
[extParams setValue:@"true" forKey:@"returnVideo"];
```
如需服务端查询接口返回视频，需要额外在extParams中添加ZIM_EXT_PARAMS_KEY_USE_VIDEO_UPLOAD，并且设置值为true。代码示例如下：
```
[extParams setValue:@"true" forKey:ZIM_EXT_PARAMS_KEY_USE_VIDEO_UPLOAD]
```
说明
金融级实人认证支持设置返回活体检测的视频，默认设置为不返回。如果设置为返回，在您使用金融级实人认证SDK完成认证（不区分认证结果为F或T），并在SDK回调和查询接口时返回视频路径，请您及时处理。
如需自定义X号（页面关闭按钮），您可以参照以下步骤：
- 如需自定义X号的图片，需要额外在extParams中添加cancelImage，并设置值为UIImage。代码示例如下：
```
[extParams setValue:UIImage forKey:@"cancelImage"];
```
- 如需自定义X号的图片位置，需要额外在extParams中添加imageOrientation，并设置值为right或left 。默认为left。代码示例如下：
```
[extParams setValue:@"right" forKey:@"imageOrientation"];
```

返回结果说明：

[AliyunFaceAuthFacade verifyWith:certifyId extParams:extParams onCompletion:^(ZIMResponse *response) {}];

response.code包含以下返回参数，具体说明如下表所示。

错误码	错误码文案	错误码描述
1000（ZIMResponseSuccess）	刷脸成功	表示刷脸成功。说明该结果仅供参考。可通过调用服务端DescribeFaceVerify接口获取最终认证结果。
1001（ZIMInternalError）	系统错误	表示系统错误。
1003（ZIMInterrupt）	验证中断	表示验证中断。
2002（ZIMNetworkfail）	网络错误	表示网络错误。
2003（ZIMTIMEError）	客户端设备时间错误	表示客户端设备时间错误。
2006（ZIMResponseFail）	刷脸失败	表示刷脸失败。说明如需获取认证不通过的详情，需通过调用服务端DescribeFaceVerify接口。

说明

关于错误码的更多信息，请参见iOS客户端错误码详情。

代码示例：

[AliyunFaceAuthFacade verifyWith:certifyId extParams:extParams onCompletion:^(ZIMResponse *response) {
         dispatch_async(dispatch_get_main_queue(), ^{
             NSString *title = @"刷脸成功";
             switch (response.code) {
                 case ZIMResponseSuccess://1000。
                     break;
                 case ZIMInterrupt://1003。
                     title = @"用户退出";
                     break;
                 case ZIMNetworkfail://2002。
                     title = @"网络错误";
                     break;
                 case ZIMTIMEError: //2003。
                     title = @"设备时间设置不对";
                     break;
                 case ZIMResponseFail: //2006。
                     title = @"刷脸失败";
                     break;
                 case ZIMInternalError://1001。
                     title = @"初始化失败";
                     break;
                 default:
                     break;
             }
         });
    }];

Demo代码包

您可以下载以下iOS Demo代码包进行体验。在使用过程中，请替换iOS Demo代码包中的文件的版本为最新的版本：

SDK包大小裁剪说明

更多说明，请参见SDK包裁剪说明。