IOS开发文档
更新时间：2026-07-23 19:05:12
一.准备工作
概述
本文结合示例代码指导您在 iOS 应用中集成活体检测 SDK，帮助您在 App 中实现刷脸认证功能。
前置条件
- 应用必须在 iOS 9.0+ 平台上运行。
创建应用
应用的创建流程及 AppId 的获取，请查看「账号创建」文档
注意：**AppId**与 bundle id 一一对应的绑定关系，否则会校验不通过。
认证流程
graph LR A[SDK 检测] --> B[SDK 返回结果] --> C[云上校验] --> D[认证结果]
快速体验 demo
-
iOS 压缩包中的 demo 文件夹中是示例工程源码，使用 Xcode 打开完成以下步骤配置，可直接运行测试：
-
- 将项目中 bundle id 更改成您的创建应用时填写的 bundle id
- 将项目中的 AppId 换成您创建应用后生成的 AppId
开发环境搭建
- 添加隐私权限
- Privacy - Camera Usage Description
- Privacy - NSUserTrackingUsageDescription
ps:参考文案“请放心，开启权限不会获取您在其他 APP 或网站的隐私信息，该权限仅用于标识设备并保障认证流程安全
- Xcode 关闭 BitCode 选项
Build Setting -搜索 Enable Bitcode -修改设置为NO
- 编译配置
在 Xcode 变异设置的Linking > Other Linker Flags中**，**添加 -ObjC
- 导入 SDK 包及系统依赖包
- SDK 库
APBToygerFacade
APPSecuritySDK
BioAuthEngine
DTFIdentityManager
DTFUtility
ToygerNative
ToygerService
CLLivingDetectSDK- 系统依赖库
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++.1.tbd
libc++abi.tbd
AudioToolbox.framework
CFNetwork.framework
MobileCoreServices.framework
libz.1.2.8.tbd
AdSupport.framework- 拷贝资源文件
选择 TARGETS ，点击 Build Phases 标签页，在 Copy Bundle Resources 中添加如下四个 bundle：
APBToygerFacade.bundle：位于 APBToygerFacade.framework 中。
BioAuthEngine.bundle：位于 BioAuthEngine.framework 中。
ToygerService.bundle: 所在位置为 ToygerService.framework 中。
CLLivingDetect.bundle：所在位置为 CLLivingDetectSDK.framework中。二.API 说明
1.初始化
导入头文件 #import <CLLivingDetectSDK/CLLivingDetectSDK.h>
- 为提高身份核验的用户体验，并为刷脸认证准备必要数据，iOS 客户端需要进行 SDK 初始化。
方法原型
/// 初始化
/// @param appId 控制台创建应用的appid
+ (void)initWithAppId:(NSString *)appId;示例代码
/// 初始化
/// @param appId 控制台创建应用的appid
+ (void)initWithAppId:(NSString *)appId;2.认证参数配置
- 【可选方法】每个配置都有默认值，可以不配置。如需修改默认配置，调用相应配置方法即可。
/// 扫脸圆圈颜色，默认为蓝色，颜色格式为 @"#FFFFFF"
@property(nonatomic, strong) NSString * faceCircleColor;
/// 验证请求超时时间设置
@property(nonatomic, strong) NSNumber * vertifyOutTime;
/// 是否返回图片，默认为@(NO)
@property(nonatomic, strong)NSNumber * returnImage;
/// 是否返回录制视频地址，默认不返回，格式@(YES) or @(NO)
@property(nonatomic, strong) NSNumber * returnVideo;
/// 活体检测动作
///（默认）眨眼动作活体检测；
/// CLLivingVertifyActionMulti：多动作活体检测，眨眼+任意摇头检测
@property(nonatomic, assign) CLLivingVerifyAction vertifyAction;
///是否自定义协议，默认为@(YES),显示协议页 ，为@(NO)需要用户自定义协议页面
@property(nonatomic, assign)NSNumber * showProtocol;
+ (CLLvingConfig *)defaultConfig;示例代码
CLLvingConfig * config = [CLTestSettingModel defaultConfig];
[CLLivingDetectManager setLivingConfig:config];3.开始认证
- 调用此方法会启动 SDK 内部活体检测界面，并返回第4 步服务端查询刷脸认证结果所需要的certifyId。
方法原型
/// 开启活体校验
/// @param viewController 当前显示viewcontroller
/// @param completion 返回结果
+ (void)startVerifyWithViewController:(UIViewController *)viewController
completion:(void(^)(CLLivingResult * result))completion;示例代码
[CLLivingDetectManager startVerifyWithViewController:self completion:^(CLLivingResult * _Nonnull result) {
}];刷脸认证结果
/**
SDK返回外层码
10000 ：刷脸结束
10001：校验失败
10002：验签失败
10003：网络异常
10004：本地异常
*/
@property (nonatomic, assign, readonly)NSInteger code;
/// SDK返回响应描述
@property (nonatomic, strong, readonly)NSString * message;
/// SDK内层码
@property (nonatomic, assign )NSInteger innerCode;
/// SDK内层描述，可查看具体原因
@property (nonatomic, strong )NSString * innerMessage;
/// SDK报错，返回错误信息
@property (nonatomic, strong, readonly)NSError * error;
@property (nonatomic, strong)id ext;
/// SDK 活体检测后返回详细信息
@property (nonatomic, strong)CLLivingDetectResponse * response;4.查询认证结果
客户端刷脸结束，并不能判断是否为真是自然人，务必对接服务端 “活体检测结果查询” 接口，并以服务端查询接口返回的结果为准。 5.日志开关
- 放到初始化之前调用，开启后可打印 SDK 内部调用日志
方法原型
/// 是否开启控制台日志打印
/// @param enable 默认为NO
+ (void)setPrintConsoleEnable:(BOOL)enable;示例代码
[CLLivingDetectManager setPrintConsoleEnable:YES];三、返回码
| 外层码 | 外层描述 | 内层码 | 内层描述 |
|---|---|---|---|
| 10000 | 刷脸结束 | 1000 | 刷脸结束，请通过服务端查询接口获取认证结果（Android端、iOS端） |
| 10001 | 校验失败 | 1001 | 本地代码异常（Android端） |
| 人脸识别算法初始化失败（Android端） | |||
| 不支持的CPU架构（Android端） | |||
| Android系统版本过低（Android端） | |||
| 刷脸超时(单次)（Android端、iOS端） | |||
| 多次刷脸超时（Android端、iOS端） | |||
| 无前置摄像头（Android端） | |||
| 摄像头权限未赋予（Android端） | |||
| 打开摄像头失败（Android端） | |||
| SDK认证流程正在进行中，请等待本地认证流程完成后再发起新调用（Android端） | |||
| 上传炫彩Meta信息失败（Android端） | |||
| 上传炫彩视频失败（Android端） | |||
| 用户点击Home键（Android端） | |||
| 抱歉，系统出错了，请您稍后再试（iOS端） | |||
| 拒绝开通相机权限（iOS端） | |||
| 无法启动相机（iOS端） | |||
| 本地活体检测出错（iOS端） | |||
| 验证中断（用户点击home键等导致验证停止）（iOS端） | |||
| 业务参数错误（iOS端） | |||
| 本地活体检测出错（iOS端） | |||
| 1003 | 用户主动退出认证（Android端、iOS端） | ||
| 用户暂不认证（Android端） | |||
| 2001 | 用户OCR主动退出（iOS端） | ||
| 2002 | |||
| 客户端初始化网络错误（Android端） | |||
| 客户端初始化接口返回网络错误（Android端） | |||
| 信息上传网络错误（Android端） | |||
| 服务端认证接口网络错误（Android端） | |||
| 服务端接口并发请求超出限制（Android端） | |||
| 网络错误（iOS端） | |||
| 2003 | 客户端设备时间错误（iOS端） | ||
| 2006 | 刷脸结束，请通过服务端查询接口获取认证结果（Android端、iOS端） | ||
| 10002 | 验签失败 | 400001 | 参数校验异常（Android端、iOS端） |
| 600016 | Android签名参数异常（Android端） | ||
| 600009 | bundleId不能为空（iOS端） | ||
| 600017 | 平台类型非法（Android端、iOS端） | ||
| 600005 | 签名校验失败（Android端、iOS端） | ||
| 600018 | 签名失效（Android端、iOS端） | ||
| 600004 | 包名签名对应的appid不匹配 或 appid未匹配到应用（Android端、iOS端） | ||
| 500006 | 请求外部系统失败（Android端、iOS端） | ||
| 600019 | 包名签名校验失败（Android端、iOS端） | ||
| 500003 | 业务操作失败（Android端、iOS端） | ||
| 1010 | 服务端返回为空（Android端） | ||
| 10003 | 网络异常 | 1023 | 网络原因导致的超时、域名解析异常等（Android端、iOS端） |
| 10004 | 本地异常 | 1014 | 本地捕获异常（Android端、iOS端） |
| 10005 | 重复调用 | 1015 | 刷脸进行中，请稍后再试 |
| 10006 | 代理异常 | 1016 | 代理返回为空 |
这篇文档对您有帮助吗？
