tencent cloud

Feedback

Integration Process

Last updated: 2024-01-19 14:57:50
    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.
    Complete enterprise identity verification. For more information, see 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

    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.
    API for getting the token: ApplySdkVerificationToken
    API for pulling the identity verification result: GetSdkVerificationResult
    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.
    3. The merchant server passes in relevant parameters to call the TencentCloud API ApplySdkVerificationToken.
    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() {
    // Instantiate a client configuration object. You can specify the timeout period and other configuration items
    prof := profile.NewClientProfile()
    prof.HttpProfile.ReqTimeout = 60
    // TODO replace the SecretId and SecretKey string with the API SecretId and SecretKey
    credential := cloud.NewCredential("SecretId", "SecretKey")
    var err error
    // Instantiate the client object of the requested faceid
    FaceIdClient, err = faceid.NewClient(credential, "ap-singapore", prof)
    if nil != err {
    log.Fatal("FaceIdClient init error: ", err)
    }
    }
    
    // ApplySdkVerificationToken get token
    func ApplySdkVerificationToken(w http.ResponseWriter, r *http.Request) {
    log.Println("get face id token")
    // Step 1: ... parse parameters
    _ = r.ParseForm()
    var IdCardType = r.FormValue("IdCardType")
    var NeedVerifyIdCard = false
    
    // Step 2: instantiate the request object and provide necessary parameters
    request := faceid.NewApplySdkVerificationTokenRequest()
    request.IdCardType = &IdCardType
    request.NeedVerifyIdCard = &NeedVerifyIdCard
    // Step 3: call the Tencent Cloud API through FaceIdClient
    response, err := FaceIdClient.ApplySdkVerificationToken(request)
    
    // Step 4: process the Tencent Cloud API response and construct the return 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)
    
    // ... more codes are omitted
    
    //Step 5: return the service response
    _, _ = w.Write(b)
    }
    
    // GetSdkVerificationResult get result
    func GetSdkVerificationResult(w http.ResponseWriter, r *http.Request) {
    // Step 1: ... parse parameters
    _ = r.ParseForm()
    SdkToken := r.FormValue("SdkToken")
    // Step 2: instantiate the request object and provide necessary parameters
    request := faceid.NewGetSdkVerificationResultRequest()
    request.SdkToken = &SdkToken
    // Step 3: call the Tencent Cloud API through FaceIdClient
    response, err := FaceIdClient.GetSdkVerificationResult(request)
    
    // Step 4: process the Tencent Cloud 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)
    
    // ... more codes are omitted
    
    //Step 5: return the service response
    _, _ = w.Write(b)
    }
    
    func main() {
    // expose endpoints
    http.HandleFunc("/api/v1/get-token", ApplySdkVerificationToken)
    http.HandleFunc("/api/v1/get-result", GetSdkVerificationResult)
    // listening port
    err := http.ListenAndServe(":8080", nil)
    if nil != err {
    log.Fatal("ListenAndServe error: ", err)
    }
    
    Note: For the full code example, see faceid-server-demo.

    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.
    <!-- Camera permission -->
    <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" />
    
    <!-- Permissions required by the SDK -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <!-- Permissions optional for the SDK -->
    <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.
    // Set startup configurations
    EkycHyConfig ekycHyConfig = new EkycHyConfig();
    // Set the license name
    ekycHyConfig.setLicenseName("ekycLicense.license");
    ekycHyConfig.setOcrType(OcrRegionType.HK);
    // Customize UI configurations
    OcrUiConfig config = new OcrUiConfig();
    ekycHyConfig.setOcrUiConfig(config);
    // Set specific startup verification logic
    // `sdkToken` is the unique credential obtained from the server for this process
    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
    ├── HKOCRSDK.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
    ├── idverificationres.bundle
    ├── ocr-v001.bundle
    ├── OcrSDK.bundle
    └── ytsdkviidres.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>
    <key>Privacy - Photo Library Usage Description</key>
    <string>The SDK needs to access your album</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.verAutoTimeOut = 30000;// Set the verification timeout period
    config.hyFaceTimeOut = 15000;// Set the timeout period of a single face authentication operation
    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.
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support