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 API Description

PDF
Focus Mode
Font Size
Last updated: 2026-02-11 16:08:25

API Detailed Description

The eKYC SDK mainly includes the following classes and APIs: the API class HuiYanOSKit, the parameter configuration class HuiYanOSConfig, and the result callback APIs HuiYanOKitSuccessCallback and HuiYanOKitFailCallback.

HuiYanOSKit

API
Description
Enter liveness detection process of the SDK.
API for releasing SDK resources.
startHuiYaneKYC
Feature introduction:
Enable the liveness detection SDK, configure it, and handle the returned results or errors through callbacks.
/// Enable the liveness detection process.
/// @param faceToken token
/// @param kitConfig SDK configuration.
/// @param succCallback Callback for successful liveness detection.
/// @param failCallback Callback for failed liveness detection.
- (void)startHuiYaneKYC:(NSString *)faceToken withConfig:(HuiYanOsConfig *)kitConfig
witSuccCallback:(HuiYanOKitSuccCallback)succCallback
withFailCallback:(HuiYanOKitFailCallback)failCallback;
Input parameters:
Type
Parameter
Description
NSString
faceToken
Selfie verification process token
kitConfig
SDK configuration class
successCallback
Callback for successful selfie verification
failCallback
Callback for failed selfie verification
clearInstance()
Feature introduction:
The API for releasing resources of SDK.
+ (void)clearInstance;

HuiYanOSConfig

HuiYanOSConfig is the configuration entity class that is used when initiating the SDK. It primarily contains the following properties.
Type
Name
Description
Default Value
NSString
authLicense
Name of the License file for user authentication authorized by the customer.
N/A
long
prepareTimeoutMs
Sets the timeout period for the detection during the preparation phase.
30000 milliseconds (30s)
long
actionTimeoutMs
Set the timeout period for the motion detection phase.
30000 milliseconds (30s)
showTimeoutMode
Sets to display the countdown phase.
HYShowTimeoutMode_PREPARE
BOOL
isDeleteVideoCache
Whether to delete the local cache of the selfie verification video
YES
BOOL
isShowTipsPage
Whether to display the guide page
NO
NSString
userUIBundleName
Custom UI bundle filename; for example, set UserUIBundle for UserUIBundle.bundle
nil
NSString
userLanguageFileName
Custom languageBundle name; for example, set UseLanguage for UseLanguage.bundle.
nil
NSString
userLanguageBundleName
Custom local file name for internationalization; for example, set en for en.lproj.
nil
languageType
Text language settings inside the SDK
DEFAULT
NSString
setLanguageFileName
Language file directory name added in HuiYanSDKUI.bundle has the highest priority by default
nil
BOOL
isHideAvatarGuideFrame
Sets whether to hide the profile picture guidance box during identity verification process.
NO
id<HuiYanOverseasDelegate>
delegate
Event callback.
N/A
NSUInteger
feedbackErrorColor
Color of the tips for abnormal feedback.
0xFF584C
NSUInteger
feedbackTextColor
Color of the tips for normal feedback.
0x29CC85
NSUInteger
authCircleErrorColor
Color of the background circular frame when a motion is performed incorrectly.
0xFF584C
NSUInteger
authCircleCorrectColor
Color of the background circular frame when a motion is performed correctly
0x29CC85
NSUInteger
authLayoutBgColor
Color of the background on the identity verification page (if not specified, it will follow the system settings: white background in light mode, black background in dark mode).
-100
UIFont
feedbackTxtFont
Font and size of the verification prompt text.
18
UIFont
feedbackExtraTxtFont
Size of additional prompt text.
18
BOOL
isShowDialog
Whether to display the internal dialog.
YES
NSString
huiyanSdkUIBundlePath
Sets path for the HuiYanSDKUI.bundle file (required when the file is not located within the mainBundle).
nil
NSString
userUIBundlePath
Sets path for the UserUIBundle.bundle file (required when the file is not located within the mainBundle; it is essential when using a custom UI).
nil
NSString
languageBundlePath
Sets path for the LanguageSrcBundle.bundle file (required when the file is not located within the mainBundle; it is essential when using a custom multilingual setup).
nil
NSString
faceTrackerBundlePath
Sets path for the face-tracker file (required when the file is not located within the mainBundle).
nil
BOOL
isShowPrivacyAgreementDialog
Whether to display the privacy policy pop-up.
YES
BOOL
isHideAvatarGuideFrame
Sets whether to hide the profile picture guidance box.
NO
BOOL
isUseBackCamera
Whether to use the rear camera.
NO
UIColor
loadingLayoutBgColor
Color of the loading page background.
nil
UIColor
feedbackExtraTipColor
Color of extra tips.
nil
UIColor
loadingTextColor
Color of text on the loading page.
nil
CameraZoom
zoomType
Sets the camera focal length. This is usually used when the rear camera is enabled.
ZOOM_1X
CGFloat
smallfaceRatioThreshold
Minimum proportion of the face area.
0.5
CGFloat
bigfaceRatioThreshold
Maximum proportion of the face area.
0.8
BOOL
isOpenBOTCheck
Whether to enable BOT mode.
NO
CGFloat
longCheckTimeoutMs
Sets the timeout period for the duration detection phase.
30000 milliseconds (30s)
BOOL
disableSystemRecordScreen
Whether to prohibit the system from recording videos during the identity verification process.
NO
BOOL
isOtherActionCheckMouthOpen
Whether to prohibit opening mouth during motion detection? (Apart from the detection of mouth-opening motions)
NO
NSUInteger
countdownTxtColor
Sets the color of countdown.
0x000000
NSUInteger
cancelTxtColor
Sets the color of return button.
0x000000
FaceAngleValidationLevel
faceAngleValidation
Face angle detection level; the default setting is “Loose” mode.
FaceAngleValidationLevelLoose
BOOL
openCheckRiskMode
Whether to enable risk detection.Enhance and Plus versions require this field to be enabled for their capabilities
NO
NSString
riskLicense
Path to the risk detection authorization file.The Enhance version and Plus version capabilities need to be passed into this path
nil
BOOL
supportSystemAdjustsFont
Whether to respond to adjustments in font size within the system settings.
NO
BOOL
isShowNoPermissionDialog
Whether to configure to display a pop-up for camera permission, and guide users through the process of granting this permission.
NO
BOOL
isEntireHighlight
During the face recognition process, whether to remain the brightness of the phone screen at its maximum level throughout the entire process.
YES

