tencent cloud

人脸核身

iOS 接口概述

下载
聚焦模式
字号
最后更新时间: 2026-10-29 11:05:35
本文档已由 AI 辅助审校

API 的详细说明

接入 SDK 主要涉及如下几个类,它们分别是 API 的接口类 HuiYanOSKit , 参数配置类 HuiYanOsConfig ,结果回调类 HuiYanOKitSuccCallback 以及 HuiYanOKitFailCallback 。

HuiYanOSKit

API
功能描述
获取 HuiYanOSKit 单例
进入 SDK 活体检测流程
释放 SDK 资源的接口
获取设备元信息加密字符串,用于云 API 获取 SdkToken
获取 SDK 版本号

startHuiYaneKYC

功能介绍:
​ 开启活体检测 SDK,并配置 SDK,回调返回结果或错误。
/// 开启eKYC活体检测流程
/// @param faceToken token
/// @param kitConfig SDK配置
/// @param succCallback 活体检测成功回调
/// @param failCallback 活体检测失败回调
- (void)startHuiYaneKYC:(NSString *)faceToken withConfig:(HuiYanOsConfig *)kitConfig
withSuccCallback:(HuiYanOKitSuccCallback)succCallback
withFailCallback:(HuiYanOKitFailCallback)failCallback;
传入参数:
类型
参数名称
参数含义
NSString
faceToken
活体流程单号
kitConfig
SDK 配置类
successCallback
活体检测成功回调
failCallback
活体检测失败回调

clearInstance()

功能介绍:
​ SDK 资源释放的接口。
+ (void)clearInstance;

createMetaData()

功能介绍:
获取设备元信息的加密字符串。该字符串来源于 SDK 采集的本地设备信息,需在调用云 API(GetFaceIdTokenIntl)获取 SdkToken 时作为 MetaData 入参传入,SDK 在内部流程中将使用对应的配置数据。
+ (NSString * _Nullable)createMetaData;
返回值:
类型
说明
NSString
设备元信息加密字符串。调用失败时返回 nil

sharedInstance

功能介绍:
获取 HuiYanOSKit 单例对象。
+ (instancetype)sharedInstance;

sdkVersion

功能介绍:
获取当前 SDK 版本号。
+ (NSString *)sdkVersion;
返回值:
类型
说明
NSString
SDK 版本号字符串


HuiYanOsConfig

