首页活体检测SDK API接口Android开发文档

Android开发文档

更新时间：2025-04-24 11:07:39

一.准备工作

概述

本文结合示例代码指导您在 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端）
		1003	用户暂不认证（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	代理返回为空

没有更多了

没有上一篇

下一篇：羊毛盾标准版

文档目录

收缩

产品中心

联系我们

热门搜索

中国站

国际站

Android开发文档

一.准备工作

概述

前置条件

快速体验demo

开发环境搭建

配置依赖

权限说明

混淆规则

二.API 说明

1.初始化

2.认证参数配置

3.开始认证

4.查询认证结果

5.日志开关

三、返回码