Android-方案集成指南
1. 文档说明
| 文档名称 | 人脸实名认证APP方案 6.3版本集成文档 |
|---|---|
| 所属平台 | Android |
| 提交日期 | 2023-11-09 |
2. 版本说明
| 名称 | 版本号 |
|---|---|
| 名镜方案 | 6.3.0 |
| 系统支持 | android 5.1+ |
| 架构支持 | CPU架构平台，armeabi-v7a、arm64-v8a |
3. SDK说明
| 文件名称 | 版本号 | 说明 |
|---|---|---|
| lib-logic.aar | 1.0.3 | 名镜SDK，业务逻辑封装 |
| faceplatform-ui.aar | 6.3 | 人脸SDK的UI层，封装采集和活体UI等功能，以及各平台so库 |
| lib-liantian.aar | 3.8.0.2 | 安全SDK |
| ocr_ui.aar | 1.3.0 | 百度OCR身份识别库 |
4. Demo运行
4.1 配置包名和签名
从百度云控制台下载Demo之后，需要在build.gradle中配置好包名和签名信息。
4.2 修改accessToken
以下两处修改为AI开放平台AK、SK获取到的access_token，正式环境需要APP服务端通过AK、SK来获取access_token，移动端测试可以链接拼接AK、SK的方式来获取access_token。【此处需要注意】 access_token存在有效期，正式环境需要APP服务端通过AK、SK来获取access_token，此处只测试使用。 （https://aip.baidubce.com/oauth/2.0/token?grant_type=client_credentials&client_id=【百度云应用的AK】&client_secret=【百度云应用的SK】）。
测试实名认证，请将获取到的access_token填在如下地方：
测试在线活体，请将获取到的access_token填在如下地方：
5. SDK集成
首先在app工程中增加lib-liantian.aar、faceplatform-ui.aar、lib-logic.aar、ocr-ui.aar。此处需要注意，如果需要使用OCR身份证识别能力，则需要增加此ocr-ui-release.aar，如果不使用则不需要增加。在app工程的build.gradle中添加相关依赖，然后点击运行。
6. 授权文件、加密文件
请将百度云控制台创建应用时获取的人脸授权文件(idl-license.face-android)、加密文件（idl-key.face-android）放置于Assets目录下。如果使用OCR身份证识别功能，请将OCR身份证识别授权文件（aip.license）也放置于Assets目录下，如下图所示。
7. 人脸相关接口
7.1 初始化接口
初始化接口调用
| 返回值 | API | 描述 |
|---|---|---|
| void | init(Context context, String licenseKey, String licenseName,FaceInitCallback FaceInitCallback) | 人脸初始化接口 |
入参说明
| 参数 | 类型 | 说明 |
|---|---|---|
| context | Context | 上下文 |
| licenseKey | String | 授权Key |
| licenseName | String | 授权文件名称 |
onCallback回调说明
| 参数 | 类型 | 含义 | 值 |
|---|---|---|---|
| resultCode | int | 错误码 | 1000为成功，其他为失败，详情参考resultCode错误码说明 |
| resultMsg | String | 详情见resultCode错误码说明 |
resultCode错误码说明
| resultCode | resultMsg | 自查方案 |
|---|---|---|
| 1001 | License未初始化 | 请按照集成文档说明完成SDK初始化 |
| 1002 | License数据解密失败 | 请检查License文件是否正确 |
| 1003 | Licesen数据格式错误 | 请检查license文件内容有被修改过 |
| 1004 | License-Key校验错误 | 请检查工程代码初始化参数中的licenseId，和申请license文件的licenseId是否匹配 |
| 1005 | 算法ID校验错误 | 请提交工单或者线下联系百度产研人员 |
| 1006 | MD5校验错误 | 请检查工程所使用的签名文件，和申请license文件的签名信息是否匹配 |
| 1007 | 设备ID校验错误 | 采集SDK的授权模式不会出现这个错误码 |
| 1008 | 包名（应用名校验错误） | 请检查工程代码中的applicationId（包名）和申请license文件的applicationId（包名）是否匹配 |
| 1009 | 过期时间不正确 | 请提交工单或者线下联系百度产研人员 |
| 1010 | 功能未授权 | 请查看授权文件中是否缺少必要的采集SDK功能声明（funclist参数），例如炫瞳活体 |
| 1011 | 授权已过期 | 请查看当前设备时间是否已不在授权文件有效期内 |
| 1012 | 本地文件读取失败 | 请检查授权文件名称以及路径 |
| 1013 | 远程数据拉取失败 | 本地鉴权失败之后，会远程拉取授权文件；若远程鉴权依然失败，可以关闭网络后重试 |
| 1014 | 本地时间校验错误 | 请检查当前设备时间是否早于实际时间 |
| 2001 | 非法的参数 | 请提交工单或者线下联系百度产研人员 |
| 2002 | 内存分配失败 | 请提交工单或者线下联系百度产研人员 |
| 2003 | 实例对象为空 | 请提交工单或者线下联系百度产研人员 |
| 2004 | 模型内容为空 | 请提交工单或者线下联系百度产研人员 |
| 2005 | 不支持的能力类型 | 请提交工单或者线下联系百度产研人员 |
| 2006 | 不支持的预测库类型 | 请提交工单或者线下联系百度产研人员 |
| 2007 | 预测库对象创建失 | 请提交工单或者线下联系百度产研人员 |
| 2009 | 预测库对象初始化失败 | 请提交工单或者线下联系百度产研人员 |
| 2010 | 人脸能力初始化失败 | 请按照集成文档说明正常完成SDK初始化 |
| 2011 | 能力未加载 | 请确认当前人脸相关资源库是否完整引用 |
| 2012 | 人脸能力已加载 | 底层已做过滤，无需关注 |
| 2013 | 未授权 | 检查授权文件是否按照集成文档正常使用 |
| 2014 | 人脸能力运行异常 | 请提交工单或者线下联系百度产研人员 |
| 2015 | 不支持的图像类型 | 请提交工单或者线下联系百度产研人员 |
| 2016 | 图像转换失败 | 检查摄像头分辨率，格式要求 %2==0 |
7.2 人脸实名认证接口（有源）
基于姓名、身份证号、当前SDK获取的人脸图片，与权威库进行对比，并得出比对分数，并基于此进行业务判断是否为同一人。
此处最终采集到的数据经过加密处理，需要配合开放平台人脸实名认证V4接口使用，包含活体检测、质量检测、实名认证功能，可通过传入参数进行控制，如您的业务场景核心为实名认证，无需重复请求7.3活体检测接口（startFaceLiveness）。
注：如果配置APP方案时，身份信息录入的方式选择【业务调用时传入身份信息】，那么通过APP服务端接口获取姓名和证件号后，将获取到的姓名和证件号赋值给name和idcard_number字段即可。
| 返回值 | API | 描述 |
|---|---|---|
| void | startFaceRecognize(Context context, Map params, FaceServiceCallbck FaceServiceCallbck) | 实名认证接口 |
入参params (HashMap类型) key值列表如下：
| 参数 | 类型 | 说明 | 必选 |
|---|---|---|---|
| access_token | String | 需要APP服务端通过AK、SK获取，参考 https://ai.baidu.com/docs#/Auth/top 【此处需要注意】access_token存在有效期，建议每次调用接口重新获取access_token | 是 |
| name | String | 姓名(需要是 utf8 编码) | 是 |
| id_card_number | String | 身份证件号 | 是 |
| plan_id | String | 在控制台配置的方案Id | 否 |
| verify_type | int | 证件类型（默认为0）0：中国居民二代身份证，1：港澳台来往内地通行证，2：外国人永久居留证，3：定居国外的中国公民护照，4：港澳台居民居住证 | 否 |
| quality_control | String | 质量控制参数 NONE: 不进行控制 LOW:较低的质量要求 NORMAL: 一般的质量要求 HIGH: 较高质量要求 默认为NONE | 否 |
| liveness_control | String | 活体控制参数 NONE: 不进行控制 LOW:较低的活体要求(高通过率 低攻击拒绝率) NORMAL: 一般的活体要求(平衡的攻击拒绝率, 通过率) HIGH: 较高的活体要求(高攻击拒绝率 低通过率) 默认为NORMAL | 否 |
onCallback回调说明
| 参数 | 类型 | 含义 | 值 |
|---|---|---|---|
| resultCode | int | 错误码 | 0为成功，其他为失败，详情参考resultCode错误码说明 |
| resultMap | HashMap | 回调结果Map | 详情见下表 |
resultMap key值列表说明：
| Key值 | 类型 | 含义 |
|---|---|---|
| resultMsg | String | 详情见resultCode错误码说明 |
| data | String | 服务端返回结果json,只有错误码为0时会返回 此字段，具体内容可以参考人脸实名认证（V4）接口文档 |
resultCode和resultMsg说明
| resultCode | resultMsg | 自查方案 |
|---|---|---|
| -101 | 已有采集流程运行中 | |
| -102 | 采集流程取消 | 用户自行取消采集流程，调用cancel接口触发 |
| -103 | 安全SDK未初始化 | 需要检查LH.init有没有调用，最好在application里面调用 |
| -104 | 未同意隐私协议 | 需要检查LH.setAgreePolicy有没有调用，最好在application里面调用 |
| -107 | 获取安全数据失败 | 请提交工单或者线下联系百度产研人 |
| -301 | 云端验证异常 | 云端错误，检查加解密相关信息 |
| -303 | 视频录制错误 | 是否授权视频/音频 |
| -304 | 线程异常 | 已在logcat输出异常栈，请根据异常栈排查 |
| -305 | 在线筛选图片异常 | 没有成功拿到图片 |
| -306 | 采集前内部异常 | 请提交工单或者线下联系百度产研人 |
| -307 | 活体验证步骤异常 | 请提交工单或者线下联系百度产研人 |
| -308 | 预览异常 | 请提交工单或者线下联系百度产研人 |
| -309 | 采集后内部异常 | 请提交工单或者线下联系百度产研人 |
| -310 | 摄像头调起失败 | 请检查摄像头权限 |
| -401 | 超时，用户取消采集流程 | 非预期用户行为导致的总流程超时，可通过设置延长超时时间限制 |
| -402 | 炫瞳异常 | 炫瞳打光颜色与模型输出不匹配 |
| -1001 | 网络异常 | 请检查网络通讯｜ |
| -1002 | accessToken参数不合法 | access_token字段未传，或者为空 |
| -1003 | 姓名参数不合法 | 请检查参数是否为空或格式不规范 |
| -1004 | 证件号码参数不合法 | 请检查参数是否为空或格式不规范 |
7.3 活体检测接口
包含本地活体加云端活体，本地活体分静默活体、炫瞳活体、动作活体三种，云端活体可以判断图片中的人脸是否为二次翻拍以及是否为合成图攻击。
此处最终采集到的数据经过加密处理，需要配合开放平台在线图片活体V4接口使用，实现二次验证采集图片是否存在假体攻击破绽的情况。
如您的业务场景核心为人脸实名认证，请直接请求7.2 实名认证接口。
| 返回值 | API | 描述 |
|---|---|---|
| void | startFaceLiveness(Context context, Map params, FaceServiceCallbck FaceServiceCallbck) | 活体检测接口 |
入参params (HashMap类型) key值列表如下：
| 参数 | 类型 | 说明 | 必选 |
|---|---|---|---|
| access_token | String | 需要APP服务端通过AK、SK获取access_token。 注意：由于access_token存在有效期，建议每次调用接口重新获取access_token |
是 |
onCallback回调说明
| 参数 | 类型 | 含义 | 值 |
|---|---|---|---|
| resultCode | int | 错误码 | 0为成功，其他为失败，详情参考实名认证resultCode错误码说明 |
| resultMap | HashMap | 回调结果Map | 详情见下表 |
resultMap key值列表说明：
| Key值 | 类型 | 含义 |
|---|---|---|
| resultMsg | String | 详情见resultCode错误码说明 |
| data | String | 服务端返回结果json,只有错误码为0时会返回 此字段，具体内容可以参考在线图片活体V4 |
7.4 人脸采集及人脸比对接口（无源）
包含本地质量和本地活体，本地质量可以确保采集到的人脸图像符合各条件校验（满足姿态角、光照、模糊度、遮挡等校验），本地活体分静默活体、炫瞳活体、动作活体三种。
此处最终采集到的数据经过加密处理，需要配合开放平台人脸对比V4接口使用，包含活体检测、质量检测、人脸1:1识别功能，可通过传入参数进行控制，如您的业务场景核心为实名认证，无需重复请求7.3活体检测接口（startFaceLiveness）。
| 返回值 | API | 描述 |
|---|---|---|
| void | startFaceCollect(Context context, FaceServiceCallbck FaceServiceCallbck) | 人脸采集接口 |
onCallback回调说明
| 参数 | 类型 | 含义 | 值 |
|---|---|---|---|
| resultCode | int | 错误码 | 0为成功，其他为失败，详情参考实名认证resultCode错误码说明 |
| resultMap | HashMap | 回调结果Map | 详情见下表 |
resultMap key值列表说明：
| Key值 | 类型 | 含义 |
|---|---|---|
| resultMsg | String | 详情见resultCode错误码说明 |
| sKey | String | 安全相关：sKey |
| xDeviceId | String | 安全相关：xDeviceId |
| data | String | 安全相关数据 |
7.5 人脸释放接口
人脸释放接口调用，实现对采集功能、模型的释放，减小内存。
| 返回值 | API | 描述 |
|---|---|---|
| void | release() | 人脸释放接口 |
7.6 人脸相关配置
人脸相关配置来自于百度云控制台下发的console_config.json文件，详情请参考Demo的BaseFragment类中以下2个方法：
(1) setFaceQualityConfig()：人脸质量判断相关配置
(2) setFaceLivenessConfig()：设置活体类型、活体动作、活体阈值
注：不设置，将使用默认值。
8. OCR身份证识别相关接口
8.1 OCR身份证识别初始化接口
| 返回值 | API | 描述 |
|---|---|---|
| void | initAccessToken(OnResultListener |
OCR初始化接口 |
入参说明
| 参数 | 类型 | 含义 |
|---|---|---|
| context | Context | 上下文 |
onError回调参数说明：
| 参数 | 类型 | 含义 |
|---|---|---|
| errorCode | int | 服务端返回错误码，详情见鉴权机制接口：https://ai.baidu.com/ai-doc/REFERENCE/Ck3dwjhhu |
| errorMessage | String | 服务端返回错误信息，详情见鉴权机制接口：https://ai.baidu.com/ai-doc/REFERENCE/Ck3dwjhhu |
8.2 OCR身份证识别接口
支持对二代居民身份证字段进行结构化识别，包括姓名、性别，调用参考OCR身份证识别接口文档。
| 返回值 | API | 描述 |
|---|---|---|
| void | startOcrRecognize(Context context, OcrConfig ocrConfig, OcrRecognizeCallback ocrRecognizeCallback) | OCR识别接口 |
入参说明
| 参数 | 类型 | 含义 |
|---|---|---|
| context | Context | 上下文 |
| ocrConfig | OcrConfig | OCR配置类 |
OcrConfig配置字段说明
| 参数 | 类型 | 含义 | |
|---|---|---|---|
| ocrPageNavigationColor | int | OCR页面导航栏背景色，默认为白色 | |
| ocrPageTitleText | String | OCR标题内容，默认为"身份信息采集" | |
| ocrPageTitleColor | int | OCR标题颜色，默认为黑色 | |
| ocrPageTopText | String | OCR顶部扫描文字，默认为"请将您本人的\n身份证人像面放入框内" | |
| ocrPageTopTextColor | int | OCR 顶部扫描文字颜色，默认为白色 |
onError回调参数说明
| 参数 | 类型 | 含义 | 值 |
|---|---|---|---|
| errorCode | int | 错误码 | 服务端返回错误码，详情见在线身份证识别接口：https://ai.baidu.com/ai-doc/OCR/rk3h7xzck |
| errorMessage | String | 回调结果Map | 服务端返回错误信息，详情见在线身份证识别接口：https://ai.baidu.com/ai-doc/OCR/rk3h7xzck |
9. 代码混淆
-dontwarn com.baidu.idl.**
-keep class com.baidu.idl.** { *; }
-dontwarn com.baidu.vis.**
-keep class com.baidu.vis.** { *; }
-dontwarn com.baidu.liantian.**
-keep class com.baidu.liantian.** { *; }
-dontwarn com.baidu.protect.**
-keep class com.baidu.protect.** { *; }
-dontwarn com.baidu.ocr.**
-keep class com.baidu.ocr.** { *; }10. 权限
| 名称 | 说明 | 必选 |
|---|---|---|
| 需要动态申请的权限 | ||
| android.permission.CAMERA | 拍照权限 | 是 |
| android.permission.RECORD_AUDIO | 录音权限（录制视频） | 否 |
| android.permission.READ_EXTERNAL_STORAGE | 读取手机外部存储权限（安全相关、OCR相关） | 否 |
| android.permission.READ_EXTERNAL_STORAGE | 写入手机外部存储权限（安全相关、OCR相关） | 否 |
| 不需要动态申请的权限 | ||
| android.permission.INTERNET | 允许访问网络 | 是 |
| android.permission.ACCESS_NETWORK_STATE | 获取网络状态权限 | 是 |
| android.permission.READ_PHONE_STATE | 允许访问电话状态权限 | 是 |
| android.hardware.camera.autofocus | 允许相机对焦（OCR相关） | 否 |
| android.permission.ACCESS_WIFI_STATE | 获取wifi权限 | 是 |
| android.permission.WAKE_LOCK | 屏幕常亮权限 | 是 |
11. 不使用OCR，只使用人脸相关能力
不使用OCR，可以删除ocr-ui.aar、aip.license，以及OCR相关代码。 OCR初始化代码如下图所示：
OCR调用代码如下图所示：
设置页面，关闭OCR运行Demo即可。
