tencent cloud

eKYC

ドキュメントeKYC

Android APIs Overview Documentation

Download
フォーカスモード
フォントサイズ
最終更新日: 2026-08-12 11:10:24
AI翻訳
The classes involved in the Android Identity Verification SDK primarily include EkycHySdk, EkycHyConfig, and EkycHyCallBack. Detailed descriptions of their supported APIs are provided below.


EkycHySdk

EkycHySdk is the external API class for the Identity Verification SDK, and the main logic is implemented by calling this class.
API
Feature Description
init()
Initialization API
release()
Resource Release API
startEkycCheck()
Start the Identity Verification detection process.
createMetaData()
Collects and encrypts device metadata for the business party to fill in the MetaData field when a token is requested.
setAuthEventCallBack()
Set the event callback during the Identity Verification process.
setOcrCloudEventListener()
Registers an event listener for the OCR collection phase to intercept pop-ups and customize the UI.

init()

public static void init(Context context)

Feature Introduction:
Identity Verification SDK's initialization API.

Input Parameters:
Parameter Type
Parameter Name
Parameter Description
Context
context
App context information

release()

public static void release()

Feature Introduction:
Identity Verification SDK resource release API.


startEkycCheck()

public static void startEkycCheck(Activity activity, final String ekycToken,
            String serverParamInfo, EkycHyConfig ekycHyConfig, EkycHyCallBack ekycHyCallBack)

Feature Introduction:
Function to initiate the Identity Verification process.

Parameters:
Parameter Type
Parameter Name
Parameter Description
Activity
activity
The caller's Activity, which the SDK uses to launch its internal UI.
String
ekycToken
Token value obtained from the server-side, serving as the unique business credential for this process.
String
serverParamInfo
Encrypted configuration string issued by the server-side, which is decrypted and used internally by the SDK.
ekycHyConfig
Configuration information for initiating the Identity Verification process.
ekycHyCallBack
Callback API for receiving authentication results.



createMetaData()

public static String createMetaData()

Feature Introduction:

Collect and encrypt device metadata for the business party to populate the MetaData field when a token is requested.

Return Value:

Type
Meaning
String
An encrypted Base64 string. Returns an empty string on failure.



setAuthEventCallBack()

public static void setAuthEventCallBack(HuiYanAuthEventCallBack authEventCallBack)

Feature Introduction:
Setting the event callback during the Identity Verification process, which can be used to monitor the verification page lifecycle and key events during detection.

Parameters:
Parameter Type
Parameter Name
Parameter Description
HuiYanAuthEventCallBack
authEventCallBack
Event callback API for Identity Verification
HuiYanAuthEventCallBack callback methods:
Methodology
Meaning
onMainViewCreate(View)
Callback upon creation of the Identity Verification main page.
onMainViewDestroy()
Callback upon destruction of the Identity Verification main page.


setOcrCloudEventListener()

public static void setOcrCloudEventListener(IOcrCloudEventListener listener)

Feature Introduction:

Register an event listener for the OCR collection phase (Token mode), which allows the caller to intercept various pop-ups and UI events within the SDK to achieve fully customized UI interaction. This must be called before startEkycCheck(). Pass null to unregister.

