Integration Preparations
Sign up for a Tencent Cloud account. For more information, see Signing Up. Overall Architecture Diagram
The following diagram shows the architecture of the liveness detection and face comparison SDK integration.
eKYC SDK integration includes two parts:
Client-side integration: Integrate the eKYC SDK into the customer's terminal service app.
Server-side integration: Expose the endpoint of your (merchant) application to your (merchant) server so that the merchant application can interact with the merchant server and then access the eKYC SaaS API to obtain the SdkToken
, which is used throughout the liveness detection and face comparison process and to pull the final verification result.
Overall Interaction Process
You only need to pass in the token and start the corresponding eKYC SDK's liveness detection method to complete liveness detection and return the result.
The following diagram shows the overall logic of interaction between the SDK, client, and server:
The recommended detailed interaction process is as follows:
1. The customer triggers the merchant application on the terminal to call the liveness verification service scenario.
2. The merchant application sends a request to the merchant server to notify that the liveness detection service token is required for starting liveness verification once.
3. The merchant server passes in relevant parameters to call the TencentCloud API GetFaceldTokenIntl. 4. After receiving the request for calling GetFaceldTokenIntl, the FaceID SaaS delivers the service token to the merchant server. 5. The merchant server delivers the obtained service token to the customer's merchant application.
6. The merchant application calls the eKYC SDK's startup API startHuiYanAuth to pass in the token and configuration information and starts liveness verification.
7. The eKYC SDK captures and uploads the required user data, including liveness data, to the eKYC SaaS.
8. The eKYC SaaS returns the verification result to the eKYC SDK after completing liveness verification (including the liveness detection and face comparison).
9. The eKYC SDK actively triggers callback to notify the merchant application that the verification is complete and of the verification status.
10. After receiving the callback, the merchant application sends a request to notify the merchant server to obtain the verification result for confirmation.
11. The merchant server actively calls the eKYC SaaS API GetFaceIdResultIntl to pass in the relevant parameters and service token and obtain the verification result. 12. After receiving the request for calling GetFaceIdResultIntl, the eKYC SaaS returns the verification result to the merchant server. 13. After receiving the verification result, the merchant server delivers the required information to the merchant application.
14. The merchant application displays the final result on the UI to notify the customer of the verification result.
Integration
Server Integration
1. Integration preparations
Before server integration, you need to activate the Tencent Cloud eKYC service and obtain TencentCloud API access key SecretId and SecretKey by following the instructions in Getting API Key. In addition, you need to follow the instructions in Connecting to TencentCloud API to import the SDK package with the programming language you are familiar with to your server modules, to ensure that the TencentCloud API can be successfully called and API requests and responses can be properly processed. 2. Integration process
To ensure that your (merchant) client application interacts with your (merchant) server, the merchant server needs to call the API GetFaceIdTokenIntl provided by eKYC to obtain SDKToken
, which is used throughout the liveness detection and face comparison process and used by the API GetFaceIdResultIntl to obtain the liveness comparison result. The merchant server also needs to provide the corresponding endpoint for the merchant client to call. The following sample code with the Golang language is used as an example to show how to call TencentCloud API on the server and obtain the correct response. Note: This example only demonstrates the processing logic required for interaction between the merchant server and TencentCloud API service. If necessary, you need to implement your own business logic, for example:
After you obtain the SDKToken
using the API GetFaceIdTokenIntl, you can return other responses required by the client application to the client along with the SDKToken
.
After you obtain the liveness detection and face comparison result using the API GetFaceIdResultIntl, you can save the returned photo with the best frame rate for later business logic.
var FaceIdClient *faceid.Client
func init() {
prof := profile.NewClientProfile()
prof.HttpProfile.ReqTimeout = 60
credential := cloud.NewCredential("SecretId", "SecretKey")
var err error
FaceIdClient, err = faceid.NewClient(credential, "ap-singapore", prof)
if nil != err {
log.Fatal("FaceIdClient init error: ", err)
}
}
func GetFaceIdToken(w http.ResponseWriter, r *http.Request) {
log.Println("get face id token")
_ = r.ParseForm()
var SecureLevel = r.FormValue("SecureLevel")
request := faceid.NewGetFaceIdTokenIntlRequest()
request.SecureLevel = &SecureLevel
response, err := FaceIdClient.GetFaceIdTokenIntl(request)
if nil != err {
_, _ = w.Write([]byte("error"))
return
}
SdkToken := response.Response.SdkToken
apiResp := struct {
SdkToken *string
}{SdkToken: SdkToken}
b, _ := json.Marshal(apiResp)
_, _ = w.Write(b)
}
func GetFaceIdResult(w http.ResponseWriter, r *http.Request) {
_ = r.ParseForm()
SdkToken := r.FormValue("SdkToken")
request := faceid.NewGetFaceIdResultIntlRequest()
request.SdkToken = &SdkToken
response, err := FaceIdClient.GetFaceIdResultIntl(request)
if nil != err {
_, _ = w.Write([]byte("error"))
return
}
result := response.Response.Result
apiResp := struct {
Result *string
}{Result: result}
b, _ := json.Marshal(apiResp)
_, _ = w.Write(b)
}
func main() {
http.HandleFunc("/api/v1/get-token", GetFaceIdToken)
http.HandleFunc("/api/v1/get-result", GetFaceIdResult)
err := http.ListenAndServe(":8080", nil)
if nil != err {
log.Fatal("ListenAndServe error: ", err)
}
}
3. API testing
After you complete the integration, you can test whether the current integration is correct by running the postman or curl command. To be specific, access the API (http://ip:port/api/v1/get-token) to check whether SdkToken
is returned and access the API (http://ip:port/api/v1/get-result) to check whether the value of the Result
field is 0. Through these results, you can determine whether the server integration is successful. For details on responses, see API introduction.
Integration with Android
1. Dependent environment
The current FaceID SDK for Android is supported by API 19 (Android 4.4) or later.
2. SDK integration steps
1. Add the files huiyansdk_android_overseas_1.0.9.6_release.aar, 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 version numbers of the files downloaded from the official website shall prevail) to the libs directory of your project.
2. Configure build.gradle in your project as follows:
ndk {
abiFilters 'armeabi-v7a'
}
dependencies {
implementation files("libs/huiyansdk_android_overseas_1.0.9.5_release.aar")
implementation files("libs/tencent-ai-sdk-youtu-base-1.0.1.32-release.aar")
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 'com.google.code.gson:gson:2.8.5'
}
3. Make the necessary permission declaration in the AndroidManifest.xml
file.
<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.WRITE_EXTERNAL_STORAGE" />
If your app needs to be compatible with Android 6.0 or later, in addition to declaring the above permissions in the AndroidManifest.xml
file, you need to add the code Dynamically apply for permissions.
3. API initialization
This API is called during app initialization, which is mainly used to perform some initialization operations for the SDK. We recommend you call this API in Application
.
@Override
public void onCreate() {
super.onCreate();
instance = this;
HuiYanOsApi.init(getApp());
}
4. Start the liveness verification API
HuiYanOsConfig huiYanOsConfig = new HuiYanOsConfig();
huiYanOsConfig.setAuthLicense("YTFaceSDK.license");
if (compatCheckBox.isChecked()) {
huiYanOsConfig.setPageColorStyle(PageColorStyle.Dark);
}
if (needBestImageCB.isChecked()) {
huiYanOsConfig.setNeedBestImage(true);
}
HuiYanOsApi.startHuiYanAuth(currentToken, huiYanOsConfig, new HuiYanOsAuthCallBack() {
@Override
public void onSuccess(HuiYanOsAuthResult authResult) {
showToast("Liveness verification passed.");
if (!TextUtils.isEmpty(authResult.getBestImage())) {
CommonUtils.decryptBestImgBase64(authResult.getBestImage(), false);
}
}
@Override
public void onFail(int errorCode, String errorMsg, String token) {
String msg = "Liveness verification failed " + "code: " + errorCode + " msg: " + errorMsg + " token: " + token;
Log.e(TAG, "onFail" + msg);
showToast(msg);
}
});
HuiYanOsAuthResult is the returned result of successful liveness verification. The final liveness verification result can be obtained by accessing GetFaceldResultIntl through the token. Note: You need to contact the customer service to apply for the "YTFaceSDK.license" file, and then place the license file in the Assets Folder
.
5. Release SDK resources
Before your app exits, you can call the API to release SDK resources.
@Override
protected void onDestroy() {
super.onDestroy();
HuiYanOsApi.release();
}
If the obfuscation feature is enabled for your app, add the following to your obfuscation file to ensure the normal running of the SDK:
# The following FaceID SDK obfuscation rules should be added:
-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 {*;}
Integration with iOS
1. Dependent environment
1. Development environment: Xcode 11.0 or later
2. The eKYC SDK for iOS is only supported by iOS 9.0 or later.
2. SDK integration steps
Manual integration
1. Import libraries and files.
Click Link Binary With Libraries
to add frameworks.
2. The SDK depends on the following libraries:
├──HuiYanOverseasSDK.framework
├──YtSDKKitSilentLiveness.framework
├──YtSDKKitReflectLiveness.framework
├──YtSDKKitActionLiveness.framework
├──YtSDKKitFramework.framework
├──tnnliveness.framework
├──YTFaceAlignmentTinyLiveness.framework
├──YTFaceTrackerLiveness.framework
├──YTFaceDetectorLiveness.framework
├──YTPoseDetector.framework
├──YTCommonLiveness.framework
├──TXYCommonDevice.framework
├──TXYCommonNetworking.framework
├──TXYCommonUtils.framework
├──YTCv.framework
├──YtSDKKitFrameworkTool.framework
├──YTSm.framework
└──YTFaceLiveReflect.framework
3. Click Link Binary With Libraries
to add system frameworks.
├── AVFoundation.framework
├── libc++.tbd
└── Accelerate.framework
4. Import the model in Copy Bundle Resources
.
└── face-tracker-v003.bundle
5. Import the resource file in Copy Bundle Resources
.
Integration by using pod
1. Copy the CloudHuiYanSDK_FW
folder to the directory at the same level as that of the integration project Podfile
.
2. Set the following in Podfile
:
target 'HuiYanAuthDemo' do
use_frameworks!
pod 'CloudHuiYanSDK_FW', :path => './CloudHuiYanSDK_FW'
end
3. Run pod install
.
Note:
For the file levels and specific settings, see the demo.
Build Phases
settings
1. Click Other Linker Flags
to add -ObjC.
2. Integrate ViewController.m
and set the extension to .mm
(for a Swift project, add the system library libc++.tbd
).
Permission settings
As the SDK requires a mobile network and camera permission, include the following key-value pair in info.plist
of the main project to add the corresponding permission declaration.
<key>Privacy - Camera Usage Description</key>
<string>FaceID requires you to grant the camera permission for face recognition.</string>
3. Start the liveness detection API
#import <HuiYanOverseasSDK/HuiYanOsApi.h>
#import <HuiYanOverseasSDK/HuiYanOSKit.h>
// Get the token
NSString *faceToken = self.tokenTextField.text;
// Configure the SDK
HuiYanOsConfig *config = [[HuiYanOsConfig alloc] init];
// Set the license
config.authLicense = [[NSBundle mainBundle] pathForResource:@"xxx.lic" ofType:@""];
// Timeout configuration for the preparation stage
config.prepareTimeoutMs = 20000;
// Timeout configuration for the detection stage
config.authTimeOutMs = 20000;
config.isDeleteVideoCache = YES;
config.languageType = EN;
// config.userLanguageFileName = @"ko";
// config.userLanguageBundleName = @"UseLanguageBundle";
config.iShowTipsPage = YES;
config.isGetBestImg = YES;
[[HuiYanOSKit sharedInstance] startHuiYaneKYC:faceToken withConfig:config
witSuccCallback:^(HuiYanOsAuthResult * _Nonnull authResult, id _Nullable reserved) {
NSString *bestImg = authResult.bestImage;
NSString *token = authResult.faceToken;
} withFailCallback:^(int errCode, NSString * _Nonnull errMsg, id _Nullable reserved) {
NSString *showMsg = [NSString stringWithFormat:@"err:%d:%@",errCode,errMsg];
NSLog(@"err:%@",showMsg);
}];
HuiYanOsAuthResult is the returned result of successful liveness verification. The final liveness verification result can be obtained by accessing GetFaceldResultIntl through the token. Note:
Currently, you need to contact the customer service to apply for the "xxx.lic" file actively.
4. Release SDK resources
Before your app exits, you can call the API to release SDK resources.
// Release the resources before exit
- (void)dealloc {
[HuiYanOsApi release];
}
//[iOS demo](https://github.com/TencentCloud/huiyan-faceid-demo/tree/main/faceid-iOS-example)
[Android demo](https://github.com/TencentCloud/huiyan-faceid-demo/tree/main/id-verification-android-example)
Was this page helpful?