tencent cloud

eKYC

Kebijakan eKYC
Kebijakan Privasi
Perjanjian Pemrosesan dan Keamanan Data

Integration Process

Mode fokus
Ukuran font
Terakhir diperbarui: 2026-03-27 11:18:36
This article describes the overall integration process for Identity Verification(App SDK).


Access Preparations

Register a Tencent Cloud enterprise account. For details, refer to the Signing Up.
To complete enterprise real-name authentication, refer to the Enterprise Identity Verification Guide.
Log in to the eKYC console Activate service.
Contact Us to obtain the latest SDK and License.

Overall Architecture Diagram

The following figure shows the architecture diagram for Tencent Cloud eKYC product's Identity Verification(App SDK) integration:



SDK integration includes two parts:
A. Client-side integration: Integrate the SDK into the client's end business App.
B. Server-side integration: In your (merchant's) server, expose the endpoint of your (merchant's) application, so that the merchant application can interact with the merchant server, then access the Server API to obtain the SdkToken for the serialized selfie verification process and pull the final identity verification result via the SdkToken.

Overall Interaction Flow

Integrators only need to pass in the Token and start the corresponding Identity Verification(App SDK) to implement full-process user identity authentication, including document recognition + liveness detection + face comparison. After the end user completes the authentication, the integrator can obtain the complete authentication result via the API.
API for obtaining Token: ApplySdkVerificationToken
API for retrieving identity authentication results: GetSdkVerificationResult
The following diagram illustrates the overall interaction logic among the SDK, client, and server. Module descriptions in the diagram:
End User: end user
Identity Verification(App SDK): the Identity Verification(App SDK) obtained during the preparation phase
Merchant Application: client-side business application using and integrating the Identity Verification SDK
Merchant Server: client's server program
Identity Verification Server: Tencent Cloud Identity Verification backend service API



The recommended interaction flow is detailed below:
1. The user triggers the Merchant Application to prepare for invoking the identity verification business scenario.
2. Merchant Application sends a request to Merchant Server, requesting a liveness Business Token to initiate an identity verification process.
3. Merchant Server invokes the TencentCloud API ApplySdkVerificationToken by passing relevant parameters.
4. Identity Verification Server receives the ApplySdkVerificationToken call and issues the token for this business session to Merchant Server.
5. Merchant Server can distribute the obtained business Token to the client's Merchant Application.
6. Merchant Application invokes the Identity Verification SDK's launch interface startHuiYanAuth by passing the token and configuration information, initiating the identity verification process.
7. Identity Verification SDK initiates OCR to upload the ID photo to Identity Verification Server for extracting user identity information.
8. Identity Verification Server returns the identification results to Identity Verification SDK.
9. Identity Verification SDK captures and uploads the required user data, including liveness data, to Identity Verification Server.
10. Identity Verification Server returns the results to Identity Verification SDK after completing identity verification (including the liveness check and comparison process).
11. Identity Verification SDK triggers a callback to Merchant Application, notifying the completion and status of the verification.
12. After receiving the callback, Merchant Application can send a request to notify Merchant Server to actively obtain the result of this identity verification for confirmation check.
13. Merchant Server actively invokes the Identity Verification Server API GetSdkVerificationResult by passing relevant parameters and the Token for this business session to obtain the result of this identity verification.
14. Identity Verification Server receives the GetSdkVerificationResult call and returns the result of this identity verification to Merchant Server.
15. After receiving the result of this identity verification, Merchant Server can distribute the required information to Merchant Application.
16. Merchant Application displays the final result on the UI interface to inform the user of the authentication outcome.


Access Process

Server-side integration

Integration Preparation

Before server-side integration, you need to follow the instructions in the obtain API key guide to activate Tencent Cloud eKYC Service and obtain the Tencent Cloud API access keys SecretId and SecretKey. Additionally, you need to follow the operation process in the connect to Tencent Cloud API guide to integrate the SDK package of the development language you are familiar with into your server-side module, to ensure that you can successfully call Tencent Cloud APIs and properly handle API requests and responses.

Start integration

