动态与公告

产品动态

产品公告

产品简介

产品概述

产品优势

应用场景

购买指南

计费概述

购买方式

欠费说明

退费说明

接入文档

开始集成

活体人脸比对（纯 API）接入指引

活体人脸比对 (移动端H5) 接入指引

活体人脸比对 (App SDK) 接入指引

卡证活体人脸比对（移动端 H5）接入指引

卡证活体人脸比对（App SDK）接入指引

其他指引

API 文档

History

Introduction

API Category

Making API Requests

Selfie Verification (Pure API) APIs

Selfie Verification (App SDK) APIs

Identity Verification (App SDK) APIs

Identity Verification(Mobile HTML5) APIs

AI Face Shield (Pure API) APIs

Other APIs

Data Types

Error Codes

常见问题

联系我们

词汇表

eKYC 政策

隐私协议

数据处理和安全协议

服务等级协议

Android 接口概述文档

PDF

聚焦模式

字号

最后更新时间： 2026-03-27 11:15:53

Android 端卡证活体人脸比对 SDK 涉及的类包含 EkycHySdk、EkycHyConfig、EkycHyCallBack 这几个主要类型，下面对其支持的 API 做出详细说明。
﻿
EkycHySdk
EkycHySdk 为卡证活体人脸比对SDK的对外接口类，主要逻辑也都是调用此类完成。
API
功能描述
﻿init()﻿
初始化接口
﻿release()﻿
资源释放接口
﻿startEkycCheck()﻿
启动卡证活体人脸比对检测全流程
﻿setAuthEventCallBack()﻿
设置活体人脸比对过程中的事件回调
﻿setOcrEventCallBack()﻿
设置OCR证件识别过程中的事件回调
init()
public static void init(Context context)
﻿
功能介绍：
​卡证活体人脸比对SDK的初始化接口。
﻿
传入参数:    
参数类型
参数名称
参数含义
Context
context
App的上下文信息
release()
public static void release() 
﻿
功能介绍：
​卡证活体人脸比对SDK资源释放的接口。
﻿
startEkycCheck()
public static void startEkycCheck(final String ekycToken, EkycHyConfig ekycHyConfig,
            EkycHyCallBack ekycHyCallBack)
﻿
功能介绍：
​启动卡证活体人脸比对检测流程的函数。
﻿
传入参数：
参数类型
参数名称
参数含义
String
ekycToken
从服务器端获取的Token值，作为此次流程唯一业务凭证
﻿EkycHyConfig﻿
ekycHyConfig
卡证活体人脸比对本次流程启动的配置信息
﻿EkycHyCallBack﻿
ekycHyCallBack
用来接收认证结果回调的接口
setAuthEventCallBack()
public static void setAuthEventCallBack(HuiYanAuthEventCallBack authEventCallBack)
﻿
功能介绍：
设置活体人脸比对过程中的事件回调，可用于监听验证页面生命周期及检测过程中的关键事件。
﻿
传入参数：
参数类型
参数名称
参数含义
HuiYanAuthEventCallBack
authEventCallBack
活体人脸比对事件回调接口
HuiYanAuthEventCallBack 主要回调方法：
方法
含义
onMainViewCreate(View)
活体人脸比对主界面创建时回调
onMainViewDestroy()
活体人脸比对主界面销毁时回调
setOcrEventCallBack()
public static void setOcrEventCallBack(OcrEventListener ocrEventListener)
﻿
功能介绍：
​设置 OCR 证件识别过程中的事件回调，可用于监听 OCR 页面生命周期及摄像头状态。
﻿
传入参数：
参数类型
参数名称
参数含义
OcrEventListener
ocrEventListener
OCR 事件回调接口
OcrEventListener 主要回调方法：
方法
含义
onMainViewCreate(View)
OCR 主界面创建时回调
onMainViewDestroy()
OCR 主界面销毁时回调
EkycHyConfig
EkycHyConfig 是在启动卡证活体人脸比对 SDK 时的配置实体类，主要包含了以下属性。
类型
名称
含义
默认值
String
licenseName
客户申请的用户授权 License 文件名
空
String
riskLicenseName
新增设备风险检测的license配置，当 openCheckRiskMode 为 true 时，需配置
空
boolean
openCheckRiskMode
是否开启设备风险检测，当 ApplySdkVerificationToken 中入参 SdkVersion 设置为 ENHANCE 或 PLUS 时，需配置为开启（true）
false
int
ocrAutoTimeout
OCR_DETECT_AUTO_MANUAL模式下，自动捕获的超时时间（毫秒单位，最少设置5秒，内部上限30秒）
20000毫秒（20秒）
﻿LanguageStyle﻿
languageStyle
本次流程的语言风格
LanguageStyle.AUTO
String
languageCode
语言码，和LanguageStyle.CUSTOMIZE_LANGUAGE配合使用
空
long
livenessAutoTimeout
活体人脸比对的超时时间
30000毫秒（30秒），支持范围最大600秒，最小10秒
boolean
showPrivacyPolicyDialog
是否显示隐私政策的dialog
true
boolean
isUseBackCameraOnFaceAuth
是否活体人脸比对时使用后置摄像头，如配置开启光线活体检测，开启时将报错12008
false
String
ocrModelPath
OCR模型文件路径，不引入 OcrSDK-common-model AAR 时需通过此字段指定外部模型文件路径（文件名为 subject.iap）
空
String
faceModelPath
活体人脸比对模型目录路径，不引入 huiyanmodels AAR 时需通过此字段指定外部模型目录路径（目录名为 face-tracker-v003）
空
﻿OcrUiConfig﻿
ocrUiConfig
OCR识别界面的自定义 UI 配置
null
﻿FaceAuthUiConfig﻿
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
启动参数校验失败
12008
活体人脸比对结果返回失败
12009
活体人脸比对过程本地失败

