使用原生App SDK模式接入

App SDK模式即客户端/服务器模式。ZOLOZ提供了客户端SDK和服务端API,以便您将原生的移动App接入ZOLOZ服务。本文从支持的产品、集成架构、交互流程和接入流程等方面对App SDK接入模式进行介绍。

支持的产品

App SDK接入模式支持以下产品:

  • RealID
  • Face Capture
  • ID Recognition
  • Connect
  • NFC Reader

集成架构

App SDK模式的集成架构图如下所示。

image.png

App SDK模式集成包括以下两部分:

  • 客户端接入
    将ZOLOZ SDK集成到商户移动App中。ZOLOZ SDK为iOS和Android客户端分别提供了一组工具插件,用来采集用户数据,例如人脸图片、证件图片等。
    通过集成ZOLOZ SDK,您可以在以下方面为终端用户提供友好的交互体验。
    • 巧妙的UI设计,能够引导用户快速完成整个业务流程
    • 采用多种算法,保证高成功率和高安全性
    • 接入过程简单,直接将图片上传到ZOLOZ服务即可
  • 服务端接入
    在商户服务端为商户移动App开放端点,使商户移动App与商户服务端能够进行交互,然后通过ZOLOZ API初始化业务,并对校验结果进行双重检查。

交互流程

下图介绍了通过移动App启动ZOLOZ服务的完整交互流程。

使用原生App SDK模式接入
  1. 用户通过商户移动App发起业务流程,例如身份验证
  2. 商户移动App调用getMetaInfo接口获取ZOLOZ SDK和用户设备的元信息。
  3. ZOLOZ SDK将元信息返回给商户移动App
  4. 商户移动App初始化交易信息并将元信息传递给商户服务端
  5. 商户服务端获取到元信息后,调用initialize接口获取客户端配置信息,包括SDK连接和行为相关参数。
  6. ZOLOZ服务器根据元信息进行可用性检查,检查通过ZOLOZ服务器将客户端配置信息返回给商户服务端。
  7. 商户服务端将客户端配置信息返回给商户移动App。
  8. 商户移动App使用客户端配置信息启动ZOLOZ SDK。
  9. ZOLOZ SDK与用户交互,采集所需数据(例如人脸图片)并上传到ZOLOZ服务器进行验证。期间ZOLOZ SDK和ZOLOZ服务器之间可能会进行多次交互。
  10. ZOLOZ服务器检查上传的用户数据,并将交易状态返回给ZOLOZ SDK。
    如果所有检查均通过,则向ZOLOZ SDK返回一个表示成功的结果码;否则该过程可能会中断,用户和ZOLOZ SDK之间需要进一步交互。
  11. ZOLOZ SDK通知商户移动App交易已完成
  12. 商户移动App与商户服务端同步交易已完成,并开始对交易明细进行双重检查。
  13. 商户服务端调用checkResult接口与ZOLOZ服务器再次核对交易明细。
  14. ZOLOZ服务器将交易明细返回给商户服务端。
  15. 商户服务端过滤交易明细,并将非敏感信息返回给商户移动App。
    说明:为了保证信息安全,采集到的人脸图片等敏感信息仅返回给商户服务端,不会返回给商户移动App。
  16. 商户移动App通知用户流程完成。

接入流程

服务端接入流程

前提条件

请确保已接入ZOLOZ网关,使ZOLOZ网关能够被正常调用,以便正确处理API请求和响应。接入ZOLOZ网关的操作,请参见接入ZOLOZ网关

操作步骤

为了使商户移动App与商户服务端能够交互,以及商户服务端能够调用ZOLOZ API,您需要在商户服务端为商户移动App开放端点。本文以RealID API为例,介绍如何通过注解为商户移动App开放端点。

本示例仅展示商户服务端与ZOLOZ服务器交互所需的处理逻辑,在实际接入过程中,您需要根据具体业务需求来实现业务逻辑。例如:

  • 调用initialize API时,可以保存ZOLOZ服务器返回的交易ID,便于后续查询使用。
  • 调用checkResult API时,可以保存交易明细并对其进行脱敏,将脱敏后的信息返回给客户端。
copy
// 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 8及以上版本。
  • Android和iOS客户端必须授予ZOLOZ SDK网络和摄像头权限
  • Android客户端的架构必须为armeabi、arm64-v8a、armeabi-v7a,不支持x86架构。

Android客户端接入

  1. 导入SDK。
    1. 配置Maven仓库。
      在项目所在根目录下的
      build.gradle文件中添加Maven仓库配置。
copy
mavenCentral()
    1. 添加SDK依赖。
      将SDK作为依赖项添加到模块(应用级)的
      gradle文件中,文件路径通常为app/build.gradle
