Flutter接入 - ID Verification

ID Verification 提供了 Flutter 平台外掛程式，可以協助您在 Flutter 應用中實現 eKYC 遠程身分識別驗證功能。本文將結合範例程式碼介紹 Flutter 平台的接入流程。

使用限制

SDK不支援模擬器，請使用真機開發調試。
系統版本要求：iOS 9.0及以上、Android 5.0及以上。

依賴配置

下載 Flutter SDK並解壓。
將Flutter SDK整個目錄拷貝到您的業務工程中。
編輯業務工程的pubspec.yaml檔案，在dev_dependencies欄位下增加阿里雲依賴外掛程式。
```
aliyun_face_plugin:
    path: aliyun_face_plugin
```

Android 環境配置

增加模組依賴

選擇業務工程下的android > build.gradle檔案，在allprojects欄位中增加flatDir配置。

flatDir {
    dirs project(':aliyun_face_plugin').file('libs')
}

配置Proguard混淆規則

如果在release情境下配置了Proguard代碼混淆，則需要在業務工程的android > app > proguard-rules.pro檔案中添加如下規則：

-verbose
-keep class com.idv.identity.platform.api.** {*;}
-keep class com.idv.identity.platform.log.** {*;}
-keep class com.idv.identity.util.IdentityUtils {*;}
-keep class com.idv.identity.ocr.IdentityOcrApi {*;}
-keep class com.idv.identity.platform.model.** {*;}
-keep class com.idv.identity.platform.config.** {*;}
-keep class com.idv.identity.face.IdentityFaceApi {*;}


-keep class com.face.verify.intl.** {*;}
-keep class com.alibaba.fastjson.** {*;}
-keep class face.security.device.api.** {*;}
-keep class net.security.device.api.** {*;}
-keep class com.dtf.toyger.** { *; }
-dontwarn net.security.device.api.**
-dontwarn face.security.device.api.**


-keep class com.idv.identity.service.algorithm.** {*;}
-keep class com.idv.identity.base.algorithm.** {*;}
-keep class com.idv.identity.quality.QualityRouter {*;}
-keep class com.idv.identity.blink.BlinkRouter {*;}
-keep class com.idv.identity.service.IdentityFaceService {*;}
-keep class com.idv.identity.service.ocr.IdentityDocService {*;}

-keep class com.alibaba.sdk.android.oss.** { *; }
-dontwarn okio.**
-dontwarn org.apache.commons.codec.binary.**



# NFC
-keep class com.idv.identity.nfc.IdentityNfcApi { *; }
-keep class org.jmrtd.** {*;}
-keep class net.sf.**{*;}
-keep class org.**{*;}
-keep class cn.**{*;}


# Please add these rules to your existing keep rules in order to suppress warnings.
# This is generated automatically by the Android Gradle plugin.
-dontwarn com.fasterxml.**
-dontwarn com.google.**
-dontwarn java.applet.Applet
-dontwarn java.awt.**
-dontwarn javax.**
-dontwarn org.**
-dontwarn retrofit2.**
-dontwarn springfox.documentation.spring.web.json.Json

#日誌混淆，可選
-assumenosideeffects class android.util.Log {
    public static *** d(...);
}

iOS環境配置

添加Camera許可權

選擇業務工程下iOS > Runner.xcworkspace，使用Xcode開啟Runner工程。
在Runner工程的Info.plist檔案中增加Camera許可權。Value內容根據業務需要自訂即可。

添加Bundle

選擇Runner，單擊Build Phases頁簽，在Copy Bundle Resources中添加以下4個Bundle。

Bundle檔案在SDK目錄下，所在路徑為aliyun_face_plugin/ios/Products的相關framework中。

ToygerService.bundle：位於ToygerService.framework中。
AliyunIdentityPlatform.bundle：位於AliyunIdentityPlatform.framework中。
AliyunIdentityOCR.bundle：位於AliyunIdentityOCR.framework中。
AliyunIdentityFace.bundle：位於AliyunIdentityFace.framework中。

增加 -ObjC 連結標誌

選擇Pods，單擊Build Settings頁簽，在Linking欄位的Other Linker Flags設定項中增加-ObjC標誌。

介面說明

Flutter SDK包含初始化SDK（initWithOptions）、擷取MetaInfos（getMetaInfos）、開始認證（verify）和自訂UI（setCustomUI）4個介面。

class AliyunFacePlugin {
  // 初始化
  Future<void> init() {
    return AliyunFacePluginPlatform.instance.init();
  }
  // SDK初始化介面
  Future<void> initWithOptions(Map<String, String> options) {
    return AliyunFacePluginPlatform.instance.initWithOptions(options);
  }

  // 擷取用戶端的metainfos，用於伺服器端介面擷取認證id，即transactionId
  Future<String?> getMetaInfos() {
    return AliyunFacePluginPlatform.instance.getMetaInfos();
  }
  
  // SDK認證介面
    Future<String?> verify(Map<String, String> params) {
    return AliyunFacePluginPlatform.instance.verify(params);
  }
  
