原生 App SDK 模式

2022-05-09 03:03

概述

ZOLOZ 提供了 SDK 和 API，以便您将原生的移动 App 接入 ZOLOZ。本文从集成架构、支持的产品、交互流程和通用接入流程等方面对 App SDK 接入模式进行说明。

集成架构

下面是App SDK集成架构图。

App SDK集成包括以下两部分：

客户端接入：将商家 App 接入到 ZOLOZ SDK。ZOLOZ SDK 为 iOS 和 Android 客户端分别提供了一组屏幕和工具插件，用来捕获用户数据，例如面部图像、身份证件图像等。通过接入 ZOLOZ SDK，可以为终端用户创造友好的交互体验：

UI设计巧妙，能够快速引导用户完成整个业务流程。
采用多种算法，保证高成功率和高安全性。
接入过程简单，直接将图像上传到ZOLOZ服务即可。

服务端接入：在商家服务器中为商家 App 开放端点，以便商家 App 与商家服务器进行交互，然后通过ZOLOZ API 进行业务初始化，并对校验结果进行双重检查。

支持的产品

App SDK集成可应用于以下内容：

真实ID
连接
身份识别
面部捕捉

交互流程

下面的序列图描述了通过移动 App 启动 ZOLOZ 服务时的整个交互过程。

用户通过商家 App 发起业务流程（如身份验证）。
商家 App 调用 getMetaInfo 接口获取 ZOLOZ SDK 和用户设备的元信息。
ZOLOZ SDK 将元信息返回给商家 App。
商家 App 初始化交易信息并将元信息传递给商家服务器。
商家服务器获取元信息后，调用 initialize API 获取客户端配置信息，包括 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 API 与 ZOLOZ 服务器再次核对交易明细。
ZOLOZ 服务器将交易明细返回给商家服务器。

注：为保证信息安全，采集到的人脸图像等敏感信息仅返回给商家服务器。

商家服务器对 ZOLOZ 服务器返回的交易明细进行过滤，并将非敏感信息返回给商家App。
商家 App 通知用户流程完成。

一般接入流程

服务端接入

前置条件

在服务端接入 ZOLOZ 前，请确认已接入 ZOLOZ 网关，以确保 ZOLOZ 网关能够被正常调用，使其正确处理 API 请求和响应。接入 ZOLOZ 网关的操作请参见接入 ZOLOZ 网关。

操作步骤

为了使商家 App 与商家服务器能够交互，以及商家服务器调用 ZOLOZ API，您必须在商家服务器中为商家 App 开放端点。下面以 Real ID 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 的更多信息，请参见：

客户端接入

SDK 使用须知

ZOLOZ SDK 支持 Android 和 iOS 客户端接入，但是 Android 和 iOS 系统必须满足以下要求：

Android 系统必须为 Android 4.3 或更高版本。
iOS 系统必须为 iOS 8 或更高版本。
Android 和 iOS 客户端必须授予 ZOLOZ SDK 网络和摄像头的权限。

注意：不支持 x86 架构。

Android 接入

导入 SDK

配置 maven 仓库
在工程根目录下的 build.gradle 文件中添加 maven 存储库配置。

copy
mavenCentral()

添加 SDK 依赖
将 SDK 作为依赖项添加到模块（应用级）的 gradle（通常是app/build.gradle）文件中。

copy
implementation 'com.zoloz.android.build:zolozkit:1.0.3'
implementation "com.squareup.okio:okio:1.7.0@jar"
implementation "com.alibaba:fastjson:1.1.68.android"

获取元信息
使用 ZLZFacae 类及其方法 getMetaInfo 获取有关 ZOLOZ SDK 和用户设备的元信息。元信息用于后续初始化交易信息。有关 ZLZFacade 和 getMetaInfo 的更多信息，请参见 ZLZFacade。

copy
String metaInfo = ZLZFacade.getMetaInfo(applicationContext);

初始化交易
通过向商家服务器发送包含元信息的请求进行初始化交易，然后商家服务器调用initialize API来获取客户端配置并将其返回给商家 App。
启动交易流程

使用从商家服务器返回的客户端配置，以及从 ZOLOZ 门户获取的 ZOLOZ 公钥构建 ZLZRequest 对象。

