iOS-方案集成指南
1. 文档说明
文档名称 | 人脸实名认证APP方案 6.3版本集成文档 |
---|---|
所属平台 | iOS |
提交日期 | 2023-11-09 |
2. 版本说明
名称 | 版本号 |
---|---|
名镜方案 | 6.3.0 |
系统支持 | iOS 9.0 + |
架构 | arm64 |
IDE | Xcode 14+ |
2.1 版本升级改动点说明:
- 去除『人形虚线检测框』、改成圆形进度条显示进度、采集提示文案一级、二级文案字体、颜色调整
- 采集框新增倒计时功能提示,默认20秒阈值,全流程整数倒计时
- 新增中英文文案切换,语言类型非简体中文ZH_CN时,禁用所有采集提示音。默认简体中文ZH_CN,SDK初始化前支持传入英文标识EN来修改配置。
- 部分页面icon图片尺寸和文字字体大小调整
- 外国人永居证件号新规则兼容 在已有15位老证件号校验规则的同时,新增支持18位新证件号的规则校验,同时满足以下条件的证件号,允许透传至权威数据源进行核验: (1)总位数为18,仅存在数字或"X" (2)首位数字固定为“9”,为外国人标识码 (3)最后一位为校验位,与通过前17位计算得来的结果匹配(同二代身份证校验位计算)
- ocr鉴权首次下载失败问题优化修复
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 使用如下链接请求百度Token
https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=【百度云应用的AK】&client_secret=【百度云应用的SK】 注意:上述百度云应用的AK和百度云应用的SK,应当替换为您自己名下的AK和SK。 详细获取资料,请参考:https://ai.baidu.com/ai-doc/REFERENCE/Ck3dwjhhu 最终获取到的token应如下图所示:
4.3 全局搜索关键词: #warning developer
注意:这种方式只是调试阶段的代码,上线代码不可用如下方式,而应该每次都重写获取,因为token会在一定时间内变化)可以找到如下,被注释的代码 /// self.accessToken = @"";如下图所示
【重要】这里这种写法仅仅用于测试功能,正式上线,token不能写成固定值,需要每次都请求。为了安全期间,建议将请求放到自己服务器上,做一层转发,而不是将AK,SK写在端上来请求。
打开这个注释,将上述token内容写入:例: self.accessToken = @"25.b55fe1d287227ca97aab219bb249b8ab.315360000.1798284651.282335-8574074"; 代码如下图所示:
4.4 确认bundleId等信息是否正确
连接真机进行运行,之后可以看到如下界面:
4.5 点击开始身份认证
测试示例工程是否跑通,之后扫码身份证或输入身份证信息后,点击进行身份核验,验证成功可以看到如下界面:
上图为示例工程运行成功,之后可以将示例工程代码集成到目标项目中。
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 | 本地时间校验错误 | 请检查当前设备时间是否早于实际时间 |
BDFaceOTHER_ERROR | 1015 | 其他错误 | 请提交工单或者线下联系百度产研人员 |
BDFaceILLEGAL_PARAMS | 2001 | 非法的参数 | 请提交工单或者线下联系百度产研人员 |
BDFaceMEMORY_ALLOCATION_FAILED | 2002 | 内存分配失败 | 请提交工单或者线下联系百度产研人员 |
BDFaceINSTANCE_IS_EMPTY | 2003 | 实例对象为空 | 请提交工单或者线下联系百度产研人员 |
BDFaceMODEL_IS_EMPTY | 2004 | 模型内容为空 | 请提交工单或者线下联系百度产研人员 |
BDFaceUNSUPPORT_ABILITY_TYPE | 2005 | 不支持的能力类型 | 请提交工单或者线下联系百度产研人员 |
BDFaceUNSUPPORT_INFER_TYPE | 2006 | 不支持的预测库类型 | 请提交工单或者线下联系百度产研人员 |
BDFaceNN_CREATE_FAILED | 2007 | 预测库对象创建失败 | 请提交工单或者线下联系百度产研人员 |
BDFaceNN_INIT_FAILED | 2009 | 预测库对象初始化失败 | 请提交工单或者线下联系百度产研人员 |
BDFaceABILITY_INIT_FAILED | 2010 | 人脸能力初始化失败 | 请按照集成文档说明正常完成SDK初始化 |
BDFaceABILITY_UNLOAD | 2011 | 能力未加载 | 请确认当前人脸相关资源库是否完整引用 |
BDFaceABILITY_ALREADY_LOADED | 2012 | 人脸能力已加载 | 底层已做过滤,无需关注 |
BDFaceNOT_AUTHORIZED | 2013 | 未授权 | 检查授权文件是否按照集成文档正常使用 |
BDFaceABILITY_RUN_EXCEPTION | 2014 | 人脸能力运行异常 | 请提交工单或者线下联系百度产研人员 |
BDFaceUNSUPPORT_IMAGE_TYPE | 2015 | 不支持的图像类型 | 请提交工单或者线下联系百度产研人员 |
BDFaceIMAGE_TRANSFORM_FAILED | 2016 | 图像转换失败 | 检查摄像头分辨率,格式要求 %2==0 |
7.2 人脸实名认证接口(有源)
基于姓名、身份证号、当前SDK获取的人脸图片,与公安权威数据源进行对比,并得出比对分数,并基于此进行业务判断是否为同一人。
此处最终采集到的数据经过加密处理,需要配合开放平台人脸实名认证V4接口使用,包含活体检测、质量检测、实名认证功能,可通过传入参数进行控制,如您的业务场景核心为实名认证,无需重复请求7.3活体检测接口(startFaceLiveness)。
注:如果配置APP方案时,身份信息录入的方式选择【业务调用时传入身份信息】,那么通过APP服务端接口获取姓名和证件号后,将获取到的姓名和证件号赋值给name和idcard_number字段即可。
API | 描述 |
---|---|
-(void)startRecognize:(NSDictionary )dic callBack:(void(^)(int resultCode, NSDictionary resultDic))callBack; | 实名认证接口 |
入参dic (NSDictionary类型) key值列表如下:
参数 | Value类型 | 说明 | 必选 |
---|---|---|---|
BDFaceLogicServiceTokenKey | NSString | 访问Token,需要APP服务端通过AK、SK获取 | 是 |
BDFaceLogicServiceNameKey | NSString | 在控制台配置的方案Id | 是 |
BDFaceLogicServiceCardNumberKey | NSNumber | 姓名 | 是 |
BDFaceLogicServiceCardTypeKey | NSString | 证件类型(默认为0)0:中国居民二代身份证,1:港澳台来往内陆通行证,2:外国人永久居留证,3:定居海外的中国公民护照,4:港澳台居民居住证 | 否 |
BDFaceLogicServicePlanIdKey | NSString | 方案ID | 否 |
BDFaceLogicServiceOnlineQualityControlKey | NSString | 质量控制参数 LOW:宽松 NORMAL:正常 | 否 |
BDFaceLogicServiceLivenessQualityControlKey | NSString | 活体控制参数 LOW:宽松 NORMAL:正常 HIGH:严格 | 否 |
回调说明
参数 | 类型 | 含义 | 值 |
---|---|---|---|
resultCode | int | 错误码 | 0为成功,其他为失败,详情参考回调code错误码说明 |
resultDic | NSDictionary | 回调结果 | 详情见下表 |
resultDic key值列表说明:
Key值 | 类型 | 含义 |
---|---|---|
BDFaceLogicServiceReturnKeyForResultMsg | NSString | code对应的错误码,详情见code错误码说明 |
BDFaceLogicServiceReturnKeyForResultData | Dictionary | 服务端返回结果,错误码为0时此字段存在内容,可以参考人脸实名认证V4接口文档。 |
resultCode和resultMsg对应情况如下:
resultCode | resultMsg | 自查建议 |
---|---|---|
-101 | 已有采集流程运行中 | 前面有人脸流程还未结束,建议排查是否存在未关闭的采集流程的页面进程 |
-102 | 采集流程取消 | 用户自行取消采集流程,调用cancel接口触发 |
-103 | 安全SDK未初始化 | 未成功启动安全SDK(指的是采集SDK内部封装的安全模块),初始化配置尽可能早 |
-105 | 安全SDK未加载 | 未成功启动安全SDK(指的是采集SDK内部封装的安全模块),初始化配置尽可能早 |
-106 | 网络错误 | 检查网络环境 |
-201 | 风控验证失败 | 是否越狱设备 |
-301 | 云端验证异常 | 云端错误,检查加解密相关信息 |
-302 | 摄像头未授权 | 请检查摄像头权限 |
-303 | 视频录制错误 | 是否授权视频/音频 |
-305 | 在线筛选图片异常 | 没有成功拿到图片,检查白盒、licenseid是否正确 |
-401 | 超时,用户取消采集流程 | 非预期用户行为导致的总流程超时,可通过设置延长超时时间限制 |
-402 | 炫瞳异常 | 炫瞳打光颜色与模型输出不匹配 |
-403 | 活体分数异常 | 活体分数不在正常范围,可能是受到活体攻击异常导致,建议在安全人脸环境下重新采集 |
-404 | 活体分数异常 | 活体分数不在正常范围,可能是受到活体攻击异常导致,建议在安全人脸环境下重新采集 |
-405 | 动作活体分数过低 | 动作活体图片分数过低 |
-1001 | 网络异常 | 检查网络是否畅通 |
-1002 | accessToken参数不合法 | accessToken参数为空 |
-1003 | 姓名参数不合法 | 请检查参数是否为空或格式不规范 |
-1004 | 证件号参数不合法 | 请检查参数是否为空或格式不规范 |
7.3 活体检测接口
包含本地活体加云端活体,本地活体分静默活体、炫瞳活体、动作活体三种,云端活体可以判断图片中的人脸是否为二次翻拍以及是否为合成图攻击。
此处最终采集到的数据经过加密处理,需要配合开放平台在线图片活体V4接口使用,实现二次验证采集图片是否存在假体攻击破绽的情况。
如您的业务场景核心为人脸实名认证,请直接请求7.2 实名认证接口。
API | 描述 |
---|---|
-(void)startRecognizeToCheckLive:(NSDictionary )dic callBack:(void(^)(int resultCode, NSDictionary resultDic))callBack; | 活体检测接口 |
入参dic (NSDictionary类型) key值列表如下:
参数 | 类型 | 说明 | 必选 |
---|---|---|---|
BDFaceLogicServiceTokenKey | NSString | 访问Token,需要APP服务端通过AK、SK获取access_token | 是 |
回调说明
参数 | 类型 | 含义 | 值 |
---|---|---|---|
resultCode | int | 错误码 | 0为成功,其他为失败,详情参考实名认证resultCode错误码说明 |
resultDic | NSDictionary | 回调结果 | 详情见下表 |
callback key值列表说明:
Key值 | 类型 | 含义 |
---|---|---|
BDFaceLogicServiceReturnKeyForResultMsg | NSString | code对应的错误码,详情见code错误码说明 |
BDFaceLogicServiceReturnKeyForResultData | Dictionary | 服务端返回结果,错误码为0时此字段存在内容,可以参考在线图片活体V4接口文档。 |
7.4 人脸采集及人脸比对接口(无源)
包含本地质量和本地活体,本地质量可以确保采集到的人脸图像符合各条件校验(满足姿态角、光照、模糊度、遮挡等校验),本地活体分静默活体、炫瞳活体、动作活体三种。
此处最终采集到的数据经过加密处理,需要配合开放平台人脸对比V4接口使用,包含活体检测、质量检测、人脸1:1识别功能,可通过传入参数进行控制,如您的业务场景核心为实名认证,无需重复请求7.3活体检测接口(startFaceLiveness)。
返回值 | 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 | 安全相关数据 |
7.5 人脸相关配置
人脸相关配置来自于百度云控制台下发的console_config.json文件,详细参考BDConfigFileParser类,不设置,将使用默认值。
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
保证程序只能手动输入身份信息来调用人脸,此部分功能模块不使用也可以对应删除。
运行工程