iOS-服务端接入指南
1. 文档说明
| 文档名称 | 人脸实名认证APP方案 6.3版本集成文档 |
|---|---|
| 所属平台 | iOS |
| 提交日期 | 2023-11-09 |
2. 版本说明
| 名称 | 版本号 |
|---|---|
| 名镜方案 | 6.3.0 |
| 系统支持 | iOS 9.0 + |
| 架构 | arm64 |
| IDE | Xcode 14+ |
3. SDK说明
| SDK | 版本号 | 说明 | 类型 |
|---|---|---|---|
| BDFaceBaseKit.framework | 6.3.0 | 人脸采集SDK | 静态库 |
| AipOcrSdk.framework | 1.1.0 | OCR识别SDK | 动态库 |
| AipBase.framework | 1.0.0 | 基础工具类SDK | 动态库 |
| IdcardQuality.framework | 1.0.0 | 身份证质量控制SDK | 动态库 |
| BDFaceLogicLayer.framework | 1.0.0 | 名镜服务SDK | 静态库 |
4. 运行项目工程
4.1 打开下载的iOS示例工程
如下图所示：
4.2 确认bundleId等信息是否正确
连接真机进行运行，之后可以看到如下界面：
4.3 点击开始身份认证
测试示例工程是否跑通，之后扫码身份证或输入身份证信息后，点击进行身份核验，验证成功可以看到如下界面：
上图为示例工程运行成功，之后可以将示例工程代码集成到目标项目中。
5. 集成步骤
5.1 将BDFaceSDK文件夹下所有文件拖动到目标项目中
如下图所示
5.2 将AipBase.framework, AipOcrSdk.framework和IdcardQuality.framework DebugFramework.framework拖动到目标项目
如下所图示
5.3 将BDFaceSDK文件夹（如下图所示的文件夹）整体拖入到目标代码中；
5.4 在Build Phases中点击下面的+号
选择NewCopyFilePhases,添加一个CopyFiles（可重新命名为Embed）
5.5 双击CopyFiles
改为Embed Frameworks，同时Destination改为framework，之后将AipBase.framework、AipOcrSdk.framework和IdcardQuality.framework 拖动到下面
5.6 Link Binary With Libraries中添加libc++.tbd、libz.tbd 和 对应的framework
如下图所示:
5.7 确认添加的库文件设置正确
如下图所示，点击general, 这三个库需要为Do Not Embed：BDFaceBaseKit.framework, BDFaceLogicLayer.framework，CoreTelephony.framework.
5.8 info.plist 文件中添加以下key（获取相机和照片权限）
最后之后可以将人脸核验示例工程代码代码结合自身工程项目，将相关代码集成到目标工程中。
6. 授权文件、加密文件
人脸识别授权文件（idl-license.face-ios），图片加密文件（idl-key.face-ios），OCR身份证识别授权文件（aip.license），从console平台下载完iOS项目，这些文件即包括在下载的示例项目中，不需要特殊处理，按上面第5.3步整体拖入目标项目中即可。
6.1 鉴权文件配置相关问题说明:
配置授权信息： 导入license文件后，需配置FACE_LICENSE_NAME、FACE_LICENSE_ID等信息:
具体参数使用请参照示例demo。
license文件使用注意事项：如出现鉴权失败无法调用人脸采集，请检查license id与license文件导入及配置是否正常。
（1）license id需要注意-face-ios后缀是否添加。
（2）如存在多种环境配置，请确保每个环境下的license id与license文件一一对应。tip：license文件存在运行缓存，切换测试环境请清空缓存，删除安装包后重新编译安装。
（3）确保license文件路径访问正常。
（4）如出现网络鉴权失败等提示，说明license文件与FACE_LICENSE_NAME未正确设置，请才考接入demo检查工程环境，确保参数无误。
加解密key文件使用注意事项：根据2.1-2.2步骤添加加解密key文件到项目工程
（1）确保加解密key文件已重命名为idl-key.face-ios。
（2）确保idl-key.face-ios文件路径访问正常。
（3）若存在多中环境配置，请手动更新该对应文件，清空缓存后重新编译安装app包进行测试。
7. 人脸相关接口
7.1 设置默认参数（动作活体参数，人脸配置参数，UI参数）
初始化人脸和OCR SDK */
- (void)initFaceServiceAndInfoCollectService
初始化人脸SDK动作活体参数配置 */
- (void)initFaceSDK
7.2 初始化接口
初始化接口调用 用于初始化人脸识别和OCR识别
| API | 描述 |
|---|---|
| -(instancetype)initWithController:(UIViewController * _Nonnull)controller face:(void(^)(void))initFaceBlock ocr:(void(^)(void))initOcrBlock | 传入当前controller，并初始化人脸和ocrSDK |
入参说明
| 参数 | 类型 | 说明 |
|---|---|---|
| controller | UIViewController * | 当前controller |
| initFaceBlock | Block对象 | 人脸识别初始化Block |
| initOcrBlock | Block对象 | OCR识别初始化Block |
initFaceBlock中，使用以下函数进行人脸SDK初始化 -(void)initCollectWithLicenseID:(NSString )licenseID andLocalLicenceName:(NSString )licenseName andExtradata:(NSDictionary *)extradata callback:(FaceSDKInitResultBlock )block;
回调状态码说明
| 参数 | 类型 | 说明 |
|---|---|---|
| BDFaceInitRemindCode | 枚举 | 初始化人脸的状态码,1000为成功，其他为失败，详情参考如下错误码说明 |
具体枚举值如下
| 枚举值 | 对应数字 | 说明 | 自查建议 |
|---|---|---|---|
| BDFaceLICENSE_NOT_INIT_ERROR | 1001 | license未初始化 | 请按照集成文档说明完成SDK初始化 |
| BDFaceLICENSE_DECRYPT_ERROR | 1002 | license数据解密失败 | 请检查License文件是否正确 |
| BDFaceLICENSE_INFO_FORMAT_ERROR | 1003 | license数据格式错误 | 请检查license文件内容有被修改过 |
| BDFaceLICENSE_KEY_CHECK_ERROR | 1004 | license-key(api-key)校验错误 | 请检查工程代码初始化参数中的licenseId，和申请license文件的licenseId是否匹配 |
| BDFaceLICENSE_ALGORITHM_CHECK_ERROR | 1005 | 算法ID校验错误 | 请提交工单或者线下联系百度产研人员 |
| BDFaceLICENSE_MD5_CHECK_ERROR | 1006 | MD5校验错误 | 请检查工程所使用的签名文件，和申请license文件的签名信息是否匹配 |
| BDFaceLICENSE_DEVICE_ID_CHECK_ERROR | 1007 | 设备ID校验错误 | 采集SDK的授权模式不会出现这个错误码 |
| BDFaceLICENSE_PACKAGE_NAME_CHECK_ERROR | 1008 | 包名(应用名)校验错误 | 请检查工程代码中的applicationId（包名）和申请license文件的applicationId（包名）是否匹配 |
| BDFaceLICENSE_EXPIRED_TIME_CHECK_ERROR | 1009 | 授权过期时间有问题 | 请提交工单或者线下联系百度产研人员 |
| BDFaceLICENSE_FUNCTION_CHECK_ERROR | 1010 | 功能未授权 | 请查看授权文件中是否缺少必要的采集SDK功能声明（funclist参数），例如炫瞳活体 |
| BDFaceLICENSE_TIME_EXPIRED | 1011 | 授权已过期 | 请查看当前设备时间是否已不在授权文件有效期内 |
| BDFaceLICENSE_LOCAL_FILE_ERROR | 1012 | 本地授权文件读取失败 | 请检查授权文件名称以及路径 |
| BDFaceLICENSE_REMOTE_DATA_ERROR | 1013 | 远程授权文件拉取失败 | 本地鉴权失败之后，会远程拉取授权文件；若远程鉴权依然失败，可以关闭网络后重试 |
| BDFaceLICENSE_LOCAL_TIME_ERROR | 1014 | 本地时间校验错误 | 请检查当前设备时间是否早于实际时间 |
7.3 人脸信息加密采集接口
- 包含本地质量和本地活体，本地质量可以确保采集到的人脸图像符合各条件校验（满足姿态角、光照、模糊度、遮挡等校验），本地活体分静默活体、炫瞳活体、动作活体三种。
- 此处最终采集到的数据经过加密处理，需要配合服务端的 人脸实名认证V4 或 人脸对比V4 或 在线图片活体V4 来使用。分别用来实现「权威数据源身份信息核验」、「本地图片无源比对」以及「仅活体检测」，适用于不同的业务场景需要。
- sKey、xDeviceId、data 为此接口的成功回调结果信息，作为上述3个服务端接口重要字段入参
| 返回值 | API | 描述 |
|---|---|---|
| -(void)startFaceCollect:(void(^)(int resultCode, NSDictionary *resultDic))callBack; | 人脸采集接口 |
回调说明
| 参数 | 类型 | 含义 | 值 |
|---|---|---|---|
| resultCode | int | 错误码 | 0为成功，其他为失败，详情参考实名认证code错误码说明 |
| resultDic | NSDictionary | 回调结果 | 详情见下表 |
resultDic key值列表说明：
| Key值 | 类型 | 含义 |
|---|---|---|
| resultMsg | String | 详情见code错误码说明 |
| sKey | String | 安全相关：sKey |
| xDeviceId | String | 安全相关：xDeviceId |
| data | String | 安全相关数据 |
8. OCR身份证识别相关接口
8.1 OCR身份证识别初始化接口
| API | 描述 |
|---|---|
| -(void) authWithLicenseFileData: (NSData *)licenseFileContent; | 将aip.license文件的NSData数据传入OCR SDK进行初始化和鉴权 |
入参说明
| 参数 | 类型 | 含义 |
|---|---|---|
| licenseFileContent | NSData | 将aip.license文件读出来，转发NSData类型 |
注：如果aip.license文件鉴权文件正确，那么可以使用OCR识别成功识别身份证信息。
8.2 OCR身份证识别接口
支持对二代居民身份证字段进行结构化识别，包括姓名、性别，调用参考OCR身份证识别接口文档。
| 返回值 | API | 描述 |
|---|---|---|
| UIViewController | -(UIViewController )startOcrRecognize:(BDAipOCRConfig )config didGetImage:(void(^)(UIImage image))getImageAction success:(void(^)(NSDictionary result))success failure:(void (^)(NSError *error))failure; | OCR识别接口 |
参数值列表如下：
| 参数 | 类型 | 说明 | 必选 |
|---|---|---|---|
| config | BDAipOCRConfig | 用于设置OCR页面相关UI | 否 |
| getImageAction | Block | 获取到的图片信息回调 | 否 |
| success | Block | 获取身份信息成功回调 | 否 |
| failure | Block | 获取身份信息失败回调 | 否 |
config配置说明
| 属性 | 类型 | 说明 |
|---|---|---|
| titleViewBgColor | UIColor | OCR页面导航栏背景色，默认为白色 |
| pageTitle | NSString | OCR标题内容，默认为"身份信息采集" |
| pageTitleTextColor | UIColor | OCR标题颜色，默认为黑色 |
| topTipText | NSString | OCR顶部扫描文字，默认为"请将您本人的\n身份证人像面放入框内" |
| topTipTextColor | UIColor | OCR 顶部文字颜色，默认为白色 |
9. 权限
| 名称 | 用途 |
|---|---|
| Privacy - Camera Usage Description | 获取相机权限，需要使用相机做人脸识别和OCR识别 |
| Privacy - Photo Library Additions Usage Description | iOS 11及以后保存照片到相册权限,OCR识别需要从相册选择照片 |
| Privacy - Photo Library Usage Description | 使用相册权限，OCR识别需要从相册选择照片 |
| Privacy - Microphone Usage Description | 人脸识别视频录制功能会使用该权限 |
10. 只使用人脸采集功能，不使用OCR
10.1 运行示例工程代码
点击开始身份核验，走完所有流程，可以出现如下界面：
10.2 删除库文件：AipOcrSdk.framework，AipBase.framework，IdcardQuality.framework
10.3 全局搜索与AipOcrSDK/AipOcrSdk.h
找到后并删除项目中所有引入对应SDK的代码，也可以注释，在删除后可能导致编译不通过，可以根据报错部分保证正常功能不受影响的同时进行相应的代码注释。
10.4 全局搜索 -(void) startOCRSdk 并注释该函数
注意：其他编译报错部分调用的地方也需要注释或删除
// 打开相机扫描
- (void)startOCRSdk {
[self configCallback];
// 身份证识别
[AipCaptureCardVC clearIdCard];
BDAipOCRConfig *config = [[BDAipOCRConfig alloc] init];
AipNavigationController *detectNavi = [AipCaptureCardVC viewControllerToDetectIdCard:config
handler:^(UIImage *image) {
_idCardImage = image;
[[AipOcrService shardService] detectIdCardFrontFromImage:image
withOptions:nil
successHandler:^(id result) {
_successHandler(result);
} failHandler:_failHandler];
}];
UIViewController *detectRoot = [[UIViewController alloc] init];
detectRoot.view.backgroundColor = [UIColor whiteColor];
detectRoot.view.clipsToBounds = YES;
[detectRoot addChildViewController:detectNavi];
[detectRoot.view addSubview:detectNavi.view];
[self.navigationController pushViewController:detectRoot animated:YES];
_vc = detectRoot;
__weak typeof(detectRoot) weakDetectRoot = detectRoot;
detectNavi.captureController.backAction = ^{
[weakDetectRoot.navigationController popViewControllerAnimated:YES];
};}10.5 .编译运行代码首页并将身份证OCR功能关闭或者使用代码
// 身份证获取方式 1 OCR扫描 0 手动输入 2代码传
+ (int)useOCR {
BDConfigDataService *service = [self sharedInstance];
NSNumber *value = service.sharedDic[BDConfigDataServiceKeyForSettingOcr];
if (value) {
return value.intValue;
}
return [[BDConfigFileParser sharedInstance] useOCR];}10.6 将userOCR的值设置为0
保证程序只能手动输入身份信息来调用人脸，此部分功能模块不使用也可以对应删除。
运行工程