一、SDK集成
1、概述
本文是实人认证SDK_Android 端接入文档，用于指导 SDK 的集成使用。
2、本地集成
a.将 SDK 中 libs 目录下的 aar 包拷贝到您工程的 libs 目录下，如没有该目录需新建。
b.在 build 文件的 dependencies 中添加 aar 包依赖：
repositories {
flatDir {
dirs '../app/libs'
}
}
dependencies {implementation fileTree(include: ['*.aar'], dir: 'libs')}
3、 SDK 初始化
调用 SDK 其他流程方法前，请确保已调用过初始化，否则会返回未初始化。（会采集信息，建议放到同意协议后调用）
方法原型
public void init(Context context, String appId)
参数描述
| 参数 | 类型 | 说明 |
|---|
| context | Context | 传 ApplicationContext 对象 |
| appId | String | 创蓝平台获取到的 appId |
示例代码
@Override
public void onCreate() {
super.onCreate();
// 设置调试模式，可以输出日志，方便调试，生产环境请关闭此开关
CLBaseManager.setDebuggable(true);
//实人认证SDK初始化
CLBaseManager.init(getApplicationContext(),appId);
}
二、API 调用
1、活体检测
我们提供了一个 Demo 供您参考，如果觉得我们提供的界面文案、标题、文字大小、titleBar 的背景颜色，活体检测提示音，活体检测时的提示动画（GIF图片）等等不满足你们的需求，或者与你们的 App 页面风格样式不搭，想自定义修改这些配置当然也是可以的。
请求示例
SdkConfiguration configuration = new SdkConfiguration.Builder()
// 建议从服务端调用获取 authToken 接口获取
.setAuthToken(authToken)
// 设置动作数量 1-3 分别代表 1-3 个动作，4 代表 1-3 个动作随机，不设置默认是 4
.setActionSize(1)
// 每个动作的执行时间，单位为秒
.setActionSecond(3)
// 安全级别 0：低 1：高 (不设置默认为0) 低级别随机动作，高级别将包含局部和全脸动作
.setSecurityLevel(0)
// 设置当前 Activity 对象
.setActivity(this)
// 人脸检测超时时间，不大于 120s，且不小于 10s，不设置默认为 30s
.setTimeout(30)
// 设置相机配置，比如相机预览的大小等等
.setICameraConfig(this::getCameraParameters)
.build();
OnlineAliveDetectorApi.getInstance().start(configuration, new IAliveDetectedListener() {
@Override
public void onReady() {
}
@Override
public void onReceivedActions(List<OnlineAliveBean> actions) {
}
@Override
public void onActionChanged(final int index) {
}
@Override
public void onStateTipChanged(String tip) {
}
@Override
public void onFaceStateChanged(boolean isFullFace) {
}
@Override
public void onFaceReady() {
}
@Override
public void onStartDetect() {
}
@Override
public void onDetectComplete() {
}
@Override
public void onPassed(String data) {
// 返回数据示例： {"score":0.9667554498,"action_verify":"pass"}
// action_verify 为 pass 时代表动作验证通过，score 为活体检测分数，
// 请自行根据自身业务场景设置阈值进行判断是否通过
}
@Override
public void onError(String errCode, String errMsg) {
}
@Override
public void onOverTime() {
}
});
温馨提示： 所有回调的方法都是在子线程中，所以，如果要处理 UI 相关的逻辑，需要切换到主线程处理。
当调用过一次后，如果失败了，可以调用重试方法，会重新开始活体检测：
// @Deprecated method
OnlineAliveDetectorApi.getInstance().tryAgain();
// 推荐使用
OnlineAliveDetectorApi.getInstance().tryAgain(authToken);
推荐使用带参数的 tryAgain 方法，这样可以设置新的 authToken，防止使用旧的 authToken 提示过期的问题。
将活体检测视频保存到自己的服务器（可选项，非必需）
活体检测 SDK 内部默认采用的是 BASE64 编码的方式上传视频，如果要将视频上传到自己的服务器或其他 OSS 服务器也是可以的，需要在调用活体开始之前先设置一个监听回调：
// 设置视频录制的监听器，当需要自己上传是需要设置此监听
OnlineAliveDetectorApi.getInstance().setIVideoRecordListener(this);
// 并实现接口方法
public interface IVideoRecordListener {
void onComplete(String videoPath, IVideoUploadListener listener);
}
可以在 onComplete 回调方法中进行视频的上传操作，视频上传完成后将视频的 url 地址再通过回调方法中的监听器传递给 SDK 内部，此时会自动触发活体检测。
文件上传的代码可以参考 Demo。
响应数据
① 当活体检测通过时，会在 onPassed() 回调方法中收到回调；
② 当活体检测有错误的时候，会在 onError() 回调方法中回调 errCode、errMsg 信息，具体的错误信息如下表所示：
| 错误码 | 错误信息 | 备注说明 |
|---|
| 权限相关（1开头） | | |
| 10001 | 缺少相机权限 | / |
| 10002 | 缺少读写SD卡权限 | / |
| 参数相关（2开头） | | |
| 20001 | context为空，SDK没有初始化或者初始化失败 | / |
| 20002 | appId为空，SDK没有初始化或者初始化失败 | / |
| 20003 | 网络异常，请检查网络连接 | / |
| 20004 | 请求超时，请检查网络连接或重试！ | / |
| 业务相关（3、0或216开头） | | |
| 30001 | 动作验证未通过，请按提示完成动作 | / |
| 30002 | 活体检测超时，请在规定时间内完成提示动作 | / |
| 30003 | 当前网络不稳定，请切换网络后再试 | / |
| 30004 | 返回数据解析异常 | / |
| 30005 | 活体检测视频解析失败，请重新再试 | |
| 216434 | 人脸动作与提示动作不吻合，请重试 | / |
| 216501 | 没有检测到人脸，请重试 | / |
| 216507 | 检测到有多张人脸，请重试 | / |
| 216908 | 检测到人脸模糊，请重试 | / |
| 000400 | 令牌无效 | authToken超过有效期或者使用的AppId 和 AppKey 不对 |
| 000998 | 账户金额预消耗失败 | 账号余额不足了 |
| 500003 | 活体检测视频太长 | 活体视频超过15秒 |
温馨提示：
① 调用活体检测方法之前，请确保已经获取到相机、读写 SD 卡的权限，SDK 内部不做权限申请的处理！！！
② 我们提供了默认的声音文件和 GIF 图片文件，如果觉得我们的声音不好听或者图片不好看，也可以使用你们自己的，声音文件支持 mp3、wav 等常见格式，GIF 图片设计规范：123px * 111px；
③ 在调用之前需要获取到 authToken，为了安全，建议从服务端请求，具体参考服务端的接口文档，或者参考Demo 中的示例代码，Demo 请求是为了方便测试，生产环境建议从服务端请求；
2、身份证 OCR
2.1 识别单面
| 入参 | 说明 | 备注 |
|---|
| authToken | 授权token，建议通过服务端获取 | / |
| side | front 为正面，back 为反面 | / |
| imageBytes | 身份证照片文件的 byte 数组 | / |
| IDetectedListener | 监听器 | / |
IdCardApi.getInstance().singleSide(authToken, side, imageBytes, new IDetectedListener() {
@Override
public void onSuccess(String result) {
Log.d(TAG, "json:" + result);
}
@Override
public void onFailed(int errorCode, String errorMsg) {
Log.e(TAG, "onFailure():call=" + errorCode);
}
});
响应数据示例：
{
"code": "000000",
"message": "成功",
"data": {
"address": "江西省九江市庐山河南路xx号xx室",
"id_card_no": "360402200111133850",
"brith_day": "20011113",
"name": "黄xx",
"sex": "男",
"nation": "汉",
"issuing_authority": null,
"issuing_date": null,
"expire_date": null,
"msg": null
}
}
2.2 识别双面
| 入参 | 说明 | 备注 |
|---|
| authToken | 授权token，建议通过服务端获取 | / |
| frontBytes | 身份证正面文件的 byte 数组 | / |
| backBytes | 身份证反面文件的 byte 数组 | / |
| IDetectedListener | 监听器 | / |
传递身份证正、反面照片的文件字节数组：
IdCardApi.getInstance().doubleSide(authToken, frontBytes, backBytes, new IDetectedListener() {
@Override
public void onSuccess(String result) {
Log.d("TAG", "onSuccess() -> result:" + result);
}
@Override
public void onFailed(int errorCode, String errorMsg) {
Log.e("TAG", "onFailed() -> errorCode:" + errorCode + ",errorMsg:" + errorMsg);
}
});
温馨提示：
在调用之前，需要将图片做压缩处理，推荐每张照片压缩小于 1M 以内。
返回数据格式：
{
"code":"000000",
"message":"成功",
"data":{
"back":{
"address":null,
"id_card_no":null,
"brith_day":null,
"name":null,
"sex":null,
"nation":null,
"issuing_authority":"xxx县公安局",
"issuing_date":"20110123",
"expire_date":"20211123",
"msg":null
},
"front":{
"address":"河南省xx县xx乡xx村xxx组",
"id_card_no":"111111199012202638",
"brith_day":"19901220",
"name":"张三",
"sex":"男",
"nation":"汉",
"issuing_authority":null,
"issuing_date":null,
"expire_date":null,
"msg":null
}
}
}
当 OCR 成功时，返回如上的数据结构，当照片模糊、边角缺失或者正反面颠倒时，front 或 back 节点中的 msg 字段会提示模糊或者正反颠倒。
错误时的数据格式：
{
"code":"000000",
"message":"成功",
"data":{
"back":{
"address":null,
"id_card_no":null,
"brith_day":null,
"name":null,
"sex":null,
"nation":null,
"issuing_authority":"上海市公安局xx分局",
"issuing_date":"20051008",
"expire_date":"20151008",
"msg":null
},
"front":{
"address":null,
"id_card_no":"",
"brith_day":null,
"name":"",
"sex":null,
"nation":null,
"issuing_authority":null,
"issuing_date":null,
"expire_date":null,
"msg":"正反面颠倒"
}
}
}
温馨提示：
如果某一面识别成功了，某一面识别失败了，那么重新调用的时候，还是两张都要一起上传的。
3、身份证二要素认证
IdentityAuthApi.getInstance().verify(authToken, name, idNum, new IDetectedListener() {
@Override
public void onSuccess(String result) {
Log.d("TAG", "json:" + result);
}
@Override
public void onFailed(int errorCode, String errorMsg) {
Log.e("TAG", "onFailure():call=" + errorCode);
}
});
请求参数
| authToken | 授权token，建议通过服务端获取 | / |
|---|
| name | 姓名 | / |
| idNum | 身份证号 | / |
| IDetectedListener | 监听器 | / |
响应数据
{
"code": "000000",
"message": "成功",
"data": {
"order_no": "011634609037212683",
"handle_time": "2021-10-19 10:03:57",
"province": "湖南省",
"city": "邵阳市",
"country": "邵阳县",
"birthday": "19760320",
"age": "46",
"gender": "1",
"remark": "一致",
"result": "01"
}
}
没有更多了
