使用原生App SDK模式接入
App SDK模式即客户端/服务器模式。ZOLOZ提供了客户端SDK和服务端API,以便您将原生的移动App接入ZOLOZ服务。本文从支持的产品、集成架构、交互流程和接入流程等方面对App SDK接入模式进行介绍。
支持的产品
App SDK接入模式支持以下产品:
- RealID
- Face Capture
- ID Recognition
- Connect
- NFC Reader
集成架构
App SDK模式的集成架构图如下所示。
App SDK模式集成包括以下两部分:
- 客户端接入
将ZOLOZ SDK集成到商户移动App中。ZOLOZ SDK为iOS和Android客户端分别提供了一组工具插件,用来采集用户数据,例如人脸图片、证件图片等。
通过集成ZOLOZ SDK,您可以在以下方面为终端用户提供友好的交互体验。
- 巧妙的UI设计,能够引导用户快速完成整个业务流程。
- 采用多种算法,保证高成功率和高安全性。
- 接入过程简单,直接将图片上传到ZOLOZ服务即可。
- 服务端接入
在商户服务端为商户移动App开放端点,使商户移动App与商户服务端能够进行交互,然后通过ZOLOZ API初始化业务,并对校验结果进行双重检查。
交互流程
下图介绍了通过移动App启动ZOLOZ服务的完整交互流程。
- 用户通过商户移动App发起业务流程,例如身份验证。
- 商户移动App调用
getMetaInfo
接口获取ZOLOZ SDK和用户设备的元信息。 - ZOLOZ SDK将元信息返回给商户移动App。
- 商户移动App初始化交易信息并将元信息传递给商户服务端。
- 商户服务端获取到元信息后,调用
initialize
接口获取客户端配置信息,包括SDK连接和行为相关参数。 - ZOLOZ服务器根据元信息进行可用性检查,检查通过ZOLOZ服务器将客户端配置信息返回给商户服务端。
- 商户服务端将客户端配置信息返回给商户移动App。
- 商户移动App使用客户端配置信息启动ZOLOZ SDK。
- ZOLOZ SDK与用户交互,采集所需数据(例如人脸图片)并上传到ZOLOZ服务器进行验证。期间ZOLOZ SDK和ZOLOZ服务器之间可能会进行多次交互。
- ZOLOZ服务器检查上传的用户数据,并将交易状态返回给ZOLOZ SDK。
如果所有检查均通过,则向ZOLOZ SDK返回一个表示成功的结果码;否则该过程可能会中断,用户和ZOLOZ SDK之间需要进一步交互。 - ZOLOZ SDK通知商户移动App交易已完成。
- 商户移动App与商户服务端同步交易已完成,并开始对交易明细进行双重检查。
- 商户服务端调用
checkResult
接口与ZOLOZ服务器再次核对交易明细。 - ZOLOZ服务器将交易明细返回给商户服务端。
- 商户服务端过滤交易明细,并将非敏感信息返回给商户移动App。
说明:为了保证信息安全,采集到的人脸图片等敏感信息仅返回给商户服务端,不会返回给商户移动App。 - 商户移动App通知用户流程完成。
接入流程
服务端接入流程
前提条件
请确保已接入ZOLOZ网关,使ZOLOZ网关能够被正常调用,以便正确处理API请求和响应。接入ZOLOZ网关的操作,请参见接入ZOLOZ网关。
操作步骤
为了使商户移动App与商户服务端能够交互,以及商户服务端能够调用ZOLOZ API,您需要在商户服务端为商户移动App开放端点。本文以RealID API为例,介绍如何通过注解为商户移动App开放端点。
本示例仅展示商户服务端与ZOLOZ服务器交互所需的处理逻辑,在实际接入过程中,您需要根据具体业务需求来实现业务逻辑。例如:
- 调用
initialize
API时,可以保存ZOLOZ服务器返回的交易ID,便于后续查询使用。 - 调用
checkResult
API时,可以保存交易明细并对其进行脱敏,将脱敏后的信息返回给客户端。
// Use annotation to expose endpoints for the client application to consume
@RestController
//Define the common base path for the API endpoints
@RequestMapping(value = {"/webapi"})
public class NativeClientModeController {
// Auto wire the openApiClient object that is provided by ZOLOZ for calling ZOLOZ // APIs
@Autowired
private OpenApiClient openApiClient;
// Define the first service to map with the API URL path
@RequestMapping(value = {"/realid/initialize"}, method = RequestMethod.POST)
public JSONObject realIdInit(@RequestBody JSONObject request) {
// Step 1: instantiate the request object and provide necessary parameters
JSONObject apiReq = new JSONObject();
apiReq.put("flowType", "REALIDLITE_KYC");
// apiReq.put("...","..."); Add more request parameters as required. For more // information about the request parameters of the Real ID initialize API, see // the correspoding API specification in the API reference chapter.
// Step 2: call the ZOLOZ API through openApiClient
String apiRespStr = openApiClient.callOpenApi(
"v1.zoloz.realid.initialize",
JSON.toJSONString(apiReq)
);
// Step 3: process the ZOLOZ API response and construct the return object
JSONObject apiResp = JSON.parseObject(apiRespStr);
JSONObject response = new JSONObject(apiResp);
response.put("rsaPubKey", openApiClient.getOpenApiPublicKey());
// ... more codes are omitted
// Step 4: return the service response
return response;
}
// Define more services as required, for example, for Real ID, you need to define // a service to check the transaction results
@RequestMapping(value = "/realid/checkresult", method = RequestMethod.POST)
public JSONObject realIdCheck(@RequestBody JSONObject request) {
// Implement the detailed logic to create a request and handle the response
}
}
集成示例
针对不同的产品,ZOLOZ提供了一个简化版商户服务端的代码示例。代码示例中包含了与ZOLOZ SaaS环境交互所需的最基本的代码资源,且代码示例已开源,您可以在Github中获取。
注意:商户服务端代码需要与ZOLOZ提供的Demo配合使用。有关Demo的更多信息,请参见代码示例。
相关API
单击下方链接,可查看ZOLOZ相关产品的服务端API。
客户端接入流程
前提条件
ZOLOZ SDK支持Android和iOS客户端接入,Android和iOS客户端必须满足以下要求:
- 客户端操作系统版本必须为Android 4.3及以上版本,iOS 9及以上版本。
- Android和iOS客户端必须授予ZOLOZ SDK网络和摄像头权限。
- Android客户端的架构必须为armeabi、arm64-v8a、armeabi-v7a,不支持x86架构。
Android客户端接入
- 导入SDK。
- 配置Maven仓库。
在项目所在根目录下的build.gradle
文件中添加Maven仓库配置。
mavenCentral()
- 添加SDK依赖。
将SDK作为依赖项添加到模块(应用级)的gradle
文件中,文件路径通常为app/build.gradle
。
implementation 'com.zoloz.android.build:zolozkit:latest-version' //建议您使用最新版SDK,可提升产品体验和安全性。版本发布说明,请参见https://docs.zoloz.com/zoloz/saas/releasenotes/。
implementation "com.squareup.okio:okio:1.7.0@jar"
implementation "com.alibaba:fastjson:1.1.68.android"
implementation 'com.zoloz.android.build:znfc:latest-version' //可选,支持NFC Reader功能。
说明:
- 代码
implementation 'com.zoloz.android.build:znfc:latest-version'
对应NFC功能,如需开通该功能,请联系ZOLOZ技术支持;如果不需要使用该功能,则无需添加对应的代码。 - 如果同时在
build.gradle
文件中集成了其他SDK,可能会遇到“More than one file was found with OS independent path 'lib/arm64-v8a/libc++_shared.so'.”问题,原因是ZOLOZ SDK和其他SDK都添加了libc++_shared.so库,您可以在build.gradle
中添加如下配置来解决该问题。
packagingOptions {
pickFirst 'lib/arm64-v8a/libc++_shared.so'
pickFirst 'lib/armeabi-v7a/libc++_shared.so'
}
- 获取元信息。
使用ZLZFacae
类及其方法getMetaInfo
获取ZOLOZ SDK和用户设备的元信息,元信息用于后续初始化交易。有关ZLZFacade
和getMetaInfo
的更多信息,请参见ZLZFacade。
String metaInfo = ZLZFacade.getMetaInfo(applicationContext);
- 初始化交易。
商户移动App向商户服务端发送包含元信息的请求来初始化交易,然后商户服务端调用initialize
API获取客户端配置并将其返回给商户移动App。 - 启动交易流程。
- 使用客户端配置构建
ZLZRequest
对象。
ZLZRequest request = new ZLZRequest();
request.bizConfig = new HashMap<>();
request.bizConfig.put(ZLZConstants.CONTEXT, this);
request.bizConfig.put(ZLZConstants.LOCALE, locale);
request.zlzConfig = clientCfg;
return request;
- 启动交易流程。
使用构建的ZLZRequest
对象调用start
方法来启动交易流程,并重写回调函数来处理交易结果。
ZLZFacade.getInstance().start(request, new IZLZCallback() {
@Override
public void onCompleted(ZLZResponse response) {
}
@Override
public void onInterrupted(ZLZResponse response) {
}
});
交易结果中包含标识交易流状态的结果码,具体如下:
- 如果终端用户已完成整个交互流程,则调用
onComplete
方法,交易状态需要与商户服务端同步,并且需要启动双重检查。然后商户服务端调用checkResult
API获取交易详情并将其返回给商户移动App。 - 如果终端用户未完成整个交互流程,则调用
onInterrupted
方法,并根据具体的业务需求来实现相关的业务逻辑。
有关ZLZRequest、ZLZResponse、ZLZConstants类的更多信息,请参见Android SDK。
- 配置ProGuard(可选)。
如果您在Android应用中启用了ProGuard,为确保您的应用可以成功地调用ZOLOZ SDK,请在项目的混淆文件中添加以下配置。
-dontwarn com.zoloz.**
-keep class okio.** { *; }
-keep class com.alibaba.fastjson.** { *; }
-keep class com.alibaba.fastjson2.** { *; }
-keep class com.zoloz.zhub.** { *; }
-keep class com.alipay.zoloz.** { *; }
-keep class com.zoloz.zcore.facade.common.** { *; }
-keep class com.alipay.android.phone.zoloz.** { *; }
-keep class com.alipay.biometrics.** { *; }
-keep class com.alipay.bis.** { *; }
-keep class com.alipay.mobile.security.** { *; }
-keep class com.ap.zoloz.** { *; }
-keep class com.ap.zhubid.endpoint.** { *; }
-keep class com.zoloz.android.phone.zdoc.** { *; }
-keep class zoloz.ap.com.toolkit.** { *; }
-keep class com.zoloz.builder.** { *; }
-keep class com.ant.phone.xmedia.** { *; }
-keep class com.alipay.alipaysecuritysdk.** { *; }
-keep class com.alipay.blueshield.** { *; }
-keep class com.alipay.deviceid.** { *; }
-keep class com.alipay.edge.** { *; }
-keep class com.alipay.softtee.NativeHelper { *; }
-keep class com.alipay.apmobilesecuritysdk.tool.si.SIUtils { *; }
iOS客户端接入
- 配置SDK依赖。
- 在Podfile中配置私有规范。
source "https://github.com/zoloz-pte-ltd/zoloz-demo-ios"
- 在Podfile中添加SDK依赖。
#zolozkit变更日志:https://docs.zoloz.com/zoloz/saas/releasenotes/
# #建议您使用最新版SDK,其包含了新功能并在安全方面进行了改进。如果您需要有关特定版本的更多信息,请查看变更日志。
pod 'zolozkit' #核心模块
pod 'zolozkit/ZolozNfcReader' #NFC Reader模块
说明:代码pod 'zolozkit/ZolozNfcReader'
对应NFC功能,如需开通该功能,请联系ZOLOZ技术支持;如果不需要使用该功能,则无需添加对应的代码。
- 获取SDK。
执行以下命令获取SDK。
pod install
- 配置链接器标志。
在Build Settings > Other Linker Flags中添加-ObjC
和$(inherited)
常量。 - 引用头文件。
Objective-C:
#import <hummer/ZLZFacade.h>
#import <hummer/ZLZRequest.h>
#import <hummer/ZLZResponse.h>
Swift:
import hummer
- 获取元信息。
使用ZLZFacade
类及其方法getMetaInfo
获取ZOLOZ SDK和用户设备的元信息,元信息用于后续初始化交易。有关ZLZFacade
和getMetaInfo
的更多信息,请参见ZLZFacade。
Objective-C:
NSString *metainfo = [ZLZFacade getMetaInfo];
Swift:
let metainfo = ZLZFacade.getMetaInfo()
- 初始化交易。
商户移动App向商户服务端发送包含元信息的请求来初始化交易,然后商户服务端调用initialize
API获取客户端配置并将其返回给商户移动App。 - 启动交易流程。
- 使用客户端配置构建
ZLZRequest
对象。
Objective-C:
NSString *clientConfig = clientCfg;
NSMutableDictionary *bizConfig = [NSMutableDictionary dictionary];
// the `self` viewcontroller need nested in UINavigationController
[bizConfig setObject:self forKey:kZLZCurrentViewControllerKey];
//.pass the locale to bizConfig
[bizConfig setObject:locale forKey:kZLZLocaleKey]
ZLZRequest *request = [[ZLZRequest alloc] initWithzlzConfig:clientConfig bizConfig:bizConfig];
Swift:
let clientConfig = clientCfg
let bizConfig = NSMutableDictionary()
// the `self` viewcontroller need nested in UINavigationController
bizConfig[kZLZCurrentViewControllerKey] = self
//.pass the locale to bizConfig
bizConfig[kZLZLocaleKey] = locale
let request = ZLZRequest.init(zlzConfig: clientConfig ?? "", bizConfig: bizConfig as! [AnyHashable : Any])
b. 启动交易流程。
使用构建的ZLZRequest
对象调用startWithRequest
方法来启动交易流程,并重写回调函数来处理交易结果。
Objective-C:
[[ZLZFacade sharedInstance] startWithRequest:request completeCallback:^(ZLZResponse *response) {
} interruptCallback:^(ZLZResponse *interrupt){
}];
Swift:
ZLZFacade.sharedInstance().start(with: request) { response in
} interruptCallback: { response in
}
交易结果中包含标识交易流状态的结果码,具体如下:
- 如果终端用户已完成整个交互流程,则调用
completeCallback
方法,交易状态需要与商户服务端同步,并且需要启动双重检查。然后商户服务端调用checkResult
API获取交易详情并将其返回给商户移动App。 - 如果终端用户未完成整个交互流程,则调用
interruptCallback
方法,并根据具体的业务需求来实现相关的业务逻辑。
有关ZLZRequest和ZLZResponse类的更多信息,请参见iOS SDK。
代码示例
ZOLOZ提供了适用于iOS和Android客户端的代码示例,代码示例中模拟了集成ZOLOZ SDK的移动应用环境。您可以使用代码示例以及ZOLOZ提供的商户服务端代码来测试整个集成流程。
Demo App已在Github上开源,您可以通过下方链接获取。
如需获取商户服务端代码示例,请参见集成示例。