tencent cloud

Android API Description

Unduh
Mode fokus
Ukuran font
Terakhir diperbarui: 2026-10-26 19:58:21
Diterjemahkan oleh AI

API Classification

The eKYC SDK primarily involves the following classes:

Core Classes

Class Name
Type
Description
HuiYanOsApi
Interface Class
The main entry point of the SDK, providing core methods such as initialization, starting selfie verification, and resource release
HuiYanOsConfig
Configuration Class
Parameter configuration for starting the SDK, including License, timeout settings, UI customization, and so on.
HuiYanOsAuthResult
Result Class
The result object generated after successful selfie verification, containing information such as the Token

Callback API

API Name
Description
HuiYanOsAuthCallBack
Selfie verification process result callback, which includes both success and failure methods
HuiYanAuthEventCallBack
Key event callback during the selfie verification process, used to listen for events such as action detection

Enumeration Type

Enumeration Type
Description
PageColorStyle
Selfie verification interface color scheme (light/dark)
LanguageStyle
Language type (Chinese/English/follow system, and so on)
VideoSize
Selfie verification video resolution (480P/720P)
CameraZoom
Rear camera zoom level (1x/1.5x/2x)
FaceAngleValidation
Face angle detection strictness level (lenient/medium/strict)
FaceOcclusionLevel
Face occlusion detection level (strict/medium/lenient/pass)

Event type

Class Name
Description
HuiYanAuthTipsEvent
Tips prompt events during the selfie verification process (for example, "Please open your mouth", "Please move closer", and so on)
HuiYanAuthEvent
Key action events during the selfie verification process (such as start detection and detection completed)

Configuration Helper Classes

Class Name
Description
AuthUiConfig
UI customization configuration for the identity verification page, including parameters such as color, font, and layout.



Detailed API Specifications

The following sections provide detailed descriptions of each class and interface:

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.
Obtain device metadata (used to exchange for an SdkToken from the TencentCloud API).
Obtain the current SDK version.

init()

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

release()

Feature Introduction:
The resource release APIs of the eKYC SDK.
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:
To start the eKYC liveness detection process, pass in the business Token and SDK configuration, and receive the verification result via a callback.
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

createMetaData()

public static String createMetaData()

Feature Introduction:
Obtain device metadata, which is used to exchange for an SdkToken from the TencentCloud API. The returned encrypted string is passed to the TencentCloud API as the MetaData input parameter when an SdkToken is requested. You must first call init() to complete initialization.

Response Parameters:
Type
Name
Parameter Description
String
metaData
Encrypted device metadata string. The access party does not need to care about its specific content and can pass it through to the TencentCloud API as the MetaData input parameter. An empty string is returned if collection/encryption fails.
Note:
When to call: Call this method before requesting an SdkToken from the TencentCloud API, and pass the return value to the TencentCloud API as the MetaData input parameter. The TencentCloud API returns the ServerParamInfo configuration string along with the SdkToken, which you need to pass through to the SDK (see HuiYanOsConfig.serverParamInfo).
Example:
// 1. Obtain device metadata
String metaData = HuiYanOsApi.createMetaData();
// 2. Apply for an SdkToken from TencentCloud API (pass through metaData)
// TencentCloud API returns SdkToken + ServerParamInfo
// 3. Start identity verification (pass through serverParamInfo)
HuiYanOsConfig config = new HuiYanOsConfig();
config.setServerParamInfo(serverParamInfo);
HuiYanOsApi.startHuiYanAuth(sdkToken, config, authCallBack);

getVersion()

public static String getVersion()

Feature Introduction:
Obtain the version number of the current SDK.

Response Parameters:
Type
Name
Parameter Description
String
version
Current SDK version


HuiYanOsConfig

