动态与公告
- 产品动态
- 产品公告
产品简介
购买指南
接入文档
- 开始集成
- 活体人脸比对（纯 API）接入指引
- 活体人脸比对 (移动端H5) 接入指引
- 活体人脸比对 (App SDK) 接入指引
- 卡证核验（App SDK）
- 卡证活体人脸比对（移动端 H5）接入指引
- 卡证活体人脸比对（App SDK）接入指引
- 其他指引
API 文档
- 更新历史
- 简介
- API 概览
- 调用方式
- 其他接口
- 人脸核身SaaS服务相关接口
- 活体人脸比对（移动端H5）相关接口
- 活体人脸比对（App SDK）相关接口
- 卡证活体人脸比对 (App SDK) 相关接口
- AI人脸防护盾相关接口
- 反洗钱服务相关接口
- 实名信息核验相关接口
- 数据结构
- 错误码
常见问题
联系我们
词汇表
eKYC 政策

iOS 接口概述文档

下载

聚焦模式

字号

最后更新时间： 2026-10-23 12:02:02

本文档已由 AI 辅助审校

API 概述
iOS 端卡证活体人脸比对（App SDK）涉及的类主要包含 VerificationKit、VerificationConfig、OcrCustomConfig、FaceCustomConfig、VerificationDelegate、VerifiCommDef 等，下面对其支持的 API 做出详细说明。
VerificationKit
VerificationKit 为卡证活体人脸比对（App SDK）的对外接口类，主要逻辑也是调用此类来完成。
API
功能描述
initWithViewController
初始化接口
clearInstance
资源释放接口
createMetaData
获取申请 Token 所需的 MetaData 字符串数据
startVerifiWithConfig
启动卡证活体人脸比对的流程
initWithViewController
// 初始化方法
- (void)initWithViewController:(UIViewController *)viewController;
功能介绍：
卡证活体人脸比对（App SDK）的初始化接口。
传入参数:
参数类型
参数名称
参数含义
UIViewController
viewController
当前调用 SDK 页面 VC 对象
clearInstance
/// 清理SDK资源
+ (void)clearInstance;
功能介绍：
​SDK 资源释放的接口。
﻿
createMetaData
/// 获取 MetaData 字符串
+ (NSString *)createMetaData;
功能介绍：
获取向腾讯云申请 SDK Token 时所需的 MetaData 字段内容。请在调用腾讯云获取 Token 接口时，将返回值作为 MetaData 参数传入。
﻿
startVerifiWithConfig
/// 开启验证
- (void)startVerifiWithConfig:(VerificationConfig *)verifiConfig
             withSuccCallback:(TXYVerifiKitProcessSucceedBlock)succCallback
             withFialCallback:(TXYVerifiKitProcessFailedBlock)failCallback;
功能介绍：
​启动卡证活体人脸比对的流程方法。
传入参数：
参数类型
参数名称
参数含义
VerificationConfig
verifiConfig
本次流程启动的配置信息
TXYVerifiKitProcessSucceedBlock
succCallback
SDK 检测成功回调
TXYVerifiKitProcessFailedBlock
failCallback
SDK 检测失败回调
TXYVerifiKitProcessSucceedBlock
/// SDK 处理成功回调接口
/// @param errorCode 错误码
/// @param resultInfo 回调返回的信息
/// @param reserved 预留位
typedef void (^TXYVerifiKitProcessSucceedBlock)(int errorCode,id _Nonnull resultInfo, id _Nullable reserved);
TXYVerifiKitProcessFailedBlock
/// SDK 处理失败回调接口
/// @param errorCode 错误码
/// @param errorMsg 错误信息
/// @param reserved 预留位
typedef void (^TXYVerifiKitProcessFailedBlock)(int errorCode, NSString *_Nonnull errorMsg, id _Nullable reserved);
VerificationConfig
VerificationConfig 是在启动 SDK 时的配置实体类，主要包含了以下属性。
类型
名称
含义
默认值
NSString
licPath
客户申请的用户授权 License 文件路径
空
BOOL
openCheckRiskMode
是否开启设备风险检测，当 ApplySdkVerificationToken 中入参 SdkVersion 设置为 ENHANCE 或 PLUS 时，需配置为开启（YES）
NO
NSString
riskLicense
风控授权文件路径，openCheckRiskMode 为 YES 时必填
空
NSString
ekycToken
从服务器端获取的 Token 值，作为此次核身唯一业务凭证
空
NSString
serverParamInfo
从腾讯云获取的 Token 模式服务端参数，与 token 一同下发
空
HYEkycLanguageType
languageType
设置 SDK 语言类型
HY_EKYC_EN
BOOL
isHiddenFlash
是否隐藏 OCR 环节中打开手电筒的按钮
NO
NSString
userLanguageFileName
自定义语言 Bundle 中目标 .lproj 文件夹名称，如 ja.lproj。仅 languageType 为 HY_EKYC_CUSTOMIZE_LANGUAGE 时生效
空
BOOL
isShowPrivacyAgreementDialog
是否在验证流程开始前显示隐私协议弹窗
YES
CGFloat
livenessAutoTimeout
活体阶段超时时间，单位：毫秒
30000
BOOL
isOpenClipImage
OCR 阶段用户通过相册选图后，是否开启裁剪页面
NO
BOOL
isUseBackCameraOnFaceAuth
是否在人脸检测阶段使用后置摄像头
NO
BOOL
supportSystemAdjustsFont
是否响应系统无障碍设置中的字体大小调整
NO
OcrCustomConfig
ocrCustomConfig
OCR 阶段自定义 UI 配置，控制识别框颜色、提示文本样式等
空
FaceCustomConfig
faceCustomConfig
人脸阶段自定义 UI 配置，控制背景色、提示文本样式、圆框颜色等
空
VerificationDelegate
delegate
SDK 界面生命周期事件代理，可监听 OCR/人脸界面的创建与销毁
空
NSString
userUIBundlePath
用户自定义 UI 资源包绝对路径；未使用自定义 UI 默认为空
空
NSString
userLanguageBundlePath
用户自定义多语言资源包绝对路径；为 nil 时使用 mainBundle 中的 huiyan_verification.bundle
空
NSString
huiyanSDKBundlePath
活体人脸比对环节的 UI 资源包绝对路径（HuiYanSDKUI.bundle）；为 nil 时使用 mainBundle 中的 HuiYanSDKUI.bundle
空
NSString
verificationBundlePath
卡证活体人脸比对环节核心验证资源包绝对路径（huiyan_verification.bundle）；为 nil 时使用 mainBundle 中的 huiyan_verification.bundle
空
NSString
ocrSDKBundlePath
OCR（证件识别和鉴伪）环节资源包绝对路径（OcrSDK.bundle），用于动态下载场景；为 nil 时使用 mainBundle 中的 OcrSDK.bundle。
空
NSString
ocrModelBundlePath
OCR 模型资源包绝对路径（OcrModel.bundle），用于多图 OCR 模型文件的动态下载场景；为 nil 时使用 mainBundle 中的 OcrModel.bundle
空
NSString
faceTrackerBundlePath
活体人脸比对环节资源包绝对路径（face-tracker-v003.bundle），用于动态下载场景；为 nil 时使用 mainBundle 中的 face-tracker-v003.bundle
空
BOOL
isShowTipsPage
是否显示活体人脸比对环节的准备提示页（FaceVerifiPreViewController）。设为 NO 时，SDK 跳过提示页，直接进入活体检测
YES
BOOL
isShowResultPage
是否显示活体人脸比对环节的结果展示页（FaceVerifiResultViewController）。设为 NO 时，SDK 跳过结果页，直接通过回调将结果返回给宿主
YES
BOOL
isEntireHighlight
是否在活体人脸检测全程保持手机屏幕高亮状态。设为 YES 时人脸识别全程手机屏幕亮度处于高亮状态
NO
﻿
OcrCustomConfig
OcrCustomConfig 是指证件识别和鉴伪阶段的自定义 UI 配置类。
类型
名称
含义
默认值
UIColor
rectNormalColor
识别框正常状态颜色
空
UIColor
rectErrorColor
识别框错误状态颜色
空
UIColor
rectPassColor
识别框通过状态颜色
空
UIColor
tipsNormalColor
提示文字正常状态颜色
空
UIColor
tipsErrorColor
提示文字错误状态颜色
空
UIColor
tipsPassColor
提示文字通过状态颜色
空
UIFont
tipsFont
提示文字字体（设置后优先于 tipsFontSize）
空
CGFloat
rectScaleX
识别框横向边距占屏幕宽度的比例，取值范围 0.0~0.15
0.03
CGFloat
rectTopMarginScale
识别框顶部边距占屏幕高度的比例（仅竖屏有效，横屏时居中显示）
0.28
BOOL
isShowTips
是否显示提示文字
YES
NSString
tipsShowText
自定义提示文字内容，为 nil 时显示 SDK 默认文案
空
BOOL
showBestImgConfirmDialog
自动检测完成后是否弹出最佳帧确认弹窗
NO
FaceCustomConfig
FaceCustomConfig 是活体人脸比对阶段的自定义 UI 配置类。
类型
名称
含义
默认值
UIColor
backgroundColor
人脸验证页面背景颜色
空
UIColor
tipsTextColor
提示文字颜色（正常状态）
空
UIColor
tipsTextErrorColor
提示文字颜色（错误状态）
空
UIFont
tipsTextFont
提示文字字体（含大小）
空
UIColor
faceCircleErrorColor
人脸圆框颜色（错误状态）
空
UIColor
faceCircleCorrectColor
人脸圆框颜色（正确状态）
空
UIColor
countDownTextColor
倒计时文字颜色
空
UIColor
cancelButtonTextColor
取消按钮文字颜色
空
UIStatusBarStyle
faceStatusBarStyle
人脸检测页面的状态栏文字颜色样式。默认跟随系统（UIStatusBarStyleDefault）
UIStatusBarStyleDefault
BOOL
faceAuthAnimated
进入人脸检测页面时是否使用跳转动画。设为 NO 时无动画进入
YES
BOOL
isHideFaceCountDown
是否隐藏人脸检测页面的倒计时。设为 YES 时隐藏所有倒计时显示
NO
BOOL
isShowErrorPopup
活体检测失败后是否显示重试弹窗。设为 YES 时，SDK 在活体失败后弹出重试提示弹窗；宿主可通过 VerificationDelegate 的 onFaceErrorPopupWithView:title:message:retryBlock:cancelBlock: 回调自定义弹窗
NO
BOOL
isOpenAudio
是否开启语音播报。设为 YES 时识别页显示语音开关按钮，设为 NO 时隐藏按钮且不播放语音
YES
BOOL
isShowSoundToggleBtn
语音开关按钮的初始状态。YES=开启语音（播放），NO=关闭语音（静音）；仅在 isOpenAudio 为 YES 时生效
YES
BOOL
isShowGuideAnimation
是否显示动作引导动画。设为 NO 时识别页不显示动作引导动画
YES
VerifiCommDef
HYEkycLanguageType
SDK 默认界面的多语言配置信息。
类型
含义
HY_EKYC_DEFAULT = 0
跟随系统语言版本
HY_EKYC_ZH_HANS
简体中文
HY_EKYC_ZH_HANT
繁体中文
HY_EKYC_EN
英语
HY_EKYC_CUSTOMIZE_LANGUAGE
自定义语言，使用设置的自定义语言 bundle（userLanguageFileName）
﻿
VerificationDelegate
SDK 界面生命周期事件协议，用于监听证件识别界面和活体人脸比对界面的创建与销毁事件：
@protocol VerificationDelegate <NSObject>
@optional
/// OCR界面创建回调，authView 为 SDK 展示的根视图
- (void)ocrMainViewCreate:(UIView *)authView;
/// OCR界面被移除时回调
- (void)ocrMainViewDestroy;
/// 人脸界面创建回调，authView 为 SDK 展示的根视图
- (void)faceMainViewCreate:(UIView *)authView;
/// 人脸界面被移除时回调
- (void)faceMainViewDestroy;
﻿
// Face phase dialog
- (BOOL)onFaceErrorPopupWithView:(UIView *)authView
                           title:(NSString *)title
                         message:(NSString *)message
                       nextBlock:(nullable void(^)(void))nextBlock
                     cancelBlock:(void(^)(void))cancelBlock;
                     