HuiYanOsConfig 是在启动 SDK 时的配置实体类,主要包含了以下属性。
类型
名称
含义
默认值
NSString
authLicense
客户申请的用户核身授权的 License 文件名
空
long
prepareTimeoutMs
设置准备阶段检测的超时时间
30000 毫秒(30秒)
long
actionTimeoutMs
设置动作检测阶段超时时间
30000 毫秒(30秒)
showTimeOutMode
设置显示倒计时阶段
HYShowTimeOutMode_PREPARE
BOOL
isDeleteVideoCache
是否删除核身视频的本地缓存
YES
BOOL
isShowTipsPage
是否显示引导页
NO
NSString
userUIBundleName
自定义的 UI 的 bundle 文件名 比如 UserUIBundle.bundle 则设置为 "UserUIBundle" ;
nil
NSString
userLanguageFileName
自定义的 languageBundle 名称 比如 UseLanguage.bundle 则设置为 "UseLanguage";
nil
NSString
userLanguageBundleName
自定义本地国际化文件名 比如 en.lproj 则设置为 "en" ;
nil
languageType
SDK 内部文字语言设置
DEFAULT
NSString
setLanguageFileName
默认 HuiYanSDKUI.bundle 内新增的语言文件目录名称 优先级最高
nil
BOOL
isHideAvatarGuideFrame
设置隐藏核身过程中头像引导框
NO
id<HuiYanOverseasDelegate>
delegate
事件回调
空
NSUInteger
feedbackErrorColor
反馈异常 Tips 的颜色
0xFF584C
NSUInteger
feedbackTxtColor
反馈正常 Tips 的颜色
0x29CC85
NSUInteger
authCircleErrorColor
动作错误背景圆框的颜色
0xFF584C
NSUInteger
authCircleCorrectColor
动作正确时背景圆框的颜色
0x29CC85
NSUInteger
authLayoutBgColor
核身界面背景颜色(不设置则跟随系统,浅色模式为白色背景,深色模式为黑色背景)
-100
UIFont
feedbackTxtFont
核身提示文字字体及大小
18
UIFont
feedbackExtraTxtFont
额外提示文字大小
18
BOOL
isShowDialog
切换应用错误弹窗 Dialog 是否显示,对应错误码 HY_DONOT_SWITCH_APPS
YES
NSString
huiyanSdkUIBundlePath
设置 HuiYanSDKUI.bundle 的路径(当该文件不在 mainBundle 中时需要必填)
nil
NSString
userUIBundlePath
设置 UserUIBundle.bundle 的路径(当该文件不在 mainBundle 中时需要设置,使用自定义 UI 时必填)
nil
NSString
languageBundlePath
设置 LanguageSrcBundle.bundle 的路径(当该文件不在 mainBundle 中时需要设置,使用自定义多语言时必填)
nil
NSString
faceTrackerBundlePath
设置 face-tracker 的路径(当该文件不在 mainBundle 中时需要必填)
nil
BOOL
isShowPrivacyAgreementDialog
是否显示隐私协议弹窗
YES
BOOL
isUseBackCamera
是否使用后置摄像头
NO
UIColor
loadingLayoutBgColor
加载页面背景颜色
nil
UIColor
feedbackExtraTipColor
额外 tips 颜色
nil
UIColor
loadingTextColor
加载页面文字颜色
nil
CameraZoom
zoomType
设置摄像头焦距,通常在后置摄像头开启时使用
ZOOM_1X
CGFloat
smallFaceRatioThreshold
最小人脸占比
0.5
CGFloat
bigFaceRatioThreshold
最大人脸占比
0.8
BOOL
isOpenBOTCheck
开启 BOT 模式
NO
CGFloat
longCheckTimeoutMs
设置耗时检测阶段的超时时间
30000毫秒(30秒)
BOOL
disableSystemRecordScreen
开启核身时禁止系统录屏操作
NO
BOOL
isOtherActionCheckMouthOpen
动作检测时禁止张嘴(除张嘴动作检测外)
NO
NSUInteger
countdownTxtColor
设置倒计时颜色
0x000000
NSUInteger
cancelTxtColor
设置返回按钮颜色
0x000000
faceAngleValidation
人脸角度校验等级,默认宽松
FaceAngleValidationLevelLoose
BOOL
openCheckRiskMode
已废弃:风控开关改由获取 token 接口中 SdkVersion 配置控制,此字段不再生效
NO
NSString
riskLicense
已废弃:风控能力改由获取 token 接口中 SdkVersion 配置控制,此字段不再生效,无需再传入
nil
BOOL
supportSystemAdjustsFont
响应系统设置内字体大小调整
NO
BOOL
isShowNoPermissionDialog
设置显示无相机权限弹窗,引导去设置打开权限
NO
BOOL
isEntireHighlight
在人脸识别过程中,手机屏幕的亮度持续保持在最大值
YES
int
occlusionThreshold
已废弃:已由后端配置等级,端侧设置不生效。面部遮挡阈值配置, 1:严格;2:中等,只判断眼睛(阈值0.7)+ 鼻子(阈值0.3); 3:宽松,只判断眼睛(阈值0.7);4:放过,完全不做遮挡判断(即阈值0.0)
1
UIStatusBarStyle
statusBarStyle
状态栏样式,作用于核身页面。`UIStatusBarStyleDefault`:跟随系统;`UIStatusBarStyleDarkContent`:深色(状态栏文字为深色,适合浅色背景);`UIStatusBarStyleLightContent`:浅色(状态栏文字为浅色,适合深色背景)
UIStatusBarStyleDefault
BOOL
authPageAnimated
跳转识别页面时是否使用转场动画,默认 YES。协议引导页(iShowTipsPage=YES 时)始终不使用动画,不受此字段影响
YES
netConfig
网络请求参数配置对象,可对三个接口各自设置超时时间和最大请求次数
nil
BOOL
isShowErrorPopup
核身失败后是否显示重试弹窗。开启后失败时弹出重试弹窗(仍有重试次数)或退出确认弹窗(次数耗尽)
NO
BOOL
isOpenAudio
是否开启语音播报。开启时识别页显示语音开关按钮并播放语音提示,关闭时隐藏按钮且不播放
YES
BOOL
isShowSoundToggleBtn
语音开关按钮初始状态。YES=开启语音(播放),NO=关闭语音(静音)。仅在 isOpenAudio=YES 时生效
YES
BOOL
isShowGuideAnimation
是否显示引导动画。关闭后识别页不显示动作引导动画
YES
NSString
audioBundlePath
语音 bundle 文件路径(HuiYanAudioBundle.bundle 所在目录的完整路径,开启语音播报时必填)
nil
NSString
serverParamInfo
云 API(GetFaceIdTokenIntl)返回的加密配置字符串(ServerParamInfo 字段),透传给 SDK 使用
nil

