Flutter

本指南介绍如何将 geelabguard_flutter 接入 Flutter App，并完成设备指纹 receipt 的生成与提交。

本文只覆盖客户端接入。submitReceipt 返回的 originalResponse 需要由业务服务端按照双方确认的 GeelabGuard 对接协议继续处理；插件不会替代服务端查询、验签或风控决策。

前置条件

开始前请准备：

Flutter SDK 3.10.0 或更高版本
Dart 3.0.5 或更高版本
一个有效的 GeelabGuard AppID
Android Studio/Android SDK，或 Xcode（取决于目标平台）
基本的 Dart 和 Flutter 开发经验

Android 最低支持 API 19，插件原生层最低支持 iOS 11.0；实际 iOS 最低版本还受所用 Flutter SDK 约束，本仓库示例工程按当前 Flutter stable 配置为 iOS 15.0。真机调试时，还需要完成设备信任、开发者模式和代码签名配置。

1. 添加插件

在业务工程的 pubspec.yaml 中添加依赖：

dependencies:
  flutter:
    sdk: flutter
  geelabguard_flutter: ^1.0.1

然后获取依赖：

flutter pub get

如果你正在运行本仓库自带的 example，可以用路径依赖验证本地源码：

dependencies:
  geelabguard_flutter:
    path: ../

2. 配置 Android

插件内置预编译的 Android SDK（JAR 和四种 ABI 的 JNI 库），接入方不需要编译 C/C++ 源码，也不需要为本插件单独安装或指定 NDK 版本。

插件不声明固定的 ndkVersion，由宿主工程和 Flutter 工具链统一管理。如果其他依赖明确要求特定 NDK 版本，请根据构建提示在宿主工程中配置所有依赖要求的最高版本。

插件已经声明 Android INTERNET 权限。

3. 配置 iOS

进入 Flutter 工程目录并安装 CocoaPods 依赖：

cd ios
pod install
cd ..

也可以直接执行 flutter run，Flutter 通常会自动触发 pod install。如果需要用 Xcode 调试，请打开 workspace，而不是 project：

open -a Xcode ios/Runner.xcworkspace

在 Xcode 中选择 Runner target，配置 Signing & Capabilities 的 Team 和唯一 Bundle Identifier，然后选择模拟器或真机运行。真机需要开启开发者模式并信任当前 Mac；Xcode 还必须支持设备的 iOS 版本。

4. 注册 AppID

在 App 启动阶段或首次使用前调用 register。注册成功后，才能调用 fetchReceipt 或 submitReceipt：

import 'package:geelabguard_flutter/geelabguard_flutter.dart';

Future<void> initializeGeelabGuard() async {
  await GeelabGuard.register('YOUR_GEELABGUARD_APP_ID');
}

使用自定义服务地址（可选）

如果部署环境需要覆盖原生 SDK 的默认服务地址，可以在注册时传入 serverUrl：

await GeelabGuard.register(
  'YOUR_GEELABGUARD_APP_ID', // 后台获取的public_key
  serverUrl: 'https://riskct-global.geelabapi.com/api/v2/client_report',
);

serverUrl 会同时传递给 Android 和 iOS 原生 SDK 的注册接口。不传该参数时，继续使用各平台 SDK 内置的默认地址。

插件会在 Dart 层校验该值：必须是包含主机名的 http 或 https URL；为空或格式不合法时会抛出 ArgumentError，不会发起原生注册调用。是否需要包含具体接口路径，请以 GeelabGuard 原生 SDK 对接文档为准。

register 是异步操作，建议在 main 中等待完成：

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await GeelabGuard.register(
    'YOUR_GEELABGUARD_APP_ID', // 后台获取的public_key
    // 可选：覆盖原生 SDK 默认服务地址。
    serverUrl: 'https://riskct-global.geelabapi.com/api/v2/client_report',
  );
  runApp(const MyApp());
}

请将占位符替换为真实 AppID，不要把生产 AppID、业务密钥或服务端凭据写入公开代码仓库。

5. 生成本地 receipt

fetchReceipt 只在本地生成 receipt，不执行提交：

final receipt = await GeelabGuard.fetchReceipt('YOUR_BUSINESS_DATA');

if (receipt != null) {
  print('GeeID: ${receipt.geeID}');
  print('GeeToken: ${receipt.geeToken}');
  print('GeeIDTimestamp: ${receipt.geeIDTimestamp}');
}

data 用于 SDK 的签名校验，不会按原文提交。请使用能够关联本次业务操作的流水号或凭据，并避免放入密码、密钥等敏感信息。

6. 提交 receipt

submitReceipt 会生成并提交 receipt，超时参数统一使用毫秒，默认值为 5000 毫秒：

final receipt = await GeelabGuard.submitReceipt(
  'YOUR_BUSINESS_DATA',
  timeoutMilliseconds: 5000,
);

if (receipt != null) {
  print('GeeID: ${receipt.geeID}');
  print('RespondedGeeToken: ${receipt.respondedGeeToken}');
  print('OriginalResponse: ${receipt.originalResponse}');
}

例如，将超时调整为 10 秒：

await GeelabGuard.submitReceipt(
  'YOUR_BUSINESS_DATA',
  timeoutMilliseconds: 10000,
);

7. 处理错误

原生 SDK 错误会以 PlatformException 返回；在注册前调用其他方法会抛出 GeelabGuardException。建议在业务入口统一捕获：

import 'package:flutter/services.dart';

Future<void> submit() async {
  try {
    final receipt = await GeelabGuard.submitReceipt('YOUR_BUSINESS_DATA');
    // 将 receipt 中的结果交给业务流程处理。
    print(receipt?.toDisplayText());
  } on GeelabGuardException catch (error) {
    print('GeelabGuard 调用顺序错误：${error.message}');
  } on PlatformException catch (error) {
    print('GeelabGuard 原生错误：${error.code} ${error.message}');
    // Android 提交错误时，error.details['code'] 可能包含 SDK 错误码。
  }
}

8. 运行示例工程

本仓库自带完整 Demo，位于 example/：

cd example
flutter pub get
flutter devices
flutter run -d <设备ID>

运行前编辑 example/lib/main.dart，将 mGeelabGuardAppID 替换为真实 AppID。Demo 中按以下顺序点击：

Register
Fetch Receipt
Submit Receipt

Chrome 和 macOS 桌面端不能验证 Android/iOS 原生 SDK；请使用 Android 真机/模拟器或 iOS 模拟器/真机。

验证清单

Register 成功后，GeelabGuard.isRegistered 为 true
Fetch Receipt 能返回 appID、geeToken、geeID 和 geeIDTimestamp
Submit Receipt 能返回 respondedGeeToken 或 originalResponse
使用非空的业务数据，且所有超时值以毫秒传递
在未注册状态下调用 receipt 方法时，能够返回明确的调用顺序错误
真机测试时，在设备锁屏、无网络或服务异常情况下验证错误提示

下一步

将 GeeID、GeeToken、时间戳以及提交结果接入业务服务端流程，并按照 GeelabGuard 服务端协议完成查询、验签和风险决策。服务端接口地址、鉴权方式和响应字段以正式对接文档为准。

Flutter

On this page