﻿
// Face phase events
- (void)onFaceAuthEvent:(HYEkycAuthEvent)event;
- (void)onFaceAuthTipsEvent:(HYEkycAuthTipsEvent)tipsEvent;
﻿
// OCR phase dialogs
- (BOOL)onOcrBestFrameConfirmDialog:(NSDictionary *)info
                          imageView:(UIImageView *)imageView
                         parentView:(UIView *)parentView
                       confirmBlock:(void(^)(void))confirmBlock
                        cancelBlock:(void(^)(void))cancelBlock;
﻿
- (BOOL)onOcrNextSideDialog:(NSDictionary *)info
                 parentView:(UIView *)parentView
               confirmBlock:(void(^)(void))confirmBlock;
﻿
- (BOOL)onOcrChangeModeDialog:(NSDictionary *)info
                   parentView:(UIView *)parentView
                 confirmBlock:(void(^)(void))confirmBlock
                  cancelBlock:(void(^)(void))cancelBlock;
﻿
- (BOOL)onOcrCloudErrorDialog:(NSDictionary *)info
                   parentView:(UIView *)parentView
                   retryBlock:(nullable void(^)(void))retryBlock
                    exitBlock:(void(^)(void))exitBlock;
﻿
- (BOOL)onOcrCameraPermissionDialog:(NSDictionary *)info
                         parentView:(UIView *)parentView
                      settingsBlock:(void(^)(void))settingsBlock
                        cancelBlock:(void(^)(void))cancelBlock;
