tencent cloud

人脸核身

文档人脸核身接入文档卡证活体人脸比对（App SDK）接入指引SDK 接口 API 概述Android 接口概述文档

Android 接口概述文档

Download
聚焦模式
字号
最后更新时间： 2026-08-12 11:10:46
Android 端卡证活体人脸比对 SDK 涉及的类包含 EkycHySdk、EkycHyConfig、EkycHyCallBack 这几个主要类型，下面对其支持的 API 做出详细说明。


EkycHySdk

EkycHySdk 为卡证活体人脸比对 SDK 的对外接口类，主要逻辑也都是调用此类完成。
API
功能描述
init()
初始化接口
release()
资源释放接口
startEkycCheck()
启动卡证活体人脸比对检测流程
createMetaData()
采集设备元数据并加密，供业务方请求 token 时填入 MetaData 字段
setAuthEventCallBack()
设置活体人脸比对过程中的事件回调
setOcrCloudEventListener()
注册 OCR 采集阶段事件监听器，用于拦截弹窗并自定义 UI

init()

public static void init(Context context)

功能介绍：
​卡证活体人脸比对 SDK 的初始化接口。

传入参数:
参数类型
参数名称
参数含义
Context
context
App 的上下文信息

release()

public static void release()

功能介绍：
​卡证活体人脸比对 SDK 资源释放接口。


startEkycCheck()

public static void startEkycCheck(Activity activity, final String ekycToken,
            String serverParamInfo, EkycHyConfig ekycHyConfig, EkycHyCallBack ekycHyCallBack)

功能介绍：
​启动卡证活体人脸比对流程的函数。

传入参数：
参数类型
参数名称
参数含义
Activity
activity
调用方 Activity，SDK 需要用它启动内部 UI
String
ekycToken
从服务器端获取的 Token 值，作为此次流程唯一业务凭证
String
serverParamInfo
服务端下发的加密配置字符串，SDK 内部解密后使用
ekycHyConfig
卡证活体人脸比对本次流程启动的配置信息
ekycHyCallBack
用来接收认证结果回调的接口



createMetaData()

public static String createMetaData()

功能介绍：

采集设备元数据并加密，供业务方请求 token 时填入 MetaData 字段。

返回值：

类型
含义
String
加密后的 Base64 字符串，失败返回空字符串



setAuthEventCallBack()

public static void setAuthEventCallBack(HuiYanAuthEventCallBack authEventCallBack)

功能介绍：
设置活体人脸比对过程中的事件回调，可用于监听验证页面生命周期及检测过程中的关键事件。

传入参数：
参数类型
参数名称
参数含义
HuiYanAuthEventCallBack
authEventCallBack
活体人脸比对事件回调接口
HuiYanAuthEventCallBack 主要回调方法：
方法
含义
onMainViewCreate(View)
活体人脸比对主界面创建时回调
onMainViewDestroy()
活体人脸比对主界面销毁时回调


setOcrCloudEventListener()

public static void setOcrCloudEventListener(IOcrCloudEventListener listener)

功能介绍：

注册 OCR 采集阶段事件监听器（Token 模式），允许调用方拦截 SDK 内部的各类弹窗和 UI 事件，实现完全自定义的 UI 交互。必须在 startEkycCheck() 之前调用。传 null 取消注册。

