tencent cloud

eKYC

Release Notes and Announcements
Release Notes
Product Announcements
Product Introduction
Overview
Strengths
Use Cases
Purchase Guide
Billing Overview
Purchase Method
Payment Overdue
Refund
Integration Guide
Getting Started
Selfie Verification (Pure API)
Selfie Verification (Mobile HTML5)
Selfie Verification (App SDK)
Identity Verification (Mobile HTML5)
Identity Verification (App SDK)
Other Guide
API Documentation
History
Introduction
API Category
Making API Requests
Selfie Verification (Pure API) APIs
Selfie Verification (App SDK) APIs
Identity Verification (App SDK) APIs
Identity Verification(Mobile HTML5) APIs
AI Face Shield (Pure API) APIs
Other APIs
Data Types
Error Codes
FAQs
Contact Us
Glossary
eKYC Policy
Privacy Policy
Data Processing And Security Agreement
Service Level Agreement

iOS custom capabilities

PDF
Focus Mode
Font Size
Last updated: 2026-03-27 11:19:27
This document primarily introduces the custom capabilities supported by the iOS SDK, including customizing multilingual support and customizing the UI.
Note:
Supported version: v1.0.1.5 and above.
Starting from v1.0.1.5, the Bundle configuration field has been changed from "Bundle Name" to "Bundle Absolute Path". If you are migrating from an older version, see the migration instructions at the end of this document.

Custom Multilingual

SDK built-in languages

The SDK supports the following three languages by default, configured via VerificationConfig.languageType:
Enumeration Value
Description
HY_EKYC_DEFAULT
Follows system settings
HY_EKYC_ZH_HANS
Simplified Chinese
HY_EKYC_ZH_HANT
Traditional Chinese
HY_EKYC_EN
English (Default)
HY_EKYC_CUSTOMIZE_LANGUAGE
Custom language
Using built-in languages requires no additional configuration, for example, specifying Simplified Chinese:
VerificationConfig *config = [[VerificationConfig alloc] init];
config.languageType = HY_EKYC_ZH_HANS;

Custom language configuration

If the built-in languages do not meet your requirements, you can provide a custom language Bundle. This Bundle contains all multilingual fields within the SDK, as follows.

Step 1: Build UserLanguageBundle

1. Open the delivery package demo/ directory to find the project files, then locate the Localizable under the UserLanguageBundle directory; this part serves as the translation source file.



2. Locate the UserLanguageBundle (Build Target) in the project.



3. Add language files as needed (such as ja.lproj).



4. Add the new multilingual content to Localizable.strings.



5. Locate the newly added multilingual files in Localizable and translate their content.
// The left side is the Key used by the SDK, and the right side is the translation content in the target language.
"Verifi_OK"="OK";
"Verifi_exit"="Exit";
// ... For the remaining Keys, refer to the Key reference table below.

6. Compile to produce UserLanguageBundle.bundle.



7. If a signature error occurs during compilation, please configure the signature and recompile. After successful compilation, delete the Info.plist and _CodeSignature folders within the Bundle.
8. Import the UserLanguageBundle.bundle into the host project.

Step 2: Configure to the SDK

VerificationConfig *config = [[VerificationConfig alloc] init];
// 1. Enable custom language mode
config.languageType = HY_EKYC_CUSTOMIZE_LANGUAGE;
// 2. Specify the absolute path to the Bundle
config.userLanguageBundlePath = [[NSBundle mainBundle] pathForResource:@"UserLanguageBundle" ofType:@"bundle"];
// 3. Specify the language folder name
config.userLanguageFileName = @"ja.lproj";
Required
Type
Required condition
Description
languageType
Enumeration
Required
Set to HY_EKYC_CUSTOMIZE_LANGUAGE to enable customization only when
userLanguageBundlePath
NSString *
Required when a custom language is used
UserLanguageBundle's absolute path
userLanguageFileName
NSString *
Required when a custom language is used
The target .lproj folder name, such as ja.lproj
Note:
If userLanguageBundlePath is nil, the SDK will look up multilingual resources from the huiyan_verification.bundle in the mainBundle (the default behavior).


Custom UI

Code-level UI customization (no XIB required)

If you only need to adjust styles such as colors and fonts, the SDK provides a lighter-weight configuration class without requiring recompilation of the Bundle.

1. OCR Stage (OcrCustomConfig)

