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指定不同的上报站点。
一次应用会话生命周期内只能指定一个地域上报，且服务端查询时地域需要和上报地域保持一致。各产品服务端支持的地域有所不同，详情请参考支持的地域。
各地域的CustomUrl：
- 中国香港：https://cloudauth-device.cn-hongkong.aliyuncs.com
- 新加坡：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

字段名	说明	示例
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。