传入参数：
参数类型
参数名称
参数含义
IOcrCloudEventListener
listener
OCR 事件监听器，传 null 取消注册
IOcrCloudEventListener 回调方法：
方法
说明
返回值含义
onMainViewCreate(View)
OCR 识别主 View 创建时回调
无
onMainViewDestroy()
OCR 识别主 View 销毁时回调
无
onEventParamMap(HashMap)
额外参数透传
无
onShowCloudErrorDialog(HashMap, View, Runnable, Runnable)
拦截失败弹窗
true=自行处理，false=SDK 默认弹窗
onShowBestFrameConfirmDialog(HashMap, View, ImageView, Runnable, Runnable)
拦截最佳帧确认弹窗
同上
onShowCameraPermissionDialog(HashMap, View, Runnable, Runnable)
拦截相机权限弹窗
同上
onShowNextSideDialog(HashMap, View, Runnable)
拦截"切换下一面"弹窗
同上
onShowChangeModeDialog(HashMap, View, Runnable, Runnable)
拦截"超时切换手动模式"弹窗
同上
onShowUploadLoading(View)
拦截上传 Loading
同上
onHideUploadLoading()
上传 Loading 结束回调，与 onShowUploadLoading 成对调用
无
注意：
调用时机：必须在 startEkycCheck() 之前注册监听器。
Block 必须调用：弹窗回调中提供的 retryBlock/exitBlock/confirmBlock/cancelBlock 等 Runnable，用户做出选择后必须调用其中一个，否则 SDK 流程会卡住。
retryBlock 可能为 null：onShowCloudErrorDialog 中 retryBlock 为 null 表示不可重试，调用方无需展示重试按钮。
弹窗类回调返回 true 表示调用方自行处理（SDK 不展示默认 UI），返回 false 则 SDK 展示默认弹窗。所有弹窗方法默认返回 false，可按需覆写。
Loading 生命周期：仅当 `onShowUploadLoading` 返回 `true` 时，SDK 才会回调 `onHideUploadLoading()`，调用方应在此隐藏自定义 loading。
取消注册：不再需要自定义 UI 时，传 null 取消注册。


EkycHyConfig

EkycHyConfig 是在启动卡证活体人脸比对 SDK 时的配置实体类，主要包含了以下属性。
类型
名称
含义
默认值
String
licenseName
客户申请的用户授权 License 文件名
空
String
riskLicenseName
新增设备风险检测的 license 配置，当 openCheckRiskMode 为 true 时，需配置
空
boolean
openCheckRiskMode
是否开启设备风险检测，当 ApplySdkVerificationToken 中入参 SdkVersion 设置为 ENHANCE 或 PLUS 时，需配置为开启（true）
false
languageStyle
本次流程的语言风格
LanguageStyle.AUTO
String
languageCode
语言码，和 LanguageStyle.CUSTOMIZE_LANGUAGE 配合使用
空
long
livenessAutoTimeout
活体人脸比对的超时时间
30000毫秒（30秒），支持范围最大600秒，最小10秒
boolean
showPrivacyPolicyDialog
是否显示隐私政策的 dialog
true
boolean
isUseBackCameraOnFaceAuth
是否在活体人脸比对时使用后置摄像头，如配置开启光线活体检测，开启时将报错12008
false
String
faceModelPath
活体人脸比对模型目录路径，不引入 huiyanmodels AAR 时需通过此字段指定外部模型目录路径（目录名为 face-tracker-v003）
空
boolean
isShowGuidePage
是否显示人脸识别前的准备提示页。设为 false 时，SDK 跳过提示页，直接进入活体检测
true
boolean
isShowResultPage
是否显示人脸识别后的结果展示页。设为 false 时，SDK 跳过结果页，直接通过回调将结果返回给宿主
true
boolean
isEntireHighlight
人脸识别页面全程高亮，设为 true 时，人脸识别页面全程高亮
false
boolean
isShowErrorPopup
活体失败时是否显示重试弹窗。设为 true 时，活体失败弹出重试弹窗，不再展示失败结果页
false
boolean
showBestImgConfirmDialog
OCR 最佳图片确认弹窗，设为 true 时拍摄完成后弹出确认弹窗
false
ocrUiConfig
OCR 识别界面的自定义 UI 配置
null
faceAuthUiConfig
活体人脸比对页面的自定义 UI 配置
null

OcrUiConfig

OCR 识别界面的自定义 UI 配置，通过 EkycHyConfig.setOcrUiConfig() 传入。