OcrCustomConfig *ocrConfig = [[OcrCustomConfig alloc] init];
ocrConfig.rectNormalColor = [UIColor whiteColor]; // Normal color for the recognition frame
ocrConfig.rectErrorColor = [UIColor redColor]; // Error color for the recognition frame
ocrConfig.rectPassColor = [UIColor greenColor]; // Pass color for the recognition frame
ocrConfig.tipsNormalColor = [UIColor whiteColor]; // Normal color for the prompt text
ocrConfig.tipsErrorColor = [UIColor redColor]; // Error color for the prompt text
ocrConfig.tipsPassColor = [UIColor greenColor]; // Pass color for the prompt text
ocrConfig.tipsFont = [UIFont systemFontOfSize:14]; // Font for the prompt text
ocrConfig.rectScaleX = 0.03; // Horizontal margin ratio for the recognition frame (0.0~0.15)
ocrConfig.rectTopMarginScale = 0.28; // Top margin ratio for the recognition frame (only effective in portrait mode)
ocrConfig.isShowTips = YES; // Show prompt text
ocrConfig.tipsShowText = nil; // Custom prompt text (when set to nil, the SDK default text will be displayed.)

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

2. Selfie Verification stage (FaceCustomConfig)

FaceCustomConfig *faceConfig = [[FaceCustomConfig alloc] init];
faceConfig.backgroundColor = [UIColor blackColor]; // Background color
faceConfig.tipsTextColor = [UIColor whiteColor]; // Prompt text color
faceConfig.tipsTextErrorColor = UIColorFromRGB(0xFF3B30); // Error state color for the prompt text
faceConfig.tipsTextFont = [UIFont systemFontOfSize:16]; // Font for the prompt text
faceConfig.faceCircleErrorColor = UIColorFromRGB(0xFF3B30); // Error state color for the face frame
faceConfig.faceCircleCorrectColor = UIColorFromRGB(0x34C759); // Correct state color for the face frame
faceConfig.countDownTextColor = [UIColor whiteColor]; // Countdown text color
faceConfig.cancelButtonTextColor = [UIColor whiteColor]; // Cancel button text color

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

Adding UI controls (XIB not required)

By using VerificationConfig.delegate, you can monitor the creation and destruction events of the SDK interface, for example, inserting custom logic when the OCR or selfie verification interface is displayed:
VerificationConfig *config = [[VerificationConfig alloc] init];
config.delegate = self; // Implements the VerificationDelegate protocol
// Methods of the VerificationDelegate protocol
@protocol VerificationDelegate <NSObject>
@optional
/// Callback when the OCR interface is displayed, where authView is the root view presented by the SDK
- (void)ocrMainViewCreate:(UIView *)authView;
/// Callback when the OCR interface is removed
- (void)ocrMainViewDestroy;
/// Callback when the selfie verification interface is displayed, authView is the root view presented by the SDK.
- (void)faceMainViewCreate:(UIView *)authView;
/// Callback when the selfie verification interface is removed
- (void)faceMainViewDestroy;
@end
Example:
@interface ViewController ()<VerificationDelegate>
@end
@implementation ViewController

// OCR interface creation callback
- (void)ocrMainViewCreate:(UIView *)authView {
[self addCustomLabel:authView];
}

// Callback when the OCR interface is reclaimed
- (void)ocrMainViewDestroy {
NSLog(@"ekyc ocr vc destroy");
}

// Callback upon creation of the selfie verification interface
- (void)faceMainViewCreate:(UIView *)authView {
[self addCustomLabel:authView];
}

