Android 端慧眼 SDK 主要涉及的类主要包含 HuiYanAuth、AuthConfig、HuiYanAuthResultListener、CreateFaceIdToken 以及 PageColorStyle,下面对其支持的 API 做出详细说明。
HuiYanAuth
HuiYanAuth 为慧眼 SDK 的对外接口类,主要逻辑也都是调用此类完成。
API | 功能描述 |
初始化接口 | |
资源释放接口 | |
设置核身过程中的核身关键动作的回调 | |
启动活体核身检测的接口 | |
获得当前 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
对应的事件类型与含义:
事件枚举 | 事件含义 |
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
自定义布局
使用方式大致如下:
AuthConfig authConfig = new AuthConfig();CustomerConfig customerConfig = new CustomerConfig();// 传入自定义的layout idcustomerConfig.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"><!-- 取消按钮 --><TextViewandroid: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" /><!-- 倒计时的显示 --><TextViewandroid: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" /><FrameLayoutandroid: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.CameraDateGatherViewandroid: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.CommonAuthBackViewandroid: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" /><!-- 展示的默认头像图片 --><ImageViewandroid: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.LoadingFrontAnimatorViewandroid: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><!-- 提示信息的展示界面 --><TextViewandroid: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" /><!-- 额外的警告信息的提示控件 --><TextViewandroid: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() {@Overridepublic void onAuthTipsEvent(HuiYanAuthTipsEvent tipsEvent) {Log.e(TAG, "current is : " + tipsEvent);}@Overridepublic 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!");});}}@Overridepublic 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 | 越南 - 越南 |