iOS 自定义能力
Download
聚焦模式
字号
本文档主要介绍 iOS SDK 支持的自定义能力，包括自定义多语言和自定义 UI 两部分。
一、自定义多语言
SDK 内置语言
SDK 默认支持以下语言，通过
HuiYanOsConfig.languageType 配置：枚举值 | 含义 |
HY_DEFAULT | 跟随系统设置（默认） |
HY_CUSTOMIZE_LANGUAGE | 自定义语言 |
使用内置语言无需额外配置，例如跟随系统：
HuiYanOsConfig *config = [[HuiYanOsConfig alloc] init];config.languageType = HY_DEFAULT;
自定义语言配置
若内置语言不满足需求，可提供自定义语言 Bundle，该 Bundle 包含 SDK 内所有多语言字段，步骤如下。
步骤1：构建 UserLanguageBundle
1. 打开交付包
demo/ 目录下的工程文件，找到 UserLanguageBundle 目录下的 Localizable，该部分为翻译源文件。
2. 在工程中找到
UserLanguageBundle 构建目标（Build Target）。
3. 按需新增语言文件（如
ar.lproj）。
4. 将新增的多语言添加到
Localizable.strings。
5. 在
Localizable 中找到新增的多语言文件，并对内容进行翻译：
// 左侧为 SDK 使用的 Key，右侧为目标语言翻译内容"Verifi_OK" = "OK";"Verifi_exit" = "Exit";// ... 其余 Key 见交付包内 Localizable 文件
6. 编译出
UserLanguageBundle.bundle。
7. 若编译时出现签名报错，请配置签名后再编译。编译成功后需删除 Bundle 内的
Info.plist 和 _CodeSignature 文件夹。8. 将
UserLanguageBundle.bundle 导入宿主工程。步骤2：配置到 SDK
HuiYanOsConfig *config = [[HuiYanOsConfig alloc] init];// 1. 启用自定义语言模式config.languageType = HY_CUSTOMIZE_LANGUAGE;// 2. 指定 Bundle 的绝对路径config.languageBundlePath = [[NSBundle mainBundle] pathForResource:@"UserLanguageBundle" ofType:@"bundle"];// 3. 指定语言文件夹名称config.userLanguageFileName = @"ja.lproj";
属性 | 类型 | 必填条件 | 说明 |
languageType | 枚举 | 必填 | 设为 HY_CUSTOMIZE_LANGUAGE 才启用自定义 |
languageBundlePath | NSString * | 使用自定义语言时必填 | UserLanguageBundle 的绝对路径 |
userLanguageFileName | NSString * | 使用自定义语言时必填 | 目标 .lproj 文件夹名，如 ja.lproj |
注意：
若
languageBundlePath 为 nil，SDK 将从 mainBundle 中查找多语言资源（默认行为）。二、自定义 UI
代码级 UI 定制（无需 XIB）
如果仅需调整颜色、字体等样式，SDK 提供了配置字段，无需重新编译 Bundle。
HuiYanOsConfig *config = [[HuiYanOsConfig alloc] init];// 设置出现操作错误时提示文本的颜色config.feedBackErrorColor = 0xFF584C;// 设置操作正确时提示文本的颜色config.feedBackTxtColor = 0xFF0000;// 设置出现操作错误时圆形框的颜色config.authCircleErrorColor = 0xFF584C;// 当动作正确时设置圆形框的颜色config.authCircleCorrectColor = 0x29CC85;// 设置识别页面背景颜色config.authLayoutBgColor = 0xFFFFFF;// 设置提示文本字体和大小config.feedBackTxtFont = [UIFont systemFontOfSize:18];// 设置其他提示文本字体和大小config.feedbackExtraTxtFont = [UIFont systemFontOfSize:18];// 设置倒计时文字颜色config.countDownTxtColor = 0xFFFFFF;// 设置取消按钮文字颜色config.cancelTxtColor = 0xFFFFFF;// 设置是否显示内部对话框，默认为 YESconfig.isShowDialog = YES;// 设置隐藏核身头像引导框，默认为 NOconfig.isHideAvatarGuideFrame = NO;
新增 UI 控件（无需 XIB）
通过
HuiYanOsConfig.delegate 可监听 SDK 界面的创建与销毁事件，在核身页面显示时插入自定义控件：HuiYanOsConfig *config = [[HuiYanOsConfig alloc] init];config.delegate = self; // 实现 HuiYanOverseasDelegate 协议
// HuiYanOverseasDelegate 协议方法@protocol HuiYanOverseasDelegate <NSObject>@required/// 核身主界面显示时回调，authView 为 SDK 展示的根视图- (void)onMainViewCreate:(UIView *)authView;@optional/// 核身界面被移除时回调- (void)onMainViewDestroy;@end
示例：在核身页面插入自定义标签：
@interface ViewController ()<HuiYanOverseasDelegate>@end@implementation ViewController- (void)onMainViewCreate:(UIView *)authView {UILabel *label = [[UILabel alloc] initWithFrame:CGRectMake(0, 100, 200, 30)];label.backgroundColor = [UIColor blackColor];label.textColor = [UIColor yellowColor];label.text = @"Custom Label";label.font = [UIFont systemFontOfSize:16];label.textAlignment = NSTextAlignmentCenter;[authView addSubview:label];}- (void)onMainViewDestroy {NSLog(@"huiyan face vc destroy");}@end
修改 UI 控件（无需 XIB）
控件名称 | 控件描述 | tag 值 |
cancelButton | 活体核身页面取消/返回按钮 | 101 |
timeoutLabel | 活体核身页面倒计时标签 | 102 |
tipsLabel | 活体核身页面提示文字 | 103 |
fakeNavBarView | 活体核身页面虚拟导航栏 | 200 |
通过
onMainViewCreate: 回调，可在核身页面创建后直接通过 viewWithTag: 获取以上控件并进行修改。示例：修改活体核身页面各控件样式
- (void)onMainViewCreate:(UIView *)authView {// 修改取消按钮图标UIButton *cancelButton = (UIButton *)[authView viewWithTag:101];UIImage *backImage = [UIImage systemImageNamed:@"chevron.left"];[cancelButton setImage:backImage forState:UIControlStateNormal];// 修改取消按钮的 leading 左边距约束for (NSLayoutConstraint *constraint in cancelButton.superview.constraints) {if ((constraint.firstItem == cancelButton && constraint.firstAttribute == NSLayoutAttributeLeading) ||(constraint.secondItem == cancelButton && constraint.secondAttribute == NSLayoutAttributeLeading)) {constraint.constant = 16.0;break;}}// 修改倒计时标签颜色和字体UILabel *timeoutLabel = (UILabel *)[authView viewWithTag:102];timeoutLabel.textColor = [UIColor whiteColor];timeoutLabel.font = [UIFont systemFontOfSize:15];// 修改虚拟导航栏背景颜色UIView *navBarView = [authView viewWithTag:200];navBarView.backgroundColor = [UIColor colorWithRed:0.05 green:0.05 blue:0.1 alpha:1.0];// 在虚拟导航栏上增加自定义标题CGFloat statusBarHeight = [UIApplication sharedApplication].statusBarFrame.size.height;CGRect frame = CGRectMake(0, statusBarHeight, navBarView.bounds.size.width, navBarView.bounds.size.height - statusBarHeight);UILabel *titleLabel = [[UILabel alloc] initWithFrame:frame];titleLabel.text = @"Custom Title";titleLabel.textColor = [UIColor whiteColor];titleLabel.textAlignment = NSTextAlignmentCenter;[navBarView addSubview:titleLabel];}
说明：
1. 修改前建议对控件进行非空判断（
if (view) { ... }），防止控件不存在时引发崩溃。2. 代码级样式配置（如
feedBackErrorColor）与回调中的控件修改可以同时使用，回调中的修改将覆盖对应控件的最终效果。使用 XIB 自定义页面
SDK 提供 XIB 文件供宿主 App 完整自定义活体核身页面布局，位于工程的
UserUIBundle 构建目标下：demo/└── UserUIBundle/└── TXYOsAuthingViewController.xib # 活体核身主页面
XIB 文件名 | 对应页面 | 说明 |
TXYOsAuthingViewController | 活体核身主页面 | 活体检测与人脸比对的主界面 |
警告：
可修改控件的布局约束、添加新控件，但**不允许删除 XIB 中已有的控件，否则运行时可能崩溃。
1. 活体核身页面（TXYOsAuthingViewController.xib）
该页面支持修改以下组件的大小和位置：
rectFrameImage：修改约束可控制取景框大小和位置。
tipsLabel：修改约束可控制提示文字的位置。
timeoutLabel：修改约束可控制倒计时标签的位置。
cancelButton：修改约束可控制返回按钮的位置。
2. 构建 UserUIBundle
1. 打开交付包
demo/ 目录下的工程文件。2. 在工程中找到
UserUIBundle 构建目标（Build Target）。3. 按需修改
TXYOsAuthingViewController.xib 的布局约束，或新增控件。4. 编译出
UserUIBundle.bundle。5. 若编译时出现签名报错，请配置签名后再编译；编译成功后需删除 Bundle 内的
Info.plist 和 _CodeSignature 文件夹。6. 将
UserUIBundle.bundle 导入宿主工程。3. 配置到 SDK
HuiYanOsConfig *config = [[HuiYanOsConfig alloc] init];// 指定 HuiYanSDKUI Bundle 的绝对路径（必填）config.huiyanSdkUIBundlePath = [[NSBundle mainBundle] pathForResource:@"HuiYanSDKUI" ofType:@"bundle"];// 指定自定义 UI Bundle 的绝对路径config.userUIBundlePath = [[NSBundle mainBundle] pathForResource:@"UserUIBundle" ofType:@"bundle"];
4. 自定义 XIB 源码管理建议
建议将
demo/UserUIBundle/ 整个目录拷贝到宿主工程的代码仓库中，作为自定义 UI 的源码目录，后续所有修改均在此目录进行，便于随项目一起版本管理。完整配置示例
以下示例同时启用自定义 UI 和自定义多语言：
HuiYanOsConfig *config = [[HuiYanOsConfig alloc] init];config.authLicense = [[NSBundle mainBundle] pathForResource:@"license" ofType:@""];// --- 自定义 UI ---// Bundle 路径（必填）config.huiyanSdkUIBundlePath = [[NSBundle mainBundle] pathForResource:@"HuiYanSDKUI" ofType:@"bundle"];config.faceTrackerBundlePath = [[NSBundle mainBundle] pathForResource:@"face-tracker-v003" ofType:@"bundle"];// 自定义 UI Bundle（可选）config.userUIBundlePath = [[NSBundle mainBundle] pathForResource:@"UserUIBundle" ofType:@"bundle"];// 代码级样式微调（可选）config.feedBackErrorColor = 0xFF584C;config.authCircleCorrectColor = 0x29CC85;// 实现 delegate 监听 UI 事件（可选）config.delegate = self;// --- 自定义多语言 ---config.languageType = HY_CUSTOMIZE_LANGUAGE;config.languageBundlePath = [[NSBundle mainBundle] pathForResource:@"UserLanguageBundle" ofType:@"bundle"];config.userLanguageFileName = @"ja.lproj";// 启动核身[[HuiYanOSKit sharedInstance] startHuiYaneKYC:@"your-face-token"withConfig:configwithSuccessCallback:^(HuiYanOsAuthResult *authResult, id reserved) {// 核身成功，使用 authResult.faceToken 查询结果} withFailCallback:^(int errCode, NSString *errMsg, id reserved) {// 核身失败，错误码 HY_BUNDLE_CONFIGURATION_EXCEPTION(307) 表示 Bundle 路径配置异常}];
三、错误处理
Bundle 路径校验失败时，SDK 通过
failCallback 返回以下错误码：错误码 | 枚举 | 触发条件 |
307 | HY_BUNDLE_CONFIGURATION_EXCEPTION | 某个 Bundle 路径不存在或不合法 |
错误信息（
errMsg）示例："HuiYanSDKUI bundle path is not found"：huiyanSdkUIBundlePath 指向的路径不存在"face-tracker-v003 bundle path is not found"：faceTrackerBundlePath 指向的路径不存在"user bundle is invalid"：userUIBundlePath 指向的路径不存在"user language bundle is not found"：languageBundlePath 指向的路径不存在四、迁移说明
v1.0.9.11 对 Bundle 配置字段做了变更，由"Bundle 名称"改为"Bundle 绝对路径"，请按以下对照表更新代码：
旧字段 | 新字段 | 变更说明 |
userUIBundleName | userUIBundlePath | 由 Bundle 名称改为绝对路径 |
userLanguageBundleName | languageBundlePath | 由 Bundle 名称改为绝对路径 |
迁移示例：
// 旧写法（v1.0.9.10 及以下）config.userUIBundleName = @"UserUIBundle";config.userLanguageBundleName = @"UserLanguageBundle";// 新写法（v1.0.9.11 及以上）config.userUIBundlePath = [[NSBundle mainBundle] pathForResource:@"UserUIBundle" ofType:@"bundle"];config.languageBundlePath = [[NSBundle mainBundle] pathForResource:@"UserLanguageBundle" ofType:@"bundle"];
若路径字段为
nil，SDK 保持与旧版本相同的默认行为（从 mainBundle 中查找对应 Bundle），不影响未使用自定义功能的接入方。
文档反馈