HuiYanOKitSuccCallback

/**
* Callback for successful liveness detection and face comparison
*
* @param authResult Liveness detection and face comparison result
* @param reserved Reserved
*/
typedef void (^HuiYanOKitSuccCallback)(HuiYanOsAuthResult * _Nonnull authResult, id _Nullable reserved);

HuiYanOKitFailCallback

/**
* Callback for failed liveness detection and face comparison
*
* @param errCode Error code
* @param errMsg Error message
* @param reserved Reserved
*/
typedef void (^HuiYanOKitFailCallback)(int errCode, NSString * _Nonnull errMsg ,id _Nullable reserved);

LanguageType

The SDK includes internationalized strings.
typedef enum : NSUInteger {
DEFAULT = 0,//Auto
ZH_HANS,//Simplified Chinese
ZH_HANT,//Traditional Chinese
ZH_HK,//Traditional Chinese (Hong Kong)
ZH_TW,//Traditional Chinese (Taiwan)
EN,//English
MS,//Malaysian
RU,//Russian
JA,//Japanese
CUSTOMIZE_LANGUAGE, //Custom language
} LanguageType;

HYShowTimeOutMode

typedef NS_OPTIONS(int, HYShowTimeOutMode) {
HYShowTimeOutMode_TIMEOUT_HIDDEN = 1 << 0,// Hide all countdowns.
HYShowTimeOutMode_PREPARE = 1 << 1,// Countdown for the preparation phase.
HYShowTimeOutMode_ACTION = 1 << 3,// Countdown for the motion detection phase.
};
HuiYanOverseasDelegate
@protocol HuiYanOverseasDelegate <NSObject>
@required
// Identity verification event.
- (void)onAuthEvent:(HYAuthEvent)actionEvent;
// Notification callback for events where the tips change during identity verification.
- (void)actionCallbackType:(HYAuthTipsEvent)actionType;
// The callback when the authenticated main View is created.
- (void)onMainViewCreate:(UIView *)authView;
@optional
// The callback when the interface is reclaimed.
- (void)onMainViewDestroy;
@end
HuiYanOsAuthResult
Parameter type
Parameter name
Description
NSString
faceToken
Liveness process token.
Finally, it is necessary to use this token to access the backend API GetFaceIdResultIntl of Tencent Cloud API to obtain the final result indicating whether the liveness detection was successful or not.
FaceAngleValidationLevel
FaceAngleValidationLevel Type
Description
FaceAngleValidationLevelLoose
In the loose mode, a face rotation of approximately 30 degrees is allowed; moreover, if the rotation angle exceeds this limit, the recognition detection process will not automatically terminate.
FaceAngleValidationLevelMedium
In the medium mode, a face rotation of approximately 20 degrees is allowed; moreover, if the rotation angle exceeds this limit, the recognition detection process will automatically terminate.
FaceAngleValidationLevelStrict
In the strict mode, a face rotation of approximately 10 degrees is allowed; moreover, if the rotation angle exceeds this limit, the recognition detection process will automatically terminate.

