Android-服务端接入指南
1. 文档说明
| 文档名称 | 人脸实名认证APP方案 6.4版本集成文档 |
|---|---|
| 所属平台 | Android |
| 提交日期 | 2025-04-27 |
2. 版本说明
| 名称 | 版本号 |
|---|---|
| 名镜方案 | 6.4.3 |
| 系统支持 | android 5.1+ |
| 架构支持 | CPU架构平台，armeabi-v7a、arm64-v8a |
3. SDK说明
| 文件名称 | 版本号 | 说明 |
|---|---|---|
| lib-logic.aar | 1.0.3 | 名镜SDK，业务逻辑封装 |
| faceplatform-ui.aar | 6.4 | 人脸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 人脸信息加密采集接口
包含本地质量和本地活体，本地质量可以确保采集到的人脸图像符合各条件校验（满足姿态角、光照、模糊度、遮挡等校验），本地活体分静默活体、炫瞳活体、动作活体三种。
- 此处最终采集到的数据经过加密处理，需要配合服务端的 人脸实名认证V4 或 人脸对比V4 或 在线图片活体V4 来使用。分别用来实现「权威数据源身份信息核验」、「本地图片无源比对」以及「仅活体检测」，适用于不同的业务场景需要。
- sKey、xDeviceId、data 为此接口的成功回调结果信息，作为上述3个服务端接口重要字段入参
| 返回值 | 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.3 人脸释放接口
人脸释放接口调用，实现对采集功能、模型的释放，减小内存。
| 返回值 | API | 描述 |
|---|---|---|
| void | release() | 人脸释放接口 |
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即可。