HuiYanOsNetConfig

网络请求参数子配置类,挂载在 HuiYanOsConfig.netConfig。
类型
字段
含义
默认值
int
compareRequestTimeOutMs
比对(liveness)请求的超时时间,单位 ms
60000
int
compareRequestAttempts
比对(liveness)请求的最大请求次数(含主域名),最小为 1
3
int
lightRequestTimeOutMs
拉取光线序列(getLight)请求的超时时间,单位 ms
30000
int
lightRequestAttempts
拉取光线序列(getLight)请求的最大请求次数(含主域名),最小为 1
3


HuiYanOKitSuccCallback

/**
* 活体检测成功回调
*
* @param authResult 活体验证结果
* @param reserved 预留位
*/
typedef void (^HuiYanOKitSuccCallback)(HuiYanOsAuthResult * _Nonnull authResult, id _Nullable reserved);

HuiYanOKitFailCallback

/**
* 活体检测失败回调
*
* @param errCode 错误码
* @param errMsg 错误信息
* @param reserved 预留位
*/
typedef void (^HuiYanOKitFailCallback)(int errCode, NSString * _Nonnull errMsg ,id _Nullable reserved);

HY_LanguageType

SDK 内包含的国际化 String
typedef enum : NSUInteger {
HY_DEFAULT = 0,//跟随系统设置
HY_ZH_HANS,//中文简体
HY_ZH_HANT,//中文繁体//(中文繁体)
HY_EN,//英文
HY_CUSTOMIZE_LANGUAGE //定制语言
} HY_LanguageType;

HYShowTimeOutMode

typedef NS_OPTIONS(int, HYShowTimeOutMode) {
HYShowTimeOutMode_TIMEOUT_HIDDEN = 1 << 0,// 隐藏所有倒计时
HYShowTimeOutMode_PREPARE = 1 << 1,// 准备阶段倒计时
HYShowTimeOutMode_ACTION = 1 << 3,// 动作阶段倒计时
};

HuiYanOverseasDelegate

@protocol HuiYanOverseasDelegate <NSObject>
@required
//核身Event事件
- (void)onAuthEvent:(HYAuthEvent)actionEvent;
//核身时tips发生改变的事件通知回调
- (void)actionCallbackType:(HYAuthTipsEvent)actionType;
//当认证的主View被创建的回调
- (void)onMainViewCreate:(UIView *)authView;
@optional
//界面被回收的回调
- (void)onMainViewDestroy;
//核身弹窗回调(可选):实现并返回 YES 时由宿主自定义弹窗,返回 NO 或不实现时使用 SDK 默认弹窗
- (BOOL)onErrorPopupWithView:(UIView *)authView
scene:(HYErrorPopupScene)scene
title:(NSString *)title
message:(NSString *)message
nextBlock:(nullable void(^)(void))nextBlock
cancelBlock:(void(^)(void))cancelBlock;
@end