﻿
// Loading
- (BOOL)onEkycShowLoading:(NSDictionary *)info parentView:(UIView *)parentView;
- (BOOL)onEkycHideLoading:(UIView *)parentView;
﻿
@end
onFaceErrorPopupWithView
核身失败重试弹窗回调（可选）。
前提条件：FaceCustomConfig.isShowErrorPopup = YES 时该回调才会触发；isShowErrorPopup = NO 时 SDK 直接回调失败，不触发此方法。
返回值行为：
实现此方法并返回 YES：SDK 不弹出内部默认弹窗，由宿主自行展示自定义弹窗，并在用户操作后调用 nextBlock（重试）或 cancelBlock（退出）以驱动 SDK 后续流程。
实现此方法并返回 NO：SDK 忽略宿主处理，自动弹出内部默认重试弹窗。
未实现此方法：SDK 自动弹出内部默认重试弹窗。
参数类型
参数名称
参数含义
UIView
authView
核身主页面的根 View，宿主可将自定义弹窗添加到该 View 上
NSString
title
弹窗主标题（已根据当前语言和错误码本地化）
NSString
message
弹窗副标题（已根据当前语言和错误码本地化）
void(^)(void)
nextBlock
用户点击重试时调用，SDK 将重置状态重新开始核身流程。当重试次数耗尽时该字段为 nil
void(^)(void)
cancelBlock
用户点击退出时调用，SDK 将按失败流程退出并回调失败结果
返回值类型
含义
BOOL
YES：宿主接管弹窗展示；NO：使用 SDK 默认弹窗
onFaceAuthEvent
人脸活体检测阶段事件回调（可选）。当活体检测进入新阶段时触发，可用于在宿主侧埋点统计或更新自定义 UI 状态。未实现则 SDK 不通知。
参数类型
参数名称
参数含义
HYEkycAuthEvent
event
当前检测阶段事件，枚举值详见 HYEkycAuthEvent﻿
onFaceAuthTipsEvent
人脸活体检测 Tips 变化回调（可选）。
﻿
当检测过程中实时提示文字发生变化时触发（如：无人脸、遮挡、光线不足、距离不当等），可用于宿主自定义提示展示逻辑。未实现则 SDK 不通知。
﻿
参数类型
参数名称
参数含义
HYEkycAuthTipsEvent
tipsEvent
当前 Tips 事件类型，枚举值详见 HYEkycAuthTipsEvent﻿
OCR 阶段弹窗回调
以下 5 个方法均采用相同的两级回退模式：实现并返回 YES 时，SDK 不展示内部弹窗，由宿主使用提供的 block 驱动流程；返回 NO 或未实现时，SDK 使用内部默认弹窗。
﻿
info 字典中可读取 HYEkycDialogInfoKeyTitle（弹窗标题）和 HYEkycDialogInfoKeyMessage（弹窗内容）。
﻿
方法
触发条件
关键参数
onOcrBestFrameConfirmDialog:imageView:parentView:confirmBlock:cancelBlock:
OcrCustomConfig.showBestImgConfirmDialog = YES 且自动检测到最佳帧
imageView：包含最佳帧的视图；confirmBlock：确认使用；cancelBlock：重新采集
onOcrNextSideDialog:parentView:confirmBlock:
正面识别完成，需引导用户翻转到背面
confirmBlock：用户确认翻面
onOcrChangeModeDialog:parentView:confirmBlock:cancelBlock:
自动识别超时，提示切换为手动拍摄
confirmBlock：切换手动；cancelBlock：继续等待
onOcrCloudErrorDialog:parentView:retryBlock:exitBlock:
OCR 识别请求失败，询问重试或退出
retryBlock：重试（为 nil 时不显示重试按钮）；exitBlock：退出并触发失败回调
onOcrCameraPermissionDialog:parentView:settingsBlock:cancelBlock:
检测到相机无访问权限
settingsBlock：跳转系统设置；cancelBlock：退出并触发失败回调
Loading 回调
onEkycShowLoading:parentView: 和 onEkycHideLoading: 覆盖 eKYC 全流程所有 loading 场景（OCR 识别处理、相册选图、结果上传等）。
﻿
实现并返回 YES 时，SDK 不展示内部 HUD，由宿主自行显示/隐藏 loading；返回 NO 或未实现时，SDK 使用内部 TXYEkycProgressHUD。
﻿
onEkycShowLoading:parentView: 的 info 字典中包含 HYEkycLoadingInfoKeyType，取值如下：
﻿
常量
含义
HYEkycLoadingTypeOcrProcessing
OCR 识别处理中
HYEkycLoadingTypeImagePicking
打开相册选图中
HYEkycLoadingTypeResultUploading
OCR 结果上传中
注意：
onEkycShowLoading:parentView: 与 onEkycHideLoading: 必须配对使用；SDK 保证每次 show 之后都会调用对应的 hide。
Dialog info key 常量
OCR 阶段弹窗回调的 info 字典使用以下公开常量作为 key，宿主无需引入 OCR SDK 头文件：
﻿
常量
说明
HYEkycDialogInfoKeyTitle
弹窗标题文字
HYEkycDialogInfoKeyMessage
弹窗正文内容
HYEkycDialogInfoKeyErrorCode
错误码（仅 onOcrCloudErrorDialog 携带）
﻿
HYEkycAuthEvent
人脸活体检测阶段事件枚举，在 VerificationDelegate.onFaceAuthEvent: 回调中使用。
枚举值
含义
HYEkycAuthEventNone = 0
默认，不通知
HYEkycAuthEventStartAuth = 1
活体检测已启动
HYEkycAuthEventOpenMouthCheck = 2
开始张嘴动作检测
HYEkycAuthEventSilentCheck = 3
开始静默检测
HYEkycAuthEventBlinkCheck = 4
开始眨眼检测
HYEkycAuthEventNodHeadCheck = 5
开始点头检测
HYEkycAuthEventShakeHeadCheck = 6
开始摇头检测
HYEkycAuthEventReflectCheck = 7
开始炫光检测
HYEkycAuthEventOpenMouthCheckEnd = 8
张嘴动作检测结束
HYEkycAuthEventSilentCheckEnd = 9
静默检测结束
HYEkycAuthEventBlinkCheckEnd = 10
眨眼检测结束
HYEkycAuthEventNodHeadCheckEnd = 11
点头检测结束
HYEkycAuthEventShakeHeadCheckEnd = 12
摇头检测结束
HYEkycAuthEventActionCheckEnd = 13
所有动作检测结束
HYEkycAuthEventLocalDetectionDone = 14
本地检测（所有动作）完成
HYEkycAuthEventFaceQualityCheck = 15
人脸质量检测开始
HYEkycAuthEventFaceQualityCheckEnd = 16
人脸质量检测结束
HYEkycAuthTipsEvent
人脸活体检测 Tips 事件枚举，在 VerificationDelegate.onFaceAuthTipsEvent: 回调中使用。
枚举值
含义
HYEkycAuthTipsEventNone = 0
无提示，不通知
HYEkycAuthTipsEventOpenMouth = 1
请张嘴
HYEkycAuthTipsEventBlink = 2
请眨眼
HYEkycAuthTipsEventNodHead = 3
请点头
HYEkycAuthTipsEventShakeHead = 4
请摇头
HYEkycAuthTipsEventScreenShaking = 5
请保持手机稳定
HYEkycAuthTipsEventLightNotRight = 6
光线不佳
HYEkycAuthTipsEventNoFace = 7
未检测到人脸
HYEkycAuthTipsEventNoLeftFace = 8
请勿遮挡左侧脸部
HYEkycAuthTipsEventNoRightFace = 9
请勿遮挡右侧脸部
HYEkycAuthTipsEventNoChin = 10
请勿遮挡下巴
HYEkycAuthTipsEventNoMouth = 11
请勿遮挡嘴部
HYEkycAuthTipsEventNoNose = 12
请勿遮挡鼻子
HYEkycAuthTipsEventNoLeftEye = 13
请勿遮挡左眼
HYEkycAuthTipsEventNoRightEye = 14
请勿遮挡右眼
HYEkycAuthTipsEventPoseKeep = 15
验证中，请保持不动
HYEkycAuthTipsEventPoseCloser = 16
请靠近一些
HYEkycAuthTipsEventPoseFarther = 17
请离远一些
HYEkycAuthTipsEventPoseOpenEye = 18
请睁开眼睛
HYEkycAuthTipsEventPoseIncorrect = 19
请正对屏幕
HYEkycAuthTipsEventTooManyFace = 20
请确保画面中只有一张人脸
HYEkycAuthTipsEventIncompleteFace = 21
请将人脸移入框内
HYEkycAuthTipsEventLightTooLow = 22
光线太暗
HYEkycAuthTipsEventLightTooStrong = 23
光线太强
HYEkycAuthTipsEventAngleDetectLarge = 24
炫光阶段人脸角度过大
HYEkycAuthTipsEventFaceTooBright = 25
人脸过亮
HYEkycAuthTipsEventFaceTooDark = 26
人脸过暗
﻿
错误码与含义
错误码
错误码含义
0
成功
-1
检测失败
-2
证件识别失败
-4
SDK 内部错误
216
人脸本地检测失败
217
相机开启失败
218
请勿在核身过程中切换应用
219
摄像头权限异常
220
视频裁剪失败
221
光线数据格式错误
222
动作检测超时
223
超过包体设置大小限制
227
后置摄像头反光错误
272
网络异常
300
准备阶段超时
301
耗时检测超时
302
请勿在核身过程中开启录制
303
请勿在核身过程中截屏
304
风控模块初始化失败
310
初始化参数异常
311
bundle 配置异常
313
先调用初始化接口
314
SDK 授权失败
315
用户手动取消
322
获取远程数据错误
400
风控配置不匹配
101000
OCR 识别失败
100100
OCR 参数异常
100102
OCR 网络异常
100103
OCR 摄像头权限异常
300101
OCR 初始化异常
300102
OCR 服务解析异常
300103
OCR 签名失败
300104
OCR 摄像头异常
300105
OCR 初始化配置失败
300106
OCR 图片为空
300107
OCR 授权失败
300108
OCR 系统版本过低
300109
OCR 自动模式超时
300110
OCR SDK 内部错误
300111
OCR 图片裁剪异常
400100
触发指定拦截的告警码
400101
用户传入的证件类型和指定证件类型不一致
400102
用户传入的证件面和选择的面不同
400103
用户传入照片中卡证占比太小
400104
用户传入的照片中包括多张卡证照片
400105
OCR 识别失败
400106
卡证信息校验失败
400107
入参存在错误
400108
内部服务错误
400109
服务未开通 / 账号欠费 / 资源包耗尽 / 计费异常
400110
触发限流
400111
文件 size 太大或无效
400112
文件解析失败
﻿

