使用 App Check 保护您的 API 密钥

Firebase App Check 可屏蔽来自合法应用以外的流量，为您的应用对 Google Maps Platform 的调用提供保护。为此，它会检查来自 reCAPTCHA Enterprise 等证明提供方的令牌。将应用与 App Check 集成，有助于防范恶意请求，让您不会为未经授权的 API 调用付费。

App Check 是否适合我？

在大多数情况下，建议使用 App Check，但在以下情况下，不需要或不支持 App Check：

专用应用或实验性应用。如果您的应用不公开，则不需要使用 App Check。
如果您的应用仅用于服务器到服务器的通信，则不需要使用 App Check。不过，如果与 GMP 通信的服务器由公共客户端（例如移动应用）使用，请考虑使用 App Check 保护该服务器，而不是使用 GMP。

实施步骤概览

概括来讲，您需要按照以下步骤将应用与 App Check 集成：

将 Firebase 添加到您的应用。
添加并初始化 App Check 库。
将令牌提供程序添加到您的应用中。
初始化 Maps JS API 和 App Check API。
启用调试功能。
监控应用请求，并决定是否强制执行。

与 App Check 集成后，您将能够在 Firebase 控制台中查看后端流量指标。这些指标可按请求是否附带有效的 App Check 令牌对其进行细分。如需了解详情，请参阅 Firebase App Check 文档。

当您确定大多数请求都来自合法来源，并且用户已更新到包含 App Check 实现的应用最新版本时，您就可以开启强制执行。强制执行后，App Check 会拒绝所有没有有效 App Check 令牌的流量。

规划 App Check 集成时的注意事项

在规划集成时，请注意以下事项：

我们推荐的其中一个认证提供方 reCAPTCHA Enterprise 会对每月超过 10,000 次的评估收费。
我们推荐的另一个认证服务提供商 reCAPTCHA v3 有配额限制，超出配额后，流量将不会被评估。

您可以选择使用自定义认证提供方，不过这是一种高级用例。如需了解详情，请参阅 App Check 文档。
应用的用户在启动时会遇到一些延迟。不过，此后任何定期重新认证都将在后台进行，用户应该不会再遇到任何延迟。启动时的确切延迟时间取决于您选择的认证提供方。

App Check 令牌的有效时长（存留时间或 TTL）决定了重新证明的频率。此持续时间可在 Firebase 控制台中进行配置。当 TTL 过去大约一半时，系统会重新进行认证。如需了解详情，请参阅适用于您的认证提供方的 Firebase 文档。

将您的应用与 App Check 集成

前提条件和要求

加载了最新每周或每季度版本 Maps JS API 和核心库的应用。
已启用 Maps JS API 的云项目。
您必须是 Cloud 控制台中应用的所有者。
您需要从 Cloud 控制台获取应用的项目 ID

第 1 步：将 Firebase 添加到您的应用

按照 Firebase 开发者文档中的说明将 Firebase 添加到您的应用。

第 2 步：添加 App Check 库并初始化 App Check

Firebase 为每个默认认证提供方提供了说明。这些说明介绍了如何设置 Firebase 项目以及如何将 App Check 库添加到应用中。请按照提供的代码示例初始化 App Check。

reCAPTCHA Enterprise 说明。
reCAPTCHA v3 说明。

您必须先向 reCAPTCHA v3 注册您的网站，并使用 reCAPTCHA 网站注册工具获取 reCAPTCHA v3 网站密钥和 Secret 密钥，然后才能在 Cloud 控制台中启用该 API。如需了解详情和说明，请参阅 reCAPTCHA v3 文档。

第 3 步：加载 Maps JS API 库

加载核心库和 Maps 库，如以下代码段所示。如需了解详情和说明，请参阅 Maps JavaScript API 文档。

async function init() {
  const {Settings} = await google.maps.importLibrary('core');
  const {Map} = await google.maps.importLibrary('maps');
}

第 4 步：初始化 Maps API 和 App Check API

使用 Firebase 控制台提供的配置初始化 App Check。
- reCAPTCHA v3 说明。
- reCAPTCHA Enterprise 说明。

确保向 Maps JS API 发出的请求附带 App Check 令牌：

  import {initializeApp} from 'firebase/app';
  import {
    getToken,
    initializeAppCheck,
    ReCaptchaEnterpriseProvider,
  } from 'firebase/app-check';
    
  async function init() {
    const {Settings} = await google.maps.importLibrary('core');
    const {Map} = await google.maps.importLibrary('maps');
  
    const app = initializeApp({
      // Your firebase configuration object
    });
  
    // Pass your reCAPTCHA Enterprise site key to initializeAppCheck().
    const appCheck = initializeAppCheck(app, {
      provider: new ReCaptchaEnterpriseProvider(
        'abcdefghijklmnopqrstuvwxy-1234567890abcd',
      ),
  
      // Optional argument. If true, the SDK automatically refreshes App Check
      // tokens as needed.
      isTokenAutoRefreshEnabled: true,
    });
  
    Settings>.getInstance().fetchAppCheckToken = () =
        getToken(appCheck, /* forceRefresh = */ false);
  
    // Load a map
    map = new Map(document.getElementById("map"), {
      center: { lat: 37.4161493, lng: -122.0812166 },
      zoom: 8,
    });
  }

第 5 步：启用调试（可选）

如果您想在本地开发和测试应用，或在持续集成 (CI) 环境中运行应用，可以创建应用的调试 build，该 build 使用调试密钥来获取有效的 App Check 令牌。这可以让您避免在调试 build 中使用真实的证明提供方。

如需在本地测试应用，请执行以下操作：

激活调试提供程序以用于开发。
您将从 SDK 的调试日志中收到自动生成的随机 UUID4（在 App Check 文档中称为“调试令牌”）。将此令牌添加到 Firebase 控制台。
如需了解详情和说明，请参阅 App Check 文档。

如需在 CI 环境中运行应用，请执行以下操作：

从 Firebase 控制台生成随机 UUID4。
将 UUID4 添加为调试令牌，然后将其复制到 CI 测试在每次测试运行时都会访问的 Secret 存储区。
如需了解详情和说明，请参阅 App Check 文档。

第 6 步：监控应用请求，并决定是否强制执行

在开始强制执行之前，您需要确保不会干扰应用的合法用户。为此，请访问 App Check 指标界面，查看应用的流量中有多少百分比是经过验证的、过时的或非法的。如果您发现大部分流量都已通过验证，即可启用强制执行。

如需了解详情和说明，请参阅 Firebase App Check 文档。