tencent cloud

人脸核身

文档人脸核身接入文档卡证活体人脸比对（App SDK）接入指引SDK 自定义能力说明iOS 自定义能力

iOS 自定义能力

PDF
聚焦模式
字号
最后更新时间： 2026-03-27 11:19:18
本文档主要介绍 iOS SDK 支持的自定义能力，包括自定义多语言和自定义 UI 两部分。
说明：
适用版本：v1.0.1.5 及以上。
v1.0.1.5 起，Bundle 配置字段由"Bundle 名称"改为"Bundle 绝对路径"。如果您从旧版本迁移，请参考本文末尾的迁移说明。

自定义多语言

SDK 内置语言

SDK 默认支持以下三种语言，通过 VerificationConfig.languageType 配置：
枚举值
含义
HY_EKYC_DEFAULT
跟随系统设置
HY_EKYC_ZH_HANS
简体中文
HY_EKYC_ZH_HANT
繁体中文
HY_EKYC_EN
英文（默认）
HY_EKYC_CUSTOMIZE_LANGUAGE
自定义语言
使用内置语言无需额外配置，例如指定简体中文：
VerificationConfig *config = [[VerificationConfig alloc] init];
config.languageType = HY_EKYC_ZH_HANS;

自定义语言配置

若内置语言不满足需求，可提供自定义语言 Bundle，该 Bundle 包含 SDK 内所有多语言字段，步骤如下。

步骤1：构建 UserLanguageBundle

1. 打开交付包 demo/ 目录下的工程文件，找到 UserLanguageBundle 目录下的 Localizable，该部分为翻译源文件。



2. 在工程中找到 UserLanguageBundle 构建目标（Build Target）。



3. 按需新增语言文件（如 ja.lproj）。



4. 将新增的多语言添加到 Localizable.strings。



5. 在 Localizable 中找到新增的多语言文件，并对内容进行翻译。
// 左侧为 SDK 使用的 Key，右侧为目标语言翻译内容
"Verifi_OK"="OK";
"Verifi_exit"="Exit";
// ... 其余 Key 见下方 Key 参考表

6. 编译出 UserLanguageBundle.bundle。



7. 若编译时出现签名报错，请配置签名后再编译。编译成功后需删除 Bundle 内的 Info.plist 和 _CodeSignature 文件夹。
8. 将 UserLanguageBundle.bundle 导入宿主工程。

步骤2：配置到 SDK

VerificationConfig *config = [[VerificationConfig alloc] init];
// 1. 启用自定义语言模式
config.languageType = HY_EKYC_CUSTOMIZE_LANGUAGE;
// 2. 指定 Bundle 的绝对路径
config.userLanguageBundlePath = [[NSBundle mainBundle] pathForResource:@"UserLanguageBundle" ofType:@"bundle"];
// 3. 指定语言文件夹名称
config.userLanguageFileName = @"ja.lproj";
属性
类型
必填条件
说明
languageType
枚举
必填
设为 HY_EKYC_CUSTOMIZE_LANGUAGE 才启用自定义
userLanguageBundlePath
NSString *
使用自定义语言时必填
UserLanguageBundle 的绝对路径
userLanguageFileName
NSString *
使用自定义语言时必填
目标 .lproj 文件夹名，如 ja.lproj
注意：
若 userLanguageBundlePath 为 nil，SDK 将从 mainBundle 的 huiyan_verification.bundle 中查找多语言资源（默认行为）。


自定义 UI

代码级 UI 定制（无需 XIB）

如果仅需要调整颜色、字体等样式，SDK 提供了更轻量的配置类，无需重新编译 Bundle。

1. 卡证阶段（OcrCustomConfig）

OcrCustomConfig *ocrConfig = [[OcrCustomConfig alloc] init];
ocrConfig.rectNormalColor  = [UIColor whiteColor];   // 识别框正常颜色
ocrConfig.rectErrorColor   = [UIColor redColor];     // 识别框错误颜色
ocrConfig.rectPassColor    = [UIColor greenColor];   // 识别框通过颜色
ocrConfig.tipsNormalColor  = [UIColor whiteColor];   // 提示文字正常颜色
ocrConfig.tipsErrorColor   = [UIColor redColor];     // 提示文字错误颜色
ocrConfig.tipsPassColor    = [UIColor greenColor];   // 提示文字通过颜色
ocrConfig.tipsFont         = [UIFont systemFontOfSize:14]; // 提示文字字体
ocrConfig.rectScaleX       = 0.03;   // 识别框横向边距比例（0.0~0.15）
ocrConfig.rectTopMarginScale = 0.28; // 识别框顶部边距比例（仅竖屏有效）
ocrConfig.isShowTips       = YES;    // 是否显示提示文字
ocrConfig.tipsShowText     = nil;    // 自定义提示文字（nil 时显示 SDK 默认文案）

