接入流程说明

最后更新时间：2025-04-15 11:14:49
接入流程说明
最后更新时间： 2025-04-15 11:14:49
本文介绍Identity Verification(App SDK)整体接入的流程。
﻿
接入准备
注册腾讯云企业账号，请见注册指引。
完成企业实名认证，请见企业实名指引。
登录 eKYC 控制台开通服务。
﻿联系我们获取最新的 SDK 及 License。
整体架构图
下图为腾讯云eKYC产品的Identity Verification(App SDK)集成的架构图：
﻿
﻿
﻿
SDK集成包括两部分：
A.客户端集成： 将SDK集成到客户终端业务App中。
B.服务器端集成： 在您的（商家）服务器中公开您的（商家）应用程序的端点，以便商家应用程序可以与商家服务器交互，然后访问 Server API 以获取串联活体比对流程的SdkToken以及通过SdkToken拉取最终的核身结果。
整体交互流程
集成方只需要传入Token并启动对应的Identity Verification(App SDK) ，便可以实现包含证件识别+活体检测+人脸比对全流程的用户身份认证，待终端用户完成认证后，集成方可通过API接口获取完整的认证结果。
获取Token的API接口：ApplySdkVerificationToken﻿
拉取身份认证结果的API接口: GetSdkVerificationResult﻿
下图展示了SDK、客户端以及服务器端的整体交互逻辑，图中负责模块解析：
​ End User：终端用户
​ Identity Verification(App SDK)：在准备阶段获取到的Identity Verification(App SDK)
​ Merchant Application：使用并集成Identity Verification SDK的客户终端业务App
​ Merchant Server：客户的服务器的程序
​ Identity Verification Server：腾讯云Identity Verification后台服务API接口
﻿
﻿
﻿
具体的推荐交互流程详细交互如下：
1. 用户触发终端 Merchant Application 准备调用核身业务场景。
2. Merchant Application 发送请求到 Merchant Server，告知启动一次核身业务需要活体业务Token。
3. Merchant Server 传入相关参数调用云API接口ApplySdkVerificationToken。
4. Identity Verfication Server 接收到ApplySdkVerificationToken调用后，下发此次业务的token给 Merchant Server。
5. Merchant Server可以将获取到的业务Token，下发给客户的 Merchant Application。
6. Merchant Application 调用Identity Verfication SDK的启动接口startHuiYanAuth传入token与配置信息，开始核身验证。
7. Identity Verfication SDK 启动OCR，将证件照片上传至Identity Verfication Server识别用户证件信息。
8. Identity Verfication Server将证件识别结果返回给Identity Verfication SDK。
9. Identity Verfication SDK 捕捉并上传所需的用户数据，包括活体数据等，上传至 Identity Verfication Server 。
10. Identity Verfication Server 在完成核身检测（包括活体与比对流程）以后，会返回结果给 Identity Verfication SDK 。
11. Identity Verfication SDK 主动触发回调给 Merchant Application 通知核验完成以及核验状态。
12. Merchant Application 接收到回调以后，可以发送请求通知 Merchant Server去主动获取本次核身的结果，进行确认检查。
13. Merchant Server主动调用 Identity Verfication Server 的接口GetSdkVerificationResult传入相关参数以及本次业务的Token，去获取本次核身的结果。
14. Identity Verfication Server 接收到GetSdkVerificationResult调用后，会返回本次核身的结果到 Merchant Server。
15. Merchant Server接收到本次核身的结果后，可以下发需要的信息到 Merchant Application。
16. Merchant Application 展示最后的结果，呈现在UI界面上，告知用户认证的结果。
﻿
接入流程
服务器端集成
集成准备
在服务端集成之前，你需要按照获取API秘钥指引中的说明进行操作，开通腾讯云慧眼服务，并且拿到了腾讯云api访问秘钥SecretId和SecretKey。除此之外你还需要按照连接腾讯云API接口中的操作流程，引入你所熟悉开发语言的SDK包到你服务端模块中，以确保可以成功调用腾讯云API以及正确处理API请求和响应。
开始集成
为了确保你的（商户）客户端应用程序能够跟你的（商户）服务端正常交互，商户服务端需要调用慧眼提供的API接口 ApplySdkVerificationToken 获取SDKToken串联身份认证全流程以及调用 GetSdkVerificationResult 接口获取身份认证结果，商户服务端需要提供相应的端点给商户客户端调用，下面的示例代码使用 Golang语言作为案例，展示如何在服务端调用腾讯云API接口并拿到正确的响应结果。
注意： 该示例中仅仅演示商户服务端与腾讯云API服务交互所需要的处理逻辑，如果有需要的话你需要自己实现你的业务逻辑，比如：
当你通过 ApplySdkVerificationToken 接口获取SDKToken之后，可以将客户端应用程序需要的其他响应同SDKToken一并返回给客户端。
当你通过 GetSdkVerificationResult 接口获取身份认证结果之后，可以将返回的最佳帧照片保存起来，以便后续业务逻辑使用。
var FaceIdClient *faceid.Client
﻿
func init() {
	// 初始化客户端配置对下，您可以指定超时时间和其他配置项
	prof := profile.NewClientProfile()
	prof.HttpProfile.ReqTimeout = 60
	// TODO 需要替换成您调用账号的 SecretId 和 SecretKey
	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)
	}
}
﻿
// ApplySdkVerificationToken 获取人脸核身Token
func ApplySdkVerificationToken(w http.ResponseWriter, r *http.Request) {
	log.Println("get face id token")
	// 步骤1: 解析请求参数
	_ = r.ParseForm()
	var IdCardType = r.FormValue("IdCardType")
	var NeedVerifyIdCard = false
﻿
	// 步骤2: 初始化请求对象，并给必要的参数赋值
	request := faceid.NewApplySdkVerificationTokenRequest()
	request.IdCardType = &IdCardType
	request.NeedVerifyIdCard = &NeedVerifyIdCard
	// 步骤3: 通过FaceIdClient调用人脸核身服务
	response, err := FaceIdClient.ApplySdkVerificationToken(request)
﻿
	// 步骤4: 处理腾讯云API的响应，并构造返回对象
	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)
