iOS接入-阿里云帮助中心

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

前提条件

系统版本：iOS 9.0 及以上
支持语言：Objective-C、Swift

说明

SDK 不支持模拟器调试。

权限说明

iOS SDK权限说明如下：

权限	是否必选	使用目的	场景
NSCameraUsageDescription	否	使用相机进行人脸识别。	实人认证方案、多因子意愿认证方案、活体人脸认证方案、活体检测方案
NFCReaderUsageDescription	否	使用NFC读取证件信息。	NFC认证方案
NSMicrophoneUsageDescription	否	录制音频，用于意愿认证。	多因子意愿认证方案
REPLAYKIT	否	录屏功能，用于留存意愿认证过程视频。	多因子意愿认证方案且开启存证视频功能

配置开发环境

在info.plist中配置摄像头和麦克风权限请求（仅金融级多因子意愿认证方案需配置麦克风权限）。
在Xcode的编译设置中关闭Enable Bitcode选项。
重要
Xcode 15 开始 ENABLE_BITCODE 将不再生效，详见：Xcode Release Notes。
在Xcode编译设置的Linking > Other Linker Flags中，添加设置-ObjC。
若您使用Xcode 15进行编译，还需添加Id64。
如果您的工程设置了-force_load选项，则需要加入-force_load <framework path>/AliyunOSSiOS，命令之间以空格隔开，例如-ObjC -force_load <framework path>/AliyunOSSiOS。

配置依赖

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

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

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

SDK中的包：

AliyunFaceAuthFacade.framework
APBToygerFacade.framework
APPSecuritySDK.framework
BioAuthEngine.framework
faceguard.framework
DTFIdentityManager.framework
DTFUtility.framework
MultiFactorFacade.framework
OCRDetectSDKForTech.framework
ToygerNative.framework
ToygerService.framework
VerifyNativeAbility.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数据前调用初始化SDK代码（如步骤3所示）。
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];

说明

getMetaInfo 方法的返回值类型是NSDictionary，在调用服务端的发起认证请求接口时，您需要先将其转为JSON格式。

关于发起认证请求的具体操作，请参见发起认证请求。

调用SDK开始认证。

示例代码如下：

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

参数说明如下表所示。

名称

类型

描述

certifyId

NSString

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

extParams

NSDictionary

通过以下代码传入当前ViewController，用于SDK展现网络加载和认证页面。

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

重要

请注意在 extParams 中务必传入当前控制器，否则会导致 SDK 页面无法正常展示。

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

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

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

更多UI自定义设置，请参见iOS SDK UI自定义配置说明。

返回结果说明：

[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代码包进行体验：

Demo体验前，请将其中的SDK版本更新至最新。

SDK包大小裁剪说明

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

SDK UI自定义设置

更多说明，请参见iOS SDK UI自定义配置说明。