tencent cloud

人脸核身

Android 接口概述

下载
聚焦模式
字号
最后更新时间: 2026-10-26 19:58:07
本文档已由 AI 辅助审校

API 的分类

eKYC SDK 主要涉及如下几个类:

核心类

类名
类型
说明
HuiYanOsApi
接口类
SDK 的主入口,提供初始化、启动核身、资源释放等核心方法
HuiYanOsConfig
配置类
启动 SDK 时的参数配置,包含 License、超时设置、UI 定制等
HuiYanOsAuthResult
结果类
核身成功后的结果对象,包含 Token 等信息

回调接口

接口名
说明
HuiYanOsAuthCallBack
核身流程结果回调,包含成功和失败两个方法
HuiYanAuthEventCallBack
核身过程中的关键事件回调,用于监听动作检测等事件

枚举类型

枚举类
说明
PageColorStyle
核身界面配色(亮色/暗色)
LanguageStyle
语言类型(中文/英文/跟随系统等)
VideoSize
核身视频分辨率(480P/720P)
CameraZoom
后置摄像头缩放级别(1x/1.5x/2x)
FaceAngleValidation
人脸角度检测严格等级(宽松/中等/严格)
FaceOcclusionLevel
人脸遮挡检测等级(严格/中等/宽松/通过)

事件类型

类名
说明
HuiYanAuthTipsEvent
核身过程中的 Tips 提示事件(如"请张嘴"、"请靠近"等)
HuiYanAuthEvent
核身过程中的关键动作事件(如开始检测、检测完成等)

配置辅助类

类名
说明
AuthUiConfig
核身页面 UI 自定义配置,包含颜色、字体、布局等参数



详细 API 说明

以下为各个类和接口的详细说明:

HuiYanOsApi

API
功能描述
init()
初始化接口
release()
资源释放接口
设置核身过程中的核身关键动作的回调
精简流程的海外核身接口,只需调用此接口即可完成整体核身流程。
获取设备元数据(用于向云 API 换取 SdkToken)
获取当前 SDK 的版本号

init()

功能介绍:
eKYC SDK 的初始化接口。
public static void init(Context context)
传入参数:
参数类型
参数名称
参数含义
Context
context
App 的上下文信息

release()

功能介绍:
eKYC SDK 资源释放的接口。
public static void release()

setAuthEventCallback()

功能介绍:
用来注册核身过程中的核身关键动作的回调。
public static void setAuthEventCallBack(HuiYanAuthEventCallBack huiYanAuthEventCallBack)
传入参数:
参数类型
参数名称
参数含义
huiYanAuthEventCallback
核身关键动作的回调

startHuiYanAuth()

功能介绍:
启动 eKYC 活体检测流程,传入业务 Token 和 SDK 配置,通过回调返回验证结果。
public static void startHuiYanAuth(final String startToken, final HuiYanOsConfig startConfig, HuiYanOsAuthCallBack authCallBack)
传入参数:
参数类型
参数名称
参数含义
String
startToken
从服务器兑换来启动核身使用的业务 Token
startConfig
配置的参数
authCallback
活体结果的回调

createMetaData()

public static String createMetaData()

功能介绍:
获取设备元数据(用于向云 API 换取 SdkToken)。返回加密字符串,接入方在申请 SdkToken 时作为 MetaData 入参透传给云 API。需先调用 init() 完成初始化。

返回参数:
类型
名称
参数含义
String
metaData
加密后的设备元数据字符串,接入方无需关心具体内容,作为 MetaData 入参透传给云 API 即可;采集/加密失败时返回空字符串
说明:
调用时机:在向云 API 申请 SdkToken 之前调用,将返回值作为 MetaData 入参传给云 API。云 API 会随 SdkToken 一并返回 ServerParamInfo 配置串,接入方需将其透传给 SDK(见 HuiYanOsConfig.serverParamInfo)。
示例:
// 1. 获取设备元数据
String metaData = HuiYanOsApi.createMetaData();
// 2. 向云 API 申请 SdkToken(透传 metaData)
// 云 API 返回 SdkToken + ServerParamInfo
// 3. 启动核身(透传 serverParamInfo)
HuiYanOsConfig config = new HuiYanOsConfig();
config.setServerParamInfo(serverParamInfo);
HuiYanOsApi.startHuiYanAuth(sdkToken, config, authCallBack);