VerificationConfig *config = [[VerificationConfig alloc] init];
config.ocrCustomConfig = ocrConfig;

2. 活体人脸比对阶段（FaceCustomConfig）

FaceCustomConfig *faceConfig = [[FaceCustomConfig alloc] init];
faceConfig.backgroundColor       = [UIColor blackColor]; // 背景颜色
faceConfig.tipsTextColor         = [UIColor whiteColor]; // 提示文字颜色
faceConfig.tipsTextErrorColor    = UIColorFromRGB(0xFF3B30); // 提示文字错误态颜色
faceConfig.tipsTextFont          = [UIFont systemFontOfSize:16]; // 提示文字字体
faceConfig.faceCircleErrorColor  = UIColorFromRGB(0xFF3B30); // 圆框错误态颜色
faceConfig.faceCircleCorrectColor = UIColorFromRGB(0x34C759); // 圆框正确态颜色
faceConfig.countDownTextColor    = [UIColor whiteColor]; // 倒计时文字颜色
faceConfig.cancelButtonTextColor = [UIColor whiteColor]; // 取消按钮文字颜色

VerificationConfig *config = [[VerificationConfig alloc] init];
config.faceCustomConfig = faceConfig;

新增 UI 控件（无需 XIB）

通过 VerificationConfig.delegate 可监听 SDK 界面的创建与销毁事件，例如在 OCR 或活体人脸比对界面显示时插入自定义逻辑：
VerificationConfig *config = [[VerificationConfig alloc] init];
config.delegate = self; // 实现 VerificationDelegate 协议
// VerificationDelegate 协议方法
@protocol VerificationDelegate <NSObject>
@optional
/// OCR 界面显示时回调，authView 为 SDK 展示的根视图
- (void)ocrMainViewCreate:(UIView *)authView;
/// OCR 界面被移除时回调
- (void)ocrMainViewDestroy;
/// 活体人脸比对界面显示时回调，authView 为 SDK 展示的根视图
- (void)faceMainViewCreate:(UIView *)authView;
/// 活体人脸比对界面被移除时回调
- (void)faceMainViewDestroy;
@end
例如：
@interface ViewController ()<VerificationDelegate>
@end
@implementation ViewController

// OCR界面创建回调
- (void)ocrMainViewCreate:(UIView *)authView {
    [self addCustomLabel:authView];
}

// OCR界面被回收的回调
- (void)ocrMainViewDestroy {
    NSLog(@"ekyc ocr vc destroy");
}

// 活体人脸比对界面创建回调
- (void)faceMainViewCreate:(UIView *)authView {
    [self addCustomLabel:authView];
}

// 活体人脸比对界面被回收的回调
- (void)faceMainViewDestroy {
    NSLog(@"ekyc face vc destroy");
}

- (void)addCustomLabel:(UIView *)authView {
    UILabel *label = [[UILabel alloc]initWithFrame:CGRectMake(0, 100, 100, 30)];
    label.backgroundColor = [UIColor blackColor];
    label.textColor = [UIColor yellowColor];
    label.text = @"This is a newly added control";
    label.font = [UIFont systemFontOfSize:20];
    label.textAlignment = NSTextAlignmentCenter;
        [authView addSubview:label];
}
@end


使用 XIB 自定义页面

SDK 提供两个 XIB 文件供宿主 App 自定义 UI，均位于工程的 UserUIBundle 构建目标下：
demo/
└── UserUIBundle/
    ├── TXYOsAuthingViewController.xib   # 活体人脸比对页面
    ├── CustOcrView.xib                  # 证件识别页面
    ├── txy_nav_back.png                 # 返回按钮图标（可替换）
    └── txy_waring.png                   # 提示图标（可替换）
XIB 文件名
对应页面
说明
TXYOsAuthingViewController
人脸核身页面
活体检测与人脸比对的主界面
CustOcrView
卡证识别页面
OCR 拍摄与识别的主界面
警告：
可修改控件的布局约束、添加新控件，但不允许删除 XIB 中已有的控件及约束，否则运行时可能崩溃。




1. 证件识别阶段

该页面支持修改 XIB 文件中组件约束，如取消按钮、提示信息。支持替换返回按钮 icon（txy_nav_back）等。
注意：
不允许修改 XIB 中拍照、相册、手电筒控件的约束。




2. 活体人脸比对阶段