HuiYanOsConfig is the configuration entity class for initializing the eKYC SDK, which mainly contains the following attributes.
Type
Name
Description
Default Value
pageColorStyle
The color scheme for this selfie verification.
PageColorStyle.Light
String
authLicense
License file name for customer-requested user identity verification authorization
Empty
String
riskLicense
License file name for customer-requested device risk control authorization. This path is required for the Enhanced and Plus edition capabilities.
Null
long
authTimeOutMs
Set the timeout for liveness detection.
10000 milliseconds (10 seconds)
boolean
openCheckRiskMode
Whether to enable the risk control detection switch. This field must be enabled for the Enhanced 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 the Android custom capability documentation), used together 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 works in pure action or silent mode; otherwise, if the liveness detection includes a reflective stage, the SDK will report 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
String
modelPath
Custom model resource path
Null
boolean
isShowErrorPopup
Whether to enable the error retry pop-up
false
int
compareRequestTimeOutMs
Timeout for liveness comparison requests (in milliseconds)
60000
int
compareRequestAttempts
Number of attempts for liveness comparison requests, with a minimum value of 1.
3
int
lightRequestTimeOutMs
Timeout for light sequence retrieval requests (in milliseconds)
30000
int
lightRequestAttempts
Number of attempts for light sequence retrieval requests, with a minimum value of 1.
3
String
serverParamInfo
Encrypted configuration string returned by the TencentCloud API when the TencentCloud API applies for an SdkToken (required). If an empty string or abnormal content is passed in, the SDK reports an error.
Null
boolean
isOpenAudio
Whether to enable voice broadcast during identity verification (action prompts, exception feedback, and more). After enabling, you must also import the huiyanaudio-oversea_1.x.x_release.aar voice resource package; otherwise, no sound will be played even if this is set to true. For details, see Enable Voice Broadcast.
true
boolean
isShowGuideAnimation
Whether to show the guide animation before identity verification (for example, an animation that prompts users to align their face)
true



Enabling Voice Broadcast

The SDK supports voice broadcasting during selfie verification, including action prompts, exception feedback, and posture guidance. To enable voice broadcasting, the following two conditions must be met simultaneously:

1. Import the voice resource package huiyanaudio-oversea_1.x.x_release.aar

This resource package is a pure resource aar (containing only assets/audio/*.m4a audio files and no Java classes). Import it the same way as other AARs by placing it in the libs directory and declaring the dependency in build.gradle:
├── codedemo
│ ├── libs
│ │ ├── huiyanaudio-oversea_1.x.x_release.aar
│ │ └── ...
dependencies {
// Voice broadcast resource pack (optional)
implementation files("libs/huiyanaudio-oversea_1.x.x_release.aar")
}
2. Enable the configuration switch isOpenAudio
HuiYanOsConfig config = new HuiYanOsConfig();
// Enable voice broadcast (enabled by default; can be explicitly set for readability)
config.setOpenAudio(true);
// To hide the "speaker/mute" toggle button on the identity verification page, disable it
config.getAuthUiConfig().setShowSoundToggleBtn(false);

Behavior description:
If isOpenAudio = true but the voice resource package aar is not imported, the SDK silently degrades when it fails to load voice resources internally. The identity verification process can still proceed normally, but without sound.
If isOpenAudio = false, the SDK directly skips loading voice resources and neither depends on nor loads the aar.
The identity verification page displays a "Speaker/Mute" toggle button by default, allowing users to switch at any time during the verification process. To hide this button, disable it by calling AuthUiConfig.setShowSoundToggleBtn(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 customizing the selfie verification page UI
Type
Name
Description
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 the abnormal feedback Tips (type 0xFFFFFFFF); use -1 when no adjustment is needed.
-1
int
feedBackTxtColor
The color of the normal feedback Tips (type 0xFFFFFFFF); use -1 when no adjustment is needed.
-1
int
authCircleErrorColor
The color of the circular background frame during incorrect actions (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
boolean
isShowSoundToggleBtn
Whether to show the "speaker/mute" toggle button on the selfie verification page (the button is meaningful only when HuiYanOsConfig.isOpenAudio is true)
true

VideoSize

Resolution enumeration supported by 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
Description
Default Value
String
token
The token used in this liveness process
Empty
Finally, use this token to call the TencentCloud API backend interface GetFaceIdResultIntl to retrieve the final liveness verification result.

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, and the startup API was called directly.
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 integrator actively terminates the selfie verification process when the reflectSequence parameter of 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 interface is valid.
HY_ILLEGAL_TOKEN
288
Illegal token
HY_TURING_CONFIG_MISMATCH_EXCEPTION
400
Risk control module configuration mismatch (scenario: the openCheckRiskMode configuration in HuiYanOsConfig must match the SdkVersion used when applying for a business token; when applying for an ENHANCE or Plus mode token, openCheckRiskMode must be set to true).

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.
FACE_TOO_BRIGHT
Face is too bright.
FACE_TOO_DARK
Face is too dark.

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.
FACE_QUALITY_CHECK
Face quality check starts.
FACE_QUALITY_CHECK_END
Face quality check 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.


Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan