类名 | 类型 | 说明 |
HuiYanOsApi | 接口类 | SDK 的主入口,提供初始化、启动核身、资源释放等核心方法 |
HuiYanOsConfig | 配置类 | 启动 SDK 时的参数配置,包含 License、超时设置、UI 定制等 |
HuiYanOsAuthResult | 结果类 | 核身成功后的结果对象,包含 Token 等信息 |
接口名 | 说明 |
HuiYanOsAuthCallBack | 核身流程结果回调,包含成功和失败两个方法 |
HuiYanAuthEventCallBack | 核身过程中的关键事件回调,用于监听动作检测等事件 |
枚举类 | 说明 |
PageColorStyle | 核身界面配色(亮色/暗色) |
LanguageStyle | 语言类型(中文/英文/跟随系统等) |
VideoSize | 核身视频分辨率(480P/720P) |
CameraZoom | 后置摄像头缩放级别(1x/1.5x/2x) |
FaceAngleValidation | 人脸角度检测严格等级(宽松/中等/严格) |
FaceOcclusionLevel | 人脸遮挡检测等级(严格/中等/宽松/通过) |
类名 | 说明 |
HuiYanAuthTipsEvent | 核身过程中的 Tips 提示事件(如"请张嘴"、"请靠近"等) |
HuiYanAuthEvent | 核身过程中的关键动作事件(如开始检测、检测完成等) |
类名 | 说明 |
AuthUiConfig | 核身页面 UI 自定义配置,包含颜色、字体、布局等参数 |
API | 功能描述 |
初始化接口 | |
资源释放接口 | |
设置核身过程中的核身关键动作的回调 | |
精简流程的海外核身接口,只需调用此接口即可完成整体核身流程。 | |
获取设备元数据(用于向云 API 换取 SdkToken) | |
获取当前 SDK 的版本号 |
public static void init(Context context)
参数类型 | 参数名称 | 参数含义 |
Context | context | App 的上下文信息 |
public static void release()
public static void setAuthEventCallBack(HuiYanAuthEventCallBack huiYanAuthEventCallBack)
参数类型 | 参数名称 | 参数含义 |
huiYanAuthEventCallback | 核身关键动作的回调 |
public static void startHuiYanAuth(final String startToken, final HuiYanOsConfig startConfig, HuiYanOsAuthCallBack authCallBack)
参数类型 | 参数名称 | 参数含义 |
String | startToken | 从服务器兑换来启动核身使用的业务 Token |
startConfig | 配置的参数 | |
authCallback | 活体结果的回调 |
public static String createMetaData()
init() 完成初始化。类型 | 名称 | 参数含义 |
String | metaData | 加密后的设备元数据字符串,接入方无需关心具体内容,作为 MetaData 入参透传给云 API 即可;采集/加密失败时返回空字符串 |
ServerParamInfo 配置串,接入方需将其透传给 SDK(见 HuiYanOsConfig.serverParamInfo)。// 1. 获取设备元数据String metaData = HuiYanOsApi.createMetaData();// 2. 向云 API 申请 SdkToken(透传 metaData)// 云 API 返回 SdkToken + ServerParamInfo// 3. 启动核身(透传 serverParamInfo)HuiYanOsConfig config = new HuiYanOsConfig();config.setServerParamInfo(serverParamInfo);HuiYanOsApi.startHuiYanAuth(sdkToken, config, authCallBack);
public static String getVersion()
类型 | 名称 | 参数含义 |
String | version | SDK 当前的版本号 |
类型 | 名称 | 含义 | 默认值 |
pageColorStyle | 此次人脸核身检测的配色 | PageColorStyle.Light | |
String | authLicense | 客户申请的用户核身授权的 License 文件名 | 空 |
String | riskLicense | 客户申请的设备风控授权的 License 文件名,增强版和 Plus 版能力需要传入该路径 | 空 |
long | authTimeOutMs | 设置活体检测的超时时间 | 10000毫秒(10秒) |
boolean | openCheckRiskMode | 是否开启风控检测的开关,增强版和 Plus 版能力需要开启该字段 | false |
boolean | isDeleteVideoCache | 是否删除核身视频的本地缓存 | true |
boolean | isShowGuidePage | 是否打开核身的引导页 | true |
languageStyle | 语言类型 | 跟随系统语言 | |
String | languageCode | 语言码(见 Android 自定义能力文档),配合 languageStyle 一起使用 | 空 |
String[] | backupIPs | 备用 IP 列表 | 空 |
String | backUpHost | 备用域名 | 空 |
authUiConfig | UI 配置项 | 空 | |
boolean | isUseBackCamera | 是否开启后置摄像头(后置摄像头只有在纯动作或者静默时生效,否则包含反光阶段的话 SDK 会报错 HY_USE_BACK_CAMERA_WITH_REFLECTIVE_ERROR 227) | false |
float | smallFaceRatioThreshold | 最小人脸占比的阈值,小于该阈值会提示靠近一些 | 0.5f |
float | bigFaceRatioThreshold | 最大人脸占比的阈值,大于该阈值会提示靠远一些 | 0.8f |
zoomLevel | 后置摄像头缩放级别 | CameraZoom.ZOOM_1X | |
boolean | isOpenBOTCheck | 是否开启 Bot 模式 | false |
long | longCheckTimeoutMs | 开启 Bot 模式,Bot 阶段的超时时间 | 30000毫秒(30秒) |
boolean | showPrivacyPolicyDialog | 是否默认打开合规弹窗(设置 false 可以关闭) | true |
boolean | disableSystemRecordScreen | 是否禁止核身界面系统截屏或者录屏 | false |
boolean | isOtherActionCheckMouthOpen | 其他动作阶段是否启用额外嘴巴张开检测 | false |
faceAngleValidation | 人脸角度检测等级,默认为宽松模式 | FaceAngleValidation.LevelLoose | |
faceOcclusionLevel | 人脸遮挡检测等级,默认为严格模式 | FaceOcclusionLevel.STRICT | |
boolean | isAllowCancelWaiting | 是否允许等待结果时通过 back 键取消 | false |
boolean | isEntireHighlight | 是否在进入活体时立即将屏幕亮度调至最大,流程结束后自动恢复。 | false |
String | modelPath | 客户自定义的模型资源地址 | 空 |
boolean | isShowErrorPopup | 是否启用错误重试弹窗 | false |
int | compareRequestTimeOutMs | 活体比对请求的超时时间(单位:毫秒) | 60000 |
int | compareRequestAttempts | 活体比对请求的尝试次数,最小值为1 | 3 |
int | lightRequestTimeOutMs | 拉取光线序列请求的超时时间(单位:毫秒) | 30000 |
int | lightRequestAttempts | 拉取光线序列请求的尝试次数,最小值为1 | 3 |
String | serverParamInfo | 云 API 在申请 SdkToken 时一并返回的加密配置字符串(必传)。传入空字符串或内容异常时 SDK 会报错 | 空 |
boolean | isOpenAudio | 是否开启核身过程中的语音播报(动作提示、异常反馈等)。开启后还需引入 huiyanaudio-oversea_1.x.x_release.aar 语音资源包,否则设置为 true 也不会有声音,详见 开启语音播报 | true |
boolean | isShowGuideAnimation | 是否展示核身前的引导动画(例如提示用户对准人脸的动效) | true |
huiyanaudio-oversea_1.x.x_release.aarassets/audio/*.m4a 音频文件,不含 Java 类),接入方式与其他 aar 一致,将其放入 libs 目录并在 build.gradle 中声明依赖:├── codedemo│ ├── libs│ │ ├── huiyanaudio-oversea_1.x.x_release.aar│ │ └── ...
dependencies {// 语音播报资源包(可选)implementation files("libs/huiyanaudio-oversea_1.x.x_release.aar")}
isOpenAudioHuiYanOsConfig config = new HuiYanOsConfig();// 开启语音播报(默认已开启,可显式设置以便阅读)config.setOpenAudio(true);// 如需在核身界面隐藏"喇叭/静音"切换按钮,可关闭config.getAuthUiConfig().setShowSoundToggleBtn(false);
isOpenAudio = true 但未引入语音资源包 aar:SDK 内部加载语音资源失败会静默降级,核身流程仍可正常进行,只是没有声音。isOpenAudio = false:SDK 会直接跳过加载语音资源,不依赖也不加载 aar。PageColorStyle 类型 | 含义 |
PageColorStyle.Light | 亮色调配色 |
PageColorStyle.Dark | 暗色调配色 |
LanguageStyle 类型 | 含义 |
LanguageStyle.AUTO | 跟随系统 |
LanguageStyle.ENGLISH | 英语 |
LanguageStyle.SIMPLIFIED_CHINESE | 简体中文 |
LanguageStyle.TRADITIONAL_CHINESE | 繁体中文 |
LanguageStyle.CUSTOMIZE_LANGUAGE | 自定义语言 |
类型 | 名称 | 含义 | 默认值 |
videoSize | 核身过程中的分辨率 | 480p | |
boolean | isShowCountdown | 是否显示倒计时的控件 | true |
boolean | isShowErrorDialog | 是否显示错误的 dialog | true |
int | authLayoutResId | 核身导出客户自定义的布局 resID ,不调整时使用 -1 | -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 | loadingStageBgColor | 核身界面 loading 阶段的背景颜色( 0xFFFFFFFF 的类型) | -1 |
int | loadingStageTipsColor | 核身界面 loading 阶段的 tips 提示的颜色( 0xFFFFFFFF 的类型) | -1 |
int | cancelTxtColor | 核身界面取消按钮的颜色( 0xFFFFFFFF 的类型) | -10 |
int | countDownTxtColor | 核身界面倒计时提示的颜色( 0xFFFFFFFF 的类型) | -10 |
boolean | isHideAvatarGuideFrame | 是否需要隐藏头像引导框 | false |
boolean | isShowSoundToggleBtn | 是否在核身界面显示"喇叭/静音"切换按钮(仅在 HuiYanOsConfig.isOpenAudio 为 true 时该按钮才有意义) | true |
VideoSize 类型 | 含义 |
VideoSize.SIZE_480P | 480P |
VideoSize.SIZE_720P | 720P |
类型 | 名称 | 含义 | 默认值 |
String | token | 此次活体流程中使用的 token | 空 |
错误码 | 错误码值 | 错误码含义 |
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_OPEN_CAMERA_ERROR | 215 | 打开摄像头过程中发生异常 |
HY_INIT_SDK_ERROR | 216 | 未调用 init() 方法,直接调用了启动接口 |
HY_VERIFY_LOCAL_ERROR | 217 | 本地人脸检测失败(已废弃),统一使用 228 错误码 |
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_USE_BACK_CAMERA_WITH_REFLECTIVE_ERROR | 227 | 使用后置摄像头时,SDK 采用的活体模式包含反光数据时报错 |
HY_ACTION_REFLECTIVE_SDK_ERROR | 228 | 内部算法本地检测识别失败 |
HY_RISK_INIT_AUTH_ERROR | 231 | 设备风控模块授权检测异常 |
HY_ILLEGAL_CONTEXT_ERROR | 233 | 非法 context,检查 init 接口传入的 context 是否合法 |
HY_ILLEGAL_TOKEN | 288 | 非法 token |
HY_TURING_CONFIG_MISMATCH_EXCEPTION | 400 | 风控模块配置不匹配(场景:HuiYanOsConfig 的配置 openCheckRiskMode 和申请获取业务 token 时的 SdkVersion 需要匹配、申请增强或者 Plus 模式的 token ,openCheckRiskMode 需要设置为 true ) |
/*** 海外精简的结果回调** @author jerrydong* @since 2022/6/10*/public interface HuiYanOsAuthCallBack {/*** 活体成功回调** @param authResult 结果*/void onSuccess(HuiYanOsAuthResult authResult);/*** 活体失败** @param errorCode 错误码* @param errorMsg 错误信息* @param token 本次核身使用的*/void onFail(int errorCode, String errorMsg, String token);}
/*** 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();void onBeginTransition();void onEndTransition();}
事件枚举 | 事件含义 |
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_CHIN | 请勿遮挡下巴 |
NO_NOSE | 请勿遮挡鼻子 |
NO_LEFT_EYE | 请勿遮挡左眼 |
NO_RIGHT_EYE | 请勿遮挡右眼 |
POSE_KEEP | 验证中,请保持姿势不变 |
POSE_CLOSER | 请靠近一点 |
POSE_FARTHER | 请离远一点 |
POSE_OPEN_EYE | 请勿闭眼 |
POSE_INCORRECT | 没有检测到完整人脸 |
TOO_MANY_FACE | 请确保框内只有一张人脸 |
INCOMPLETE_FACE | 请将脸移动到框内 |
LIGHT_TOO_LOW | 环境光线太暗 |
LIGHT_TOO_STRONG | 环境光线太亮 |
FACE_TOO_BRIGHT | 人脸过亮 |
FACE_TOO_DARK | 人脸过暗 |
事件枚举 | 事件含义 |
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 | 本地检测结束 |
FACE_QUALITY_CHECK | 人脸质量检测开始 |
FACE_QUALITY_CHECK_END | 人脸质量检测结束 |
CameraZoom 类型 | 含义 |
CameraZoom.ZOOM_1X | 1倍缩放 |
CameraZoom.ZOOM_1_5X | 1.5倍缩放 |
CameraZoom.ZOOM_2X | 2倍缩放 |
FaceAngleValidation 类型 | 含义 |
FaceAngleValidation.LevelLoose | 宽松模式,大约允许30度的人脸旋转且如果旋转角度过大反光阶段不会主动退出。 |
FaceAngleValidation.LevelMedium | 中等模式,大约允许20度的人脸旋转且如果旋转角度过大反光阶段会主动退出。 |
FaceAngleValidation.LevelStrict | 严格模式,大约允许10度的人脸旋转且如果旋转角度过大反光阶段会主动退出。 |
FaceOcclusionLevel 类型 | 含义 |
FaceOcclusionLevel.STRICT | 严格模式,对人脸遮挡检测最为严格。 |
FaceOcclusionLevel.MODERATE | 中等模式,对人脸遮挡检测适中。 |
FaceOcclusionLevel.LOOSE | 宽松模式,对人脸遮挡检测较为宽松。 |
FaceOcclusionLevel.PASS | 通过模式,跳过人脸遮挡检测。 |
文档反馈