帮助和支持

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

您也可以联系销售或提交工单以寻求帮助。

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

文档反馈

方法	触发条件	关键参数
`onOcrBestFrameConfirmDialog:imageView:parentView:confirmBlock:cancelBlock:`	`OcrCustomConfig.showBestImgConfirmDialog = YES` 且自动检测到最佳帧	`imageView`：包含最佳帧的视图；`confirmBlock`：确认使用；`cancelBlock`：重新采集
`onOcrNextSideDialog:parentView:confirmBlock:`	正面识别完成，需引导用户翻转到背面	`confirmBlock`：用户确认翻面
`onOcrChangeModeDialog:parentView:confirmBlock:cancelBlock:`	自动识别超时，提示切换为手动拍摄	`confirmBlock`：切换手动；`cancelBlock`：继续等待
`onOcrCloudErrorDialog:parentView:retryBlock:exitBlock:`	OCR 识别请求失败，询问重试或退出	`retryBlock`：重试（为 nil 时不显示重试按钮）；`exitBlock`：退出并触发失败回调
`onOcrCameraPermissionDialog:parentView:settingsBlock:cancelBlock:`	检测到相机无访问权限	`settingsBlock`：跳转系统设置；`cancelBlock`：退出并触发失败回调

API	功能描述
initWithViewController	初始化接口
clearInstance	资源释放接口
createMetaData	获取申请 Token 所需的 MetaData 字符串数据
startVerifiWithConfig	启动卡证活体人脸比对的流程

