<a name="Yrr29"></a>
# 创蓝实人认证&活体检测 SDK 集成文档 V2.0.0.X

> **名称：** 实人认证&活体检测 iOS SDK 集成文档 **版本：** V2.0.0.X **作者：** 王亚东 **更新日期：** 2021-12-22 **邮箱：** wangyd@253.com **手机：** 16621001237

<a name="E6RPu"></a>
## 合规性说明
| SDK名称 | 场景描述 | 收集个人信息的类型 | 第三方机构名称 | 数据是否加密传输 | 第三方隐私政策链接 |
| --- | --- | --- | --- | --- | --- |
| 实名认证SDK | 活体检测 | 实人认证&活体检测SDK提供活体检测服务过程中收集和使用的信息包括： 用户的面部识别信息、用户的设备摄像头权限：用于活体检测服务中人脸检测、人脸检索、人脸比对； | 上海创蓝云智信息科技股份有限公司 | 是 | [http://git.253.com/wanggang/sdk-release-package](http://git.253.com/wanggang/sdk-release-package) |

<a name="Ixl1O"></a>
## 一、SDK集成
**说明**

- SDK使用Xcode 12.5.1打包，支持iOS9.0及以上系统版本。
- 2.0.0.2版本开始使用Xcode13打包
<a name="SmgYD"></a>
### 1、获取SDK

从官网[下载](https://tensdk.com/sdk-download)活体检测 sdk 包。

<a name="o0pON"></a>
### 2、开发环境搭建

<a name="R9CTv"></a>
#### 2.1 导入FrameWork 

将实人认证SDK压缩包中framework中的所有资源添加到工程中，并选择 Copy Items if need  选项 ![image.png](https://cdn.nlark.com/yuque/0/2020/png/536400/1608802209317-0de52925-5a3b-48ef-8d52-cc85cdfdfeed.png#crop=0&crop=0&crop=1&crop=1&height=354&id=JmGBL&margin=%5Bobject%20Object%5D&name=image.png&originHeight=354&originWidth=601&originalType=binary&ratio=1&rotation=0&showTitle=false&size=44723&status=done&style=none&title=&width=601)
<a name="fPgET"></a>
#### 2.2 配置Xcode

- Xcode->TARGETS->Build Settings->Linking->Other Linker Flags 添加–ObjC 

![image.png](https://cdn.nlark.com/yuque/0/2021/png/544418/1625466300383-3930bade-b555-4e24-9448-9f30f9d34b8e.png#clientId=u71be7088-a10c-4&crop=0&crop=0&crop=1&crop=1&from=paste&height=246&id=pK2kl&margin=%5Bobject%20Object%5D&name=image.png&originHeight=656&originWidth=1618&originalType=binary&ratio=1&rotation=0&showTitle=false&size=168124&status=done&style=none&taskId=ub19c7e97-35ee-4da1-905a-0ef3e271337&title=&width=606)

- Xcode->TARGETS->Info添加相机权限访问描述

![image.png](https://cdn.nlark.com/yuque/0/2020/png/536400/1608810573124-abefc529-6152-44f4-a80d-48d7a066e4b7.png#crop=0&crop=0&crop=1&crop=1&height=238&id=QCZf6&margin=%5Bobject%20Object%5D&name=image.png&originHeight=238&originWidth=601&originalType=binary&ratio=1&rotation=0&showTitle=false&size=68102&status=done&style=none&title=&width=601)

- 如果OCR需要用相册选择身份证或者在活体中需要麦克风播放提示音则需在Xcode->TARGETS->Info添加相册或者麦克风权限访问描述；（该权限为demo所用权限非SDK必须权限，仅供参考）![WeChat54ce344f20f0f0ad7c5ebc350af14638.png](https://cdn.nlark.com/yuque/0/2021/png/544418/1633944884578-aff6149a-7ff7-4431-b01a-2b800c3d1ad0.png#clientId=u1d7ff317-38a8-4&crop=0&crop=0&crop=1&crop=1&from=drop&id=BdG7M&margin=%5Bobject%20Object%5D&name=WeChat54ce344f20f0f0ad7c5ebc350af14638.png&originHeight=958&originWidth=2144&originalType=binary&ratio=1&rotation=0&showTitle=false&size=667274&status=done&style=none&taskId=u7d791bb9-745f-4817-aa14-5838256ebf3&title=)

<a name="B7gZ0"></a>
### 3、 SDK 初始化

<a name="l9zOE"></a>
#### 3.1 初始化

建议在 **Application** 的 didFinishLaunchingWithOptions 方法中进行初始化：

```objectivec
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
 ...
 
 // 控制台log开关
 [CLCoreManager printConsoleEnable:YES];
 // 设置token，建议在需要使用文档中4，5功能时设置，有效期30分钟
 [CLRealPersonManager setToken:@" token "];
 
 
 // 2.0.0.2之前版本使用：
 [CLCoreManager initWithAppid:@" appid "];
 // 2.0.0.2及之后版本使用：
 [CLCoreManager initWithAppkey:@" appkey "];
 
 ...
 return YES;
}
```

注意：在 initWithAppid: 中设置 **appId**：和在setToken：中设置token。

**温馨提示：** **appId/appkey **查看路径，登录开发者平台，右上角点击「**应用管理**」找到自己的应用，点击后面的「**配置**」按钮，然后可以看到 **appkey（对应SDK中appid、appkey）** 了，点击复制按钮即可。token从服务端api获取
<a name="lyuqB"></a>
### 
<a name="kDEZJ"></a>
### 4、调用活体检测功能

<a name="MlN4s"></a>
#### 4.1 回调数据说明

① 会在 completionHandler中回调 CLStatus 信息，具体的信息如下表所示：

| CLStatus | 错误信息 | 备注说明 |
| --- | --- | --- |
| CLCheckPass | 活体检测通过 | / |
| CLCheckNotPass | 活体检测不通过 | / |
| CLOperationTimeout | 操作超时，用户未在规定时间内完成动作 | / |
| CLGetConfFaild | 获取配置信息失败 | / |
| CLRecordFaild | 视频录制失败 | / |
| CLOnlineCheckFaild | 请求检测结果失败 | / |
| CLOnlineUploadFaild | 上传图片失败 | / |
| CLSDKError | SDK内部发生错误 | / |
| CLRPVedioNoMate | 人脸动作与提示动作不吻合，请重试 | / |
| CLRPVedioNoFace | 没有检测到人脸，请重试 | / |
| CLRPVedioMoreFace | 检测到有多张人脸，请重试 | / |
| CLRPVideoIllumination | 检测到光线不足，请重试 | / |
| CLRPVedioAngle | 检测到人脸角度有偏差，请重试 | / |
| CLRPVedioBlue | 检测到人脸模糊，请重试 | / |
| CLRPVedioMask | 检测到人脸有遮挡，请重试 | / |
| CLRPVedioSmall | 检测到人脸过于靠近屏幕，请重试 | / |
| CLNetError | 无网络链接 | / |
| CLRPVedioError | 其他错误 | / |
| CLRPNoMoney | 账号余额不足 | V2.0.0.3新增 |


温馨提示： ① 调用活体检测方法之前，请确保已经获取到相机、！！！ ② 我们提供了默认的声音文件和 **GIF** 图片文件，如不满意可以替换，具体逻辑在demo中实现，可任意更改**；**

<a name="HkOqA"></a>
#### 4.2调用流程
如下从4.2.1到4.2.4时一个完整的检测流程 4.2.1 先初始化活体检测对象
```objectivec
/// 初始化活体检测对象
/// @param recordView 传入放置检测活体的recordView对象
- (instancetype)initWithRecordView:(UIView *)recordView;
```
 4.2.2 在开始活体检测前进行相关参数设置
```objectivec
/// 设置活体检测的超时时间（在开始活体检测之前设置）
/// @param timeout 请传入10-120范围内的时间值，单位s
- (void)setTimeoutInterval:(NSTimeInterval)timeout;

/// 设置活体检测每个动作的时长（在开始活体检测之前设置）
/// @param duration 每个动作的时长（1-5s）
- (void)setActionDuration:(CGFloat)duration;

/// 设置活体检测动作的个数（在开始活体检测之前设置，默认为1-3的随机数 V2.0.0.3+版本默认为1个）
/// @param number 动作的个数（1-3）
/// @param securityLevel 安全级别：默认为低（随机动作数），高至少为两个动作(会修正number设置数量)
- (void)setActionNumber:(NSInteger)number securityLevel:(CLSecurityLevel)securityLevel;

/// 设置检测时脸离屏幕距离（在开始活体检测之前设置）V2.0.0.3版本增加
/// @param distance 默认0（-1：稍近，0：正常，1：稍远）
- (void)setDistanceNumber:(NSInteger)distance;
```
 4.2.3 开始活体检测
```objectivec
/// 开始活体检测
/// @param actionsHandler 活体检测动作序列号的回调（非主线程）
/// @param completionHandler 活体检测结果的回调（非主线程），结果状态见CLStatus枚举类型
- (void)startLiveDetectWithActionsHandler:(CLAcitionsHandler)actionsHandler
 completionHandler:(CLCompletionHandler)completionHandler;

/// 活体检测，视频转发
/// @param urlString 视频转发之后URL或者startLiveDetectWithActionsHandler：返回的url
/// @param isReTran 表示是否转发，YES：转发urlString参数值为转发后的url NO：不转发urlString参数值为startLiveDetectWithActionsHandler：中返回的url
- (void)resultWithDetectUrl:(NSString *)urlString
 isReTran:(BOOL)isReTran;
```
 4.2.4 停止活体检测
```objectivec
/// 停止活体检测
/// 调用时机：
/// 1、在活体检测结果的回调里调用
/// 2、未完成活体检测，需要中止时调用 (超时不要调用)
- (void)stopLiveDetect;
```

<a name="fXBcg"></a>
### 5、调用身份证 OCR 功能

身份证 OCR 接口封装了常用 OCR 的使用场景，例如，身份证单面 OCR，身份证双面 OCR，身份证二要素认证等类型，可根据自己的实际需求，选择合适的调用类型。

<a name="LrowO"></a>
#### 5.1 api如下
```objectivec
/// 身份证OCR接口 ⚠️ 先调用人像面（图片大小建议压缩为1M以内，超过会被SDK压缩）
/// @param image 身份证图片
/// @param isFront YES:为人像面 NO:为国徽面
/// @param complecte 结果回调（非主线程） data数据为字典，格式如下：
 /*
 国徽面数据： {
 "expire_date" = "失效日期";
 "issuing_authority" = "签发机关";
 "issuing_date" = "签发日期";
 };
 人像面数据： {
 "address" = "地址";
 "brith_day" = "出生日期";
 "id_card_no" = "身份证号";
 "name" = "姓名";
 "nation" = "民族";
 "sex" = "性别";
 };
 */
+ (void)realPersonOCR:(UIImage *)image isFront:(BOOL)isFront complect:(CLCoreNetComplete)complecte;


/// 身份证OCR接口 识别人像面和国徽面（单图片大小建议压缩为1M以内，超过会被SDK压缩）
/// @param frontImage 人像面照片
/// @param backImage 国徽面照片
/// @param complecte 结果回调（非主线程） data数据为字典，格式如下：
 /* {
 back = {
 "expire_date" = "失效日期";
 "issuing_authority" = "签发机关";
 "issuing_date" = "签发日期";
 };
 front = {
 "address" = "地址";
 "brith_day" = "出生日期";
 "id_card_no" = "身份证号";
 "name" = "姓名";
 "nation" = "民族";
 "sex" = "性别";
 };
 }
 */
+ (void)realPersonOCR:(UIImage *)frontImage backImage:(UIImage *)backImage complect:(CLCoreNetComplete)complecte;


/// 身份证认证
/// @param name 姓名
/// @param idNumber 身份证号码
/// @param complecte 结果回调（非主线程） data数据为字典，格式如下：
 /*{
 "order_no" : "业务唯一流水号",
 "city" : "城市",
 "country" : "县区",
 "gender" : "性别：1：男、2：女",
 "age" : "年龄",
 "remark" : "备注，例：一致",
 "birthday" : "生日，格式是yyyyMMdd",
 "result" : "返回结果： 01-认证一致(收费) 02-认证不一致(收费) 03-认证不确定（收费） 04-认证失败(不收费)",
 "handle_time" : "查询时间 例：2018-04-09 15:05:01",
 "province" : "省份"
 }*/
+ (void)realPersonDectect:(NSString *)name idNumber:(NSString *)idNumber complect:(CLCoreNetComplete)complecte;

```
<a name="UaE2G"></a>
#### 
<a name="CgSy0"></a>
### 6、API功能模块说明
<a name="mPJMK"></a>
#### 6.1 如果只用到活体或者OCR功能
先调用3中SDK初始化，然后调用4或者5中对应的api功能
<a name="j7cWB"></a>
#### 6.1 如果用到活体和OCR功能
先调用3中SDK初始化，然后调用4和5中对应的api功能

具体逻辑参考demo，demo提供了具体的UI和逻辑实现。
<a name="IIkJ3"></a>
## 二、历史版本
| 发布日期 | 发布版本 | 更新说明 |
| --- | --- | --- |
| 2021-07-05 | V1.0.0.0 | 初版发布 |
| 2021-07-12 | V1.0.0.1 | 优化SDK包体积 |
| 2021-07-29 | V1.0.0.2 | 新增身份证双面OCR接口，优化OCR接口安全性 |
| 2021-10-11 | V2.0.0.0 | 优化SDK包体积，更换为API形式验证 |
| 2021-12-10 | V2.0.0.1 | 优化文档和注释，demo中转发逻辑调整 |
| 2021-12-22 | V2.0.0.2 | 更改appid为appkey，demo适配iOS15 |
| 2022-03-18 | V2.0.0.3 | 优化SDK功能逻辑 |

活体检测SDK集成文档-iOS

使用入门

功能介绍

开发文档

常见问题

羊毛盾标准版

客户端接入

服务端接入

图文验证码

认证安全

创蓝云智，为企业提供全面的数据接口API/SDK。免费试用，满意为止。致力于让企业更高效高质量的获得用户及触达用户。

创蓝云智-全面的API数据接口

注册登录

新客获客

老客激活

金融行业

游戏行业

电商行业

餐饮行业

活体检测SDK集成文档-iOS