tencent cloud

eKYC

Integration Process

Download
Focus Mode
Font Size
Last updated: 2026-05-07 10:43:57

Integration Preparation

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 and activate the service.
Contact us to obtain the latest SDK and License.

Overall Architecture Diagram

The following diagram illustrates the architecture for integrating the selfie SDK:

image.5


eKYC SDK integration consists of two parts:
Client-side Integration: Integrate the eKYC SDK into your client-side business application.
Server-side Integration: Expose endpoints of your (merchant) application on your (merchant) server. This enables the merchant application to interact with the merchant server, then access the FaceId SaaS API to obtain the SdkToken for the linked selfie verification process and to pull the final verification result using the SdkToken.

Overall Interaction Flow

The integrator only needs to pass in the Token and invoke the corresponding eKYC SDK's liveness detection method. This completes the liveness detection and returns the liveness result.
1. To obtain a Token, refer to the TencentCloud API: GetFaceIdTokenIntl.
2. The TencentCloud API for users to actively pull liveness results: GetFaceIdResultIntl
The following diagram illustrates the overall interaction logic between the SDK client and the server. The modules responsible for each part in the diagram are explained below:



The specific recommended interaction flow is as follows:
1. The user triggers the terminal Merchant Application to prepare for invoking the selfie verification business scenario.
2. The Merchant Application sends a request to the Merchant Server, notifying it that initiating an selfie verification session requires a liveness service Token.
3. The Merchant Server calls the TencentCloud API GetFaceIdTokenIntl by passing in the relevant parameters.
4. Upon receiving the GetFaceIdTokenIntl call, FaceID SaaS issues the token for this session to the Merchant Server.
5. The Merchant Server can deliver the obtained service Token to the customer's Merchant Application.
6. The Merchant Application calls the eKYC SDK's startup interface startHuiYanAuth by passing in the token and configuration information, thereby initiating the selfie verification process.
7. The FaceID SDK captures and uploads the required user data, including liveness data, to FaceID SaaS.
8. After completing the selfie verification process (including liveness and comparison), FaceID SaaS returns the result to the FaceID SDK.
9. The FaceID SDK actively triggers a callback to the Merchant Application to notify it of the verification completion and status.
10. After receiving the callback, the Merchant Application can send a request to notify the Merchant Server to proactively obtain the result of this selfie verification session for confirmation.
11. The Merchant Server proactively calls the FaceID SaaS API GetFaceIdResultIntl by passing in the relevant parameters and the Token for this session to obtain the result of this selfie verification.
12. Upon receiving the GetFaceIdResultIntl call, FaceID SaaS returns the result of this selfie verification to the Merchant Server.
13. After the result of this selfie verification is received, the Merchant Server can deliver the required information to the Merchant Application.
14. The Merchant Application displays the final result on the UI page, informing the user of the selfie verification outcome.

Access Process

Server-Side Integration

1. Integration Preparation

Before integrating on the server side, you need to follow the instructions in Obtain API Key Guide to activate Tencent Cloud eKYC service and obtain the TencentCloud API access keys SecretId and SecretKey. Additionally, you need to follow the procedure in Connect to TencentCloud API to import the SDK package for your preferred programming language into your server-side module, ensuring successful calls to TencentCloud API and proper handling of API requests and responses.

2. Starting the Integration

To ensure your (merchant) client application can interact properly with your (merchant) server, the merchant server needs to call the API GetFaceIdTokenIntl provided by eKYC to obtain the SDKToken for orchestrating the entire selfie verification process, and call the GetFaceIdResultIntl API to obtain the selfie verification result. The merchant server also needs to provide corresponding endpoints for the merchant client to call. The following sample code uses the Go language as an example to demonstrate how to call TencentCloud API on the server side and obtain the correct response.
Note:
This example only demonstrates the processing logic required for the merchant server to interact with TencentCloud API. If needed, you must implement your own business logic, such as:
After you obtain the selfie verification SDKToken via the GetFaceIdTokenIntl API, you can return the other responses required by the client application together with the SDKToken to the client.
After you obtain the liveness verification result via the GetFaceIdResultIntl API, you can save the returned best-frame photo for use in subsequent business logic.
var FaceIdClient *faceid.Client

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

// GetFaceIdToken obtains the Face Identity Verification Token.
func GetFaceIdToken(w http.ResponseWriter, r *http.Request) {
log.Println("get face id token")
// Step 1: Parse the request parameters.
_ = r.ParseForm()
var SecureLevel = r.FormValue("SecureLevel")

// Step 2: Initialize the request object and assign values to the necessary parameters.
request := faceid.NewGetFaceIdTokenIntlRequest()
request.SecureLevel = &SecureLevel
// Step 3: Call the Face Identity Verification service via FaceIdClient.
response, err := FaceIdClient.GetFaceIdTokenIntl(request)

// Step 4: Process the TencentCloud API response and construct the return object.
if nil != 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 Face Identity Verification result.
func GetFaceIdResult(w http.ResponseWriter, r *http.Request) {
// Step 1: ... Parse the request parameters.
_ = r.ParseForm()
SdkToken := r.FormValue("SdkToken")
// Step 2: Initialize the request object and assign values to the necessary parameters.
request := faceid.NewGetFaceIdResultIntlRequest()
request.SdkToken = &SdkToken
// Step 3: Call the Face Identity Verification service via FaceIdClient.
response, err := FaceIdClient.GetFaceIdResultIntl(request)

// Step 4: Process the TencentCloud API response and construct the return 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 the http API path.
http.HandleFunc("/api/v1/get-token", GetFaceIdToken)
http.HandleFunc("/api/v1/get-result", GetFaceIdResult)
// Listen on the port.
err := http.ListenAndServe(":8080", nil)
if nil != err {
log.Fatal("ListenAndServe error: ", err)
}
}

3. API Testing

After completing the integration, you can test whether the integration is correct using postman or curl commands. Access the API(http://ip:port/api/v1/get-token) to check whether the SdkToken is returned normally. Access the http://ip:port/api/v1/get-result API to check whether the response of the Result field is 0, thereby determining whether the server-side integration is successful. For detailed response results, refer to the API section.

Android-Side Integration

1. Prerequisites

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

2. SDK Integration Steps

1. Add huiyansdk_android_overseas_1.0.9.6_release.aar (the specific version is subject to the official website download), tencent-ai-sdk-youtu-base-1.0.1.39-release.aar , tencent-ai-sdk-common-1.1.36-release.aar, and tencent-ai-sdk-aicamera-1.0.22-release.aar (the specific versions are subject to the final provision) to the libs directory of your project.
├── codedemo
│ ├── build.gradle
│ ├── libs
│ │ ├── huiyansdk_android_overseas_1.0.9.14_release.aar
│ │ ├── tencent-ai-sdk-aicamera-1.0.25-release.aar
│ │ ├── tencent-ai-sdk-common-1.1.43-release.aar
│ │ ├── tencent-ai-sdk-network-1.0.2.3.6-release.aar
│ │ └── tencent-ai-sdk-youtu-base-1.0.1.44-release.aar
│ ├── proguard-rules.pro
│ └── src
│ └── main
2. Configure the build.gradle file (the build.gradle file under the App module) in your project as follows:
// Configure ndk so library architecture filtering (using armeabi-v7a as an example; you can also add arm64-v8a if the device supports it).

defaultConfig {
ndk {
abiFilters 'armeabi-v7a'
}
}
dependencies {
// Import the SDK.
implementation files("libs/huiyansdk_android_overseas_1.0.9.5_release.aar")
// General Algorithm SDK
implementation files("libs/tencent-ai-sdk-youtu-base-1.0.1.32-release.aar")
// General Capability Component Library
implementation files("libs/tencent-ai-sdk-common-1.1.27-release.aar")
implementation files("libs/tencent-ai-sdk-aicamera-1.0.18-release.aar")
implementation files("libs/tencent-ai-sdk-network-1.0.2.3.6-release.aar")

// Third-party libraries required by the SDK.
// gson
implementation 'com.google.code.gson:gson:2.8.9'
}
3. Also, declare the necessary permissions in the AndroidManifest.xml file.
<!-- Camera Permission -->
<uses-permission android:name="android.permission.CAMERA" />
<uses-feature
android:name="android.hardware.camera"
android:required="true" />

<!-- Network Permission Required by the SDK -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Device Risk Control Dependencies -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Optional Permissions for the SDK -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
For applications that need to be compatible with Android 6.0 and above, in addition to declaring the permissions in the AndroidManifest.xml file, you must also request them dynamically in code.

3. SDK API Usage Instructions

Initialize the API.
Call this during your app's initialization. It is recommended to call it within the Application class, primarily to perform some SDK initialization operations.
@Override
public void onCreate() {
super.onCreate();
instance = this;
// The SDK must be initialized when the Application initializes.
HuiYanOsApi.init(getApp());
}
Main SDK Workflow
The integrator only needs to pass in the Token and invoke the corresponding liveness detection method. This completes the liveness detection and returns the liveness result.
To obtain a Token, refer to the TencentCloud API: GetFaceIdTokenIntl.
To pull the liveness detection result, refer to the TencentCloud API: GetFaceIdResultIntl.
The following diagram illustrates the overall interaction logic between the SDK, client, and server under the streamlined integration approach:

Start Streamlined Liveness Verification.
// Parameters related to HuiYanOs
HuiYanOsConfig huiYanOsConfig = new HuiYanOsConfig();
// This license file is stored under the assets directory.
huiYanOsConfig.setAuthLicense("YTFaceSDK.license");
// The license file for device risk control (required when using device risk control mode) must also be stored under the assets directory.
huiYanOsConfig.setRiskLicense("turing.lic");
// Enable Device Risk Control
huiYanOsConfig.setOpenCheckRiskMode(true);
if (compatCheckBox.isChecked()) {
huiYanOsConfig.setPageColorStyle(PageColorStyle.Dark);
}

// Start the selfie verification method to initiate liveness detection. The currentToken is data issued by the backend.
HuiYanOsApi.startHuiYanAuth(currentToken, huiYanOsConfig, new HuiYanOsAuthCallBack() {
@Override
public void onSuccess(HuiYanOsAuthResult authResult) {
// Display Result
runOnUiThread(new Runnable() {
@Override
public void run() {
Toast.makeText(SimplifyActivity.this, "Liveness passed!", Toast.LENGTH_SHORT).show();
}
});
}

@Override
public void onFail(int errorCode, String errorMsg, String token) {
String msg = "Liveness failed " + "code: " + errorCode + " msg: " + errorMsg + " token: " + token;
Log.e(TAG, "onFail" + msg);
// Display Result
runOnUiThread(new Runnable() {
@Override
public void run() {
Toast.makeText(SimplifyActivity.this, msg, Toast.LENGTH_SHORT).show();
}
});
}
});
HuiYanOsAuthResult is the return result for successful selfie verification.
Note:
The "YTFaceSDK.license" and "turing.lic" files require your active application. For now, you can contact customer service to apply for the license. Place the obtained license file under the assets directory.
├── codedemo
│ ├── build.gradle
│ ├── libs
│ ├── proguard-rules.pro
│ └── src
│ └── main
│ └── assets
│ ├── turing.lic
│ └── YTFaceSDK.license
SDK Resource Release
You can call the SDK resource release API when your APP exits.
@Override
protected void onDestroy() {
super.onDestroy();
// Release resources upon exit
HuiYanOsApi.release();
}
Obfuscation Rule Configuration
If your application has the obfuscation feature enabled, add the following section to your obfuscation file to ensure the SDK functions properly.
#SDK Obfuscation Includes
-keep class com.tencent.could.huiyansdk.** {*;}
-keep class com.tencent.could.aicamare.** {*;}
-keep class com.tencent.could.component.** {*;}
-keep class com.tencent.youtu.** {*;}
-keep class com.tenpay.utils.SMUtils {*;}
-keep class com.tencent.turingface.** {*;}
-keep class com.turingface.sdk.** {*;}
-keep class com.tencent.cloud.ai.network.** {*;}

iOS-Side Integration

1. Prerequisites

1. Development Environment: Xcode 11.0 or later
2. The eKYC iOS SDK is compatible with iOS 9.0 and later versions on mobile devices.

2. SDK Integration Steps

Manual Integration Method
1. Import the relevant libraries and files.
In the Link Binary With Libraries section, import the relevant frameworks.
2. The libraries that the SDK depends on are as follows:
└──HuiYanOverseasSDK.xcframework
3. In the Copy Bundle Resources section, import the authorization file and model resource files.
├── YTFaceSDK.license
├── turing.license
└── face-tracker-v003.bundle
4. Import resource files in the Copy Bundle Resources section.
└── HuiYanSDKUI.bundle
Integrating Using Pods
1. Create a CloudHuiYanSDK_FW folder in the project's root directory. Within this folder, create Frameworks and Resources subfolders, and then move the SDK package into the CloudHuiYanSDK_FW directory. The structure is as follows:
├──Your Project.xcodeproj
├──Podfile
├──CloudHuiYanSDK_FW
├───────CloudHuiYanSDK_FW.podspec
├───────Frameworks
├────────────HuiYanOverseasSDK.xcframework
├───────Resources
├────────────HuiYanSDKUI.bundle
└────────────face-tracker-v003.bundle
2. Create a podspec file in the CloudHuiYanSDK_FW directory:
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 = 'xx'
s.license = 'MIT'
s.source = {
:git => 'xx' ,:tag => "#{s.version}"
}
s.static_framework = true
s.compiler_flags = "-ObjC"
s.author = {'xx' => 'xx'}
s.pod_target_xcconfig = {'VALID_ARCHS' =>['arm64', 'x86_64']}
s.subspec 'Resources' do |framework|
framework.resource = 'Resources/*.bundle'
end
s.subspec 'Framework' do |framework|
framework.frameworks = 'Accelerate'
framework.vendored_frameworks = 'Frameworks/*.xcframework'
end
end
3. In the Podfile, configure the following:
target 'HuiYanAuthDemo' do
use_frameworks!
pod 'CloudHuiYanSDK_FW', :path => './CloudHuiYanSDK_FW'
end
4. Check configuration:
Build Settings -> Framework Search Paths add $(inherited)
Build Settings -> Other Linker Flags add $(inherited)
5. Run `pod install` to update.
Permission Settings
The SDK requires permissions for mobile network and camera access. Add the corresponding permission declarations. In the main project's info.plist configuration, add the following key-value pairs.
<key>Privacy - Camera Usage Description</key>
<string>Face Identity Verification requires enabling your camera permission for Face Recognition.</string>

3. 1 SDK API Usage Instructions

Main SDK Workflow
The integrator only needs to pass in the Token and invoke the corresponding liveness detection method. This completes the liveness detection and returns the liveness result.
To obtain a Token, refer to the TencentCloud API: GetFaceIdTokenIntl.
To pull the liveness detection result, refer to the TencentCloud API: GetFaceIdResultIntl.
The following diagram illustrates the overall interaction logic between the SDK, client, and server under the streamlined integration approach:

Start Liveness Verification.
#import <HuiYanOverseasSDK/HuiYanSDK.h>

// Obtain the token.
NSString *faceToken = self.tokenTextField.text;
// Configure the SDK.
HuiYanOsConfig *config = [[HuiYanOsConfig alloc] init];
// Set the license.
config.authLicense = [[NSBundle mainBundle] pathForResource:@"YTFaceSDK.license" ofType:@""];
// Preparation Phase Timeout Configuration
config.prepareTimeoutMs = 20000;
// Action Phase Timeout Configuration
config.actionTimeoutMs = 20000;
// Delete the local liveness video.
config.isDeleteVideoCache = YES;
// Set UI-related callbacks.
config.delegate = self;
// Custom Multilingual Configuration
config.languageType = EN;
// config.userLanguageFileName = @"ko";
// config.userLanguageBundleName = @"UseLanguageBundle";
config.iShowTipsPage = YES;

[[HuiYanOSKit sharedInstance] startHuiYaneKYC:faceToken withConfig:config witSuccCallback:^(HuiYanOsAuthResult * _Nonnull authResult, id _Nullable reserved) {
NSString *token = authResult.faceToken;
} withFailCallback:^(int errCode, NSString * _Nonnull errMsg, id _Nullable reserved) {
NSString *showMsg = [NSString stringWithFormat:@"err:%d:%@",errCode,errMsg];
NSLog(@"err:%@",showMsg);
}];
Note:
The "YTFaceSDK.license" file requires your active application. For now, you can contact customer service to apply for the license. Place the obtained license file under the current project directory and add it to the resource files (copy Bundle Resources).
Start Enhanced Mode / Plus Mode.
The liveness face comparison feature provides two advanced security levels: Enhanced Mode and Plus Mode, which further improve the security of liveness detection by incorporating device risk control technology. To enable these modes, you must configure the SDK and obtain the Token accordingly.
1. SDK Configuration Requirements
Whether you enable Enhanced Mode or Plus Mode, you must enable the device risk control capability in the SDK and configure the corresponding risk control license file:
HuiYanOsConfig *config = [[HuiYanOsConfig alloc] init];
config.authLicense = [[NSBundle mainBundle] pathForResource:@"YTFaceSDK.license" ofType:@""];
config.openCheckRiskMode = YES;
config.riskLicense = [[NSBundle mainBundle] pathForResource:@"turing.license" ofType:@""];
Note:
The "turing.license" file requires your active application. For now, you can contact customer service to apply for the license. Place the obtained license file under the current project directory and add it to the resource files (copy Bundle Resources).
2. Token Acquisition Configuration
When calling the GetFaceIdTokenIntl or ApplySdkVerificationToken API to obtain a business Token, you must specify Enhanced Mode or Plus Mode by setting the SdkVersion parameter:
Enhanced Mode: Set the corresponding SdkVersion value.
Plus Mode: Set the corresponding SdkVersion value.
3. Mode Enablement Process
1) Set the corresponding SdkVersion parameter when the Token is obtained.
2) Enable the device risk control capability in the SDK configuration.
3) Pass the configured Token when calling the startHuiYaneKYC method.
4) The SDK automatically enables the corresponding security level based on the mode information in the Token.
Warning:
Important: Ensure that the settings in both the SDK configuration and Token acquisition steps are completely consistent. Otherwise, mode enablement may fail.


Help and Support

Was this page helpful?

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

Feedback