﻿
    // ... 其他业务处理代码
﻿
    //步骤5: 返回服务响应
	_, _ = w.Write(b)
}
﻿
// GetFaceIdResult 获取人脸核身核验结果
func GetSdkVerificationResult(w http.ResponseWriter, r *http.Request) {
    // 步骤1: ... 解析请求参数
	_ = r.ParseForm()
	SdkToken := r.FormValue("SdkToken")
    // 步骤2: 初始化请求对象，并给必要的参数赋值
	request := faceid.NewGetSdkVerificationResultRequest()
	request.SdkToken = &SdkToken
    // 步骤3: 通过FaceIdClient调用人脸核身服务
	response, err := FaceIdClient.GetSdkVerificationResult(request)
﻿
	  // Step 4: 处理腾讯云API的响应，并构造返回对象
	if nil != err {
		_, _ = w.Write([]byte("error"))
		return
	}
	result := response.Response.Result
	apiResp := struct {
		Result *string
	}{Result: result}
	b, _ := json.Marshal(apiResp)
﻿
    // ... 其他业务处理代码
﻿
    //步骤5: 返回服务响应
	_, _ = w.Write(b)
}
﻿
func main() {
	// 注册http接口路径
	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)
	}
﻿
说明：完整的代码示例详见faceid-server-demo。
接口测试
当你完成了集成之后，可以通过postman或者curl命令来测试当前的集成是否正确，通过访问http://ip:port/api/v1/get-token 接口查看是否正常返回 SdkToken , 访问http://ip:port/api/v1/get-result 接口查看 Result 字段的响应是否为0以判断服务端集成是否成功，具体的响应结果详见API接口部分的介绍。
Android 端集成
依赖环境
当前Android端SDK适用于API 19 (Android 6) 及以上版本。
SDK 接入步骤
1. 将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 、tencent-ai-sdk-aicamera-v1.0.x.x-release.aar(具体版本号以官网下载为准)添加到您工程的libs目录下。
2. 在您工程的build.gradle中进行如下配置：
// 设置ndk so架构过滤(以armeabi-v7a为例)
ndk {
    abiFilters 'armeabi-v7a'
}
﻿
dependencies {
    // Identity verification SDK版本库
    implementation files("libs/ekyc_android_1.0.x.x_release.aar")
    // 核身组件库
    implementation files("libs/huiyansdk_android_1.0.x.x_release.aar")
    // Ocr组件库
    implementation files("libs/OcrSDK-common-model-v1.x.x-release.aar")
    implementation files("libs/OcrSDK-private-v2.x.x-release.aar")
    // 通用能力组件库
    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")
    // 引入gson三方库
    implementation 'com.google.code.gson:gson:2.8.5'
}
3. 同时需要在AndroidManifest.xml文件中进行必要的权限声明
<!-- 摄像头权限 -->
<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" />
﻿
<!-- SDK需要的权限 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- SDK可选权限 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
对于需要兼容Android 6.0以上的用户，以上权限除了需要在AndroidManifest.xml文件中声明权以外，还需使用代码动态申请权限。
初始化接口
​ 在您APP初始化的时候调用，推荐在Application中调用，主要是进行一些 SDK 的初始化操作。
@Override
public void onCreate() {
	super.onCreate();
 	EkycHySdk.init(this);
}
启动身份认证（Identity verification）检测流程
当您需要启动身份认证检测流程的时候，只需要调用EkycHySdk.startEkycCheck()函数，同时传入此次身份认证检测需要的sdkToken、配置信息以及监听结果的回调即可。
// 设置启动的配置
EkycHyConfig ekycHyConfig = new EkycHyConfig();
// 设置license的名称
ekycHyConfig.setLicenseName("ekycLicense.license");
ekycHyConfig.setOcrType(OcrRegionType.HK);
// 自定义UI配置
OcrUiConfig config = new OcrUiConfig();
ekycHyConfig.setOcrUiConfig(config);
// 具体的启动核验逻辑
// sdkToken 是从服务器端获取的当次流程的唯一凭证
EkycHySdk.startEkycCheck(sdkToken, ekycHyConfig, new EkycHyCallBack() {
  @Override  
  public void onSuccess(EkycHyResult result) {
    Log.e(TAG, "result: " + result.toString());
    showToast("核身成功: " + result.toString());
  }
﻿
  @Override
  public void onFail(int errorCode, String errorMsg, String ekycToken) {
    Log.e(TAG, "code: " + errorCode + " msg: " + errorMsg + " token: " + ekycToken);
    showToast("核身失败: " + "code: " + errorCode + " msg: " + errorMsg + " token: " + ekycToken);
  }
});
 