方法名
参数类型
含义
默认值
portraitLayoutResId
int
竖屏布局资源 ID
-2
portraitThemeResId
int
竖屏主题风格资源 ID
-2
showStatusBar
boolean
是否显示状态栏
true
statusBarColor
int
状态栏背景颜色（0xFFFFFF 格式）
-2
useDeepColorStatusBarIcon
boolean
是否使用深色状态栏图标（配合浅色状态栏使用）
false
cardFrameDefaultColor
int
卡证边框默认状态颜色（未检测到卡片时）
-2
cardFrameColor
int
卡证边框高亮状态颜色（识别成功时）
-2
warnErrorTextColor
int
卡证边框错误状态颜色及错误提示文字颜色
-2
defaultTipTextColor
int
默认状态下卡框区域提示文字颜色
-2
successRemindTextColor
int
识别成功状态下卡框区域提示文字颜色
-2
imageSelectResId
int
相册本地选图按钮图标资源 ID
-2
lightImageOnResId
int
打开闪光灯按钮图标资源 ID
-2
lightImageOffResId
int
关闭闪光灯按钮图标资源 ID
-2
takePicturesResId
int
手动拍照按钮图标资源 ID
-2
backActionIconResId
int
返回按钮图标资源 ID
-2
removeAlbum
boolean
是否隐藏相册选图功能
false
removeFlash
boolean
是否隐藏闪光灯按钮
false
isShowIdcardLogo
boolean
身份证扫描框是否显示人头/国徽 Logo
true
remindDialogText
String
提醒 Dialog 的文字内容
""
remindDialogTextColor
int
提醒 Dialog 文字颜色
-2
remindDialogTextSize
int
提醒 Dialog 文字大小
-2
remindDialogConfirmText
String
确认按钮文字
""
remindDialogCancelText
String
取消按钮文字
""
remindDialogConfirmColor
int
确认按钮颜色
-2
remindDialogCancelColor
int
取消按钮颜色
-2
remindDialogShowTitle
boolean
是否显示提醒 Dialog 的标题
true
remindDialogCommonStyle
int
提醒 Dialog 的整体风格资源 ID
-2
remindDialogCommonBgColor
int
提醒 Dialog 背景颜色
-2
remindDialogChangeModeTextOnLeft
boolean
模式切换按钮是否显示在 Dialog 左侧
false
说明：
默认值 -2 表示该字段未设置，SDK 使用内置默认值。

FaceAuthUiConfig

活体人脸比对页面的自定义 UI 配置，通过 EkycHyConfig.setFaceAuthUiConfig() 传入。
方法名
参数类型
含义
默认值
authLayoutResId
int
竖屏核身页面自定义布局 ResId
-2
mainActivityThemeId
int
核身 Activity 主题 ResId
-2
statusBarColor
int
状态栏颜色（0xFFFFFF 格式）
-2
isTransparentStatusBar
boolean
状态栏是否透明
false
transparentStatusBarMoveHeight
int
透明状态栏时内容上移高度（px）
-2
useDeepColorStatusBarIcon
boolean
状态栏图标是否使用深色
false
isShowCountdown
boolean
是否显示倒计时
true
isShowErrorDialog
boolean
是否显示错误弹窗
true
countDownTxtColor
int
倒计时文字颜色
-2
cancelTxtColor
int
取消按钮文字颜色
-2
feedBackTxtColor
int
检测反馈提示文字颜色（正常状态）
-2
feedBackErrorColor
int
检测反馈错误状态颜色
-2
feedBackExtraTipColor
int
检测反馈额外提示文字颜色
-2
authCircleCorrectColor
int
动作正确时人脸圆形框颜色
-2
authCircleErrorColor
int
动作错误时人脸圆形框颜色
-2
isHideFrontCircleViewOnStart
boolean
启动阶段是否隐藏人脸圆圈
false
isHideFrontCircleViewOnCheck
boolean
动作检测阶段是否隐藏人脸圆圈
false
isHideFrontCircleViewOnReflect
boolean
反光阶段是否隐藏人脸圆圈
false
isHideAvatarGuideFrame
boolean
是否隐藏头像引导框
false
authLayoutBgColor
int
核身页面背景色
-2
loadingStageBgColor
int
Loading 阶段背景色
-2
loadingStageTipsColor
int
Loading 阶段提示文字颜色
-2
说明：
默认值 -2 表示该字段未设置，SDK 使用内置默认值。

LanguageStyle

