Android-方案集成指南

更新时间：2024-09-02

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 listener, Context context)	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即可。

iOS-方案集成指南

人脸实名认证H5端方案