sdkToken 为从服务器兑换的本次身份认证流程的唯一凭证。
注意： "ekycLicense.license"文件是需要联系商务或者客服人员进行license申请。将申请完成后的license文件放到assets文件下。
└── src
    └── main
        ├── assets
        │   └── ekycLicense.license
SDK 资源释放
​ 在您APP退出使用的时候，可以调用SDK资源释放接口。
@Override
protected void onDestroy() {
  EkycHySdk.release();
  super.onDestroy();
}
混淆规则配置
如果您的应用开启了混淆功能，为确保SDK的正常使用，请把以下部分添加到您的混淆文件中。
# 需要混淆的对象
-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.** {*;}
说明：Android完整的代码示例详见Android demo。
iOS 端集成
依赖环境
1. 开发环境 Xcode 12.0 及以上版本，推荐使用最新的版本。
2. SDK 适用于iOS11.0及以上版本。
SDK 接入步骤
手动接入方式
1. 导入相关库及文件
Link Binary With Libraries导入相关Framework
2. SDK依赖的库如下
﻿
├── 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
﻿
Link Binary With Libraries导入系统Framework
├── AVFoundation.framework
├── libc++.tbd
├── Accelerate.framework
└── CoreML.framework
Copy Bundle Resources导入资源文件
├── face-tracker-v003.bundle
├── huiyan_verification.bundle
├── HuiYanSDKUI.bundle
└── OcrSDK.bundle
Build Phases 设置
1. Other Linker Flags 新增 -ObjC。
2. 接入ViewController.m 设置后缀为.mm(swift 工程添加系统库libc++.tbd)。
权限设置
SDK需要手机网络及 摄像头使用权限，请添加对应的权限声明。在主项目info.plist 配置中添加下面key-value值。
<key>Privacy - Camera Usage Description</key>
	<string>需要访问您的相机权限</string>
启动身份认证检测
1. 初始化
在您APP初始化的时候调用，主要是进行一些 SDK 的初始化操作。
#import <HuiYanEKYCVerification/VerificationKit.h>
- (void)viewDidLoad {
    [[VerificationKit sharedInstance] initWithViewController:self];
}
2. 启动身份认证检测流程
当您需要启动身份认证eKYC检测流程的时候，只需要调用startVerifiWithConfig方法，配置ekycToken，和一些自定义配置。
VerificationConfig *config = [[VerificationConfig alloc] init];
config.licPath = [[NSBundle mainBundle] pathForResource:@"" ofType:nil];
config.languageType = HY_EKYC_EN;
config.verAutoTimeOut = 30000;//鉴伪超时时间设置
config.hyFaceTimeOut = 15000;//人脸单动作超时设置
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为从服务器兑换的本次身份认证流程的唯一凭证。
注意："eKYC_license.lic"文件是需要联系商务或者客服人员进行license申请。将申请完成后的license文件放到Copy Bundle Resources下。
SDK 资源释放
在您调用完 SDK 不在使用时，可以调用 SDK 资源释放接口：
- (void)dealloc {
    [VerificationKit clearInstance];
}
说明：iOS 完整的代码示例详见iOS demo。
本页内容是否解决了您的问题？
您也可以联系销售或提交工单以寻求帮助。
是
否
文档反馈
tencent cloud

接入准备

整体架构图

整体交互流程

接入流程

服务器端集成

集成准备

开始集成

接口测试

Android 端集成

依赖环境

SDK 接入步骤

初始化接口

启动身份认证（Identity verification）检测流程

SDK 资源释放

混淆规则配置

iOS 端集成

依赖环境

SDK 接入步骤

手动接入方式

Build Phases 设置

权限设置

启动身份认证检测

SDK 资源释放
