Android开发文档
更新时间:2026-07-23 19:05:12
一.准备工作
概述
本文结合示例代码指导您在 Android 应用中集成活体检测 SDK,帮助您在 App 中实现刷脸认证功能。
- 全国SDK管理服务平台「备案地址」
前置条件
- 应用必须在 Android 4.3+ 平台上运行。
快速体验demo
- 可以在GitHub中下载SDK_ALIVE_DEMO示例工程源码,使用Android studio打开即可运行测试。
开发环境搭建
配置依赖
a.将 SDK 中 libs 目录下的 aar 包拷贝到您工程的 libs 目录下,如没有该目录需新建。
b.在 app 的 build.gradle 文件 dependencies 中添加 aar 包依赖:
repositories {
flatDir {
dirs '../app/libs'
}
}
dependencies {implementation fileTree(include: ['*.aar'], dir: 'libs')}权限说明
aar 包内部已添加,App 中可以不配置,此处只做用途说明
| 权限名称 | 权限说明 | 使用场景或目的 |
|---|---|---|
| INTERNET 网络 | 允许发送网络请 求、获取网络状态 | 用于确认用户的终端是否接入网络,以为用户提供安全的验证服务 |
| ACCESS_NETWORK_STATE | 允许访问网络状态 | 用于确认用户的终端网络连接状态,以为用户提供安全的验证服务 |
| ACCESS_WIFI_STATE | 允许访问 WiFi 网络状态信息 | 用于确认用户的终端 WiFi 连接状态,以为用户提供安全的验证服务 |
| CAMERA 相机 | 允许拍摄照片、视 频 | 在用户进行活体动作验证真人时需要使用摄像头权限 |
混淆规则
-verbose
-keep class com.dtf.face.network.model.** {*;}
-keep class com.dtf.face.api.IDTCallback {*;}
-keep class com.dtf.face.api.IDTFacade {*;}
-keep class com.dtf.face.api.DTFacadeBuilder {*;}
-keep class com.dtf.face.api.DTResponse {*;}
-keep class com.dtf.face.config.**{*;}
-keep class com.dtf.face.log.RecordBase {*;}
-keep class com.dtf.face.widget.ToygerWebView {*;}
-keep class com.alipay.zoloz.toyger.**{*;}
-keep class com.alipay.deviceid.** {*;}
-keep class com.alipay.rds.** {*;}
-keep class com.alipay.android.fintech.log.** {*;}
-keep class com.dtf.face.log.** {*;}
-keep class com.alipay.bis.common.service.facade.gw.** {*;}
-keep class com.alibaba.fastjson.** {*;}
-keep class org.json.** {*;}
-keep class com.chuanglan.sdk.face.api.* {*;}
-keep class com.chuanglan.sdk.face.listener.VerifyCallback{*;}
-keep class com.chuanglan.sdk.face.entity.VerifyResponse{*;}通过上面的几个步骤,工程就配置完成了
二.API 说明
1.初始化
- 【必要方法】为提高用户体验,并为刷脸认证准备必要数据,必须先进行 SDK 初始化。
方法原型
/**
* 初始化接口,放到其他接口调用前
*
* @param context 传ApplicationContext对象
* @param appId 创建应用时生成的appId
**/
public static void initWithAppId(Context context, String appId);示例代码
FaceVerification.initWithAppId(getApplicationContext(), "您的appid");2.认证参数配置
- 【可选方法】每个配置都有默认值,只需传入想要修改的配置即可,如果不需要修改可以不调用。
方法原型
/**
* 认证参数配置
*
* @param verifyConfig 参数配置对象
*/
public static void setVerifyConfig(VerifyConfig verifyConfig)VerifyConfig 类说明
/**
* 设置活体检测UI界面方向
*
* @param screenOrientation VerifyConfig.SCREEN_ORIENTATION_PORT(默认):竖屏;
* VerifyConfig.SCREEN_ORIENTATION_LAND:横屏
*/
public Builder setScreenOrientation(String screenOrientation);
/**
* 设置是否支持活体视频返回
*
* @param useVideo true:支持,并在response.videoFilePath中获取视频本地路径;
* false(默认):不支持,返回null
*/
public Builder setUseVideo(boolean useVideo)
/**
* 设置是否支持活体图片返回
*
* @param useBitmap true:支持,并在response.bitmap中获取图片byte[];
* false(默认):不支持,返回null
*/
public Builder setUseBitmap(boolean useBitmap);
/**
* 设置活体检测页面的进度条颜色
*
* @param faceProgressColor 颜色值,如红色 "#FF0000"
*/
public Builder setFaceProgressColor(String faceProgressColor)
/**
* 设置活体检测动作
*
* @param actionModel VerifyConfig.ACTION_MODEL_LIVENESS(默认):眨眼动作活体检测
* VerifyConfig.ACTION_MODEL_MULTI_ACTION:眨眼+任意摇头检测
*/
public Builder setActionModel(String actionModel)
/**
* 设置启动活体检测界面超时时间
*
* @param verifyTimeout 超时时间,单位秒,如设置6秒传6,默认值5
*/
public Builder setVerifyTimeout(int verifyTimeout)
/**
* 设置是否在sdk内部使用弹框提示错误信息
*
* @param useMsgBox true(默认):使用;
* false:不使用
*/
public Builder setUseMsgBox(boolean useMsgBox) {
this.useMsgBox = useMsgBox;
return this;
}
/**
* 设置是否使用SDK内置协议页
*
* @param usePrivacyProtocol true(默认):使用;
* false:不使用
*/
public Builder setUsePrivacyProtocol(boolean usePrivacyProtocol) {
this.usePrivacyProtocol = usePrivacyProtocol;
return this;
}示例代码
FaceVerification.setVerifyConfig(new VerifyConfig.Builder()
.setScreenOrientation(VerifyConfig.SCREEN_ORIENTATION_LAND)
.setUseVideo(true)
.setUseBitmap(false)
.setUseMsgBox(false)
.setUsePrivacyProtocol(true)
.setFaceProgressColor("#303030")
.setActionModel(VerifyConfig.ACTION_MODEL_LIVENESS)
.setVerifyTimeout(6)
.build());3.开始认证
- 调用此方法会启动 SDK 内部活体检测界面,并返回第4 步服务端查询刷脸认证结果所需要的certifyId。
方法原型
/**
* 开始认证
* 需在 UI 线程上调用,不会阻塞调用线程
*
* @param verifyCallback 认证结果的回调接口
*/
public static void faceVerify(VerifyCallback verifyCallback)刷脸认证结果 VerifyCallback 回调中的 VerifyResponse 类说明
public class VerifyResponse {
/**
* 外层码:
* 10000:刷脸结束
* 10001:校验失败
* 10002:验签失败
* 10003:网络异常
* 0004:本地异常
*/
public int code;
/**
* 内层码:
* 1000: 刷脸结束
* 1001: 系统错误
* 1003: 验证中断
* 1014:本地捕获异常
* 1023:网络原因导致的超时、域名解析异常等
* 2002: 网络错误
* 2003:客户端设备时间错误
* 2006: 刷脸失败
* 400001:参数校验异常
* 600016:Android签名参数异常
* 600017:平台类型非法
* 600005:签名校验失败
* 600018:签名失效
* 600004:包名签名对应的appid不匹配 或 appid未匹配到应用
* 500006:请求外部系统失败
* 600019:包名签名校验失败
* 500003:业务操作失败
*/
public int innerCode;
/**
* 内层结果文案描述,可能为空
*/
public String innerMsg;
/**
* 外层结果文案描述
*/
public String msg;
/**
* 设备token
*/
public String deviceToken;
/**
* 如果采用视频返照,则返回视频的路径,否则返回null
*/
public String videoFilePath;
/**
* 查询认证结果所需的唯一标识
*/
public String certifyId;
/**
* 如果设置支持照片返回,则返回照片,否则返回null
*/
public byte[] bitmap;
}示例代码
FaceVerification.faceVerify(response -> {
try {
Toast.makeText(this, "刷脸结束,请调用服务端“活体检测结果查询”接口,获取检测结果", Toast.LENGTH_LONG).show();
} catch (Exception e) {
e.printStackTrace();
}
});4.查询认证结果
客户端刷脸结束,并不能判断是否为真是自然人,务必对接服务端 “活体检测结果查询” 接口,并以服务端查询接口返回的结果为准。 5.日志开关
- 放到初始化之前调用,开启后可打印 SDK 内部调用日志,用“PROCESS_SDK_LOGTAG<-->”过滤日志
方法原型
/**
* 设置SDK基础日志开关
*
* @param debuggable true:开启;
* false(默认):关闭
*/
public static void setPrintConsoleEnable(Boolean debuggable)示例代码
FaceVerification.setPrintConsoleEnable(true);三、返回码
| 外层码 | 外层描述 | 内层码 | 内层描述 |
|---|---|---|---|
| 10000 | 刷脸结束 | 1000 | 刷脸结束,请通过服务端查询接口获取认证结果(Android端、iOS端) |
| 10001 | 校验失败 | 1001 | 本地代码异常(Android端) |
| 人脸识别算法初始化失败(Android端) | |||
| 不支持的CPU架构(Android端) | |||
| Android系统版本过低(Android端) | |||
| 刷脸超时(单次)(Android端、iOS端) | |||
| 多次刷脸超时(Android端、iOS端) | |||
| 无前置摄像头(Android端) | |||
| 摄像头权限未赋予(Android端) | |||
| 打开摄像头失败(Android端) | |||
| SDK认证流程正在进行中,请等待本地认证流程完成后再发起新调用(Android端) | |||
| 上传炫彩Meta信息失败(Android端) | |||
| 上传炫彩视频失败(Android端) | |||
| 用户点击Home键(Android端) | |||
| 抱歉,系统出错了,请您稍后再试(iOS端) | |||
| 拒绝开通相机权限(iOS端) | |||
| 无法启动相机(iOS端) | |||
| 本地活体检测出错(iOS端) | |||
| 验证中断(用户点击home键等导致验证停止)(iOS端) | |||
| 业务参数错误(iOS端) | |||
| 本地活体检测出错(iOS端) | |||
| 1003 | 用户主动退出认证(Android端、iOS端) | ||
| 用户暂不认证(Android端) | |||
| 2001 | 用户OCR主动退出(iOS端) | ||
| 2002 | |||
| 客户端初始化网络错误(Android端) | |||
| 客户端初始化接口返回网络错误(Android端) | |||
| 信息上传网络错误(Android端) | |||
| 服务端认证接口网络错误(Android端) | |||
| 服务端接口并发请求超出限制(Android端) | |||
| 网络错误(iOS端) | |||
| 2003 | 客户端设备时间错误(iOS端) | ||
| 2006 | 刷脸结束,请通过服务端查询接口获取认证结果(Android端、iOS端) | ||
| 10002 | 验签失败 | 400001 | 参数校验异常(Android端、iOS端) |
| 600016 | Android签名参数异常(Android端) | ||
| 600009 | bundleId不能为空(iOS端) | ||
| 600017 | 平台类型非法(Android端、iOS端) | ||
| 600005 | 签名校验失败(Android端、iOS端) | ||
| 600018 | 签名失效(Android端、iOS端) | ||
| 600004 | 包名签名对应的appid不匹配 或 appid未匹配到应用(Android端、iOS端) | ||
| 500006 | 请求外部系统失败(Android端、iOS端) | ||
| 600019 | 包名签名校验失败(Android端、iOS端) | ||
| 500003 | 业务操作失败(Android端、iOS端) | ||
| 1010 | 服务端返回为空(Android端) | ||
| 10003 | 网络异常 | 1023 | 网络原因导致的超时、域名解析异常等(Android端、iOS端) |
| 10004 | 本地异常 | 1014 | 本地捕获异常(Android端、iOS端) |
| 10005 | 重复调用 | 1015 | 刷脸进行中,请稍后再试 |
| 10006 | 代理异常 | 1016 | 代理返回为空 |
这篇文档对您有帮助吗?




