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

iOS 接口概述文档

Download

聚焦模式

字号

最后更新时间： 2026-08-12 11:08:16

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
/// SDKKIt处理成功回调接口
/// @param errorCode 错误码
/// @param resultInfo 回调返回的信息
/// @param reserved 预留位
typedef void (^TXYVerifiKitProcessSucceedBlock)(int errorCode,id _Nonnull resultInfo, id _Nullable reserved);
TXYVerifiKitProcessFailedBlock
/// SDKKIt处理失败回调接口
/// @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
VerifiCommDef
HYEkycLanguageType
SDK 默认界面的多语言配置信息。
类型
含义
HY_EKYC_DEFAULT = 0
跟随系统语言版本
HY_EKYC_ZH_HANS
简体中文
HY_EKYC_ZH_HANT
繁体中文
HY_EKYC_EN
英语
HY_EKYC_CUSTOMIZE_LANGUAGE
自定义语言，使用设置的自定义语言 bundle（userLanguageBundleName）
﻿
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;
﻿
// 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
﻿
错误码与含义
错误码
错误码含义
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
文件解析失败
﻿

帮助和支持

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

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

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

文档反馈

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（userLanguageBundleName）

错误码	错误码含义
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

﻿

错误码与含义

帮助和支持