文档中心>人脸核身

API 概述

最近更新时间:2026-05-11 19:35:41

我的收藏
Android 端慧眼 SDK 主要涉及的类主要包含 HuiYanAuth、AuthConfig、HuiYanAuthResultListener、CreateFaceIdToken 以及 PageColorStyle,下面对其支持的 API 做出详细说明。

HuiYanAuth

HuiYanAuth 为慧眼 SDK 的对外接口类,主要逻辑也都是调用此类完成。
API
功能描述
init()
初始化接口
release()
资源释放接口
设置核身过程中的核身关键动作的回调
启动活体核身检测的接口
获得当前 SDK 的版本号

init()

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

release()

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

setAuthEventCallBack()

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

startHuiYanAuth()

public static void startHuiYanAuth(AuthConfig authConfig, HuiYanAuthResultListener listener)
功能介绍:启动活体核身检测的接口。
传入参数:
参数类型
参数名称
参数含义
authConfig
启动活体核身的参数
listener
接受活体核身检测的结果回调

getVersion()

public static String getVersion()
功能介绍:获取当前版本慧眼 SDK 的版本号。


AuthConfig

AuthConfig 是在启动慧眼 SDK 时的配置实体类,主要包含了以下属性。
类型
名称
含义
默认值
String
sdkToken
此次人脸核身使用的 Token
""
String
authLicense
客户申请的用户核身授权的 License 文件名
long
authTimeOutMs
设置活体检测的超时时间
30000毫秒(30秒)
encryptMode
使用的加密模式
HuiYanEncryptMode.AES
String
useCustomerModelPath
客户自定义的模型文件夹地址
空(如果为空需要依赖模型 aar)
customerConfig
客户自定义的一些内容
null
languageStyle
核身页面显示的语言
LanguageStyle.SIMPLIFIED_CHINESE(简体中文)
boolean
isOpenAudio
是否开启语音播报
默认 false,如果开启需要同时依赖 huiyanaudios_x.x.x_release.aar 资源
boolean
isLandMode
是否使用横屏模式
默认 false

HuiYanEncryptMode

慧眼核身支持的加密模式。
HuiYanEncryptMode 类型
含义
HuiYanEncryptMode.AES
AES 加密算法
HuiYanEncryptMode.SM4
SM4国密加密

CustomerConfig

类型
名称
含义
默认值
boolean
isHiddenResultPage
设置是否需要隐藏核身结果页(隐藏的话,则不会显示结果页,直接进行回调)
false
boolean
isShowErrorDialog
设置是否显示错误的 dialog
true
boolean
isHiddenProtocolPage
设置是否隐藏协议展示的页面
false
boolean
useLocalPageConfig
是否以客户端的界面配置为准
false
boolean
isShowCountdown
设置是否显示倒计时
true
boolean
isTransparentStatusBar
核身页面状态栏是否透明
false
boolean
useDeepColorStatusBarIcon
核身页面是否使用深色的状态栏图标
false
String
authLayoutResId
核身页面自定义的布局 resID
-1
String
landAuthLayoutResId
核身页面自定义的横屏布局 resID
-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
mainActivityThemeId
核身界面主题,不调整使用-1
-1
int
statusBarColor
核身界面状态栏颜色,不调整使用-1
-1
int
transparentStatusBarMoveHeight
透明状态栏以后向下移动的距离,不调整使用15
15
boolean
isRecordVideo
是否录制审核视频
true
recordVideoParam
录制审核视频相关的参数
boolean
isCutRecordVideo
是否裁剪审核视频
false
long
cutVideoDurationMs
裁剪审核视频的时长,默认为2s,取值得范围是2~6s
2000

LanguageStyle

核身界面模式显示的语言类型,当前主要包括了,自动(跟随系统)、英文与简体中文。
类型
含义
LanguageStyle.AUTO
自动根据系统语言
LanguageStyle.ENGLISH
英语
LanguageStyle.SIMPLIFIED_CHINESE
简体中文
LanguageStyle.TRADITIONAL_CHINESE
繁体中文


HuiYanAuthResultListener