copy
ZLZRequest request = new ZLZRequest();
request.bizConfig = new HashMap<>();
request.bizConfig.put(ZLZConstants.CONTEXT, this);
request.bizConfig.put(ZLZConstants.PUBLIC_KEY, publickey);
request.bizConfig.put(ZLZConstants.LOCALE, locale);
request.zlzConfig = clientCfg;
return request;

启动交易流。使用上述步骤中构建的 ZLZRequest 对象来调用 start 方法，此外还需要重写回调函数来处理交易结果。
交易结果中包含标识交易流状态的结果码。如果终端用户已完成整个交互流程，则调用 onCompleted 方法，其中交易状态需要与商家服务器同步，并且需要启动双重检查。然后商家服务器调用 checkResult API 来获取交易详情并将其返回给商家 App。
如果终端用户还没有完成整个交互流程，则调用 onInterrupted 方法，同时还要根据您具体的业务需求实现相关的业务逻辑。
有关 ZLZRequest、ZLZResponse、ZLZConstants 类的更多信息，请参见Android SDK。

copy
  ZLZFacade.getInstance().start(request, new IZLZCallback() {
    @Override
    public void onCompleted(ZLZResponse response) {
    }
    @Override
    public void onInterrupted(ZLZResponse response) {
    }
});

处理 ProGuard（可选）
如果您在 Android 应用中启用了 ProGuard，为确保您的应用可以成功调用 ZOLOZ SDK，请在项目的混淆文件中添加以下配置：

copy
-dontwarn com.zoloz.**
-keep class com.zoloz.zhub.**{
  <fields>;
   <methods>;
}
-keep class com.alipay.zoloz.**{
   <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>;
}

iOS 接入

配置 SDK 依赖

在 Podfile 中配置私有规范：

copy
source https://github.com/zoloz-pte-ltd/zoloz-demo-ios

在 Podfile 中添加 SDK 依赖：

copy
pod 'zolozkit'

获取 SDK
执行以下命令获取 SDK。

copy
pod install

配置链接器标志
在 Build Settings > Other Linker Flags 中添加 -ObjC 和 $(inherited) 常量。
获取元信息
使用 ZLZFacae 类及其方法 getMetaInfo 获取有关 ZOLOZ SDK 和用户设备的元信息。元信息用于后续初始化交易信息。有关 ZLZFacade 和 getMetaInfo 的更多信息，请参见 ZLZFacade。

copy
NSString *metainfo = [ZLZFacade getMetaInfo];

初始化交易
通过向商家服务器发送包含元信息的请求进行初始化交易，然后商家服务器调用initialize API来获取客户端配置并将其返回给商家 App。
启动交易流

使用商家服务器返回的客户端配置，以及从 ZOLOZ 门户获取的 ZOLOZ 公钥构建 ZLZRequest 对象。

copy
NSString *clientConfig = clinetCfg;
//.pass the current ViewController to bizConfig
NSMutableDictionary *bizConfig = [NSMutableDictionary dictionary];
[bizConfig setObject:self forKey:kZLZCurrentViewControllerKey];
//.pass the public key to bizConfig
[bizConfig setObject:publicKey forKey:kZLZPubkey];
//.pass the locale to bizConfig
[bizConfig setObject:locale forKey:kZLZLocaleKey]
ZLZRequest *request = [[ZLZRequest alloc] initWithzlzConfig:clientConfig bizConfig:bizConfig];

启动交易流需要使用 ZLZRequest 对象来调用 start 方法，此外还需要重写回调函数来处理交易结果。

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

交易结果中包含标识交易流状态的结果码。如果终端用户已完成整个交互流程，则调用 completeCallback，其中交易状态需要与商家服务器同步，并且需要启动双重检查。然后商家服务器需要调用 checkResult API 来获取交易详情并将其返回给商家 App。

如果终端用户还没有完成整个交互流程，则调用 interruptCallback，并且还需要根据您具体的业务需求来实现相关的业务流程。

有关 ZLZRequest 和 ZLZResponse 类的更多信息，请参见 iOS SDK。

代码示例

ZOLOZ 提供了适用于 iOS 和 Android 的代码示例，代码示例中模拟了集成 ZOLOZ SDK 的移动应用环境。您可以使用代码示例以及 ZOLOZ 提供的商家服务器代码来测试整个集成流程。

Demo App 在Github上开源：

更多商家服务器代码示例，请参见集成示例。