getVersion()

public static String getVersion()

功能介绍:
获取当前 SDK 的版本号。

返回参数:
类型
名称
参数含义
String
version
SDK 当前的版本号


HuiYanOsConfig

HuiYanOsConfig 是启动 eKYC SDK 时的配置实体类,主要包含了以下属性。
类型
名称
含义
默认值
pageColorStyle
此次人脸核身检测的配色
PageColorStyle.Light
String
authLicense
客户申请的用户核身授权的 License 文件名
空
String
riskLicense
客户申请的设备风控授权的 License 文件名,增强版和 Plus 版能力需要传入该路径
空
long
authTimeOutMs
设置活体检测的超时时间
10000毫秒(10秒)
boolean
openCheckRiskMode
是否开启风控检测的开关,增强版和 Plus 版能力需要开启该字段
false
boolean
isDeleteVideoCache
是否删除核身视频的本地缓存
true
boolean
isShowGuidePage
是否打开核身的引导页
true
languageStyle
语言类型
跟随系统语言
String
languageCode
语言码(见 Android 自定义能力文档),配合 languageStyle 一起使用
空
String[]
backupIPs
备用 IP 列表
空
String
backUpHost
备用域名
空
authUiConfig
UI 配置项
空
boolean
isUseBackCamera
是否开启后置摄像头(后置摄像头只有在纯动作或者静默时生效,否则包含反光阶段的话 SDK 会报错 HY_USE_BACK_CAMERA_WITH_REFLECTIVE_ERROR 227)
false
float
smallFaceRatioThreshold
最小人脸占比的阈值,小于该阈值会提示靠近一些
0.5f
float
bigFaceRatioThreshold
最大人脸占比的阈值,大于该阈值会提示靠远一些
0.8f
zoomLevel
后置摄像头缩放级别
CameraZoom.ZOOM_1X
boolean
isOpenBOTCheck
是否开启 Bot 模式
false
long
longCheckTimeoutMs
开启 Bot 模式,Bot 阶段的超时时间
30000毫秒(30秒)
boolean
showPrivacyPolicyDialog
是否默认打开合规弹窗(设置 false 可以关闭)
true
boolean
disableSystemRecordScreen
是否禁止核身界面系统截屏或者录屏
false
boolean
isOtherActionCheckMouthOpen
其他动作阶段是否启用额外嘴巴张开检测
false
faceAngleValidation
人脸角度检测等级,默认为宽松模式
FaceAngleValidation.LevelLoose
faceOcclusionLevel
人脸遮挡检测等级,默认为严格模式
FaceOcclusionLevel.STRICT
boolean
isAllowCancelWaiting
是否允许等待结果时通过 back 键取消
false
boolean
isEntireHighlight
是否在进入活体时立即将屏幕亮度调至最大,流程结束后自动恢复。
false
String
modelPath
客户自定义的模型资源地址
空
boolean
isShowErrorPopup
是否启用错误重试弹窗
false
int
compareRequestTimeOutMs
活体比对请求的超时时间(单位:毫秒)
60000
int
compareRequestAttempts
活体比对请求的尝试次数,最小值为1
3
int
lightRequestTimeOutMs
拉取光线序列请求的超时时间(单位:毫秒)
30000
int
lightRequestAttempts
拉取光线序列请求的尝试次数,最小值为1
3
String
serverParamInfo
云 API 在申请 SdkToken 时一并返回的加密配置字符串(必传)。传入空字符串或内容异常时 SDK 会报错
空
boolean
isOpenAudio
是否开启核身过程中的语音播报(动作提示、异常反馈等)。开启后还需引入 huiyanaudio-oversea_1.x.x_release.aar 语音资源包,否则设置为 true 也不会有声音,详见 开启语音播报
true
boolean
isShowGuideAnimation
是否展示核身前的引导动画(例如提示用户对准人脸的动效)
true



开启语音播报

SDK 在核身过程中支持语音播报(动作提示、异常反馈、姿势引导等)。开启语音需要同时满足以下两个条件:

