Flutter外掛程式模式即用戶端/伺服器模式。ZOLOZ提供了Flutter外掛程式和服務端API，以便您將跨平台Flutter App接入ZOLOZ服務。本文從支援的產品、整合架構、互動流程和接入流程等方面對ZOLOZ Flutter外掛程式接入模式進行介紹。

ZOLOZ Flutter外掛程式庫，請參見zolozkit_for_flutter。

支援的產品

Flutter外掛程式接入模式支援以下產品：

RealID
Face Capture
ID Recognition
Connect

支援的硬體平台

ZOLOZ Flutter外掛程式以移動App為目標提供接入服務，目前不支援案頭和Web平台，支援的硬體平台如下：

Android
iOS

整合架構

ZOLOZ Flutter外掛程式模式的整合架構圖如下所示。

使用Flutter外掛程式1717467601844-d788228c-afe0-4f9c-b7fd-158f3e04e222.png

ZOLOZ Flutter外掛程式模式整合套件括以下兩部分：

用戶端接入
將ZOLOZ Flutter外掛程式整合到商戶Flutter App中。ZOLOZ Flutter外掛程式在iOS和Android硬體平台分別調用ZOLOZ原生iOS SDK、Android SDK來採集使用者資料，例如人臉圖片、證件圖片等。
通過整合ZOLOZ Flutter外掛程式，您可以在以下方面為終端使用者提供友好的互動體驗。
- 巧妙的UI設計，能夠引導使用者快速完成整個商務程序。
- 採用多種演算法，保證高成功率和高安全性。
- 接入過程簡單，直接將圖片上傳到ZOLOZ服務即可。

服務端接入
在商戶服務端為商戶Flutter App開放端點，使商戶Flutter App與商戶服務端能夠進行互動，然後通過ZOLOZ API初始化業務，並對校正結果進行雙重檢查。

互動流程

下圖介紹了通過Flutter App啟動ZOLOZ服務的完整互動流程。

互動流程-1df0cc60a2bcb94c145d5e7a0b7ee162.svg

使用者通過商戶Flutter App發起商務程序，例如身分識別驗證。
商戶Flutter App調用ZolozkitForFlutter.metaInfo屬性，擷取ZOLOZ原生SDK和使用者裝置的元資訊。
ZOLOZ Flutter外掛程式將元資訊返回給商戶Flutter App。
商戶Flutter App初始化交易資訊並將元資訊傳遞給商戶服務端。
商戶服務端擷取到元資訊後，調用initialize介面擷取用戶端配置資訊，包括SDK串連和行為相關參數。
ZOLOZ伺服器根據元資訊進行可用性檢查，檢查通過ZOLOZ伺服器將用戶端配置資訊返回給商戶服務端。
商戶服務端將用戶端配置資訊返回給商戶Flutter App。
商戶Flutter App使用用戶端配置資訊啟動ZOLOZ Flutter外掛程式。
ZOLOZ Flutter外掛程式調用ZOLOZ原生SDK與使用者互動，採集所需資料（例如人臉圖片）並上傳到ZOLOZ伺服器進行驗證。期間ZOLOZ原生SDK和ZOLOZ伺服器之間可能會進行多次互動。
ZOLOZ伺服器檢查上傳的使用者資料，並將交易狀態返回給ZOLOZ Flutter外掛程式。
如果所有檢查均通過，則向ZOLOZ Flutter外掛程式返回一個表示成功的結果碼；否則該過程可能會中斷，使用者和ZOLOZ Flutter外掛程式之間需要進一步互動。
ZOLOZ Flutter外掛程式通知商戶Flutter App交易已完成。
商戶Flutter App向商戶服務端同步交易已完成，並開始對交易明細進行雙重檢查。
商戶服務端調用checkResult介面與ZOLOZ伺服器再次核對交易明細。
ZOLOZ伺服器將交易明細返回給商戶服務端。
商戶服務端過濾交易明細，並將非敏感資訊返回給商戶Flutter App。
說明：為了保證資訊安全，採集到的人臉圖片等敏感資訊僅返回給商戶服務端，不會返回給商戶Flutter App。
商戶Flutter App通知使用者流程完成。

接入流程

服務端接入流程

前提條件

請確保已接入ZOLOZ網關，使ZOLOZ網關能夠被正常調用，以便正確處理API請求和響應。接入ZOLOZ網關的操作，請參見接入ZOLOZ網關。

操作步驟

為了使商戶Flutter App與商戶服務端能夠互動，以及商戶服務端能夠調用ZOLOZ API，您需要在商戶服務端為商戶Flutter App開放端點。本文以RealID API為例，介紹如何通過註解為商戶Flutter 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提供外掛程式方式接入Flutter平台，支援的硬體平台為Android和iOS，用戶端必須滿足以下要求：

用戶端作業系統版本必須為Android 4.3及以上版本，iOS 9及以上版本。
Android用戶端的架構必須為armeabi、arm64-v8a、armeabi-v7a，不支援x86架構。
Flutter版本需≥2.0.0，Dart版本需≥2.12.0，支援空安全（null safety）語言特性。

操作步驟

匯入SDK。
將ZOLOZ Flutter外掛程式作為依賴項，添加到專案的根目錄pubspec.yaml中。

environment:
  sdk: '>=2.18.5 <4.0.0'

dependencies:
  flutter:
    sdk: flutter
  zolozkit_for_flutter: ^1.1.4
  ...

說明：

強烈建議您使用最新版外掛程式，可提供最佳的產品體驗和更高的安全性。版本發布說明，詳見https://pub.dev/packages/zolozkit_for_flutter。
ZOLOZ SDK版本發布說明，詳見Release Notes。
environment.sdk為Dart語言版本，需≥2.12.0。

擷取元資訊。
使用ZolozkitForFlutter類的計算屬性MetaInfo擷取ZOLOZ原生SDK和使用者裝置的元資訊，元資訊用於後續初始化交易。

var metaInfo = await ZolozkitForFlutter.metaInfo;

初始化交易。
商戶Flutter App向商戶服務端發送包含元資訊的請求來初始化交易，然後商戶服務端調用initializeAPI擷取用戶端配置並將其返回給商戶Flutter App。
啟動交易流程。
使用構建的ZLZRequest對象調用start方法來啟動交易流程，並重寫回呼函數來處理交易結果。

    var publicKey = await ZolozkitForFlutter.zolozPublicKey;
    await ZolozkitForFlutter.start(
      result['clientCfg'],
      {},
      (String retCode, Map<Object?, Object?>? extInfo) {
        print("onInterrupted:$retCode, $extInfo");
      },
      (String retCode, Map<Object?, Object?>? extInfo) {
        print("onComplete:$retCode, $extInfo");
      },
    );

交易結果中包含標識交易流狀態的結果碼，具體如下：
- 如果終端使用者已完成整個互動流程，則調用onComplete方法，交易狀態需要與商戶服務端同步，並且需要啟動雙重檢查。然後商戶服務端調用checkResultAPI擷取交易詳情並將其返回給商戶Flutter App。
- 如果終端使用者未完成整個互動流程，則調用onInterrupted方法，並根據具體的業務需求來實現相關的商務邏輯。

自訂配置UI（可選）。
不同的行動裝置 App有不同的設計風格，例如標題列風格、按鈕風格等。為了更好地適應您的應用程式的風格，ZOLOZ支援對指定組件的顏色和文案進行簡單的UI自訂配置。
1. 配置UI並匯出設定檔，操作流程請參見步驟一：配置UI並匯出設定檔。
2. 使用設定檔啟動SDK。
  將產生的設定檔與ZOLOZ Flutter外掛程式整合，支援Android和iOS作業系統。下面為您介紹如何使用自訂UI設定檔啟動ZOLOZ Flutter外掛程式。
  說明：如果您不是用戶端開發人員，請將設定檔發送給您的用戶端開發人員進行配置。
  1. 將設定檔儲存到專案的任意檔案夾下，本文的儲存路徑為files/UIConfig.zip。

dependencies:
  path_provider: ^2.0.15

flutter:
  assets:
  - files/UIConfig.zip

ii. 修改專案的pubspec.yaml檔案，將自訂UI設定檔匯入為assets。

iii. 添加以下代碼啟動SDK。

使用copyUIConfigFile()將設定檔從assets中複製到App檔案目錄下，並在startZoloz()中將複製的設定檔傳入ZOLOZ Flutter外掛程式中。

import 'package:path_provider/path_provider.dart';
...

  Future<String> copyUIConfigFile() async {
    var file = await rootBundle.load("files/UIConfig.zip");
    Directory appDocDir = await getApplicationDocumentsDirectory();
    String configFilePath = "${appDocDir.path}/UIConfig.zip";
    final buffer = file.buffer;
    await File(configFilePath).writeAsBytes(
        buffer.asUint8List(file.offsetInBytes, file.lengthInBytes));
    return configFilePath;
  }

  void startZoloz() async {
    ...
    var configPath = await ZolozkitForFlutter.zolozChameleonConfigPath;
    String configFilePath = await copyUIConfigFile();
    await ZolozkitForFlutter.start(
      result['clientCfg'],
      {
        configPath: configFilePath
      },
      (String retCode, Map<Object?, Object?>? extInfo) {
        print("onInterrupted:$retCode, $extInfo");
      },
      (String retCode, Map<Object?, Object?>? extInfo) {
        print("onComplete:$retCode, $extInfo");
      },
    );

  }

c. 配置多語言（可選）。

ZOLOZ門戶的UI配置頁面支援配置多語言，為了使ZOLOZ Flutter外掛程式在啟動時使用其中一種語言，您需要在ZLZRequest對象中為相關參數指定語言資訊。ZOLOZ Flutter外掛程式將以指定的語言讀取設定檔，並將其呈現在您的應用中。

例如，您在UI配置頁面添加的語言為Chinese(Simplified)(zh-CN)，並希望ZOLOZ Flutter外掛程式使用該語言，則需要指定ZolozkitForFlutter.zolozLocale參數的值。ZolozkitForFlutter.zolozLocale參數的取值必須為language-Country格式。UI配置頁面中提供的各個語言選項的取值，請參見語言相關的參數值格式。

    var configPath = await ZolozkitForFlutter.zolozChameleonConfigPath;
    var publicKey = await ZolozkitForFlutter.zolozPublicKey;
    var local = await ZolozkitForFlutter.zolozLocale;

    await ZolozkitForFlutter.start(
      result['clientCfg'],
      {
        configPath: configFilePath,
        local: "zh-CN"
      },
      (String retCode, Map<Object?, Object?>? extInfo) {
        print("onInterrupted:$retCode, $extInfo");
      },
      (String retCode, Map<Object?, Object?>? extInfo) {
        print("onComplete:$retCode, $extInfo");
      },
    );

配置ProGuard（可選，僅Android硬體平台支援）。
如果您在Android應用中啟用了ProGuard，為確保您的應用可以成功地調用ZOLOZ Flutter外掛程式，需修改以下檔案。
1. 在android/app/build.gradle檔案中添加以下內容。

android {
    ...
    buildTypes {
        ...
        release {
            ...
            // add this line to the build.gradle file
            proguardFiles getDefaultProguardFile("proguard-android.txt"), "proguard-rules.pro"                
        }
    }        
}

b. 在專案的android/app/proguard-rules.pro混淆檔案中，添加以下配置。

說明：如果proguard-rules.pro檔案不存在，請先手動建立該檔案。

-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.**

Financial Intelligence Engine：使用Flutter外掛程式模式接入

支援的產品

支援的硬體平台

整合架構

互動流程

接入流程

服務端接入流程

前提條件

操作步驟

整合樣本

相關API

用戶端接入流程

前提條件

操作步驟