logo
logo
请输入关键词搜索产品或者文档
中国

中国站

创蓝云智

国际站

Innopaas

Android开发文档

更新时间:2026-07-23 19:05:12

一.准备工作

概述

本文结合示例代码指导您在 Android 应用中集成活体检测 SDK,帮助您在 App 中实现刷脸认证功能。

前置条件

  • 应用必须在 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端)
600016Android签名参数异常(Android端)
600009bundleId不能为空(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代理返回为空
24小时热线 400-9669-253