Android 端慧眼 SDK 主要涉及的类主要包含 HuiYanAuth、AuthConfig、HuiYanAuthResultListener、CreateFaceIdToken 以及 PageColorStyle,下面对其支持的 API 做出详细说明。
HuiYanAuth
HuiYanAuth 为慧眼 SDK 的对外接口类,主要逻辑也都是调用此类完成。
API | 功能描述 |
初始化接口 | |
资源释放接口 | |
设置主动获取客户FaceIdToken的接口 | |
设置核身过程中的核身关键动作的回调 | |
启动活体核身检测的接口 | |
设置公有云使用的回调函数接口 |
init()
public static void init(Context context)
功能介绍:慧眼 SDK 的初始化接口。
传入参数:
参数类型 | 参数名称 | 参数含义 |
Context | context | App 的上下文信息 |
release()
public static void release()
功能介绍:慧眼 SDK 资源释放的接口。
setFaceIdTokenCreateFunction()
public static void setFaceIdTokenCreateFunction(CreateFaceIdToken createFunction)
功能介绍:设置主动获取客户 FaceIdToken 的接口。
注意:也可将获取到的 FaceIdToken 通过 AuthConfig 传入 SDK,推荐使用 AuthConfig 直接传入的方式,示例如下:
AuthConfig authConfig = new AuthConfig();authConfig.setSdkToken(token);startHuiYanAuth(authConfig, callback);
传入参数:
参数类型 | 参数名称 | 参数含义 |
createFunction | 主动获取客户 FaceIdToken 的回调 |
setAuthEventCallBack()
public static void setAuthEventCallBack(HuiYanAuthEventCallBack authEventCallBack)
功能介绍:用来注册核身过程中的核身关键动作的回调。
传入参数:
参数类型 | 参数名称 | 参数含义 |
authEventCallBack | 本地核身的关键事件回调 |
startHuiYanAuth()
public static void startHuiYanAuth(AuthConfig authConfig, HuiYanAuthResultListener listener)
功能介绍:启动活体核身检测的接口。
传入参数:
参数类型 | 参数名称 | 参数含义 |
authConfig | 启动活体核身的参数 | |
listener | 接受活体核身检测的结果回调 |
setHuiYanPublicEventCallBack()
public static void setHuiYanPublicEventCallBack(HuiYanPublicEventCallBack huiYanPublicEventCallBack)
功能介绍:公有云 SDK 对外关键步骤的回调设置接口
传入参数:
参数类型 | 参数名称 | 参数含义 |
huiYanPublicEventCallBack | 公有云关键步骤的对外回调 |
AuthConfig
AuthConfig是在启动慧眼SDK时的配置实体类,主要包含了以下属性。
类型 | 名称 | 含义 | 默认值 |
String | sdkToken | 此次人脸核身使用的Token | "" |
String | authLicense | 客户申请的用户核审授权的License文件名 | 空 |
long | authTimeOutMs | 设置活体检测的超时时间 | 10000毫秒(10秒) |
PageColorStyle | pageColorStyle | 此次人脸核身检测的配色 | PageColorStyle.Light |
String | useCustomerModelPath | 客户自定义的模型文件夹地址 | 空(如果为空需要依赖模型 aar) |
customerConfig | 客户自定义的一些内容 | null | |
languageStyle | 核身页面显示的语言 | LanguageStyle.SIMPLIFIED_CHINESE(简体中文) | |
boolean | isOpenLog | 是否记录关键log | true |
boolean | openFullLog | 是否记录完整日志 | false |
PageColorStyle
默认核身界面默认配色的枚举类,当前主要包括了两种配色,白色系与黑暗色系。
PageColorStyle类型 | 含义 |
PageColorStyle.Light | 亮色调配色 |
PageColorStyle.Dark | 暗色调配色 |
CustomerConfig
类型 | 名称 | 含义 | 默认值 |
String | authTips | 核身页面客户自定义的提示信息(如有敏感信息则不会显示) | 空 |
int | authTipsTextColor | 核身页面客户自定义的提示信息的颜色(0xFFFFFF类型) | -1 |
boolean | isHiddenResultRage | 设置是否需要隐藏核身结果页(隐藏的话,则不会显示结果页,直接进行回调) | false |
boolean | isShowErrorDialog | 设置是否显示错误的dialog | true |
boolean | isHiddenProtocolPage | 设置是否隐藏协议展示的页面 | 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 |
// Main Activity的主题private int mainActivityThemeId = ConstUtils.RES_ERROR_ID;// 状态栏的颜色修改private int statusBarColor = ConstUtils.RES_ERROR_ID;// 是否透明状态栏private boolean isTransparentStatusBar = false;// 透明状态栏以后向下移动的距离private int transparentStatusBarMoveHeight = ConstUtils.STATUS_BAR_MOVE_HEIGHT;// 是否使用深色的状态栏图标private boolean useDeepColorStatusBarIcon = false;
LanguageStyle
核身界面模式显示的语言类型,当前主要包括了,自动(跟随系统)、英文与简体中文。
类型 | 含义 |
LanguageStyle.AUTO | 自动根据系统语言 |
LanguageStyle.ENGLISH | 英语 |
LanguageStyle.SIMPLIFIED_CHINESE | 简体中文 |
LanguageStyle.TRADITIONAL_CHINESE | 繁体中文 |
CreateFaceIdToken
用于提供给客户使用的获取 FaceIdToken 的接口类,客户需要返回客户获取到的 FaceIdToken 的值。
HuiYanAuth.setFaceIdTokenCreateFunction(new CreateFaceIdToken() {@Overridepublic String getCustomerFaceIdToken() {// 补充获取FaceIdToken的逻辑,返回客户获得到的faceIdTokenreturn currentToken;}});
注意:也可将获取到的 FaceIdToken 通过 AuthConfig 传入 SDK,推荐使用 AuthConfig 直接传入的方式,示例如下:
AuthConfig authConfig = new AuthConfig();authConfig.setSdkToken(token);startHuiYanAuth(authConfig, callback);
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
/*** 慧眼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();}
HuiYanPublicEventCallBack
/*** 慧眼公有云主要事件的回调*/public interface HuiYanPublicEventCallBack {/*** 回调慧眼SDK的主要事件(回调的事件在一个独立线程里,不要直接做UI操作)** @param publicEvent {"publicEvent":"GET_LIVE_TYPE","platform":2}*/void mainAuthEvent(String publicEvent);}
HuiYanPublicEvent
公有云关键事件的枚举类型。
类型 | 含义 |
HuiYanPublicEvent.GET_LIVE_TYPE | 启动拉取光线序列 |
HuiYanPublicEvent.START_CHECK | 本地识别开始 |
HuiYanPublicEvent.LOCAL_CHECK_OVER | 本地识别结束准备开启网络请求 |
HuiYanPublicEvent.GET_NET_RESULT | 得到网络请求结果,并且需要结果为success才会回调 |
自定义UI
自定义布局
使用方式大致如下:
AuthConfig authConfig = new AuthConfig();CustomerConfig customerConfig = new CustomerConfig();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.could.huiyansdk.view.HuiYanReflectLayout xmlns:android="http://schemas.android.com/apk/res/android"xmlns:app="http://schemas.android.com/apk/res-auto"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"app:layout_constraintStart_toStartOf="parent"app:layout_constraintTop_toTopOf="parent"android:textColor="@color/txy_black"android:textSize="16sp"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"app:layout_constraintTop_toTopOf="parent"app:layout_constraintEnd_toEndOf="parent"android:textSize="16sp"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_marginRight="@dimen/txy_protocol_margin_size"android:visibility="gone"/><!-- 摄像头预览界面框 720P的话,代码中height会自定乘以1.3 --><com.tencent.could.huiyansdk.view.CameraDateGatherViewandroid:id="@+id/txy_camera_gather_view"android:layout_width="@dimen/txy_auth_head_size"android:layout_height="258dp"android:background="@android:color/transparent"android:layout_marginBottom="@dimen/txy_auth_view_move"app:layout_constraintBottom_toBottomOf="parent"app:layout_constraintEnd_toEndOf="parent"app:layout_constraintStart_toStartOf="parent"app:layout_constraintTop_toTopOf="parent" /><!-- 通用背景,待竖线的圆环 --><com.tencent.could.huiyansdk.view.CommonAuthBackViewandroid:id="@+id/txy_auth_common_background_views"android:layout_width="230dp"android:layout_height="230dp"android:layout_marginBottom="@dimen/txy_auth_view_move"app:layout_constraintBottom_toBottomOf="parent"app:layout_constraintEnd_toEndOf="parent"app:layout_constraintStart_toStartOf="parent"app:layout_constraintTop_toTopOf="parent"/><!-- 展示的头像图片 --><ImageViewandroid:id="@+id/txy_camera_prepare_img"app:srcCompat="@drawable/txy_prepare_face_head_white"android:layout_width="@dimen/txy_auth_head_size"android:layout_height="@dimen/txy_auth_head_size"android:layout_marginBottom="@dimen/txy_auth_view_move"app:layout_constraintTop_toTopOf="parent"app:layout_constraintBottom_toBottomOf="parent"app:layout_constraintEnd_toEndOf="parent"app:layout_constraintStart_toStartOf="parent" /><!-- 前台的动画View --><com.tencent.could.huiyansdk.view.LoadingFrontAnimatorViewandroid:id="@+id/txy_auth_loading_front_animator_view"android:visibility="gone"app:layout_constraintTop_toTopOf="parent"app:layout_constraintBottom_toBottomOf="parent"app:layout_constraintEnd_toEndOf="parent"app:layout_constraintStart_toStartOf="parent"android:layout_marginBottom="@dimen/txy_auth_view_move"android:layout_width="@dimen/txy_auth_head_size"android:layout_height="@dimen/txy_auth_head_size"/><!-- 提示信息的展示界面 --><TextViewandroid:id="@+id/txy_auth_feed_back_txt"app:layout_constraintTop_toBottomOf="@id/txy_auth_common_background_views"app:layout_constraintStart_toStartOf="parent"app:layout_constraintEnd_toEndOf="parent"android:textColor="@color/txy_black"android:layout_marginTop="@dimen/txy_protocol_line_space"android:text="@string/txy_face_preparing3"android:textSize="18sp"android:layout_width="wrap_content"android:layout_height="wrap_content"/><!-- 额外的警告信息的提示控件 --><TextViewandroid:id="@+id/txy_auth_feed_back_extra_tip_txt"android:textSize="14sp"android:textColor="@color/txy_black"android:layout_width="match_parent"android:layout_height="wrap_content"android:gravity="center_horizontal"app:layout_constraintStart_toStartOf="parent"app:layout_constraintEnd_toEndOf="parent"android:layout_marginTop="20dp"app:layout_constraintTop_toBottomOf="@id/txy_auth_feed_back_txt"/><!-- 核身的内容提示 --><TextViewandroid:id="@+id/txy_auth_tips_txt"android:textSize="14sp"android:textColor="@color/txy_black"android:paddingHorizontal="25dp"android:layout_marginHorizontal="25dp"android:layout_marginBottom="35dp"app:layout_constraintBottom_toBottomOf="parent"app:layout_constraintStart_toStartOf="parent"app:layout_constraintEnd_toEndOf="parent"android:layout_width="wrap_content"android:layout_height="wrap_content"/></com.tencent.could.huiyansdk.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 | 越南 -越南 |
错误码
这里是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_CAMERA_PERMISSION_ERROR | 215 | 获取摄像头过程中发生异常 |
HY_INIT_SDK_ERROR | 216 | 未调用init()方法,直接调用了 |
HY_VERIFY_LOCAL_ERROR | 217 | 本地人脸检测失败 |
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_ACTION_REFLECTIVE_SDK_ERROR | 228 | 内部算法本地检测识别失败 |