参数类型	参数名称	参数含义
UIViewController	viewController	当前调用 SDK 页面 VC 对象

类型	名称	含义	默认值
NSString	licPath	客户申请的用户授权 License 文件路径	空
BOOL	openCheckRiskMode	是否开启设备风险检测，当 ApplySdkVerificationToken 中入参 SdkVersion 设置为 ENHANCE 或 PLUS 时，需配置为开启（YES）	NO
NSString	riskLicense	风控授权文件路径，openCheckRiskMode 为 YES 时必填	空
NSString	ekycToken	从服务器端获取的 Token 值，作为此次核身唯一业务凭证	空
NSString	serverParamInfo	从腾讯云获取的 Token 模式服务端参数，与 token 一同下发	空
HYEkycLanguageType	languageType	设置 SDK 语言类型	HY_EKYC_EN
BOOL	isHiddenFlash	是否隐藏 OCR 环节中打开手电筒的按钮	NO
NSString	userLanguageFileName	自定义语言 Bundle 中目标 .lproj 文件夹名称，如 ja.lproj。仅 languageType 为 HY_EKYC_CUSTOMIZE_LANGUAGE 时生效	空
BOOL	isShowPrivacyAgreementDialog	是否在验证流程开始前显示隐私协议弹窗	YES
CGFloat	livenessAutoTimeout	活体阶段超时时间，单位：毫秒	30000
BOOL	isOpenClipImage	OCR 阶段用户通过相册选图后，是否开启裁剪页面	NO
BOOL	isUseBackCameraOnFaceAuth	是否在人脸检测阶段使用后置摄像头	NO
BOOL	supportSystemAdjustsFont	是否响应系统无障碍设置中的字体大小调整	NO
OcrCustomConfig	ocrCustomConfig	OCR 阶段自定义 UI 配置，控制识别框颜色、提示文本样式等	空
FaceCustomConfig	faceCustomConfig	人脸阶段自定义 UI 配置，控制背景色、提示文本样式、圆框颜色等	空
VerificationDelegate	delegate	SDK 界面生命周期事件代理，可监听 OCR/人脸界面的创建与销毁	空
NSString	userUIBundlePath	用户自定义 UI 资源包绝对路径；未使用自定义 UI 默认为空	空
NSString	userLanguageBundlePath	用户自定义多语言资源包绝对路径；为 nil 时使用 mainBundle 中的 huiyan_verification.bundle	空
NSString	huiyanSDKBundlePath	活体人脸比对环节的 UI 资源包绝对路径（HuiYanSDKUI.bundle）；为 nil 时使用 mainBundle 中的 HuiYanSDKUI.bundle	空
NSString	verificationBundlePath	卡证活体人脸比对环节核心验证资源包绝对路径（huiyan_verification.bundle）；为 nil 时使用 mainBundle 中的 huiyan_verification.bundle	空
NSString	ocrSDKBundlePath	OCR（证件识别和鉴伪）环节资源包绝对路径（OcrSDK.bundle），用于动态下载场景；为 nil 时使用 mainBundle 中的 OcrSDK.bundle。	空
NSString	ocrModelBundlePath	OCR 模型资源包绝对路径（OcrModel.bundle），用于多图 OCR 模型文件的动态下载场景；为 nil 时使用 mainBundle 中的 OcrModel.bundle	空
NSString	faceTrackerBundlePath	活体人脸比对环节资源包绝对路径（face-tracker-v003.bundle），用于动态下载场景；为 nil 时使用 mainBundle 中的 face-tracker-v003.bundle	空
BOOL	isShowTipsPage	是否显示活体人脸比对环节的准备提示页（FaceVerifiPreViewController）。设为 NO 时，SDK 跳过提示页，直接进入活体检测	YES
BOOL	isShowResultPage	是否显示活体人脸比对环节的结果展示页（FaceVerifiResultViewController）。设为 NO 时，SDK 跳过结果页，直接通过回调将结果返回给宿主	YES
BOOL	isEntireHighlight	是否在活体人脸检测全程保持手机屏幕高亮状态。设为 YES 时人脸识别全程手机屏幕亮度处于高亮状态	NO