Parameters:
Parameter Type
Parameter Name
Parameter Description
IOcrCloudEventListener
listener
OCR event listener. Pass null to unregister.
IOcrCloudEventListener callback methods:
Methodology
Description
Return Value Description
onMainViewCreate(View)
Callback upon creation of the OCR recognition main View.
None
onMainViewDestroy()
Callback upon destruction of the OCR recognition main View.
None
onEventParamMap(HashMap)
Pass-through of additional parameters
None
onShowCloudErrorDialog(HashMap, View, Runnable, Runnable)
Intercept the failure dialog.
true = handle by the caller, false = SDK default pop-up
onShowBestFrameConfirmDialog(HashMap, View, ImageView, Runnable, Runnable)
Intercept the best-frame confirmation dialog.
Same as above.
onShowCameraPermissionDialog(HashMap, View, Runnable, Runnable)
Intercept the camera permission dialog.
Same as above.
onShowNextSideDialog(HashMap, View, Runnable)
Intercept the "Switch to Next Side" dialog.
Same as above.
onShowChangeModeDialog(HashMap, View, Runnable, Runnable)
Intercept the "Timeout Switch to Manual Mode" dialog.
Same as above.
onShowUploadLoading(View)
Intercept the upload Loading.
Same as above.
onHideUploadLoading()
Callback upon completion of the upload Loading, paired with onShowUploadLoading.
None
Attention:
Calling Time: The listener must be registered before startEkycCheck().
You must call the Runnable (such as retryBlock/exitBlock/confirmBlock/cancelBlock) provided in the pop-up callback. After the user makes a selection, you must call one of them; otherwise, the SDK process will hang.
retryBlock can be null: In onShowCloudErrorDialog, a null retryBlock indicates that retry is not allowed, so the caller does not need to display a retry button.
For pop-up callbacks, a return value of true indicates that the caller handles the UI themselves (the SDK does not display the default UI), while a return value of false causes the SDK to display the default pop-up. All pop-up methods return false by default and can be overridden as needed.
Loading Lifecycle: The SDK calls back `onHideUploadLoading()` only when `onShowUploadLoading` returns `true`. In this case, the caller should hide the custom loading.
Unregister: Pass null to unregister when custom UI is no longer needed.


EkycHyConfig

EkycHyConfig is the configuration entity class for initializing the Identity Verification SDK, mainly containing the following attributes.
Type
Name
Meaning
Default Value
String
licenseName
Customer's user-authorized License file name
Null
String
riskLicenseName
Added license configuration for device risk detection; required when openCheckRiskMode is set to true.
Null
boolean
openCheckRiskMode
Whether to enable device risk detection. When the input parameter SdkVersion in ApplySdkVerificationToken is set to ENHANCE or PLUS, it must be configured as enabled (true).
false
languageStyle
Language for the current process
LanguageStyle.AUTO
String
languageCode
Language code, used in conjunction with LanguageStyle.CUSTOMIZE_LANGUAGE.
Null
long
livenessAutoTimeout
The timeout for Identity verification.
30000 milliseconds (30 seconds), supported range: minimum 10 seconds, maximum 600 seconds.
boolean
showPrivacyPolicyDialog
Whether to display the privacy policy dialog
true
boolean
isUseBackCameraOnFaceAuth
Whether to use the rear camera for Identity verification. If light-based liveness detection is enabled, enabling this will throw error 12008.
false
String
faceModelPath
Identity verification model directory path. When the huiyanmodels AAR is not imported, this field must be used to specify the external model directory path (directory name is face-tracker-v003).
Null
boolean
isShowGuidePage
Whether to display the preparation guide page before Face Recognition. When set to false, the SDK skips the guide page and directly goes to liveness detection.
true
boolean
isShowResultPage
Whether to display the result page after Face Recognition. When set to false, the SDK skips the result page and directly returns the result to the host app via callback.
true
boolean
isEntireHighlight
The Face Recognition page remains highlighted throughout the process when set to true.
false
boolean
isShowErrorPopup
Whether to display a retry popup after liveness detection fails. When set to true, the SDK displays a retry popup and no longer shows the failure result page.
false
boolean
showBestImgConfirmDialog
Whether to display the best-frame confirmation dialog for OCR. When the option is set to true, the dialog pops up after capturing is completed.
false
ocrUiConfig
Custom UI configuration for the OCR recognition interface
null
faceAuthUiConfig
Custom UI configuration for the Identity verification page
null

OcrUiConfig

Custom UI configuration for the OCR recognition page, set via EkycHyConfig.setOcrUiConfig().

