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

Android API Description

PDF
Focus Mode
Font Size
Last updated: 2026-03-27 11:21:37

Detailed Documentation for the API

The eKYC SDK primarily involves the following classes: HuiYanOsApi (API interface class), HuiYanOsConfig (parameter configuration class), HuiYanOsAuthCallback (result callback class), and HuiYanAuthEventCallback (authentication event callback class).

HuiYanOsApi

API
Feature Description
Initialization APIs
Resource Release APIs
Set the callback for key actions during selfie verification.
Streamlined overseas selfie verification APIs. Simply call this API to complete the entire selfie verification process.

init()

Feature Introduction:
eKYC SDK initialization APIs.
public static void init(Context context)
Parameters:
Parameter Type
Parameter Name
Parameter Description
Context
context
App context information

release()

Feature Introduction:
eKYC SDK resource release APIs.
public static void release()

setAuthEventCallback()

Feature Introduction:
To register callbacks for key actions during selfie verification.
public static void setAuthEventCallBack(HuiYanAuthEventCallBack huiYanAuthEventCallBack)
Parameters:
Parameter Type
Parameter Name
Parameter Description
huiYanAuthEventCallback
Callback for key actions during selfie verification

startHuiYanAuth()

Feature Introduction:
Overseas selfie verification APIs. Simply call this API to complete the entire selfie verification process.
public static void startHuiYanAuth(final String startToken, final HuiYanOsConfig startConfig, HuiYanOsAuthCallBack authCallBack)
Parameters:
Parameter Type
Parameter Name
Parameter Description
String
startToken
Business Token retrieved from the server to initiate selfie verification.
startConfig
Configuration parameters
authCallback
Callback for liveness results

HuiYanOsConfig

The HuiYanOsConfig is the configuration entity class used when the eKYC SDK is initialized, primarily containing the following attributes.
Type
Name
Meaning
Default Value
pageColorStyle
The color scheme for this selfie verification.
PageColorStyle.Light
String
authLicense
Customer's user selfie verification authorization Licens file name
Empty
String
riskLicense
Customer's device risk control authorization License file name. The path must be provided for enhanced and Plus edition capabilities.
Null
long
authTimeOutMs
Set the timeout for liveness detection.
10000 milliseconds (10 seconds)
boolean
openCheckRiskMode
Whether to enable the device risk control detection switch. This field must be enabled for Enhance and Plus edition capabilities.
false
boolean
isDeleteVideoCache
Whether to delete the local cache of selfie verification videos.
true
boolean
isShowGuidePage
Whether to enable the selfie verification guide page.
true
languageStyle
Language type
Follow system language
String
languageCode
Language code (see Appendix), used in conjunction with languageStyle.
Empty
String[]
backupIPs
Backup IP list
Empty
String
backUpHost
Backup domain
Empty
authUiConfig
UI setting
Empty
boolean
isUseBackCamera
Whether to enable the rear camera (the rear camera only takes effect during pure actions or silent mode; otherwise, if it includes the reflective stage, the SDK will report an error HY_USE_BACK_CAMERA_WITH_REFLECTIVE_ERROR 227).
false
float
smallFaceRatioThreshold
Minimum face size ratio threshold (if the value is below this threshold, the system will prompt to move closer).
0.5f
float
bigFaceRatioThreshold
Maximum face size ratio threshold (if the value exceeds this threshold, the system will prompt to move farther away).
0.8f
zoomLevel
Rear camera zoom level
CameraZoom.ZOOM_1X
boolean
isOpenBOTCheck
Whether to enable Bot mode
false
long
longCheckTimeoutMs
Enable Bot mode, timeout duration for the Bot stage
30000 milliseconds (30 seconds)
boolean
showPrivacyPolicyDialog
Whether to display the compliance pop-up by default (set to false to disable)
true
boolean
disableSystemRecordScreen
Whether to prohibit system screenshots or screen recording in the selfie verification interface.
false
boolean
isOtherActionCheckMouthOpen
Whether to enable additional mouth opening detection during other action stages.
false
faceAngleValidation
Face angle detection level, lenient mode by default
FaceAngleValidation.LevelLoose
faceOcclusionLevel
Face occlusion detection level, strict mode by default
FaceOcclusionLevel.STRICT
boolean
isAllowCancelWaiting
Whether to allow users to cancel by pressing the back key while waiting for results
false
boolean
isEntireHighlight
Whether to immediately maximize the screen brightness when the liveness detection process is entered, and automatically restore it after completion.
false

PageColorStyle

The enumeration class for the default color scheme of the selfie verification interface, currently including two color schemes: light theme and dark theme.
PageColorStyle type
Description
PageColorStyle.Light
Light color scheme
PageColorStyle.Dark
Dark color scheme

LanguageStyle

LanguageStyle type
Description
LanguageStyle.AUTO
Follow system
LanguageStyle.ENGLISH
English
LanguageStyle.SIMPLIFIED_CHINESE
Simplified Chinese
LanguageStyle.TRADITIONAL_CHINESE
Traditional Chinese
LanguageStyle.CUSTOMIZE_LANGUAGE
Custom language