该页面支持修改XIB文件中取景框、提示信息、倒计时标签组件的大小和位置。
2.1 修改 rectFrameImage 的约束，可控制取景框大小和位置。
2.2 修改 tipsLabel 的约束，可控制提示框的位置。
2.3 修改 timeoutLabel 的约束，可控制倒计时的位置。也可配置字体及大小。
2.4 修改 cancelButton 的约束，可控制返回按钮的位置。也可配置字体及大小。




3. 构建 UserUIBundle

3.1 打开交付包 demo/ 目录下的工程文件。
3.2 在工程中找到 UserUIBundle 构建目标（Build Target）。
3.3 按需修改 TXYOsAuthingViewController.xib 或 CustOcrView.xib 的布局约束，或新增控件。
3.4 编译出 UserUIBundle.bundle。
3.5 若编译时出现签名报错，请配置签名后再编译；编译成功后需删除 Bundle 内的 Info.plist 和 _CodeSignature 文件夹。
3.6 将 UserUIBundle.bundle 导入宿主工程。

4. 配置到 SDK

VerificationConfig *config = [[VerificationConfig alloc] init];

// 指定自定义 UI Bundle 的绝对路径
config.userUIBundlePath = [[NSBundle mainBundle] pathForResource:@"UserUIBundle" ofType:@"bundle"];

5. 自定义 XIB 源码管理建议

若自定义修改后，建议将 demo/UserUIBundle/ 整个目录拷贝到宿主工程的代码仓库中，作为自定义 UI 的源码目录，后续所有修改均基于此目录进行。


完整配置示例

以下示例同时启用自定义 UI 和自定义多语言：
VerificationConfig *config = [[VerificationConfig alloc] init];
config.licPath    = @"/path/to/license.lic";
config.ekycToken  = @"your-ekyc-token";

// --- 自定义 UI ---
config.userUIBundlePath = [[NSBundle mainBundle] pathForResource:@"UserUIBundle" ofType:@"bundle"];
config.delegate = self;  // 可选：实现 VerificationDelegate 监听 UI 事件

// 代码级样式微调（可选，不需要修改 XIB 时使用）
config.ocrCustomConfig.rectNormalColor = [UIColor colorWithWhite:1.0 alpha:0.8];
config.faceCustomConfig.backgroundColor = [UIColor colorWithRed:0.1 green:0.1 blue:0.1 alpha:1.0];

// --- 自定义多语言 ---
config.languageType = HY_EKYC_CUSTOMIZE_LANGUAGE;
config.userLanguageBundlePath = [[NSBundle mainBundle] pathForResource:@"UserLanguageBundle" ofType:@"bundle"];
config.userLanguageFileName = @"ja.lproj";

// 启动验证
VerificationKit *kit = [[VerificationKit alloc] init];
[kit initWithViewController:self];
[kit startVerifiWithConfig:config withSuccCallback:^(int errorCode, id resultInfo, id reserved) {
    // 验证成功
} withFialCallback:^(int errorCode, NSString *errorMsg, id reserved) {
    // 验证失败，错误码 311 表示 Bundle 路径配置异常
}];


错误处理

Bundle 路径校验失败时，SDK 通过 failCallback 返回以下错误码：
错误码
枚举
触发条件
311
HY_EKYC_BUNDLE_CONFIGURATION_EXCEPTION
某个 Bundle 路径不存在或不是目录
错误信息（errorMsg）格式为 "<字段名> not found"，例如：
"userUIBundle not found"：userUIBundlePath 指向的路径不存在
"userLanguageBundle not found"：userLanguageBundlePath 指向的路径不存在


迁移说明

说明：
适用于从 v1.0.1.4 及以下版本升级的用户。
v1.0.1.5 对 Bundle 配置字段做了破坏性变更，旧字段已完全删除，请按以下对照表更新代码：
旧字段（已删除）
新字段
变更说明
userUIBundleName
userUIBundlePath
由 Bundle 名称改为绝对路径
userLanguageBundleName
userLanguageBundlePath
由 Bundle 名称改为绝对路径
迁移示例：
// 旧写法（v1.0.1.4 及以下）
config.userUIBundleName = @"UserUIBundle";
config.userLanguageBundleName = @"UserLanguageBundle";

// 新写法（v1.0.1.5 及以上）
config.userUIBundlePath = [[NSBundle mainBundle] pathForResource:@"UserUIBundle" ofType:@"bundle"];
config.userLanguageBundlePath = [[NSBundle mainBundle] pathForResource:@"UserLanguageBundle" ofType:@"bundle"];
若路径字段为 nil，SDK 保持与旧版本相同的默认行为（从 mainBundle 中查找对应 Bundle），不影响未使用自定义功能的接入方。

上一篇: Android 自定义能力下一篇: 常见问题与修复指引

帮助和支持

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

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

文档反馈