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);
        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的更多資訊，請參見程式碼範例。

用戶端接入流程

前提條件

ZOLOZ SDK支援Android和iOS用戶端接入，Android和iOS用戶端必須滿足以下要求：

用戶端作業系統版本必須為Android 4.3及以上版本，iOS 9及以上版本。
Android和iOS用戶端必須授予ZOLOZ SDK網路和網路攝影機許可權。
Android用戶端的架構必須為armeabi、arm64-v8a、armeabi-v7a，不支援x86架構。

Android用戶端接入

匯入SDK。
1. 配置Maven倉庫。
  在專案所在根目錄下的build.gradle檔案中添加Maven倉庫配置。
```
mavenCentral()
```
2. 添加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向商戶服務端發送包含元資訊的請求來初始化交易，然後商戶服務端調用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。
如果您在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 { *; }
-keep class face.security.device.api.** { *; }
-dontwarn face.security.device.api.**

說明：升級Android SDK版本後，需要同步更新混淆規則內容。

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的行動裝置 App環境。您可以使用程式碼範例以及ZOLOZ提供的商戶服務端代碼來測試整個整合流程。

Demo App已在Github上開源，您可以通過下方連結擷取。

如需擷取商戶服務端程式碼範例，請參見整合樣本。

Financial Intelligence Engine：使用原生App SDK模式接入

支援的產品

整合架構

互動流程

接入流程

服務端接入流程

前提條件

操作步驟

整合樣本

相關API

用戶端接入流程

前提條件

Android用戶端接入

iOS用戶端接入

程式碼範例