AuthUiConfig

Parameter configuration for custom UI on the selfie verification page
Type
Name
Meaning
Default Value
videoSize
Resolution during the selfie verification process
480p
boolean
isShowCountdown
Whether to display the countdown timer control
true
boolean
isShowErrorDialog
Whether to display the error dialog
true
int
authLayoutResId
Identity Verification exports the custom layout resID; use -1 when no adjustment is needed
-1
int
feedBackErrorColor
The color of exception feedback Tips (type 0xFFFFFFFF); use -1 when no adjustment is needed
-1
int
feedBackTxtColor
The color of normal feedback Tips (type 0xFFFFFFFF); use -1 when no adjustment is needed
-1
int
authCircleErrorColor
The color of the circular background frame during action errors (type 0xFFFFFFFF); use -1 when no adjustment is needed
-1
int
authCircleCorrectColor
The color of the circular background frame during correct actions (type 0xFFFFFFFF); use -1 when no adjustment is needed
-1
int
authLayoutBgColor
The background color of the selfie verification interface (type 0xFFFFFFFF); use -1 when no adjustment is needed
-1
int
loadingStageBgColor
The background color during the loading stage of the selfie verification interface (type 0xFFFFFFFF)
-1
int
loadingStageTipsColor
The color of the tips prompt during the loading stage of the selfie verification interface (type 0xFFFFFFFF)
-1
int
cancelTxtColor
The color of the cancel button on the selfie verification interface (type 0xFFFFFFFF)
-10
int
countDownTxtColor
The color of the countdown prompt on the selfie verification interface (type 0xFFFFFFFF)
-10
boolean
isHideAvatarGuideFrame
Whether to hide the avatar guidance box
false

VideoSize

The supported resolution enum for eKYC selfie verification
VideoSize type
Description
VideoSize.SIZE_480P
480P
VideoSize.SIZE_720P
720P

HuiYanOsAuthResult

The result type for the success callback in the selfie verification process.
Type
Name
Meaning
Default Value
String
token
The token used in this liveness process
Empty
Finally, you need to use this token to retrieve the final liveness verification result data from the TencentCloud API backend interface GetFaceidResultIntl.

Error Codes

Here are the error codes in the SDK failure callback. The error codes currently included in the SDK and their meanings are as follows:
Error Code
error code value
Error Code Definition
HY_NETWORK_ERROR
210
Network request exception.
HY_LOCAL_REF_FAILED_ERROR
211
Common exceptions when local SDK initialization fails include missing license files or expired licenses.
HY_USER_CANCEL_ERROR
212
The user actively cancels the selfie verification process.
HY_INNER_ERROR_CODE
213
An exception occurred internally in the SDK, terminating the selfie verification process.
HY_DO_NOT_CHANGE_ERROR
214
An exception event triggered by switching between applications during the selfie verification process, resulting in procedure termination.
HY_OPEN_CAMERA_ERROR
215
An exception occurred during the camera initialization process.
HY_INIT_SDK_ERROR
216
The init() method was not called; it was directly invoked.
HY_VERIFY_LOCAL_ERROR
217
On-device face detection failure (deprecated), consolidated into error code 228.
HY_PERMISSION_CHECK_ERROR
218
Local SDK had insufficient permissions (deprecated).
HY_APP_STOP_ERROR
219
The selfie verification process was terminated by the integrator when the reflectSequence parameter in startAuthByLightData is null.
HY_CHECK_LIVE_DATA_ERROR
220
Input Light Sequence parameter validation failed.
HY_INITIALIZATION_PARAMETER_EXCEPTION
221
An exception occurs when the method for setting light sequence parameters is directly invoked without first obtaining the device configuration.
HY_VERIFY_LOCAL_TIME_OUT
222
Local selfie verification action detection timeout occurred.
HY_PREPARE_TIME_OUT
223
Preparation timeout (exceeding the allowed duration from camera activation to first face detection)
HY_CHECK_PERMISSION_ERROR
224
The SDK failed to request camera permission internally.
HY_USE_BACK_CAMERA_WITH_REFLECTIVE_ERROR
227
The SDK reports an error when the rear camera is used with liveness detection mode that includes reflective data; ensure the mode excludes reflective stages to avoid error HY_USE_BACK_CAMERA_WITH_REFLECTIVE_ERROR 227.
HY_ACTION_REFLECTIVE_SDK_ERROR
228
Internal algorithm local detection recognition failure
HY_RISK_INIT_AUTH_ERROR
231
Device risk control module authorization detection abnormal
HY_ILLEGAL_CONTEXT_ERROR
233
Illegal context. Check whether the context passed to the init API is valid.
HY_ILLEGAL_TOKEN
288
Illegal token
HY_TURING_CONFIG_MISMATCH_EXCEPTION
400
Risk control module configuration mismatch

HuiYanOsAuthCallback

Callback API for streamlined liveness process
/**
* Overseas Lite result callback
*
* @author jerrydong
* @since 2022/6/10
*/
public interface HuiYanOsAuthCallBack {

/**
* Liveness success callback
*
* @param authResult result
*/
void onSuccess(HuiYanOsAuthResult authResult);

/**
* Liveness failure
*
* @param errorCode Error code.
* @param errorMsg Error message.
* @param token Used for this selfie verification.
*/
void onFail(int errorCode, String errorMsg, String token);
}

HuiYanAuthEventCallback

Callback for listening to key events during the selfie verification process, and if you need to use UI binding for custom layouts, you can perform event binding (you can refer to the documentation on custom capabilities).
HuiYanAuthTipsEvent is the callback for key event Tips during the selfie verification process in the SDK.
HuiYanAuthEvent is the callback for key events during the selfie verification process in the SDK.
/**
* SDK selfie verification event callback
*/
public interface HuiYanAuthEventCallBack {

/**
* Callback for event notifications when tips change during selfie verification.
*
* @param tipsEvent tips key events
*/
void onAuthTipsEvent(HuiYanAuthTipsEvent tipsEvent);

/**
* Selfie verification Event event
*
* @param authEvent authEvent
*/
void onAuthEvent(HuiYanAuthEvent authEvent);

/**
* Callback when the main authentication View is created.
*
* @param authView
*/
void onMainViewCreate(View authView);

/**
* Callback when the interface is reclaimed.
*/
void onMainViewDestroy();

void onBeginTransition();

void onEndTransition();
}


HuiYanAuthTipsEvent

Corresponding event types and meanings:
Event Enum
Event Description
NONE
N/A
ACT_OPEN_MOUTH
Please open your mouth.
ACT_BLINK
Please blink your eyes.
ACT_NOD_HEAD
Please nod your head.
ACT_SHAKE_HEAD
Please shake your head.
ACT_SCREEN_SHAKING
Please do not shake.
NO_FACE
No face detected.
NO_LEFT_FACE
Please do not cover the left side of your face.
NO_RIGHT_FACE
Please do not cover the right side of your face.
NO_MOUTH
Please do not cover your mouth.
NO_CHIN
Please do not cover your chin.
NO_NOSE
Please do not cover your nose.
NO_LEFT_EYE
Please do not cover your left eye.
NO_RIGHT_EYE
Please do not cover your right eye.
POSE_KEEP
Verification in progress. Please keep your position unchanged.
POSE_CLOSER
Please move a little closer.
POSE_FARTHER
Please move a little farther away.
POSE_OPEN_EYE
Please do not close your eyes.
POSE_INCORRECT
No full face detected.
TOO_MANY_FACE
Please ensure there is only a single face within the frame.
INCOMPLETE_FACE
Please move your face into the frame.
LIGHT_TOO_LOW
Ambient light is too dim.
LIGHT_TOO_STRONG
Ambient light is too bright.

HuiYanAuthEvent

Corresponding event types and meanings:
Event Enum
Event Description
NONE
Meaningless; default events will not trigger a callback.
START_AUTH
Initiate Identity Authentication
OPEN_MOUTH_CHECK
Start mouth opening action detection
SILENCE_CHECK
Start silent detection
BLINK_CHECK
Start blink action detection
NOD_HEAD_CHECK
Start nod action detection
SHAKE_HEAD_CHECK
Start head shake action detection
REFLECT_CHECK
Start light detection
OPEN_MOUTH_CHECK_DONE
Mouth opening detection completed.
SILENCE_CHECK_DONE
Silent detection completed.
BLINK_CHECK_DONE
Blink detection completed.
NOD_HEAD_CHECK_DONE
Nod detection completed.
SHAKE_HEAD_CHECK_DONE
Head shake detection completed.
ALL_ACTION_DONE
The entire action detection phase has been completed.
LOCAL_DETECTION_DONE
Local detection completed.

CameraZoom

Rear camera zoom factor, default 1x zoom.
CameraZoom type
Description
CameraZoom.ZOOM_1X
1x zoom
CameraZoom.ZOOM_1_5X
1.5x zoom
CameraZoom.ZOOM_2X
2x zoom

FaceAngleValidation

Face rotation angle detection strictness level, lenient by default.
FaceAngleValidation type
Description
FaceAngleValidation.LevelLoose
Lenient mode, which allows approximately 30 degrees of face rotation and will not automatically exit the glare processing phase if the rotation angle is excessive.
FaceAngleValidation.LevelMedium
Moderate mode, which allows approximately 20 degrees of face rotation and will automatically exit the glare processing phase if the rotation angle is excessive.
FaceAngleValidation.LevelStrict
Strict mode, which allows approximately 10 degrees of face rotation and will automatically exit the glare processing phase if the rotation angle is excessive.

FaceOcclusionLevel

Face occlusion detection threshold level, strict mode by default.
FaceOcclusionLevel type
Description
FaceOcclusionLevel.STRICT
Strict mode, which is the strictest for face occlusion detection.
FaceOcclusionLevel.MODERATE
Moderate mode, which is moderately strict for face occlusion detection.
FaceOcclusionLevel.LOOSE
Lenient mode, which is more lenient for face occlusion detection.
FaceOcclusionLevel.PASS
Pass mode, which skips face occlusion detection.


Help and Support

Was this page helpful?

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

Feedback