copy
implementation 'com.zoloz.android.build:zolozkit:1.3.0.230907171559' //1.3.0.230907171559及以下版本不显示证件提示动画,1.3.0.230907171559以上版本显示证件提示动画,并且可以通过Portal关闭;最新版本请参见https://github.com/zoloz-pte-ltd/zoloz-demo-android/blob/master/docs/changelog.md
implementation "com.squareup.okio:okio:1.7.0@jar"
implementation "com.alibaba:fastjson:1.1.68.android"

说明:如果同时在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中添加如下配置来解决该问题。

copy
packagingOptions {
    pickFirst  'lib/arm64-v8a/libc++_shared.so'
    pickFirst  'lib/armeabi-v7a/libc++_shared.so'
}
  1. 获取元信息。
    使用ZLZFacae类及其方法getMetaInfo获取ZOLOZ SDK和用户设备的元信息,元信息用于后续初始化交易。有关ZLZFacadegetMetaInfo的更多信息,请参见ZLZFacade
copy
String metaInfo = ZLZFacade.getMetaInfo(applicationContext);
  1. 初始化交易。
    商户移动App向商户服务端发送包含元信息的请求来初始化交易,然后商户服务端调用initialize API获取客户端配置并将其返回给商户移动App。
  2. 启动交易流程。
    1. 使用客户端配置构建ZLZRequest对象。
copy
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;
    1. 启动交易流程。
      使用构建的ZLZRequest对象调用start方法来启动交易流程,并重写回调函数来处理交易结果。
copy
  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

  1. 配置ProGuard(可选)。
    如果您在Android应用中启用了ProGuard,为确保您的应用可以成功地调用ZOLOZ SDK,请在项目的混淆文件中添加以下配置。
copy
-keep class okio.**{
    <fields>;
    <methods>;
}
-dontwarn com.zoloz.**
-keep class com.zoloz.zhub.**{
  <fields>;
   <methods>;
}
-keep class com.alipay.zoloz.**{
   <fields>;
   <methods>;
}
-keep class com.zoloz.zcore.facade.common.** {
   <fields>;
   <methods>;
}
-keep class com.alipay.android.phone.zoloz.**{
   <fields>;
   <methods>;
}
-keep class com.alipay.biometrics.**{
   <fields>;
   <methods>;
}
-keep class com.alipay.bis.**{
   <fields>;
   <methods>;
}
-keep class com.alipay.mobile.security.**{
   <fields>;
   <methods>;
}
-keep class com.ap.zoloz.**{
   <fields>;
   <methods>;
}
-keep class com.ap.zhubid.endpoint.**{
   <fields>;
   <methods>;
}
-keep class com.zoloz.android.phone.zdoc.**{
   <fields>;
   <methods>;
}
-keep class zoloz.ap.com.toolkit.**{
   <fields>;
   <methods>;
}
-keep class com.zoloz.builder.** {
   <fields>;
   <methods>;
}
-keep class com.ant.phone.xmedia.**{*;}
-keep class com.alipay.alipaysecuritysdk.** {*;}

iOS客户端接入

  1. 配置SDK依赖。
    1. 在Podfile中配置私有规范。
copy
source "https://github.com/zoloz-pte-ltd/zoloz-demo-ios"
    1. 在Podfile中添加SDK依赖。
copy
#zolozkit changelog https://github.com/zoloz-pte-ltd/zoloz-demo-ios/blob/master/docs/changelog.md

pod 'zolozkit' #1.3.2.231024185824及以下版本不显示证件提示动画,1.3.2.231024185824以上版本显示证件提示动画,并且可以通过Portal关闭。
  1. 获取SDK。
    执行以下命令获取SDK。
copy
pod install
  1. 配置链接器标志。
    Build Settings > Other Linker Flags中添加-ObjC$(inherited)常量。
    image
  2. 引用头文件。
    Objective-C:
copy
#import <hummer/ZLZFacade.h>
#import <hummer/ZLZRequest.h>
#import <hummer/ZLZResponse.h>

Swift:

copy
import hummer
  1. 获取元信息。
    使用ZLZFacade类及其方法getMetaInfo获取ZOLOZ SDK和用户设备的元信息,元信息用于后续初始化交易。有关ZLZFacadegetMetaInfo的更多信息,请参见ZLZFacade
    Objective-C:
copy
NSString *metainfo = [ZLZFacade getMetaInfo];

Swift:

copy
let metainfo = ZLZFacade.getMetaInfo()
  1. 初始化交易。
    商户移动App向商户服务端发送包含元信息的请求来初始化交易,然后商户服务端调用initialize API获取客户端配置并将其返回给商户移动App。
  2. 启动交易流程。
    1. 使用客户端配置构建ZLZRequest对象。
      Objective-C:
copy
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:

copy
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:

copy
 [[ZLZFacade sharedInstance] startWithRequest:request completeCallback:^(ZLZResponse *response) {
} interruptCallback:^(ZLZResponse *interrupt){
}];

Swift:

copy
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上开源,您可以通过下方链接获取。

如需获取商户服务端代码示例,请参见集成示例