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

中国站

创蓝云智

国际站

Innopaas

Android开发文档

更新时间:2026-08-20 13:50:16

一、准备工作

1、概述

本文是活体检测SDK_Android 端接入文档,用于指导 SDK 的集成使用。

2、创建应用

在创蓝平台注册账号,创建应用并获取 appIdappkey

3、开发环境搭建

a.将 SDK 中 libs 目录下的 aar 包拷贝到您工程的 libs 目录下,如没有该目录需新建。

b.在 build 文件的 dependencies 中添加 aar 包依赖:

repositories {
    flatDir {
        dirs '../app/libs'
    }
}
dependencies {implementation fileTree(include: ['*.aar'], dir: 'libs')}

4、快速体验 demo

二、API调用

0. 获取authToken

  • 请查看服务端集成文档,调用获取授权Token(authToken)接口,获取authToken为后续步骤做准备。

1、 SDK 初始化

调用 SDK 其他流程方法前,请确保已调用过初始化,否则会返回未初始化。(会采集信息,建议放到同意协议后调用)

方法原型

public void init(Context context, String appId)

参数描述

参数类型说明
contextContext传 ApplicationContext 对象
appIdString创蓝平台获取到的 appId

示例代码

@Override
public void onCreate() {
    super.onCreate();
    // 设置调试模式,可以输出日志,方便调试,生产环境请关闭此开关
    CLBaseManager.setDebuggable(true);
    //活体检测SDK初始化
    CLBaseManager.init(getApplicationContext(),appId);
}

2、活体检测

我们提供了一个 Demo 供您参考,如果觉得我们提供的界面文案、标题、文字大小、titleBar 的背景颜色,活体检测提示音,活体检测时的提示动画(GIF图片)等等不满足你们的需求,或者与你们的 App 页面风格样式不搭,想自定义修改这些配置当然也是可以的。

2.1 请求示例

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() {

            }

            /**
             * 当收到下发的动作序列时
             * @param actions 动作序列列表
             */
            @Override
            public void onReceivedActions(List<OnlineAliveBean> actions) {

            }

            /**
             * 当提示动作改变时的回调,比如提示做下一个动作时
             * @param index 动作下标,从 0 开始
             */
            @Override
            public void onActionChanged(final int index) {

            }

            /**
             * 当提示状态变化时的回调
             * @param tip 提示信息
             */
            @Override
            public void onStateTipChanged(String tip) {

            }

            /**
             * 当脸部状态变化时
             * @param isFullFace true:预览框检测到全脸,false 不是全脸
             */
            @Override
            public void onFaceStateChanged(boolean isFullFace) {

            }

            /**
             * 人脸已经就位,准备提示动作指令
             */
            @Override
            public void onFaceReady() {

            }

            /**
             * 服务端开始检测的回调,这个时候可以显示一些动画或者 Loading
             */
            @Override
            public void onStartDetect() {

            }

            /**
             * 服务端检测完成的回调,这个时候可以停止显示动画或者 Loading
             */
            @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 提示过期的问题。

2.2 将活体检测视频保存到自己的服务器(可选项,非必需)

活体检测 SDK 内部默认采用的是 BASE64 编码的方式上传视频,如果要将视频上传到自己的服务器或其他 OSS 服务器也是可以的,需要在调用活体开始之前先设置一个监听回调:

// 设置视频录制的监听器,当需要自己上传是需要设置此监听
OnlineAliveDetectorApi.getInstance().setIVideoRecordListener(this);

// 并实现接口方法
public interface IVideoRecordListener {
    void onComplete(String videoPath, IVideoUploadListener listener);
}

可以在 onComplete 回调方法中进行视频的上传操作,视频上传完成后将视频的 url 地址再通过回调方法中的监听器传递给 SDK 内部,此时会自动触发活体检测。

文件上传的代码可以参考 Demo。

2.3 响应数据

① 当活体检测通过时,会在 onPassed() 回调方法中收到回调;
② 当活体检测有错误的时候,会在 onError() 回调方法中回调 errCodeerrMsg 信息,具体的错误信息如下表所示:

错误码错误信息备注说明
权限相关(1开头)
10001缺少相机权限/
10002缺少读写SD卡权限/
参数相关(2开头)
20001context为空,SDK没有初始化或者初始化失败/
20002appId为空,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 请求是为了方便测试,生产环境建议从服务端请求;

24小时热线 400-9669-253