帮助和支持

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

您也可以联系销售或提交工单以寻求帮助。

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

文档反馈

tencent cloud

人脸核身

Android 接口概述文档

EkycHySdk

init()

release()

startEkycCheck()

setAuthEventCallBack()

setOcrEventCallBack()

EkycHyConfig

OcrUiConfig

FaceAuthUiConfig

LanguageStyle

EkycHyCallBack

EkycHyResult

错误码

帮助和支持

API	功能描述
init()	初始化接口
release()	资源释放接口
startEkycCheck()	启动卡证活体人脸比对检测全流程
setAuthEventCallBack()	设置活体人脸比对过程中的事件回调
setOcrEventCallBack()	设置OCR证件识别过程中的事件回调

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

方法	含义
onMainViewCreate(View)	活体人脸比对主界面创建时回调
onMainViewDestroy()	活体人脸比对主界面销毁时回调

类型	名称	含义	默认值
String	licenseName	客户申请的用户授权 License 文件名	空
String	riskLicenseName	新增设备风险检测的license配置，当 openCheckRiskMode 为 true 时，需配置	空
boolean	openCheckRiskMode	是否开启设备风险检测，当 ApplySdkVerificationToken 中入参 SdkVersion 设置为 ENHANCE 或 PLUS 时，需配置为开启（true）	false
int	ocrAutoTimeout	OCR_DETECT_AUTO_MANUAL模式下，自动捕获的超时时间（毫秒单位，最少设置5秒，内部上限30秒）	20000毫秒（20秒）
LanguageStyle	languageStyle	本次流程的语言风格	LanguageStyle.AUTO
String	languageCode	语言码，和LanguageStyle.CUSTOMIZE_LANGUAGE配合使用	空
long	livenessAutoTimeout	活体人脸比对的超时时间	30000毫秒（30秒），支持范围最大600秒，最小10秒
boolean	showPrivacyPolicyDialog	是否显示隐私政策的dialog	true
boolean	isUseBackCameraOnFaceAuth	是否活体人脸比对时使用后置摄像头，如配置开启光线活体检测，开启时将报错12008	false
String	ocrModelPath	OCR模型文件路径，不引入 OcrSDK-common-model AAR 时需通过此字段指定外部模型文件路径（文件名为 subject.iap）	空
String	faceModelPath	活体人脸比对模型目录路径，不引入 huiyanmodels AAR 时需通过此字段指定外部模型目录路径（目录名为 face-tracker-v003）	空
OcrUiConfig	ocrUiConfig	OCR识别界面的自定义 UI 配置	null
FaceAuthUiConfig	faceAuthUiConfig	活体人脸比对页面的自定义 UI 配置	null

方法名	参数类型	含义	默认值
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

LanguageStyle类型	含义
LanguageStyle.AUTO	跟随系统语言版本
LanguageStyle.ENGLISH	英语
LanguageStyle.SIMPLIFIED_CHINESE	简体中文
LanguageStyle.TRADITIONAL_CHINESE	繁体中文
LanguageStyle.CUSTOMIZE_LANGUAGE	自定义语言, 需配合 languageCode 使用，详情参见 Android 自定义能力

错误码	对应含义
12000	用户主动取消
12001	网络请求失败
12002	OCR识别异常导致的错误
12003	本地人脸检测失败引起的异常
12004	失效的token
12005	本地证件识别失败
12006	卡证活体人脸比对SDK初始化流程失败
12007	启动参数校验失败
12008	活体人脸比对结果返回失败
12009	活体人脸比对过程本地失败