Method name
Parameter Type
Meaning
Default Value
portraitLayoutResId
int
Portrait layout resource ID
-2
portraitThemeResId
int
Portrait theme style resource ID
-2
showStatusBar
boolean
Whether to display the status bar.
true
statusBarColor
int
Status bar background color (in 0xFFFFFF format)
-2
useDeepColorStatusBarIcon
boolean
Whether to use dark status bar icons (for use with light-colored status bars)
false
cardFrameDefaultColor
int
Default state color for the card border (when no card is detected)
-2
cardFrameColor
int
Highlight state color for the card border (when recognition is successful)
-2
warnErrorTextColor
int
Error state color for the card border and error prompt text color
-2
defaultTipTextColor
int
Prompt text color for the card frame area in default state
-2
successRemindTextColor
int
Prompt text color for the card frame area in recognition success state
-2
imageSelectResId
int
Album local image selection button icon resource ID
-2
lightImageOnResId
int
Flashlight activation button icon resource ID
-2
lightImageOffResId
int
Flashlight deactivation button icon resource ID
-2
takePicturesResId
int
Manual capture button icon resource ID
-2
backActionIconResId
int
Back button icon resource ID
-2
removeAlbum
boolean
Whether to hide the gallery image selection feature
false
removeFlash
boolean
Whether to hide the flashlight button
false
isShowIdcardLogo
boolean
Whether to display the portrait/national emblem Logo in the ID card scanning frame
true
remindDialogText
String
Alert Dialog text content
""
remindDialogTextColor
int
Alert Dialog text color
-2
remindDialogTextSize
int
Alert Dialog text size
-2
remindDialogConfirmText
String
Confirm button text
""
remindDialogCancelText
String
Cancel button text
""
remindDialogConfirmColor
int
Confirm button color
-2
remindDialogCancelColor
int
Cancel button color
-2
remindDialogShowTitle
boolean
Whether to display the title of the Alert Dialog
true
remindDialogCommonStyle
int
Alert Dialog overall style resource ID
-2
remindDialogCommonBgColor
int
Alert Dialog background color
-2
remindDialogChangeModeTextOnLeft
boolean
Whether to display the mode switch button on the left side of the Dialog
false
Note:
Default value -2 indicates that this field is not set, and the SDK uses the built-in default value.

FaceAuthUiConfig

Custom UI configuration for the Identity Verification page, passed in via EkycHyConfig.setFaceAuthUiConfig().
Method name
Parameter Type
Meaning
Default Value
authLayoutResId
int
Portrait verification page custom layout ResId
-2
mainActivityThemeId
int
Verification Activity theme ResId
-2
statusBarColor
int
Status bar color (in 0xFFFFFF format)
-2
isTransparentStatusBar
boolean
Whether the status bar is transparent
false
transparentStatusBarMoveHeight
int
Content shift-up height (px) when status bar is transparent
-2
useDeepColorStatusBarIcon
boolean
Whether dark-colored status bar icons are used
false
isShowCountdown
boolean
Whether to display the countdown timer
true
isShowErrorDialog
boolean
Whether to display the error dialog.
true
countDownTxtColor
int
Countdown text color
-2
cancelTxtColor
int
Cancel button text color
-2
feedBackTxtColor
int
Feedback prompt text color for detection (normal state)
-2
feedBackErrorColor
int
Error state color for detection feedback
-2
feedBackExtraTipColor
int
Additional prompt text color for detection feedback
-2
authCircleCorrectColor
int
Face circular frame color when actions are correct
-2
authCircleErrorColor
int
Face circular frame color when actions are incorrect
-2
isHideFrontCircleViewOnStart
boolean
Whether to hide the face circular frame during startup
false
isHideFrontCircleViewOnCheck
boolean
Whether to hide the face circular frame during the action detection phase
false
isHideFrontCircleViewOnReflect
boolean
Whether to hide the face circular frame during the reflection phase
false
isHideAvatarGuideFrame
boolean
Whether to hide the avatar guidance box
false
authLayoutBgColor
int
Identity verification page background color
-2
loadingStageBgColor
int
Loading phase background color
-2
loadingStageTipsColor
int
Loading phase prompt text color
-2
Note:
Default value -2 indicates that this field is not set, and the SDK uses the built-in default value.

LanguageStyle

Multilingual configuration for the default page of Identity Verification.
LanguageStyle type
Meaning
LanguageStyle.AUTO
Follow the system language version
LanguageStyle.ENGLISH
English
LanguageStyle.SIMPLIFIED_CHINESE
Simplified Chinese
LanguageStyle.TRADITIONAL_CHINESE
Traditional Chinese
LanguageStyle.CUSTOMIZE_LANGUAGE
Custom language. Must be used in conjunction with a languageCode. For details, see Android Custom Capabilities.

