tencent cloud

Android 接口概述
最后更新时间:2026-03-27 11:21:27
Android 接口概述
最后更新时间: 2026-03-27 11:21:27

API 的详细说明

eKYC SDK 主要涉及如下几个类,它们分别是 API 的接口类 HuiYanOsApi , 参数配置类 HuiYanOsConfig ,结果回调类 HuiYanOsAuthCallback 和 HuiYanAuthEventCallback。

HuiYanOsApi

API
功能描述
init()
初始化接口
release()
资源释放接口
设置核身过程中的核身关键动作的回调
精简流程的海外核身接口,只需调用此接口即可完成整体核身流程。

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

功能介绍:
海外核身接口,只需调用此接口即可完成整体核身流程。
public static void startHuiYanAuth(final String startToken, final HuiYanOsConfig startConfig, HuiYanOsAuthCallBack authCallBack)
传入参数:
参数类型
参数名称
参数含义
String
startToken
从服务器兑换来启动核身使用的业务 Token
startConfig
配置的参数
authCallback
活体结果的回调

HuiYanOsConfig

HuiYanOsConfig 是启动eKYC SDK 时的配置实体类,主要包含了以下属性。
类型
名称
含义
默认值
pageColorStyle
此次人脸核身检测的配色
PageColorStyle.Light
String
authLicense
客户申请的用户核身授权的 Licens 文件名
String
riskLicense
客户申请的设备风控授权的 Licens 文件名,增强版和Plus版能力需要传入该路径
long
authTimeOutMs
设置活体检测的超时时间
10000毫秒(10秒)
boolean
openCheckRiskMode
是否开启风控检测的开关,增强版和Plus版能力需要开启该字段
false
boolean
isDeleteVideoCache
是否删除核身视频的本地缓存
true
boolean
isShowGuidePage
是否打开核身的引导页
true
languageStyle
语言类型
跟随系统语言
String
languageCode
语言码(见附录),配合 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

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

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
风控模块配置不匹配

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
环境光线太亮

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
本地检测结束

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
通过模式,跳过人脸遮挡检测。

本页内容是否解决了您的问题?
您也可以 联系销售 提交工单 以寻求帮助。

文档反馈