1. 引入语音资源包 huiyanaudio-oversea_1.x.x_release.aar

该资源包为纯资源 aar(仅包含 assets/audio/*.m4a 音频文件,不含 Java 类),接入方式与其他 aar 一致,将其放入 libs 目录并在 build.gradle 中声明依赖:
├── codedemo
│ ├── libs
│ │ ├── huiyanaudio-oversea_1.x.x_release.aar
│ │ └── ...
dependencies {
// 语音播报资源包(可选)
implementation files("libs/huiyanaudio-oversea_1.x.x_release.aar")
}
2. 打开配置开关 isOpenAudio
HuiYanOsConfig config = new HuiYanOsConfig();
// 开启语音播报(默认已开启,可显式设置以便阅读)
config.setOpenAudio(true);
// 如需在核身界面隐藏"喇叭/静音"切换按钮,可关闭
config.getAuthUiConfig().setShowSoundToggleBtn(false);

行为说明:
若 isOpenAudio = true 但未引入语音资源包 aar:SDK 内部加载语音资源失败会静默降级,核身流程仍可正常进行,只是没有声音。
若 isOpenAudio = false:SDK 会直接跳过加载语音资源,不依赖也不加载 aar。
核身界面默认会展示"喇叭/静音"切换按钮,用户可在核身过程中随时切换;如需隐藏该按钮,请通过 AuthUiConfig.setShowSoundToggleBtn(false) 关闭。

PageColorStyle

核身界面默认配色的枚举类,当前主要包括了两种配色,白色系与黑暗色系。
PageColorStyle 类型
含义
PageColorStyle.Light
亮色调配色
PageColorStyle.Dark
暗色调配色

LanguageStyle

LanguageStyle 类型
含义
LanguageStyle.AUTO
跟随系统
LanguageStyle.ENGLISH
英语
LanguageStyle.SIMPLIFIED_CHINESE
简体中文
LanguageStyle.TRADITIONAL_CHINESE
繁体中文
LanguageStyle.CUSTOMIZE_LANGUAGE
自定义语言

AuthUiConfig

核身页面自定义 UI 的参数配置
类型
名称
含义
默认值
VideoSize
videoSize
核身过程中的分辨率
480p
boolean
isShowCountdown
是否显示倒计时的控件
true
boolean
isShowErrorDialog
是否显示错误的 dialog
true
int
authLayoutResId
核身导出客户自定义的布局 resID ,不调整时使用 -1
-1
int
feedBackErrorColor
异常反馈 Tips 的颜色( 0xFFFFFFFF 的类型)不调整时使用 -1
-1
int
feedBackTxtColor
正常反馈 Tips 颜色( 0xFFFFFFFF 的类型)不调整时使用 -1
-1
int
authCircleErrorColor
动作错误时背景圆形框的颜色( 0xFFFFFFFF 的类型)不调整时使用 -1
-1
int
authCircleCorrectColor
动作正确时背景圆形框的颜色( 0xFFFFFFFF 的类型)不调整时使用 -1
-1
int
authLayoutBgColor
核身界面背景的颜色( 0xFFFFFFFF 的类型)不调整时使用 -1
-1
int
loadingStageBgColor
核身界面 loading 阶段的背景颜色( 0xFFFFFFFF 的类型)
-1
int
loadingStageTipsColor
核身界面 loading 阶段的 tips 提示的颜色( 0xFFFFFFFF 的类型)
-1
int
cancelTxtColor
核身界面取消按钮的颜色( 0xFFFFFFFF 的类型)
-10
int
countDownTxtColor
核身界面倒计时提示的颜色( 0xFFFFFFFF 的类型)
-10
boolean
isHideAvatarGuideFrame
是否需要隐藏头像引导框
false
boolean
isShowSoundToggleBtn
是否在核身界面显示"喇叭/静音"切换按钮(仅在 HuiYanOsConfig.isOpenAudio 为 true 时该按钮才有意义)
true

VideoSize

eKYC 核身支持的分辨率枚举
VideoSize 类型
含义
VideoSize.SIZE_480P
480P
VideoSize.SIZE_720P
720P

HuiYanOsAuthResult

核身流程的成功回调对应的结果类型。
类型
名称
含义
默认值
String
token
此次活体流程中使用的 token
空
最后需要通过这个 token,去腾讯云 API 的后台接口 GetFaceIdResultIntl 拉取最终活体是否成功的数据。

错误码

这里是 SDK 在失败回调中的错误码,目前 SDK 包含的错误码与其含义如下:
错误码
错误码值
错误码含义
HY_NETWORK_ERROR
210
网络请求出现异常
HY_LOCAL_REF_FAILED_ERROR
211
本地初始化 SDK 时,检测失败,常见异常不存在 license 文件或者 license 过期
HY_USER_CANCEL_ERROR
212
用户主动取消核身流程
HY_INNER_ERROR_CODE
213
SDK 内部产生的异常,终止了核身流程
HY_DO_NOT_CHANGE_ERROR
214
在核身过程中切换应用发生终止流程的异常
HY_OPEN_CAMERA_ERROR
215
打开摄像头过程中发生异常
HY_INIT_SDK_ERROR
216
未调用 init() 方法,直接调用了启动接口
HY_VERIFY_LOCAL_ERROR
217
本地人脸检测失败(已废弃),统一使用 228 错误码
HY_PERMISSION_CHECK_ERROR
218
本地 SDK 所需要的权限不足(已废弃)
HY_APP_STOP_ERROR
219
集成者主动终止核身流程,startAuthByLightData 的 reflectSequence 为 null 时
HY_CHECK_LIVE_DATA_ERROR
220
传入的光线序列参数校验失败
HY_INITIALIZATION_PARAMETER_EXCEPTION
221
在未获取设备配置的前提下,直接调用设置光线序列参数的方法时,会出现的异常
HY_VERIFY_LOCAL_TIME_OUT
222
本地核身动作检测超时
HY_PREPARE_TIME_OUT
223
准备过程超时(启动摄像头到第一次检测到人脸的时间超时)
HY_CHECK_PERMISSION_ERROR
224
SDK 内部申请摄像头权限失败
HY_USE_BACK_CAMERA_WITH_REFLECTIVE_ERROR
227
使用后置摄像头时,SDK 采用的活体模式包含反光数据时报错
HY_ACTION_REFLECTIVE_SDK_ERROR
228
内部算法本地检测识别失败
HY_RISK_INIT_AUTH_ERROR
231
设备风控模块授权检测异常
HY_ILLEGAL_CONTEXT_ERROR
233
非法 context,检查 init 接口传入的 context 是否合法
HY_ILLEGAL_TOKEN
288
非法 token
HY_TURING_CONFIG_MISMATCH_EXCEPTION
400
风控模块配置不匹配(场景:HuiYanOsConfig 的配置 openCheckRiskMode 和申请获取业务 token 时的 SdkVersion 需要匹配、申请增强或者 Plus 模式的 token ,openCheckRiskMode 需要设置为 true )

HuiYanOsAuthCallback

精简活体流程的回调接口
/**
* 海外精简的结果回调
*
* @author jerrydong
* @since 2022/6/10
*/
public interface HuiYanOsAuthCallBack {

/**
* 活体成功回调
*
* @param authResult 结果
*/
void onSuccess(HuiYanOsAuthResult authResult);

/**
* 活体失败
*
* @param errorCode 错误码
* @param errorMsg 错误信息
* @param token 本次核身使用的
*/
void onFail(int errorCode, String errorMsg, String token);
}

HuiYanAuthEventCallback

用来监听核身过程中的关键事件的回调,以及如果需要使用自定义布局的 UI 绑定可以进行 事件绑定(可以参考自定义能力的文档)。
HuiYanAuthTipsEvent 是 SDK 在核身过程中的关键事件 Tips 的回调。
HuiYanAuthEvent 是 SDK 在核身过程中的关键事件的回调。
/**
* SDK核身的事件回调
*/
public interface HuiYanAuthEventCallBack {

/**
* 核身时tips发生改变的事件通知回调
*
* @param tipsEvent tips关键事件
*/
void onAuthTipsEvent(HuiYanAuthTipsEvent tipsEvent);

/**
* 核身的Event事件
*
* @param authEvent authEvent
*/
void onAuthEvent(HuiYanAuthEvent authEvent);

/**
* 当认证的主View被创建的回调
*
* @param authView
*/
void onMainViewCreate(View authView);

/**
* 界面被回收的回调
*/
void onMainViewDestroy();

void onBeginTransition();

void onEndTransition();
}


HuiYanAuthTipsEvent

对应的事件类型与含义:
事件枚举
事件含义
NONE
无意义
ACT_OPEN_MOUTH
请张张嘴
ACT_BLINK
请眨眨眼
ACT_NOD_HEAD
请点头
ACT_SHAKE_HEAD
请摇头
ACT_SCREEN_SHAKING
请不要晃动
NO_FACE
没有检测到人脸
NO_LEFT_FACE
请勿遮挡左脸
NO_RIGHT_FACE
请勿遮挡右脸
NO_MOUTH
请勿遮挡嘴巴
NO_CHIN
请勿遮挡下巴
NO_NOSE
请勿遮挡鼻子
NO_LEFT_EYE
请勿遮挡左眼
NO_RIGHT_EYE
请勿遮挡右眼
POSE_KEEP
验证中,请保持姿势不变
POSE_CLOSER
请靠近一点
POSE_FARTHER
请离远一点
POSE_OPEN_EYE
请勿闭眼
POSE_INCORRECT
没有检测到完整人脸
TOO_MANY_FACE
请确保框内只有一张人脸
INCOMPLETE_FACE
请将脸移动到框内
LIGHT_TOO_LOW
环境光线太暗
LIGHT_TOO_STRONG
环境光线太亮
FACE_TOO_BRIGHT
人脸过亮
FACE_TOO_DARK
人脸过暗

HuiYanAuthEvent

对应的事件类型与含义:
事件枚举
事件含义
NONE
无意义,默认事件不回调
START_AUTH
启动核身认证
OPEN_MOUTH_CHECK
开始张嘴动作检测
SILENCE_CHECK
开始静默检测
BLINK_CHECK
开始眨眼动作检测
NOD_HEAD_CHECK
开始点头动作检测
SHAKE_HEAD_CHECK
开始摇头动作检测
REFLECT_CHECK
启动光线检测
OPEN_MOUTH_CHECK_DONE
张嘴检测结束
SILENCE_CHECK_DONE
静默检测结束
BLINK_CHECK_DONE
眨眼检测结束
NOD_HEAD_CHECK_DONE
点头检测结束
SHAKE_HEAD_CHECK_DONE
摇头检测结束
ALL_ACTION_DONE
整个动作检测阶段结束
LOCAL_DETECTION_DONE
本地检测结束
FACE_QUALITY_CHECK
人脸质量检测开始
FACE_QUALITY_CHECK_END
人脸质量检测结束

CameraZoom

后置摄像头缩放倍数,默认缩放1倍。
CameraZoom 类型
含义
CameraZoom.ZOOM_1X
1倍缩放
CameraZoom.ZOOM_1_5X
1.5倍缩放
CameraZoom.ZOOM_2X
2倍缩放

FaceAngleValidation

人脸旋转角度检测严格等级,默认宽松
FaceAngleValidation 类型
含义
FaceAngleValidation.LevelLoose
宽松模式,大约允许30度的人脸旋转且如果旋转角度过大反光阶段不会主动退出。
FaceAngleValidation.LevelMedium
中等模式,大约允许20度的人脸旋转且如果旋转角度过大反光阶段会主动退出。
FaceAngleValidation.LevelStrict
严格模式,大约允许10度的人脸旋转且如果旋转角度过大反光阶段会主动退出。

FaceOcclusionLevel

人脸遮挡检测阈值等级,默认严格模式。
FaceOcclusionLevel 类型
含义
FaceOcclusionLevel.STRICT
严格模式,对人脸遮挡检测最为严格。
FaceOcclusionLevel.MODERATE
中等模式,对人脸遮挡检测适中。
FaceOcclusionLevel.LOOSE
宽松模式,对人脸遮挡检测较为宽松。
FaceOcclusionLevel.PASS
通过模式,跳过人脸遮挡检测。


帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