核身结果的回调类。
public interface HuiYanAuthResultListener {

/**
* 核身通过
*
* @param faceIdToken 本次核身使用的faceIdToken
*/
void onSuccess(String faceIdToken);

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

HuiYanAuthEventCallBack

用来 HuiYanAuthTipsEvent 为慧眼在核身过程中的关键事件 Tips 的回调。HuiYanAuthEvent 为慧眼在核身过程中的关键事件的回调监听核身过程中的关键事件的回调,以及如果需要使用自定义布局的 UI 绑定可以参考 事件绑定
/**
* 慧眼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();

}
HuiYanAuthTipsEvent 为慧眼在核身过程中的关键事件 Tips 的回调。
HuiYanAuthEvent 为慧眼在核身过程中的关键事件的回调。

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_CHINE
请勿遮挡下巴
NO_NOSE
请勿遮挡鼻子
NO_LEFT_EYE
请勿遮挡左眼
NO_RIGHT_EYE
请勿遮挡右眼
POSE_KEEP
请保持姿势不变
POSE_CLOSER
请靠近一点
POSE_FARTHER
请离远一点
POSE_OPEN_EYE
请勿闭眼
TOO_MANY_FACE
请确保框内只有一张人脸
VERIFY_POSE_KEEP
验证中,请保持姿势不变

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
本地检测完成

RecordVideoParam

类型
名称
含义
默认值
int
bitRate
码率
500000
int
frameRate
帧率
20

错误码

这里是 SDK 在失败回调中的错误码,目前慧眼公有云(增强版)SDK 包含的错误码与其含义如下:
错误码
错误码含义
210
网络连接异常
211
本地初始化 SDK 时,检测失败,常见异常不存在 license 文件或者 license 过期
212
用户主动取消核身流程
213
内部异常
214
勿在核身的过程中切换应用
215
打开摄像头过程中发生异常
216
先调用 init 方法后再启动 SDK
222
本地核身动作检测超时
223
准备过程超时(启动摄像头到第一次检测到人脸的时间超时
224
摄像头权限检测失败
228
SDK 内部发生错误,详情参见对应的 error msg
230
设置旋转角度失败的错误码
231
图灵盾 SDK 授权检测异常
232
SDK 入参校验失败
233
后端 API 接口报错,详情参见 error msg
251
反光验证过程中移出检测框异常
252
模型加载异常请稍后重试



自定义 UI

自定义布局

慧眼 SDK 支持自定义 UI,主要是通过 CustomerConfig 配置参数实现,通过传入 Layout resId 的方式可自定义 UI 布局,默认核身界面的布局。
使用方式大致如下:
AuthConfig authConfig = new AuthConfig();
CustomerConfig customerConfig = new CustomerConfig();
// 传入自定义的layout id
customerConfig.setAuthLayoutResId(R.layout.demo_huiyan_fragment_authing);
authConfig.setCustomerConfig(customerConfig);
下图所示属于默认布局:



默认布局如上图所示,图中的所有控件的位置均可以通过修改布局 Layout.xml 进行修改。具体的可以参考 demo 中的 demo_huiyan_fragment_authing.xml 文件。
注意
需要值得注意的是: demo_huiyan_fragment_authing.xml 中的 View 类型以及对应的 android:id 由于参与的界面事件绑定,请不要修改
这里提供默认的布局如下:
<?xml version="1.0" encoding="utf-8"?>
<com.tencent.cloud.huiyan.view.HuiYanReflectLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:id="@+id/txy_auth_layout_bg"
android:layout_width="match_parent"
android:layout_height="match_parent">

<!-- 取消按钮 -->
<TextView
android:id="@+id/txy_cancel_txt_btn"
android:text="@string/txy_cancel"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_alignParentStart="true"
android:layout_alignParentTop="true"
android:textColor="@color/txy_black"
android:textSize="@dimen/txy_tips_text_size_en"
android:layout_marginTop="@dimen/txy_title_margin_top"
android:layout_marginStart="@dimen/txy_protocol_margin_size" />

<!-- 倒计时的显示 -->
<TextView
android:id="@+id/txy_count_down_txt_view"
android:text="@string/txy_count_down_txt"
android:layout_alignParentTop="true"
android:layout_alignParentEnd="true"
android:textSize="@dimen/txy_tips_text_size_en"
android:textColor="@color/txy_black"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_marginTop="@dimen/txy_title_margin_top"
android:layout_marginEnd="@dimen/txy_protocol_margin_size"
android:visibility="gone" />


<FrameLayout
android:id="@+id/txy_core_auth_view_layout"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:layout_marginTop="@dimen/txy_core_auth_view_margin_top">

<!-- 摄像头预览界面框 720P的话,代码中height会自定乘以1.3 -->
<com.tencent.cloud.huiyansdk.turing.view.CameraDateGatherView
android:id="@+id/txy_camera_gather_view"
android:layout_gravity="center"
android:layout_width="@dimen/txy_auth_head_size"
android:layout_height="@dimen/txy_auth_head_default_height"
android:background="@android:color/transparent" />

<!-- 通用背景,待竖线的圆环 -->
<com.tencent.cloud.huiyan.view.CommonAuthBackView
android:id="@+id/txy_auth_common_background_views"
android:layout_gravity="center"
android:layout_width="@dimen/txy_auth_circle_size"
android:layout_height="@dimen/txy_auth_circle_size" />
<!-- 展示的默认头像图片 -->
<ImageView
android:id="@+id/txy_camera_prepare_img"
android:src="@drawable/txy_prepare_face_head_white"
android:layout_gravity="center"
android:layout_width="@dimen/txy_auth_head_size"
android:layout_height="@dimen/txy_auth_head_size" />

<!-- 前台的动画View -->
<com.tencent.cloud.huiyan.view.LoadingFrontAnimatorView
android:id="@+id/txy_auth_loading_front_animator_view"
android:layout_gravity="center"
android:visibility="gone"
android:layout_width="@dimen/txy_auth_head_size"
android:layout_height="@dimen/txy_auth_head_size" />
</FrameLayout>

<!-- 提示信息的展示界面 -->
<TextView
android:id="@+id/txy_auth_feed_back_txt"
android:layout_below="@id/txy_cancel_txt_btn"
android:layout_centerHorizontal="true"
android:textColor="@color/txy_black"
android:layout_marginTop="@dimen/txy_auth_tips_margin_top"
android:text="@string/txy_face_preparing3"
android:textSize="@dimen/txy_tips_text_size"
android:paddingHorizontal="@dimen/txy_title_margin_top"
android:gravity="center_horizontal"
android:layout_width="wrap_content"
android:layout_height="wrap_content" />

<!-- 额外的警告信息的提示控件 -->
<TextView
android:id="@+id/txy_auth_feed_back_extra_tip_txt"
android:textSize="@dimen/txy_tips_extra_text_size"
android:textColor="@color/txy_black"
android:layout_width="match_parent"
android:layout_height="wrap_content"
android:gravity="center_horizontal"
android:paddingHorizontal="@dimen/txy_title_margin_top"
android:layout_below="@id/txy_core_auth_view_layout"
android:layout_marginTop="20dp" />

</com.tencent.cloud.huiyan.view.HuiYanReflectLayout>

自定义布局的事件绑定

上一节介绍了如何进行自定义 UI 布局,本节主要介绍如何对自定义 UI 布局里新增的控件进行事件绑定,以满足您在使用阶段的各项需求。
当核身界面被创建时,HuiYanAuthEventCallBack 的 onMainViewCreate(View authView) 被调用。当核身界面即将销毁的时候,会回调 onMainViewDestroy() 方法,您可以在对应的生命周期中自定义处理逻辑。
// 这里设置慧眼关键事件的回调监听
HuiYanAuth.setAuthEventCallBack(new HuiYanAuthEventCallBack() {
@Override
public void onAuthTipsEvent(HuiYanAuthTipsEvent tipsEvent) {
Log.e(TAG, "current is : " + tipsEvent);
}

@Override
public void onMainViewCreate(View authView) {
if (authView == null) {
return;
}
// 获取自定义添加的控件,并且注册自定义的事件
Button findBtn = authView.findViewById(R.id.add_view_offer_button);
if (findBtn != null) {
findBtn.setOnClickListener(view -> {
Log.e(TAG, "click test button!");
});
}
}

@Override
public void onMainViewDestroy() {
Log.e(TAG, "onMainViewDestroy");
}
});
根据 onMainViewCreate 的回调与 onMainViewDestroy 的回调方式,您可以完成任意对应您新增 UI 控件的事件绑定,以实现对应效果。



自定义提示与增加语言

自定义提示
如果您需要修改提示语,或者新增其他的语言文件的话,可以按照下面的方式去实现。慧眼 SDK 会提供一个翻译文件 hy_customer_string.xml 里面包括了所有慧眼 SDK 对外可以进行修改的配置文字文件。
1. 打开主 module(集成慧眼 SDK 的 module)工程。
2. hy_customer_string.xml 添加到对应的语言文件夹下。
3. 修改其中需要自定义的文字内容即可。
4. 打包以后,您修改的内容会自动覆盖原有的内容。




新增语言

新增语言的文件,则需要执行以下两步就可以实现:
1. 在主 module(集成慧眼 SDK 的 module)工程里新增对应语言文件夹。
2. hy_customer_string.xml 拷贝到该语言文件夹下,并修改对应的 value 内容。



3. 在代码里指定对应的语言码即可(以泰文为例)。
authConfig.setLanguageStyle(LanguageStyle.CUSTOMIZE_LANGUAGE);
authConfig.setLanguageCode("th-TH");
HuiYanAuth.startHuiYanAuth(authConfig, new HuiYanAuthResultListener());

Android 语言码

这里提供一下 Android 的部分语言码,以供参考。
语言码
对应使用的国家或地区
af-ZA
公用荷兰语 - 南非
sq-AL
阿尔巴尼亚 - 阿尔巴尼亚
ar-DZ
阿拉伯语 - 阿尔及利亚
ar-BH
阿拉伯语 - 巴林
ar-EG
阿拉伯语 - 埃及
ar-IQ
阿拉伯语 - 伊拉克
ar-JO
阿拉伯语 - 约旦
ar-KW
阿拉伯语 - 科威特
ar-LB
阿拉伯语 - 黎巴嫩
ar-LY
阿拉伯语 - 利比亚
ar-MA
阿拉伯语 - 摩洛哥
ar-OM
阿拉伯语 - 阿曼
ar-QA
阿拉伯语 - 卡塔尔
eu-ES
巴斯克 - 巴斯克
bg-BG
保加利亚 - 保加利亚
ca-ES
嘉泰罗尼亚 - 嘉泰罗尼亚
zh-HK
华语 - 中国香港
zh-MO
华语 - 中国澳门
zh-CN
华语 - 中国
zh-SG
华语 - 新加坡
zh-TW
华语 - 中国台湾
zh-CHS
华语 (简体化)
zh-CHT
华语 (传统的)
hr-HR
克罗埃西亚 - 克罗埃西亚
cs-CZ
捷克 - 捷克
da-DK
丹麦文 - 丹麦
div-MV
Dhivehi - 马尔代夫
nl-BE
荷兰 - 比利时
nl-NL
荷兰 - 荷兰
en-AU
英国 - 澳洲
en-ZA
英国 - 南非
en-PH
英国 - 菲律宾共和国
en-NZ
英国 - 新西兰
en-GB
英国 - 英国
en-US
英国 - 美国
fa-IR
波斯语 - 伊朗王国
fi-FI
芬兰语 - 芬兰
fr-FR
法国 - 法国
fr-BE
法国 - 比利时
fr-MC
法国 - 摩纳哥
fr-CH
法国 - 瑞士
gl-ES
加利西亚 - 加利西亚
ka-GE
格鲁吉亚州 - 格鲁吉亚州
de-DE
德国 - 德国
de-LU
德国 - 卢森堡
de-CH
德国 - 瑞士
el-GR
希腊 - 希腊
gu-IN
Gujarati - 印度
he-IL
希伯来 - 以色列
hi-IN
北印度语 - 印度
hu-HU
匈牙利 - 匈牙利
is-IS
冰岛 - 冰岛
it-IT
意大利 - 意大利
ja-JP
日本 - 日本
kk-KZ
Kazakh - 哈萨克
kn-IN
卡纳达语 - 印度
ko-KR
韩国 - 韩国
lv-LV
拉脱维亚 - 拉脱维亚
lt-LT
立陶宛 - 立陶宛
ms-BN
马来 - 汶莱
ms-MY
马来 - 马来西亚
mr-IN
马拉地语 - 印度
mn-MN
蒙古 - 蒙古
nn-NO
挪威 (Nynorsk) - 挪威
pl-PL
波兰 - 波兰
pt-BR
葡萄牙 - 巴西
pt-PT
葡萄牙 - 葡萄牙
ro-RO
罗马尼亚语 - 罗马尼亚
sa-IN
梵文 - 印度
ru-RU
俄国 - 俄国
sk-SK
斯洛伐克 - 斯洛伐克
es-AR
西班牙 - 阿根廷
es-ES
西班牙 - 西班牙
sv-SE
瑞典 - 瑞典
th-TH
泰国 - 泰国
tr-TR
土耳其语 - 土耳其
uk-UA
乌克兰 - 乌克兰
ur-PK
Urdu - 巴基斯坦
vi-VN
越南 - 越南