类型	含义
HY_EKYC_DEFAULT = 0	跟随系统语言版本
HY_EKYC_ZH_HANS	简体中文
HY_EKYC_ZH_HANT	繁体中文
HY_EKYC_EN	英语
HY_EKYC_CUSTOMIZE_LANGUAGE	自定义语言，使用设置的自定义语言 bundle（userLanguageFileName）

返回值类型	含义
BOOL	YES：宿主接管弹窗展示；NO：使用 SDK 默认弹窗

常量	含义
`HYEkycLoadingTypeOcrProcessing`	OCR 识别处理中
`HYEkycLoadingTypeImagePicking`	打开相册选图中
`HYEkycLoadingTypeResultUploading`	OCR 结果上传中

常量	说明
`HYEkycDialogInfoKeyTitle`	弹窗标题文字
`HYEkycDialogInfoKeyMessage`	弹窗正文内容
`HYEkycDialogInfoKeyErrorCode`	错误码（仅 `onOcrCloudErrorDialog` 携带）

枚举值	含义
HYEkycAuthEventNone = 0	默认，不通知
HYEkycAuthEventStartAuth = 1	活体检测已启动
HYEkycAuthEventOpenMouthCheck = 2	开始张嘴动作检测
HYEkycAuthEventSilentCheck = 3	开始静默检测
HYEkycAuthEventBlinkCheck = 4	开始眨眼检测
HYEkycAuthEventNodHeadCheck = 5	开始点头检测
HYEkycAuthEventShakeHeadCheck = 6	开始摇头检测
HYEkycAuthEventReflectCheck = 7	开始炫光检测
HYEkycAuthEventOpenMouthCheckEnd = 8	张嘴动作检测结束
HYEkycAuthEventSilentCheckEnd = 9	静默检测结束
HYEkycAuthEventBlinkCheckEnd = 10	眨眼检测结束
HYEkycAuthEventNodHeadCheckEnd = 11	点头检测结束
HYEkycAuthEventShakeHeadCheckEnd = 12	摇头检测结束
HYEkycAuthEventActionCheckEnd = 13	所有动作检测结束
HYEkycAuthEventLocalDetectionDone = 14	本地检测（所有动作）完成
HYEkycAuthEventFaceQualityCheck = 15	人脸质量检测开始
HYEkycAuthEventFaceQualityCheckEnd = 16	人脸质量检测结束