HuiYanOsAuthResult

类型
参数名称
参数含义
NSString
faceToken
活体流程 token
最后需要通过这个 token ,去腾讯云 API 的后台接口 GetFaceIdResultIntl 拉取最终活体是否成功的数据。

FaceAngleValidationLevel

FaceAngleValidationLevel 类型
含义
FaceAngleValidationLevelLoose
宽松模式,大约允许 30 度的人脸旋转且如果旋转角度过大反光阶段不会主动退出。
FaceAngleValidationLevelMedium
中等模式,大约允许 20 度的人脸旋转且如果旋转角度过大反光阶段会主动退出。
FaceAngleValidationLevelStrict
严格模式,大约允许 10 度的人脸旋转且如果旋转角度过大反光阶段会主动退出。

SDK 终端错误码(iOS)

错误码
错误码值
错误码含义
HY_SUCCESS
0
成功
HY_INITIALIZATION_PARAMETER_EXCEPTION
210
初始化参数异常
HY_BUNDLE_CONFIGURATION_EXCEPTION
211
bundle 配置异常
HY_YTSDK_CONFIGURATION_EXCEPTION
212
优图配置异常
HY_PLEASE_CALL_FIRST_INIT_API
213
需要先进行初始化接口
HY_SDK_AUTH_FAILED
214
SDK 授权失败
HY_USER_VOLUNTARILY_CANCELED
215
用户手动取消
HY_YTSDK_LOCAL_AUTH_FAILED
216
SDK 人脸本地检测失败
HY_CAMERA_OPEN_FAIL
217
相机开启失败
HY_DONOT_SWITCH_APPS
218
请勿在核身过程中切换应用
HY_CAMERA_PERMISSION_EXCEPTION
219
摄像头权限异常
HY_SDK_VIDEO_CUT_EXCEPTION
220
视频裁剪失败
HY_LIGHT_DATA_FORMAT_EXCEPTION
221
光线数据格式错误
HY_DETECT_TIMEOUT
222
动作检测超时
HY_LIMIT_SET_PKG_SIZE
223
超过包体设置大小限制
HY_USE_BACK_CAMERA_WITH_REFLECTIVE_ERROR
227
传入数据包含反光内容请使用前置摄像头
HY_NETWORK_ERROR
272
网络异常
HY_PREPARE_TIMEOUT
300
准备阶段超时
HY_LONGCHECK_TIMEOUT
301
耗时检测超时
HY_DONOT_ALLOW_RECORDING
302
请勿在核身过程中开启视频录制
HY_DONOT_ALLOW_SCREENSHOTS
303
请勿在核身过程中截屏
HY_INITIALIZATION_TURING_EXCEPTION
304
初始化风控模块失败
HY_TURING_CONFIG_MISMATCH_EXCEPTION
400
已废弃:风控模块配置不匹配,HuiYanOsConfig 中 openCheckRiskMode 配置与 GetFaceIdTokenIntl 或 ApplySdkVerificationToken 接口的 SdkVersion 入参不匹配

常见问题

1. 在使用 pod 集成时出现 Undefined symbol :_OBJC_CLASS$_HuiYanSDK 或者其他的 framework 没有找到的情况。
TARGETS -> Build Settings -> Other Linker Flags 添加 $(inherited)
2. 控制台报错提示: authLicense is empty 或者 auth failed。
检查 license 文件正确设置到 HuiYanBaseConfig,config.authLicense 为空导致报错。
TARGETS -> BuildPhases -> copyBundleResources 是否存在 license。
确认 license 文件是否包含项目包名。
3. Xcode 模拟器运行报错 "Undefined symbols OBJC_CLASS$_HuiYanOSKit"。
需要修改 Xcode 配置,Build Settings -> Excluded Architectures 添加 arm64 后即可运行。


帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