To ensure your (merchant) client application can properly interact with your (merchant) server, the merchant server needs to call the Tencent Cloud Huiyan API ApplySdkVerificationToken to obtain the SDKToken to string together the entire identity verification process, and call the GetSdkVerificationResult API to retrieve the identity verification result. The merchant server must provide corresponding endpoints for the merchant client to call. The sample code below uses Golang as an example to demonstrate how to call Tencent Cloud APIs on the server side and obtain correct response results.
Note:
This sample only demonstrates the processing logic required for the interaction between the Merchant Server and the Tencent Cloud API service. If needed, you need to implement your own business logic, such as:
After obtaining the SDKToken through the ApplySdkVerificationToken API, you can return other required responses along with the SDKToken to the client application.
After retrieving the identity authentication result through the GetSdkVerificationResult API, you can save the returned best frame photo for utilization in subsequent business logic.
var FaceIdClient *faceid.Client

func init() {
// Initialize the client configuration below, where you can specify the timeout duration and other configuration items
prof := profile.NewClientProfile()
prof.HttpProfile.ReqTimeout = 60
// TODO Replace with your account's SecretId and SecretKey
credential := cloud.NewCredential("SecretId", "SecretKey")
var err error
// Initialize the client for calling the HuiYan FaceID service
FaceIdClient, err = faceid.NewClient(credential, "ap-singapore", prof)
if nil != err {
log.Fatal("FaceIdClient init error: ", err)
}
}

// ApplySdkVerificationToken obtains the FaceID API Token
func ApplySdkVerificationToken(w http.ResponseWriter, r *http.Request) {
log.Println("get face id token")
// Step 1: Parse request parameters
_ = r.ParseForm()
var IdCardType = r.FormValue("IdCardType")
var NeedVerifyIdCard = false

// Step 2: Initialize the request object and assign values to required parameters
request := faceid.NewApplySdkVerificationTokenRequest()
request.IdCardType = &IdCardType
request.NeedVerifyIdCard = &NeedVerifyIdCard
// Step 3: Invoke the FaceID service via FaceIdClient
response, err := FaceIdClient.ApplySdkVerificationToken(request)

// Step 4: Process the Tencent Cloud API response and construct the response object
if nil != err {
log.Println("error: ", err)
_, _ = w.Write([]byte("error"))
return
}
SdkToken := response.Response.SdkToken
apiResp := struct {
SdkToken *string
}{SdkToken: SdkToken}
b, _ := json.Marshal(apiResp)

// ... Other business processing code

// Step 5: Return the service response
_, _ = w.Write(b)
}

// GetFaceIdResult obtains the FaceID verification result
func GetSdkVerificationResult(w http.ResponseWriter, r *http.Request) {
// Step 1: ... Parse request parameters
_ = r.ParseForm()
SdkToken := r.FormValue("SdkToken")
// Step 2: Initialize the request object and assign values to required parameters
request := faceid.NewGetSdkVerificationResultRequest()
request.SdkToken = &SdkToken
// Step 3: Invoke the FaceID service via FaceIdClient
response, err := FaceIdClient.GetSdkVerificationResult(request)

// Step 4: Process the Tencent Cloud API response and construct the response object
if nil != err {
_, _ = w.Write([]byte("error"))
return
}
result := response.Response.Result
apiResp := struct {
Result *string
}{Result: result}
b, _ := json.Marshal(apiResp)

// ... Other business processing code

// Step 5: Return the service response
_, _ = w.Write(b)
}

func main() {
// Register http API path
http.HandleFunc("/api/v1/get-token", ApplySdkVerificationToken)
http.HandleFunc("/api/v1/get-result", GetSdkVerificationResult)
// Listen on port
err := http.ListenAndServe(":8080", nil)
if nil != err {
log.Fatal("ListenAndServe error: ", err)
}

Note:
For the complete code example, see faceid-server-demo.

API testing

After completing the integration, you can test its correctness using postman or curl commands. Access the http://ip:port/api/v1/get-token API to check whether it returns SdkToken normally, and access the http://ip:port/api/v1/get-result API to check whether the response of the Result field is 0 to determine whether the server integration is successful. For specific response results, refer to the API section.


Android integration

Dependencies

The current Android SDK is compatible with API 19 (Android 4.4) and later versions.


Integration Steps

1. Add ekyc-v1.0.1.2-release.aar, huiyansdk_android_overseas_1.0.10.5_release.aar, huiyanmodels_1.0.1_release.aar, OcrSDK-common-model-v1.0.0-release.aar, OcrSDK-private-v2.0.0.25-release.aar, tencent-ai-sdk-aicamera-1.0.30.4-release.aar, tencent-ai-sdk-common-1.1.49.8-release.aar, tencent-ai-sdk-network-1.0.2.13-release.aar, tencent-ai-sdk-youtu-base-1.0.2.1.1-release.aar (specific version numbers are subject to download from the official website) to the libs directory of your project.
2. Configure as follows in the build.gradle file (under the App module) of your project:
// Set ndk so architecture filtering (taking armeabi-v7a as an example; add arm64-v8a if supported)

defaultConfig {
ndk {
abiFilters 'arm64-v8a'
}
}

dependencies {
// Identity verification SDK repository
implementation files("libs/ekyc-v1.0.1.2-release.aar")
// Identity verification component library
implementation files("libs/huiyansdk_android_overseas_1.0.10.5_release.aar")
// Face model library (optional): If not imported, specify the external model directory path via EkycHyConfig.setFaceModelPath() (directory name must be face-tracker-v003), and ensure model file integrity
implementation files("libs/huiyanmodels_1.0.1_release.aar")

// Ocr component library
// OCR model library (optional): If not imported, specify the external model file path via EkycHyConfig.setOcrModelPath() (file name must be subject.iap), and ensure model file integrity
implementation files("libs/OcrSDK-common-model-v1.0.0-release.aar")
implementation files("libs/OcrSDK-private-v2.0.0.25-release.aar")

// Common component library
implementation files("libs/tencent-ai-sdk-youtu-base-1.0.2.1.1-release.aar")
implementation files("libs/tencent-ai-sdk-common-1.1.49.8-release.aar")
implementation files("libs/tencent-ai-sdk-aicamera-1.0.30.4-release.aar")
implementation files("libs/tencent-ai-sdk-network-1.0.2.13-release.aar")
// Import the gson third-party library
implementation 'com.google.code.gson:gson:2.8.9'
}
3. Declare the permissions in the AndroidManifest.xml file.
<!-- SDK required permissions -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-feature
android:name="android.hardware.camera"
android:required="true" />
<uses-feature android:name="android.hardware.camera.autofocus" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

For users who need to be compatible with Android 6.0 and above, in addition to declaring permissions in the AndroidManifest.xml file, they also need to use code to dynamically request permissions.


Initialization

Call during App initialization, it is recommended to be performed in the Application, mainly for SDK initialization operations.
@Override
public void onCreate() {
super.onCreate();
EkycHySdk.init(this);
}


Start the process

To initiate the verification process, simply call the EkycHySdk.startEkycCheck() function and pass in the following parameters:
SDK token (sdkToken)
Configuration Information
Listener for receiving result callbacks
// Set startup configuration
EkycHyConfig ekycHyConfig = new EkycHyConfig();
// Set the license name
ekycHyConfig.setLicenseName("ekycLicense.license");
ekycHyConfig.setOcrType(OcrRegionType.HK);
// If you need to enable the device risk control capability, pass in the lic file and turn on the local switch; if not enabled, no modification is required.
ekycHyConfig.setRiskLicenseName("risk.lic");
ekycHyConfig.setOpenCheckRiskMode(true);
// Custom UI configuration
OcrUiConfig config = new OcrUiConfig();
ekycHyConfig.setOcrUiConfig(config);
// Specific startup verification logic
// sdkToken is the unique credential for the current process, obtained from the server.
EkycHySdk.startEkycCheck(sdkToken, ekycHyConfig, new EkycHyCallBack() {
@Override
public void onSuccess(EkycHyResult result) {
Log.e(TAG, "result: " + result.toString());

runOnUiThread(() -> {
Toast.makeText(this.getApplicationContext(), "Verification successful: " + result.toString(), Toast.LENGTH_SHORT).show();
});
}

@Override
public void onFail(int errorCode, String errorMsg, String ekycToken) {
Log.e(TAG, "code: " + errorCode + " msg: " + errorMsg + " token: " + ekycToken);
String msg = "Check failed, code: " + errorCode + " msg: " + errorMsg + " token: " + ekycToken;
runOnUiThread(() -> {
Toast.makeText(this.getApplicationContext(), msg, Toast.LENGTH_SHORT).show();
});
}
});

sdkToken is the unique credential for the current authentication process obtained from the server.
Note:
"ekycLicense.license" and "risk.lic" files require contacting business or customer service personnel for license application. Place the obtained license files under the assets directory.
├── app
│ ├── build.gradle
│ ├── libs
│ ├── proguard-rules.pro
│ └── src
│ └── main
│ └── assets
│ ├── ekycLicense.license
│ └── risk.lic


SDK resource release

When your App exits or is no longer in use, you can call the SDK resource release API.
@Override
protected void onDestroy() {
EkycHySdk.release();
super.onDestroy();
}


Configuring Obfuscation Rules

If your app has obfuscation enabled, add the following section to your proguard-rules.pro file to ensure proper functioning of the SDK.

# Objects to be obfuscated
-keep class com.google.gson.** {*;}
-keep class com.tencent.cloud.** {*;}
-keep class com.tencent.youtu.** {*;}
-keep class com.tencent.cloud.ocr.** {*;}
-keep class com.tencent.cloud.ekyc.** {*;}

Enhanced Edition/PLUS Edition Usage Guide

The current version supports three security level modes: Basic, Enhance, and Plus. The Enhance and Plus modes can further improve the security of device and liveness detection. Enabling these two modes requires corresponding settings in both the SDK configuration and Token acquisition processes.

SDK Configuration Requirements

Whether enabling Enhanced mode or Plus mode, you need to enable the device risk control capability in the SDK and configure the corresponding risk control license file:
// Set the device risk control license file (must be placed in the assets directory)
ekycHyConfig.setRiskLicenseName("turing.lic");

// Enable device risk control capability
ekycHyConfig.setOpenCheckRiskMode(true);

Note:
The device risk control license is an independent file different from the identity verification authorization license and requires separate application.

Token acquisition configuration

When calling the ApplySdkVerificationToken API to obtain the business Token, specify whether to enable Enhance mode or Plus mode by setting the SdkVersion parameter:
Enhanced mode: Set the corresponding SdkVersion value to ENHANCE.
PLUS mode: Set the corresponding SdkVersion value to PLUS.
For specific values of SdkVersion, see ApplySdkVerificationToken.

Mode enabling process

1. Set the corresponding SdkVersion parameter when obtaining the Token.
2. Enable the device risk control capability in the SDK configuration.
3. Pass the configured Token when calling the startEkycCheck method.
4. The SDK automatically enables the corresponding security level based on the mode information in the Token.
Note:
The device risk control license is an independent file different from the identity verification authorization license and requires separate application.


iOS integration

Dependencies

1. Development environment: Xcode 12.0 or later, with the latest version recommended.
2. The SDK is compatible with iOS 11.0 and later versions.

SDK integration steps

Manual integration approach

1. Import the relevant libraries and files.
Link Binary With Libraries: add the relevant frameworks.
2. The libraries required by the SDK are as follows:
├── HuiYanEKYCVerification.framework
├── tnn.framework
├── tnnliveness.framework
├── YTCommonLiveness.framework
├── YTFaceAlignmentTinyLiveness.framework
├── YTFaceDetectorLiveness.framework
├── YTFaceLiveReflect.framework
├── YTFaceTrackerLiveness.framework
├── YTPoseDetector.framework
├── YtSDKKitActionLiveness.framework
├── YtSDKKitFramework.framework
├── YtSDKKitReflectLiveness.framework
├── YtSDKKitSilentLiveness.framework
├── tiny_opencv2.framework
├── HuiYanOverseasSDK.framework
├── OcrSDKKit.framework
├── TXYCommonDevice.framework
├── TXYCommonNetworking.framework
├── TXYCommonUtils.framework
├── YTCv.framework
├── YTImageRefiner.framework
├── YtSDKKitFrameworkTool.framework
└── YTSm.framework

3. Link Binary With Libraries: add the system frameworks.
├── libc++.tbd
├── Accelerate.framework
└── CoreML.framework
4. Copy Bundle Resources: import resource files.
├── face-tracker-v003.bundles
├── huiyan_verification.bundle
├── HuiYanSDKUI.bundle
└── OcrSDK.bundle
5. Set the Other Linker Flags in Build Settings to add -ObjC.


Integrate via local Pod

1. Create a CloudHuiYanSDK_FW.podspec file.
Pod::Spec.new do |s|
s.name = "CloudHuiYanSDK_FW"
s.version = "1.0.0"
s.platform = :ios, "9.0"
s.summary = 'frameworks and bundle resources for youtu mobile hdr'
s.homepage = 'xxx'
s.license = 'MIT'
s.source = {
:git => 'xxx' ,:tag => "#{s.version}"
}
s.static_framework = true
s.compiler_flags = "-ObjC"
s.author = {'xxx' => 'xxx'}
s.pod_target_xcconfig = {'VALID_ARCHS' =>['arm64']}
s.subspec 'Framework' do |framework|
framework.frameworks = 'Accelerate'
framework.vendored_frameworks = 'Frameworks/*.framework'
end
s.subspec 'Resource' do |resource|
resource.resources = 'Resources/*'
end
end
2. Create a CloudHuiYanSDK_FW folder in the project root directory, create Frameworks and Resources subdirectories, and move the SDK contents to these directories. The structure is as follows:
├──Project
├──CloudHuiYanSDK_FW
├───────CloudHuiYanSDK_FW.podspec
├───────Frameworks
├────────────HuiYanEKYCVerification.framework
├────────────tnn.framework
├────────────tnnliveness.framework
├────────────YTCommonLiveness.framework
├────────────YTFaceAlignmentTinyLiveness.framework
├────────────YTFaceDetectorLiveness.framework
├────────────YTFaceLiveReflect.framework
├────────────YTFaceTrackerLiveness.framework
├────────────YTPoseDetector.framework
├────────────YtSDKKitActionLiveness.framework
├────────────YtSDKKitFramework.framework
├────────────YtSDKKitReflectLiveness.framework
├────────────YtSDKKitSilentLiveness.framework
├────────────tiny_opencv2.framework
├────────────HuiYanOverseasSDK.framework
├────────────OcrSDKKit.framework
├────────────TXYCommonDevice.framework
├────────────TXYCommonNetworking.framework
├────────────TXYCommonUtils.framework
├────────────YTCv.framework
├────────────YTImageRefiner.framework
├────────────YtSDKKitFrameworkTool.framework
├────────────YTSm.framework
├───────Resources
├────────────face-tracker-v003.bundles
├────────────huiyan_verification.bundle
├────────────HuiYanSDKUI.bundle
└────────────OcrSDK.bundle
3. Set in the Podfile:
target 'ProjectName' do
use_frameworks!
pod 'CloudHuiYanSDK_FW', :path => './CloudHuiYanSDK_FW'
end
4. pod install --update;
5. Check whether $(inherited) exists in the project's Build settings -> Framework Search Paths and Other Linker Flags; if not, add it manually.


Permission Settings

The SDK requires cellular network access and camera usage permission. Please add the corresponding permission declarations. Add the following key-value pairs in the main project's info.plist configuration.
<key>Privacy - Camera Usage Description</key>
<string>Requires access to your camera</string>


Initialization

Call during your App initialization, primarily to perform some SDK initialization operations.
#import <HuiYanEKYCVerification/VerificationKit.h>
- (void)viewDidLoad {
[[VerificationKit sharedInstance] initWithViewController:self];
}


Start the process

To initiate verification, simply call the startVerifiWithConfig method to configure the ekycToken and custom settings.
VerificationConfig *config = [[VerificationConfig alloc] init];
config.licPath = [[NSBundle mainBundle] pathForResource:@"eKYC_license.lic" ofType:nil];
config.languageType = HY_EKYC_EN;
config.ocrAutoTimeout = 30000;//Anti-spoofing timeout setting
config.livenessAutoTimeout = 15000;//Face single-action timeout setting
config.ekycToken = @"";
[[VerificationKit sharedInstance] startVerifiWithConfig:config withSuccCallback:^(int errorCode, id _Nonnull resultInfo, id _Nullable reserved) {
NSLog(@"ErrCode:%d msg:%@",errorCode,resultInfo);
} withFialCallback:^(int errorCode, NSString * _Nonnull errorMsg, id _Nullable reserved) {
NSLog(@"ErrCode:%d msg:%@ extra:%@",errorCode,errorMsg,reserved);
}];
ekycToken is the unique credential for the current identity authentication process, obtained from the server.
Note: The "eKYC_license.lic" file requires contacting business representatives or customer service to apply for a license. Place the obtained license file under Copy Bundle Resources.


SDK resource release

When the SDK is no longer in use after it is called, you can invoke the SDK resource release API:
- (void)dealloc {
[VerificationKit clearInstance];
}

Note:
For the complete iOS code sample, see iOS Demo.


Instructions for using the Enhanced Edition and Plus Edition

The current version supports three security level modes: Basic, Enhance, and Plus. The Enhance and Plus modes can further improve the security of device and liveness detection. The following describes the upgrade steps from the Basic face comparison mode to the Enhanced and Plus modes.


Upgrade the SDK version

For iOS, the 1.0.0.x version is the Basic edition. To use the Enhanced and Plus edition capabilities, you need to upgrade the SDK to version 1.0.1.x. The APIs of version 1.0.1.x are fully compatible with those of version 1.0.0.x. Simply overwrite the old version with the new SDK to complete the upgrade. Switching between different versions can be done by setting the SdkVersion parameter in ApplySdkVerificationToken.

The capabilities of each edition are as follows:
SDK version
Basic edition (SdkVersion: BASIC)
Enhance edition (SdkVersion: ENHANCE)
Plus edition (SdkVersion: PLUS)
1.0.0.x
1.0.1.x

Apply for authorization file

Apply for the SDK license file (example file name: YTFaceSDK.license).
Apply for the device risk control license file (example file name: turing.license).
Please contact customer service or the operations support team to obtain the corresponding license file, and configure your system using the actual file name.


Configure and start the SDK

//Configure the SDK
VerificationConfig *config = [[VerificationConfig alloc] init];
//Set lic
config.licPath = [[NSBundle mainBundle] pathForResource:@"YTFaceSDK.license" ofType:@""];
//If device risk control is enabled, a risk control license must be provided. The Enhanced and Plus editions require this configuration to be enabled, while the Basic edition does not.
config.openCheckRiskMode = YES;
config.riskLicense = [[NSBundle mainBundle] pathForResource:@"turing.license" ofType:@""];

Note:
Place the license file in the current project directory and add it to the resource files (copy Bundle Resources).

Mode Selection Configuration

When calling the ApplySdkVerificationToken API to obtain the business Token, specify whether to enable the Enhance edition or Plus edition by setting the SdkVersion parameter:
Enhanced edition: Set the corresponding SdkVersion value to ENHANCE.
Plus edition: Set the corresponding SdkVersion value to PLUS.
For specific values of SdkVersion, see ApplySdkVerificationToken.


Complete enabling process

1. Token acquisition phase: When calling the GetFaceIdTokenIntl API, set the corresponding SdkVersion parameter.
2. SDK configuration phase: Enable the device risk control capability in the SDK initialization configuration. For details, refer to the iOS API overview documentation.
3. Feature invocation phase: When calling the start method, pass the configured Token.
4. Mode takes effect: The SDK automatically enables the corresponding security level based on the mode information in the Token.
Note:
Ensure that the parameter settings in both the SDK configuration and Token acquisition phases are exactly consistent; otherwise, it may cause mode enablement failures or abnormal functionality.


SDK API Usage Instructions

When the SDK is started with the token (sdkToken) obtained from the corresponding ApplySdkVerificationToken API, the SDK will automatically enable the corresponding mode.
Startup Mode
Corresponding CheckMode value
Mode Description
Identity verification
1
This mode includes the entire process of document recognition, liveness detection, and face comparison.
Selfie verification
2
This mode only includes but covers the entire process of liveness detection and face comparison.
Liveness detection mode
3
This mode only includes the liveness detection process.



Bantuan dan Dukungan

Apakah halaman ini membantu?

masukan