使用入门：将 App Check 与 reCAPTCHA Enterprise 搭配使用（Flutter 应用）

选择平台： iOS+ Android Web Flutter


本页介绍了如何使用 reCAPTCHA Enterprise 提供方在 Flutter 应用中设置 App Check。App Check 有助于确保只有您的应用可以访问项目的后端资源。如需了解详情，请查看我们的 App Check 概览。

App Check 需要使用基于分数的 reCAPTCHA 密钥，因此对用户来说是不可见的。这意味着 reCAPTCHA Enterprise 提供程序永远不会要求用户进行验证。

如果您的应用场景需要 reCAPTCHA Enterprise 未实现的 App Check 功能，或者您想将 App Check 与自己的自定义提供方搭配使用，请参阅实现自定义 App Check 提供方。

1. 设置您的 Firebase 项目

  1. 在 Flutter 项目中安装并初始化 Firebase（如果尚未执行此操作）。

  2. 在 Google Cloud 控制台中，前往欺诈防御页面，然后针对 reCAPTCHA Enterprise 提供商执行以下操作：

    1. 确保您位于正确的项目中（请参阅屏幕顶部的项目选择器）。

    2. 如果系统提示，请启用 reCAPTCHA Enterprise API。

    3. 根据目标平台创建密钥：

      iOS+

      创建 iOS 类型的密钥，并指定应用的软件包 ID（例如 com.example.my_app）。

      • 请务必输入您在 Firebase 项目中创建 Firebase Apple 应用时提供的软件包 ID。软件包 ID 值区分大小写。

      • 对于 App Check，每个软件包 ID 只能对应一个 reCAPTCHA 密钥。

      Android

      创建 Android 类型的密钥，并指定应用的软件包名称（例如 com.example.my_app）。

      • 请务必输入您在 Firebase 项目中创建 Firebase Android 应用时提供的软件包名称。软件包名称值区分大小写。

      • 对于 App Check，每个软件包名称只能对应一个 reCAPTCHA 密钥。

      Web

      创建网站类型的密钥，并为您的 Web 应用指定每个网域。

      • App Check不支持在超过 250 个网域上运行的 Web 应用。

      • 切勿将 localhost 作为网域添加到已部署到（或将要部署到）生产环境的 reCAPTCHA 密钥。

      • 请勿选择“使用复选框验证”选项。

      如需查看详细说明，请参阅创建基于得分的 reCAPTCHA 密钥。

    4. 记下每个密钥。您需要在 Firebase 控制台的注册流程中添加这些信息。

  3. 在 Firebase 控制台中，依次前往安全性 > App Check。

  4. 在应用标签页中，注册每个目标平台应用，以便将 App Check 与 reCAPTCHA Enterprise 提供方搭配使用。 您需要提供在 Google Cloud 控制台中获取的密钥。

  5. 可选：设置令牌存留时间 (TTL)。

    在应用注册设置中，为提供方颁发的 App Check 令牌设置自定义存留时间 (TTL)。您可以将 TTL 设置为 30 分钟到 7 天之间的任何值。更改此值时，请注意权衡以下几个方面：

    • 安全性：较短的 TTL 可以提供更强的安全性，因为它可以缩短攻击者可能滥用已泄露或者已被拦截的令牌的时长。
    • 性能：较短的 TTL 意味着您的应用将更频繁地执行证明操作。由于每次执行应用证明过程都会增加网络请求的延迟时间，因此短 TTL 可能会影响应用的性能。
    • 配额和费用：较短的 TTL 和频繁的重新证明会更快地耗尽您的配额，而对于付费服务，费用可能更高。请参阅配额和限制。

    对于大多数应用而言，默认的 TTL（1 小时）比较合理。请注意，App Check 库会在达到 TTL 时长约一半时刷新令牌。

  6. 可选：配置高级设置。

  7. 点击保存。

（可选）配置高级设置

当用户打开您的应用时，reCAPTCHA Enterprise 会评估用户在密钥控制下的互动所带来的风险等级，并返回一个介于 0.0 和 1.0 之间的得分，增量为 0.1。

  • 0.0 分表示互动风险高，可能具有欺诈性。
  • 1.0 分表示互动风险低，很可能是合法的。

借助 App Check，您可以配置应用风险阈值，以便可调整您对此风险的容忍度。

对于大多数应用场景，建议使用默认阈值 0.5。如果您的应用场景需要调整，可以在 Firebase 控制台中为每个应用配置此值（依次前往安全性 > App Check）。 请务必展开并查看下文中有关配置应用风险阈值的重要注意事项。

2. 将 App Check 插件添加到您的应用

如需使用 reCAPTCHA Enterprise 提供程序，您必须添加相应的 App Check 插件。

  1. 从 Flutter 项目的根目录运行以下命令，安装该插件：

    flutter pub add firebase_app_check

  2. 完成后，重新构建您的 Flutter 项目：

    flutter run

3. 初始化 App Check

在您的应用中，您需要先初始化 App Check，然后才能使用任何其他 Firebase 服务。

import 'package:firebase_core/firebase_core.dart';
import 'package:firebase_app_check/firebase_app_check.dart';
import 'firebase_options.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
  await FirebaseAppCheck.instance.activate(
    providerWeb: ReCaptchaEnterpriseProvider(WEB_SITE_KEY),
    providerAndroid: const AndroidReCaptchaProvider(ANDROID_SITE_KEY),
    providerApple: const AppleReCaptchaProvider(IOS_SITE_KEY),
  );
  runApp(App());
}

4. 监控指标并启用强制执行

在应用中设置 App Check 后，开始将更新后的应用分发给用户。

更新后的客户端应用会开始将 App Check 令牌随其发出的每个请求一起发送到 Firebase。不过，在App Check强制执行之前，App Check不会屏蔽包含无效令牌的请求。

监控指标

在启用强制执行之前，请确保这样做不会干扰现有的合法用户。不过，如果您发现自己的应用资源被非法使用，建议您尽快启用强制执行。

为帮助您做出相关决策，建议您查看自己使用的服务的 App Check 指标：

启用 App Check 强制执行

在了解 App Check 对用户有何影响并为后续操作做好准备之后，您便可以启用 App Check 强制执行：

在调试环境中使用 App Check

App Check 将某些环境归类为无效环境，例如在开发期间来自模拟器 / 仿真器或 localhost 的请求，或者来自持续集成 (CI) 环境的请求。

在强制执行 App Check 后，如需在这些类型的环境中运行应用，您需要创建应用的调试 build，该 build 使用 App Check 调试提供方，而不是生产环境证明提供方。

如需了解详情，请参阅将 App Check 与调试提供方搭配使用（Flutter 应用）。

价格

每次应用刷新其 App Check 令牌时，App Check 都会代表您创建评估，以验证用户的响应令牌。对于超出免费配额的每项创建的评估，我们会对您的 Firebase 项目收费。如需了解详情，请参阅reCAPTCHA 价格。

默认情况下，您的应用每 1 小时会刷新此令牌两次。如需控制应用刷新 App Check 令牌的频率（以及新评估的创建频率），您可以配置令牌 TTL。