枚举值	含义
HYEkycAuthTipsEventNone = 0	无提示，不通知
HYEkycAuthTipsEventOpenMouth = 1	请张嘴
HYEkycAuthTipsEventBlink = 2	请眨眼
HYEkycAuthTipsEventNodHead = 3	请点头
HYEkycAuthTipsEventShakeHead = 4	请摇头
HYEkycAuthTipsEventScreenShaking = 5	请保持手机稳定
HYEkycAuthTipsEventLightNotRight = 6	光线不佳
HYEkycAuthTipsEventNoFace = 7	未检测到人脸
HYEkycAuthTipsEventNoLeftFace = 8	请勿遮挡左侧脸部
HYEkycAuthTipsEventNoRightFace = 9	请勿遮挡右侧脸部
HYEkycAuthTipsEventNoChin = 10	请勿遮挡下巴
HYEkycAuthTipsEventNoMouth = 11	请勿遮挡嘴部
HYEkycAuthTipsEventNoNose = 12	请勿遮挡鼻子
HYEkycAuthTipsEventNoLeftEye = 13	请勿遮挡左眼
HYEkycAuthTipsEventNoRightEye = 14	请勿遮挡右眼
HYEkycAuthTipsEventPoseKeep = 15	验证中，请保持不动
HYEkycAuthTipsEventPoseCloser = 16	请靠近一些
HYEkycAuthTipsEventPoseFarther = 17	请离远一些
HYEkycAuthTipsEventPoseOpenEye = 18	请睁开眼睛
HYEkycAuthTipsEventPoseIncorrect = 19	请正对屏幕
HYEkycAuthTipsEventTooManyFace = 20	请确保画面中只有一张人脸
HYEkycAuthTipsEventIncompleteFace = 21	请将人脸移入框内
HYEkycAuthTipsEventLightTooLow = 22	光线太暗
HYEkycAuthTipsEventLightTooStrong = 23	光线太强
HYEkycAuthTipsEventAngleDetectLarge = 24	炫光阶段人脸角度过大
HYEkycAuthTipsEventFaceTooBright = 25	人脸过亮
HYEkycAuthTipsEventFaceTooDark = 26	人脸过暗

错误码	错误码含义
0	成功
-1	检测失败
-2	证件识别失败
-4	SDK 内部错误
216	人脸本地检测失败
217	相机开启失败
218	请勿在核身过程中切换应用
219	摄像头权限异常
220	视频裁剪失败
221	光线数据格式错误
222	动作检测超时
223	超过包体设置大小限制
227	后置摄像头反光错误
272	网络异常
300	准备阶段超时
301	耗时检测超时
302	请勿在核身过程中开启录制
303	请勿在核身过程中截屏
304	风控模块初始化失败
310	初始化参数异常
311	bundle 配置异常
313	先调用初始化接口
314	SDK 授权失败
315	用户手动取消
322	获取远程数据错误
400	风控配置不匹配
101000	OCR 识别失败
100100	OCR 参数异常
100102	OCR 网络异常
100103	OCR 摄像头权限异常
300101	OCR 初始化异常
300102	OCR 服务解析异常
300103	OCR 签名失败
300104	OCR 摄像头异常
300105	OCR 初始化配置失败
300106	OCR 图片为空
300107	OCR 授权失败
300108	OCR 系统版本过低
300109	OCR 自动模式超时
300110	OCR SDK 内部错误
300111	OCR 图片裁剪异常
400100	触发指定拦截的告警码
400101	用户传入的证件类型和指定证件类型不一致
400102	用户传入的证件面和选择的面不同
400103	用户传入照片中卡证占比太小
400104	用户传入的照片中包括多张卡证照片
400105	OCR 识别失败
400106	卡证信息校验失败
400107	入参存在错误
400108	内部服务错误
400109	服务未开通 / 账号欠费 / 资源包耗尽 / 计费异常
400110	触发限流
400111	文件 size 太大或无效
400112	文件解析失败

tencent cloud

人脸核身

iOS 接口概述文档

API 概述

VerificationKit

initWithViewController

clearInstance

createMetaData

startVerifiWithConfig

TXYVerifiKitProcessSucceedBlock

TXYVerifiKitProcessFailedBlock

VerificationConfig

﻿

OcrCustomConfig

FaceCustomConfig

VerifiCommDef

HYEkycLanguageType

﻿

VerificationDelegate

onFaceErrorPopupWithView

onFaceAuthEvent

onFaceAuthTipsEvent

OCR 阶段弹窗回调

Loading 回调

Dialog info key 常量

﻿

HYEkycAuthEvent

HYEkycAuthTipsEvent

﻿

错误码与含义

帮助和支持