有奖捉虫:办公协同&微信生态&物联网文档专题 HOT
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() {
@Override
public String getCustomerFaceIdToken() {
// 补充获取FaceIdToken的逻辑,返回客户获得到的faceIdToken
return 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

用来监听核身过程中的关键事件的回调,以及如果需要使用自定义布局的 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();

}

HuiYanPublicEventCallBack

用来监听公有云关键事件的回调,HuiYanPublicEvent关键事件的枚举类型
/**
* 慧眼公有云主要事件的回调
*/
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

自定义布局

慧眼 SDK 支持自定义 UI,主要是通过 CustomerConfig 配置参数实现,通过传入 Layout resId 的方式可自定义 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">

<!-- 取消按钮 -->
<TextView
android: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"
/>

<!-- 倒计时的显示控件 -->
<TextView
android: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.CameraDateGatherView
android: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.CommonAuthBackView
android: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"
/>

<!-- 展示的头像图片 -->
<ImageView
android: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.LoadingFrontAnimatorView
android: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"
/>

<!-- 提示信息的展示界面 -->
<TextView
android: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"/>

<!-- 额外的警告信息的提示控件 -->
<TextView
android: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"
/>

<!-- 核身的内容提示 -->
<TextView
android: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() {
@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
巴斯克 -巴斯克
be-BY
Belarusian-白俄罗斯
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-CA
英国 -加拿大
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
内部算法本地检测识别失败