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 SDK模式接入

用户通过商户移动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服务器交互所需的处理逻辑，在实际接入过程中，您需要根据具体业务需求来实现业务逻辑。例如：

调用initializeAPI时，可以保存ZOLOZ服务器返回的交易ID，便于后续查询使用。
调用checkResultAPI时，可以保存交易明细并对其进行脱敏，将脱敏后的信息返回给客户端。

// 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);
        // ... 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的更多信息，请参见代码示例。

客户端接入流程

前提条件

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.squareup.okio:okio:1.7.0@jar"
implementation "com.alibaba:fastjson:1.1.68.android"
implementation "com.zoloz.android.build:zolozcore:latest-version" //版本发布说明，请参见https://docs.zoloz.com/zoloz/saas/releasenotes/。
implementation "com.zoloz.android.build:doc:latest-version"
implementation "com.zoloz.android.build:face:latest-version"
implementation "com.zoloz.android.build:xnn:latest-version"
implementation "com.zoloz.android.build:faceguard:latest-version"
implementation "com.zoloz.android.build:apsecurity:latest-version"
//可选能力
implementation 'com.zoloz.android.build:znfc:latest-version' //可选，支持NFC Reader功能。

说明：

强烈建议您升级至最新版SDK，可提供最佳的产品体验和更高的安全性。版本发布说明，详见发布说明。
代码implementation 'com.zoloz.android.build:znfc:latest-version'对应NFC功能，如需开通该功能，请联系ZOLOZ技术支持；如果不需要使用该功能，则无需添加对应的代码。

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

String metaInfo = ZLZFacade.getMetaInfo(applicationContext);

初始化交易。
商户移动App向商户服务端发送包含元信息的请求来初始化交易，然后商户服务端调用initializeAPI获取客户端配置并将其返回给商户移动App。
启动交易流程。
1. 使用客户端配置构建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;
```
2. 启动交易流程。
  使用构建的ZLZRequest对象调用start方法来启动交易流程，并重写回调函数来处理交易结果。
```
  ZLZFacade.getInstance().start(request, new IZLZCallback() {
    @Override
    public void onCompleted(ZLZResponse response) {
    }
    @Override
    public void onInterrupted(ZLZResponse response) {
    }
});
```
交易结果中包含标识交易流状态的结果码，具体如下：
- 如果终端用户已完成整个交互流程，则调用onComplete方法，交易状态需要与商户服务端同步，并且需要启动双重检查。然后商户服务端调用checkResultAPI获取交易详情并将其返回给商户移动App。
- 如果终端用户未完成整个交互流程，则调用onInterrupted方法，并根据具体的业务需求来实现相关的业务逻辑。
有关ZLZRequest、ZLZResponse、ZLZConstants类的更多信息，请参见Android SDK。

配置ProGuard（重要）。
为确保您的应用能够成功调用ZOLOZ SDK，请严格按照以下要求配置混淆规则。如果混淆规则配置不正确，可能会导致业务完全不可用。
- 必须在app层的proguard-rules.pro文件中添加混淆规则，如果在模块层添加了Android SDK，同时需在该模块层的proguard-rules.pro文件中添加相同的混淆规则。
- 在发布应用之前，必须在Release包中完成业务功能的全面测试，以确保混淆规则生效。
- 升级Android 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.** { *; }
-keep class com.alipay.apmobilesecuritysdk.** { *; }
-keep class face.security.device.api.** { *; }
-keep class com.zoloz.zeta.** { *; }
-dontwarn face.security.device.api.**

iOS客户端接入

获取用户的隐私权限。

ZOLOZ需要获取用户的以下权限：

权限	描述
NSCameraUsageDescription	ZOLOZ需要使用相机权限来采集人脸和证件图片。
NSLocalNetworkUsageDescription	获取局域网内设备的连通性，用于检测钓鱼、群控等风险。
NSUserTrackingUsageDescription	用于获取IDFA信息，增强设备ID的稳定性。

配置SDK依赖。

a. 在Podfile中配置私有规范。

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

b. 在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向商户服务端发送包含元信息的请求来初始化交易，然后商户服务端调用initializeAPI获取客户端配置并将其返回给商户移动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方法，交易状态需要与商户服务端同步，并且需要启动双重检查。然后商户服务端调用checkResultAPI获取交易详情并将其返回给商户移动App。
如果终端用户未完成整个交互流程，则调用interruptCallback方法，并根据具体的业务需求来实现相关的业务逻辑。

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

代码示例

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

Demo App已在Github上开源，您可以通过下方链接获取。

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

金融智能引擎：使用原生App SDK模式接入

支持的产品

集成架构

交互流程

接入流程

服务端接入流程

前提条件

操作步骤

集成示例

相关API

客户端接入流程

前提条件

Android客户端接入

iOS客户端接入

代码示例