  // SDK自訂UI
  Future<String?> setCustomUI(String configuration) {
    return AliyunFacePluginPlatform.instance.setCustomUI(configuration);
  }
}

初始化SDK

initWithOptions(options)介面：需要在應用冷啟動時，使用者確認App隱私協議之後，儘可能早地調用該介面完成初始化。

options：資訊採集可選項，預設可以為null。選擇性參數如下：

說明

ID Verification用戶端內建裝置助手安全模組，為了滿足不同地區資料收集合規要求，提供了不同的資料上報地區。您可以基於使用者屬性不同，設定CustomUrl和CustomHost指定不同的上報網站。
注意：一次應用會話生命週期內只能指定一個地區上報，且服務端查詢時地區需要和上報地區保持一致。
指定網站上報：
- 新加坡網站（預設）：https://cloudauth-device.ap-southeast-1.aliyuncs.com
- 印尼網站：https://cloudauth-device.ap-southeast-5.aliyuncs.com
- 美西（矽谷）：https://cloudauth-device.us-west-1.aliyuncs.com
- 德國（法蘭克福）：https://cloudauth-device.eu-central-1.aliyuncs.com
- 中國香港：https://cloudauth-device.cn-hongkong.aliyuncs.com
不同產品服務端支援的地區，參考：支援的地區。

欄位名	說明	樣本
IPv6	是否使用IPv6網域名稱上報裝置資訊： 0（預設）：否（使用IPv4網域名稱） 1：是（使用IPv6網域名稱）	"1"
DataSwitch	裝置資訊上報時機。 0（預設）：初始化時 1：擷取Token時說明建議採用預設配置。	"1"
CustomUrl	設定資料上報伺服器網域名稱。	"https://cloudauth-device.ap-southeast-1.aliyuncs.com"
CustomHost	設定資料上報伺服器host。	"cloudauth-device.ap-southeast-1.aliyuncs.com

擷取MetaInfos

getMetaInfos()介面：該介面會返回用戶端的環境資訊，用戶端需要使用MetaInfos資訊向商務服務器發送請求，商務服務器隨後使用從用戶端接收到的MetaInfos，向阿里雲發送初始化認證請求，從而擷取transactionId，用於後續的認證環節。

開始認證

使用verify()介面發起認證請求。

verify()介面參數：

必須的參數：transactionId

擴充參數：