卡证活体人脸比对默认界面的多语言配置信息。
LanguageStyle 类型
含义
LanguageStyle.AUTO
跟随系统语言版本
LanguageStyle.ENGLISH
英语
LanguageStyle.SIMPLIFIED_CHINESE
简体中文
LanguageStyle.TRADITIONAL_CHINESE
繁体中文
LanguageStyle.CUSTOMIZE_LANGUAGE
自定义语言， 需配合 languageCode 使用，详情参见 Android 自定义能力

EkycHyCallBack

用于接收卡证活体人脸比对流程结果的监听类。
/**
 * 卡证活体人脸比对的结果回调类
 */
public interface EkycHyCallBack {

    /**
     * 识别成功的结果信息
     *
     * @param result 结果信息
     */
    void onSuccess(EkycHyResult result);

    /**
     * 卡证活体人脸比对流程失败的内容
     *
     * @param errorCode 错误码
     * @param errorMsg 错误信息
     * @param ekycToken 当次流程的token
     */
    void onFail(int errorCode, String errorMsg, String ekycToken);
}
其中 EkycHyResult 是成功返回的结果对象。


EkycHyResult

EkycHyResult 是卡证活体人脸比对 SDK 流程成功后的结果对象。
类型
名称
含义
默认值
String
ekycToken
当次卡证活体人脸比对流程的 token，此 token 可以在服务器拉取身份认证过程关键数据
空

错误码

错误码
对应含义
12000
用户主动取消
12001
网络请求失败
12002
OCR 识别异常导致的错误
12003
本地人脸检测失败引起的异常
12004
失效的 token
12005
本地证件识别失败
12006
卡证活体人脸比对 SDK 初始化流程失败
12007
启动参数校验失败
210
网络请求出现异常
211
本地初始化 SDK 时，检测失败，常见异常不存在 license 文件或者 license 过期
213
SDK 内部产生的异常，终止了核身流程
214
在核身过程中切换应用发生终止流程的异常
215
打开摄像头过程中发生异常
216
未调用 init()方法，直接调用了
217
本地人脸检测失败(已废弃)，统一使用228错误码
218
本地 SDK 所需要的权限不足（已废弃）
219
集成者主动终止核身流程，startAuthByLightData的reflectSequence为 null 时
220
传入的光线序列参数校验失败
221
在未获取设备配置的前提下，直接调用了设置光线序列参数的方法时，会出现的异常
222
本地核身动作检测超时
223
准备过程超时（启动摄像头到第一次检测到人脸的时间超时）
224
SDK内部申请摄像头权限失败
227
使用后置摄像头时，SDK采用的活体模式包含反光数据时报错
228
内部算法本地检测识别失败
231
设备风控模块授权检测异常
233
非法context, 检查init接口传入的context是否合法
288
非法token
400
风控模块配置不匹配
-1
参数校验失败（如 sdkToken / serverParamInfo 为空、Activity 为空、未先调用 init() 等）
100100
参数异常
100102
网络异常
100103
摄像头权限异常
200101
用户主动取消识别
300101
模型/SDK 初始化异常
300102
服务解析异常（含网络超时、密文解析失败、未知错误兜底）
300103
签名失败
300104
摄像头异常
300105
初始化配置失败
300106
图片异常为空
300107
license 授权失败
300108
系统版本过低
300109
自动模式超时（未捕获到图片）
300110
SDK 内部错误
300111
SDK 内部图片裁剪异常
300112
卡证类型不匹配
300113
OCR 失败：告警次数过多
400100
触发指定拦截的告警码
400101
用户传入的证件类型和指定证件类型不一致
400102
用户传入的证件面类型和选择的不同
400103
用户传入照片中卡证占比太小
400104
用户传入的照片中包括多张卡证照片
400105
OCR 识别失败
400106
卡证信息校验失败
400107
入参存在错误
400108
内部服务错误
400109
服务未开通 / 账号欠费 / 资源包耗尽 / 计费异常
400110
触发限流
400111
文件 size 太大或无效
400112
文件解析失败

上一篇: 接入流程说明下一篇: iOS 接口概述文档

帮助和支持

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

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

文档反馈