SDK Terminal Error Codes (iOS)

Error code
Value
Description
HY_SUCCESS
0
Success.
HY_INITIALIZATION_PARAMETER_EXCEPTION
210
Initialization parameter exception.
HY_BUNDLE_CONFIGURATION_EXCEPTION
211
Bundle configuration exception.
HY_YTSDK_CONFIGURATION_EXCEPTION
212
YouTu configuration exception.
HY_PLEASE_CALL_FIRST_INIT_API
213
It is necessary to initialize the API first.
HY_SDK_AUTH_FAILED
214
SDK authorization failed.
HY_USER_VOLUNTARILY_CANCELED
215
The user voluntarily cancels.
HY_YTSDK_LOCAL_AUTH_FAILED
216
SDK local face detection failed.
HY_CAMERA_OPEN_FAIL
217
Failed to enable the camera.
HY_DONOT_SWITCH_APPS
218
Please do not switch applications during the identity verification process.
HY_CAMERA_PERMISSION_EXCEPTION
219
Camera permission exception.
HY_SDK_VIDEO_CUT_EXCEPTION
220
Video cropping failed.
HY_LIGHT_DATA_FORMAT_EXCEPTION
221
Incorrect light data format.
HY_DETECT_TIMEOUT
222
Motion detection timeout.
HY_LIMIT_SET_PKG_SIZE
223
The size exceeds the limits set for the package.
HY_USE_BACK_CAMERA_WITH_REFLECTIVE_ERROR
227
The input data contains reflective elements. Please use the front camera.
HY_NETWORK_ERROR
272
Network exception.
HY_PREPARE_TIMEOUT
300
Preparation phase timeout.
HY_LONGCHECK_TIMEOUT
301
Duration detection timeout.
HY_DONOT_ALLOW_RECORDING
302
Please do not enable video recording during the identity verification process.
HY_DONOT_ALLOW_SCREENSHOTS
303
Please do not take screenshots during the identity verification process.
HY_TURING_CONFIG_MISMATCH_EXCEPTION
400
The risk control module configuration does not match, and the openCheckRiskMode configuration in HuiYanOsConfig does not match the SDKVersion input parameter of the GetFaceIdTokenIntl or ApplySdkVerificationToken interface
FAQs
1. When using pod integration, if an error such as “Undefined symbol HuiYanSDKoccurs, or if any other frameworks cannot be found,then go to"TARGETS−>BuildSettings−>OtherLinkerFlags and add (inherited).”
2. The console displays an error message stating either authLicense is empty or auth failed.
Check that the license file has been correctly configured in HuiYanBaseConfig. If the value of “config.authLicense” is not specified, an error will occur.
TARGETS -> BuildPhases -> copyBundleResources Check whether the license exists.
Verify whether the license file contains the project package name.
3. An error occurred when running the Xcode simulator: “Undefined symbols OBJC_CLASS$_HuiYanOSKit” It is necessary to modify the Xcode settings. Go to “Build Settings” and add “arm64” to the list of “Excluded Architectures” before you can run the application.


Help and Support

Was this page helpful?

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

Feedback