參考原生SDK(Android/iOS）各自的擴充參數（extParams）配置。

Android

Key	說明	樣本（String類型）
IdentityParams.OcrResultButtonColor	OCR識別結果頁面的底部按鈕顏色。	#FF0000
IdentityParams.RoundProgressColor	掃臉時的圓圈顏色。	#FF0000
IdentityParams.ShowBlbumIcon	證件OCR識別環節，是否展示相簿上傳入口： 1（預設）：展示 0：不展示	1
IdentityParams.ShowOcrResult	證件OCR識別環節，是否展示識別結果頁： 1（預設）：展示 0：不展示	1
IdentityParams.EditOcrResult	證件OCR識別環節，識別結果頁是否可編輯： 1（預設）：可編輯 0：不可編輯	1
IdentityParams.MaxErrorTimes	重試次數上限。可設定範圍為3~10次，預設10次。	10
IdentityParams.CardOcrTimeOutPeriod	OCR識別環節逾時時間長度。可設定範圍為20~60秒，預設20秒。	20
IdentityParams.FaceVerifyTimeOutPeriod	活體採集檢測環節逾時時間長度。可設定範圍為20~60秒，預設20秒。	20
IdentityParams.OcrResultTimeOutPeriod	OCR識別結果頁面可編輯時間長度。可自訂配置，預設不限。	60
IdentityParams.SdkLanguage	SDK語言自訂設定。預設跟隨行動裝置系統的設定。說明 SDK具體支援的語言列表，請參見Android和iOS SDK 自訂語種。	zh-Hans
IdentityParams.CloseButtonLayout	關閉按鈕的布局： left（預設）：左側 right：右側	left
IdentityParams.WaterMark	OCR識別成功後浮水印文字。	測試浮水印文字
IdentityParams.Protocol	SDK Protocol。說明通過服務端Initialize介面擷取protocol，傳入擴充參數中，可減少SDK內部介面互動，提升網路體驗。	無

iOS

Key	說明	樣本（String類型）
kIdentityParamKeyNextButtonColor	OCR識別結果頁面的底部按鈕顏色。	#FF0000
kIdentityParamKeyRoundProgressColor	掃臉時的圓圈顏色。	#FF0000
kIdentityParamKeyOcrSelectPhoto	證件OCR識別環節，是否展示相簿上傳入口： 1（預設）：展示 0：不展示	1
kIdentityParamKeyShowOcrResult	證件OCR識別環節，是否展示識別結果頁： 1（預設）：展示 0：不展示	1
kIdentutyParamKeyEditOcrResult	證件OCR識別環節，識別結果頁是否可編輯： 1（預設）：可編輯 0：不可編輯	1
kIdentityParamKeyMaxRetryCount	重試次數上限。可設定範圍為3~10次，預設10次。	10
kIdentityParamKeyCardOcrTimeOutPeriod	OCR識別環節逾時時間長度。可設定範圍為20~60秒，預設20秒。	20
kIdentityParamKeyFaceVerifyTimeOutPeriod	活體採集檢測環節逾時時間長度。可設定範圍為20~60秒，預設20秒。	20
kIdentityParamKeyCardOcrEditTimeOutPeriod	OCR識別結果頁面可編輯時間長度。可自訂配置，範圍為60秒到180秒之間，預設不限。	180
kIdentityParamKeyLanguage	SDK語言自訂設定。預設跟隨行動裝置系統的設定。說明 SDK具體支援的語言列表，請參見Android和iOS SDK 自訂語種。	zh-Hans
kIdentityParamKeyDefaultLanguage	SDK預設語言設定，可參考kIdentityParamKeyLanguage欄位取值。預設為en：英文。	en
kIdentityParamKeyCloseButtonPosition	SDK關閉按鈕位置： left（預設）：左側 right：右側	left
kIdentityParamKeyWatermark	OCR識別成功後浮水印文字。	測試浮水印文字
kIdentutyParamKeyProtocol	SDK Protocol。說明通過服務端Initialize介面擷取protocol，傳入擴充參數中，可減少SDK內部介面互動，提升網路體驗。	968412EB*******...

傳回值：格式為code,reason。code為錯誤碼；reason為具體原因。中間以半形逗號（,）分隔。
iOS、Android平台的code及reason解釋可能會有不同，請您參考對應文檔。

使用setCustomUI()介面自訂UI顏色：

參數：params：傳入JSON格式資料。參考原生SDK各自的ui自訂配置：
- Android SDK UI自訂配置說明
- iOS SDK UI自訂配置說明

說明

每個transactionId只能使用一次，否則會返回錯誤。錯誤資訊如下：

iOS：2002,ZIMNetworkfail。
Android：1001,NET_RESPONSE_INVALID。

範例程式碼

import 'package:flutter/material.dart';
import 'dart:async';
import 'dart:io';

import 'package:flutter/services.dart';
import 'package:aliyun_face_plugin/aliyun_face_plugin.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatefulWidget {
  const MyApp({super.key});

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  String _infos = 'Unknown';
  final _aliyunFacePlugin = AliyunFacePlugin();

  @override
  void initState() {
    super.initState();

    // 在 App 啟動的早期調用 init 介面。
    Map<String, String> options = {"CustomUrl":"https://cloudauth-device.ap-southeast-5.aliyuncs.com",
                                   "CustomHost":"cloudauth-device.ap-southeast-5.aliyuncs.com"};
    _aliyunFacePlugin.initWithOptions(options);
  }

  Future<void> getMetaInfos() async {
    String metainfos;

    try {
      // 擷取用戶端metainfos，將資訊發送到伺服器端，調用伺服器端相關介面擷取認證ID，即CertifyId。
      metainfos = await _aliyunFacePlugin.getMetaInfos() ?? 'Unknown metainfos';
    } on PlatformException {
      metainfos = 'Failed to get metainfos.';
    }

    setState(() {
      _infos = "metainfos: " + metainfos;
    });
  }

  Future<void> setCustomUi() async {
    try {
      String config = "{\"faceConfig\":{ \"faceBGColor\": \"#FF33FF\"}}";
      await _aliyunFacePlugin.setCustomUI(config) ?? '-1,error';
    } on PlatformException {
      '-2,exception';
    }
  }

  Future<void> startVerify() async {
    String verifyResult;
    try {
      String transactionId = "xxxx";//認證ID
      Map<String, String> params = {
        "transactionId": transactionId,
      };
      if (Platform.isIOS) {
        params.addAll({"kIdentityParamKeyLanguage": "en"});
      } else if (Platform.isAndroid) {
        params.addAll({"SdkLanguage": "en"});
      }

      verifyResult = await _aliyunFacePlugin.verify(params) ?? '-1,error';
    } on PlatformException {
      verifyResult = '-2,exception';
    }

    setState(() {
      _infos = "verifyResult: " + verifyResult;
    });
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Aliyun face plugin demo')),
        body: Center(
          child: Column(children: <Widget>[
            Text('$_infos\n'),
            ElevatedButton(
              onPressed: () async {
                getMetaInfos();
              },
              child: Text("getMetaInfos")),
            ElevatedButton(
              onPressed: () async {
                startVerify();
              },
              child: Text("startVerify")),
            ElevatedButton(
              onPressed: () async {
                setCustomUi();
              },
              child: Text("setCutomUi")),
          ])),
      ),
    );
  }
}

您也可以下載Flutter Demo體驗完整代碼。

重要

此Demo代碼僅作為整合樣本，建議替換最新版本SDK。