// Callback when the selfie verification interface is reclaimed
- (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


Using XIB to customize the page

The SDK provides two XIB files for the host App to customize the UI, both located under the UserUIBundle build target of the project:
demo/
└── UserUIBundle/
├── TXYOsAuthingViewController.xib # liveness face comparison page
├── CustOcrView.xib # ID document recognition page
├── txy_nav_back.png # Back button icon (replaceable)
└── txy_waring.png # warning icon (replaceable)
XIB file name
corresponding page
Description
TXYOsAuthingViewController
Selfie verification page
Liveness detection and face comparison main page
CustOcrView
Identity document recognition page
OCR capture and recognition main interface
Warning:
You can modify the layout constraints of controls and add new controls, but do not delete existing controls and constraints in the XIB, otherwise it may crash at runtime.




1. Document recognition stage

This page allows you to modify component constraints in the XIB file, such as the cancel button and hint messages. It also supports replacing the back button icon (txy_nav_back).
Note:
Do not modify the constraints of the camera, album, and flashlight controls in the XIB.




2. Selfie Verification stage

This page supports modifying the size and position of components such as viewfinder, hint messages, and countdown Tag in the XIB file.
2.1 Modify the constraints of rectFrameImage to control the size and position of the viewfinder.
2.2 Modify the constraints of tipsLabel to control the position of the tooltip box.
2.3 Modify the constraints of timeoutLabel to control the position of the countdown. You can also configure the font and size.
2.4 Modify the constraints of cancelButton to control the position of the back button. You can also configure the font and size.




3. Build UserUIBundle

3.1 Open the project file in the delivery package demo/ directory.
3.2 Locate the UserUIBundle (Build Target) in the project.
3.3 Modify the layout constraints of TXYOsAuthingViewController.xib or CustOcrView.xib as needed, or add new controls.
3.4 Compile to produce UserUIBundle.bundle.
3.5 If a signature error occurs during compilation, configure the signature and recompile; after successful compilation, delete the Info.plist and _CodeSignature folders within the Bundle.
3.6 Import the UserUIBundle.bundle into the host project.

4. Configure the SDK

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

// Specify the absolute path to the custom UI Bundle
config.userUIBundlePath = [[NSBundle mainBundle] pathForResource:@"UserUIBundle" ofType:@"bundle"];

5. Recommendations for Managing Custom XIB Source Code

It is recommended to copy the entire directory of demo/UserUIBundle/ to the code repository of the host project as the source code directory for custom UI after custom modifications are made. All subsequent modifications will be based on this directory.


Complete configuration example

The following example enables both custom UI and custom multilingual:
VerificationConfig *config = [[VerificationConfig alloc] init];
config.licPath = @"/path/to/license.lic";
config.ekycToken = @"your-ekyc-token";

// --- Custom UI ---
config.userUIBundlePath = [[NSBundle mainBundle] pathForResource:@"UserUIBundle" ofType:@"bundle"];
config.delegate = self; // Optional: Implement VerificationDelegate to listen to UI events

// Code-level style fine-tuning (Optional; use when you don't need to modify XIB files)
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];

// --- Custom Multilingual ---
config.languageType = HY_EKYC_CUSTOMIZE_LANGUAGE;
config.userLanguageBundlePath = [[NSBundle mainBundle] pathForResource:@"UserLanguageBundle" ofType:@"bundle"];
config.userLanguageFileName = @"ja.lproj";

// Start verification
VerificationKit *kit = [[VerificationKit alloc] init];
[kit initWithViewController:self];
[kit startVerifiWithConfig:config withSuccCallback:^(int errorCode, id resultInfo, id reserved) {
// Verification successful
} withFialCallback:^(int errorCode, NSString *errorMsg, id reserved) {
// Verification failed. Error code 311 indicates an exception in the Bundle path configuration.
}];


Error Handling

When Bundle path validation fails, the SDK returns the following error codes via failCallback:
Error Code
Enumeration
Trigger Condition
311
HY_EKYC_BUNDLE_CONFIGURATION_EXCEPTION
The specified Bundle path does not exist or is not a directory.
Error message (errorMsg) is in the format of "<field name> not found", for example:
"userUIBundle not found": The path specified by userUIBundlePath does not exist.
"userLanguageBundle not found": The path specified by userLanguageBundlePath does not exist.


Migration Instructions

Note:
Applicable to users upgrading from v1.0.1.4 and below.
Starting from v1.0.1.5, breaking changes have been made to the Bundle configuration field. The old field has been completely removed. Please update your code according to the following comparison table:
Old field (removed)
New field
Change Description
userUIBundleName
userUIBundlePath
Changed from Bundle name to absolute path
userLanguageBundleName
userLanguageBundlePath
Changed from Bundle name to absolute path
Migration example:
// Old syntax (v1.0.1.4 and below)
config.userUIBundleName = @"UserUIBundle";
config.userLanguageBundleName = @"UserLanguageBundle";

// New syntax (v1.0.1.5 and above)
config.userUIBundlePath = [[NSBundle mainBundle] pathForResource:@"UserUIBundle" ofType:@"bundle"];
config.userLanguageBundlePath = [[NSBundle mainBundle] pathForResource:@"UserLanguageBundle" ofType:@"bundle"];
If the path field is nil, the SDK maintains the same default behavior as the old version (searching for the corresponding Bundle from mainBundle), which does not affect integrators who do not use custom features.


Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback