This document describes the process of integrating the Identity Verification (App SDK).
Preparations
Sign up for a Tencent Cloud account. For more information, see Signing Up. Overall Architecture
The following figure shows the architecture for integrating the Identity Verification (App SDK) of Tencent Cloud eKYC.
The SDK integration includes two parts:
A. Client-side integration: Integrate the SDK into the customer's client app.
B. 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 server API to obtain SdkToken
, which is used throughout the liveness detection and face comparison process and to pull the final verification result.
Overall Interaction Process
The integrator only needs to pass in the token and start the Identity Verification (App SDK) to achieve user identity verification, which includes ID document OCR, liveness detection, and face comparison. After the end user completes the verification, the integrator can obtain the verification result using an API.
The following diagram shows the overall logic of interaction between the following modules:
End User
Identity Verification (App SDK): The SDK obtained during the preparation stage.
Merchant Application: The customer business app that uses and is integrated with the Identity Verification (App SDK).
Merchant Server: The customer server.
Identity Verification Server: Tencent Cloud Identity Verification backend service API.
The recommended detailed interaction process is as follows:
1. An end user triggers the merchant application on the terminal to call the identity 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 identity verification once.
4. After receiving the request for calling ApplySdkVerificationToken, the identity verification server delivers the 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 Identity Verification (App SDK)'s startup API startHuiYanAuth to pass in the token and configuration information and starts identity verification.
7. The Identity Verification (App SDK) starts OCR by uploading the document photo to the identity verification server to recognize the user's document information.
8. The identity verification server returns the result to the Identity Verification (App SDK).
9. The Identity Verification (App SDK) captures and uploads the required user data, including liveness data, to the identity verification server.
10. After completing liveness detection and face comparison, the identity verification server returns the result to the Identity Verification (App SDK).
11. The Identity Verification (App SDK) actively triggers callback to notify the merchant application that the verification is complete and of the verification status.
12. After receiving the callback, the merchant application sends a request to notify the merchant server to obtain the verification result for confirmation.
13. The merchant server actively calls the identity verification server API GetSdkVerificationResult with relevant parameters and the service token passed in to obtain the verification result. 14. After receiving the request for calling GetSdkVerificationResult, the identity verification server returns the verification result to the merchant server. 15. After receiving the verification result, the merchant server delivers the required information to the merchant application.
16. The merchant application displays the final result on the UI to notify the user of the verification result.
Integration Process
Server-side integration
1. Preparations
Before server-side 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] (https://www.tencentcloud.com/document/product/1061/54960!398ac9c1781426f85199f8704c2ae268) 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
To ensure that your (merchant) client application interacts with your (merchant) server, the merchant server needs to call the API ApplySdkVerificationToken provided by eKYC to obtain SDKToken
, which is used throughout the identity verification process and used by the API [GetSdkVerificationResult](https://www.tencentcloud.com/document/product/1061/49951!f60fbe65c5f7cb4584259d37c8176b67) to obtain the verification 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 ApplySdkVerificationToken API, you can return other responses required by the client application to the client along with the SDKToken
.
After you obtain the identity verification result using the GetSdkVerificationResult API, 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 ApplySdkVerificationToken(w http.ResponseWriter, r *http.Request) {
log.Println("get face id token")
_ = r.ParseForm()
var IdCardType = r.FormValue("IdCardType")
var NeedVerifyIdCard = false
request := faceid.NewApplySdkVerificationTokenRequest()
request.IdCardType = &IdCardType
request.NeedVerifyIdCard = &NeedVerifyIdCard
response, err := FaceIdClient.ApplySdkVerificationToken(request)
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)
_, _ = w.Write(b)
}
func GetSdkVerificationResult(w http.ResponseWriter, r *http.Request) {
_ = r.ParseForm()
SdkToken := r.FormValue("SdkToken")
request := faceid.NewGetSdkVerificationResultRequest()
request.SdkToken = &SdkToken
response, err := FaceIdClient.GetSdkVerificationResult(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", ApplySdkVerificationToken)
http.HandleFunc("/api/v1/get-result", GetSdkVerificationResult)
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-side integration is successful. For details on responses, see API description.
Integration with Android
1. Dependent environment
The current SDK for Android is applicable to API 19 (Android 4.4) and later.
2. SDK integration steps
1. Add the following files to the libs directory of your project: ekyc_android_1.0.x.x_release.aar, huiyansdk_android_1.0.x.x_release.aar, OcrSDK-private-v1.0.x.x-release.aar, OcrSDK-common-model-v1.0.x.x-release.aar, tencent-ai-sdk-youtu-base-v1.0.x.x-release.aar, tencent-ai-sdk-common-v1.0.x.x-release.aar, and tencent-ai-sdk-aicamera-v1.0.x.x-release.aar (the version numbers of the files downloaded from the official website apply).
2. Configure build.gradle in your project as follows:
// Set .so architecture filtering in NDK (using armeabi-v7a as an example)
ndk {
abiFilters 'armeabi-v7a'
}
dependencies {
// Identity Verification (App SDK) version
implementation files("libs/ekyc_android_1.0.x.x_release.aar")
// Identity verification components
implementation files("libs/huiyansdk_android_1.0.x.x_release.aar")
// OCR components
implementation files("libs/OcrSDK-common-model-v1.x.x-release.aar")
implementation files("libs/OcrSDK-private-v2.x.x-release.aar")
// Common capability components
implementation files("libs/tencent-ai-sdk-youtu-base-1.0.x.x-release.aar")
implementation files("libs/tencent-ai-sdk-common-1.x.x-release.aar")
implementation files("libs/tencent-ai-sdk-aicamera-1.x.x-release.aar")
// Import a `gson` library
implementation 'com.google.code.gson:gson:2.8.5'
}
3. You also need to 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.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<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();
EkycHySdk.init(this);
}
4. Starting the identity verification process
When you need to start the identity verification process, call the function EkycHySdk.startEkycCheck(), and pass in the sdkToken
required for this process, configuration information, and the callback for listening for the result.
EkycHyConfig ekycHyConfig = new EkycHyConfig();
ekycHyConfig.setLicenseName("ekycLicense.license");
ekycHyConfig.setOcrType(OcrRegionType.HK);
OcrUiConfig config = new OcrUiConfig();
ekycHyConfig.setOcrUiConfig(config);
EkycHySdk.startEkycCheck(sdkToken, ekycHyConfig, new EkycHyCallBack() {
@Override
public void onSuccess(EkycHyResult result) {
Log.e(TAG, "result: " + result.toString());
showToast ("Identity verification succeeded:" + result.toString());
}
@Override
public void onFail(int errorCode, String errorMsg, String ekycToken) {
Log.e(TAG, "code: " + errorCode + " msg: " + errorMsg + " token: " + ekycToken);
showToast ("Identity verification failed:" + "code: " + errorCode + " msg: " + errorMsg + " token: " + ekycToken);
}
});
sdkToken is the unique credential obtained from the server for this identity verification process.
Note: ekycLicense.license is the license file obtained from the sales rep or customer service, and you need to place it in the assets
folder.
└── src
└── main
├── assets
│ └── ekycLicense.license
5. Releasing SDK resources
Before your app exits, you can call the SDK resource release API.
@Override
protected void onDestroy() {
EkycHySdk.release();
super.onDestroy();
}
6. Configuring obfuscation rules
If the obfuscation feature is enabled for your app, add the following part to your obfuscation file to ensure the normal use of the SDK.
# Objects to be obfuscated
-keep class com.google.gson.** {*;}
-keep class com.tencent.could.** {*;}
-keep class com.tencent.youtu.** {*;}
-keep class com.tencent.cloud.ocr.** {*;}
-keep class com.tencent.cloud.ekyc.** {*;}
Note: For the full code example for Android, see Android demo. Integration with iOS
1. Dependent environment
1. Xcode 12.0 or later is required. We recommend you use the latest version.
2. The SDK for iOS is only supported by iOS 11.0 or later.
2. SDK integration steps
Manual integration
1. Import the relevant libraries and files.
Import relevant frameworks in Link Binary With Libraries
.
2. The SDK depends on the following libraries:
├── HuiYanEKYCVerification.framework
├── tnn.framework
├── tnnliveness.framework
├── YTCommonLiveness.framework
├── YTFaceAlignmentTinyLiveness.framework
├── YTFaceDetectorLiveness.framework
├── YTFaceLiveReflect.framework
├── YTFaceTrackerLiveness.framework
├── YTPoseDetector.framework
├── YtSDKKitActionLiveness.framework
├── YtSDKKitFramework.framework
├── YtSDKKitOcrVideoIdent.framework
├── YtSDKKitReflectLiveness.framework
├── YtSDKKitSilentLiveness.framework
├── tiny_opencv2.framework
├── HuiYanOverseasSDK.framework
├── IdVerification.framework
├── OcrSDKKit.framework
├── TXYCommonDevice.framework
├── TXYCommonNetworking.framework
├── TXYCommonUtils.framework
├── YTCv.framework
├── YTImageRefiner.framework
├── YtSDKKitFrameworkTool.framework
└── YTSm.framework
In Link Binary With Libraries
, import the system framework.
├── AVFoundation.framework
├── libc++.tbd
├── Accelerate.framework
└── CoreML.framework
Import the resource file in Copy Bundle Resources
.
├── face-tracker-v003.bundle
├── huiyan_verification.bundle
├── HuiYanSDKUI.bundle
└── OcrSDK.bundle
Build Phases
settings
1. In Other Linker Flags
, 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, add the corresponding permission declarations and add the following key-value
to the project's info.plist
configuration.
<key>Privacy - Camera Usage Description</key>
<string>The SDK needs to access your camera</string>
3. Starting the identity verification process
1. Initialize
This API is called when you initialize your app. It is mainly used for some SDK initialization operations.
#import <HuiYanEKYCVerification/VerificationKit.h>
- (void)viewDidLoad {
[[VerificationKit sharedInstance] initWithViewController:self];
}
2. Start the identity verification process
To start the identity verification process, you just need to call the startVerifiWithConfig
method with ekycToken
and some other custom fields set.
VerificationConfig *config = [[VerificationConfig alloc] init];
config.licPath = [[NSBundle mainBundle] pathForResource:@"" ofType:nil];
config.languageType = HY_EKYC_EN;
config.livenessAutoTimeout = 30000;
config.ocrAutoTimeout = 20000;
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 obtained from the server for this eKYC process.
Note: "eKYC_license.lic" is the license file obtained from the sales rep or customer service, and you need to place it in Copy Bundle Resources
.
4. Releasing SDK resources
You can call the SDK resource release API after you finish operations and no longer need the SDK.
- (void)dealloc {
[VerificationKit clearInstance];
}
Note: For the complete code example for iOS, see iOS demo.
Was this page helpful?