EkycHyCallBack

A listener class for receiving the results of the Identity Verification process.
/**
 * Result callback class for Identity Verification
 */
public interface EkycHyCallBack {

    /**
     * Information about the successful recognition result
     *
     * @param result Result information.
     */
    void onSuccess(EkycHyResult result);

    /**
     * Failure details of the Identity Verification process
     *
     * @param errorCode Error code.
     * @param errorMsg Error message.
     * @param ekycToken token for the current process
     */
    void onFail(int errorCode, String errorMsg, String ekycToken);
}
where EkycHyResult is the successfully returned result object.


EkycHyResult

The EkycHyResult is the result object returned upon successful completion of the Identity Verification SDK process.
Type
Name
Meaning
Default Value
String
ekycToken
The token for the current Identity Verification process, which can be used to retrieve key data from the identity verification process on the server.
Null

Error Code

Error Code
Meaning
12000
Voluntary cancellation by the user
12001
Network request failure.
12002
Error caused by OCR recognition exception.
12003
Exception caused by on-device face detection failure.
12004
Expired token.
12005
On-device document recognition failure
12006
Failure of the Identity Verification SDK initialization process.
12007
Startup parameter validation failure.
210
Network request exception.
211
Detection failure during local SDK initialization, typically due to missing or expired license file.
213
An exception occurred internally in the SDK, terminating the identity verification process.
214
An exception event triggered by switching between applications during the identity verification process, resulting in procedure termination.
215
Exception occurred during camera activation.
216
The init() method was not called before other methods are invoked.
217
On-device face detection failure (deprecated). Use error code 228 uniformly.
218
Insufficient permissions required by the local SDK (deprecated).
219
The integrator actively terminated the identity verification process when the reflectSequence parameter of startAuthByLightData was null.
220
Validation failure of the incoming light sequence parameters.
221
Exception that occurs when the method for setting the light sequence parameters is invoked directly without first obtaining the device configuration.
222
Local identity verification action detection timeout occurred.
223
Preparation phase timeout (the time from camera activation to the first face detection exceeds the limit).
224
The SDK's internal request for camera permission failed.
227
Error occurs when the SDK's liveness detection mode, which includes reflection data, is used with the rear camera.
228
Internal algorithm on-device detection and recognition failure.
231
Device risk control module authorization detection exception.
233
Invalid context. Check whether the context passed to the init API is valid.
288
Invalid token.
400
Risk control configuration mismatch.
-1
Parameter validation failure (such as sdkToken/serverParamInfo is empty, Activity is empty, init() not called first, and so on).
100100
Parameter exception.
100102
Network exception.
100103
Camera permission exception.
200101
Voluntary cancellation of recognition by the user.
300101
Model/SDK initialization exception.
300102
Service parsing exception (including network timeout, ciphertext parsing failure, and unknown error fallback).
300103
Signature failure.
300104
Camera exception.
300105
Initialization configuration failure.
300106
Empty image exception.
300107
license authorization failure
300108
System version is too low.
300109
Automatic mode timeout (no image captured).
300110
SDK internal error.
300111
SDK internal image cropping exception.
300112
Document type mismatch.
300113
OCR failure: excessive alarm count.
400100
Alarm Code for triggering specified interception.
400101
The document type provided by the user does not match the specified document type.
400102
The document side type provided by the user does not match the selected type.
400103
The document occupies too small a proportion in the photo uploaded by the user.
400104
The photo uploaded by the user contains multiple document images.
400105
OCR recognition failure.
400106
Document information verification failure.
400107
Input parameter error.
400108
Internal service error.
400109
Service not activated / Account overdue payment / Resource bundle exhausted / Billing exception.
400110
Rate limiting triggered.
400111
File size too large or invalid.
400112
File parsing failure.

次の記事へ: プライバシーポリシー

ヘルプとサポート

この記事はお役に立ちましたか？

フィードバック