使用 App Check 保护 Navigation SDK for Android

Firebase App Check 可屏蔽来自合法应用以外的流量，为您的应用对 Google Maps Platform 的调用提供保护。为此，它会向 Play Integrity 等证明提供方请求评估应用或设备的真实性。将应用与 App Check 集成后，您可以防范恶意请求和未经授权的请求，从而保护您的账单免遭未经授权的扣款。App Check 还可以显著改进车队应用生态系统中的实时中断报告，从而使使用您应用的所有司机受益。如需了解详情，请参阅中断报告。

为什么要使用 App Check？

App Check 可保护 Navigation SDK for Android 的两个不同方面：主要导航功能和中断报告。

App Check 有助于阻止来自恶意或未经授权来源的 Android 版 Navigation SDK 主要请求。这可直接保护您的项目免遭账单欺诈和配额耗尽的风险，从而让您受益。

运营中断报告

如果您的应用支持实时中断报告和投票功能，强烈建议您使用 App Check。启用 App Check 可确保为司机提供最准确的路线，并考虑所有实时反馈。

为什么 App Check 对报告很重要：

  • 关闭事件的信任度较高：影响路线的事件（例如道路封闭）可能会显著改变所有驾驶员的路线规划行为。为保护地图免遭潜在的恶意破坏、网络垃圾或不准确的报告，Google 的封路中断审核基础架构依赖于强大的设备和应用完整性信号。
  • App Check 如何验证报告：通过 Navigation SDK for Android 发送的用户报告和投票包含 App Check 令牌，Google 的后端会使用该令牌来验证反馈的合法性，从而提高反馈的可信度，并允许评估反馈对已发布的地图的影响。
  • 省略 App Check 的影响：如果提交的报告没有有效的 App Check 令牌，系统会根据较低信任度的模型对其进行评估，并且可能仅将其作为静默信号进行处理。这意味着，虽然用户仍可以举报和投票，但其举报不太可能显示在地图上或影响其他驾驶员的路线，并且需要进行额外验证。

App Check 是否适合我？

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

  • 私密应用或实验性应用：如果您的应用无法公开访问，则不需要使用 App Check。
  • 存在安全风险的设备：建议的证明提供程序可防止 Navigation SDK for Android 在不可信的设备（例如已启用 root 权限或已越狱的手机）上运行。如需支持这些设备，请部署自定义认证提供程序。
  • 非 GMS Android 设备：Android 设备必须运行 Google 移动服务 (GMS) 才能使用 Play Integrity。如果您计划支持非 GMS Android 设备，请部署自定义认证提供程序。

实现步骤概览

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

  1. 将 Firebase 添加到您的应用。
  2. 添加 App Check 库并初始化 App Check。
  3. 添加令牌提供方。此步骤会调用您选择的证明提供程序来验证设备或应用的完整性。
  4. 初始化 Navigation 和 App Check API。
  5. 启用调试功能。这在开发期间或持续集成 (CI) 环境中非常有用。
  6. 在启用强制执行之前，请先监控应用请求。这样，您就可以顺畅地强制执行 App Check，而不会干扰用户。

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

  • 证明提供方配额：我们推荐的证明提供方 Play Integrity 的标准 API 用量层级设有每日调用次数上限。如需详细了解调用次数限制，请参阅 Google Play Integrity 开发者文档中的设置页面。
  • 启动延迟时间：在大多数情况下，用户在正常使用时不会遇到延迟，因为 App Check 令牌会缓存在设备上。系统会在后台自动刷新 App Check 令牌，以确保在令牌过期之前保持顺畅的性能。不过，如果不存在有效的 App Check 令牌，应用用户在启动时会遇到一些延迟。例如，在冷启动期间，当缓存的令牌过期或丢失时，就会出现这种延迟。
  • 令牌 TTL：存留时间 (TTL) 决定了 App Check 令牌在需要刷新之前有效的时长。您可以在 Firebase 控制台中将此时长配置为 30 分钟到 7 天。建议将时长设置为 1 小时作为安全基准，但 SDK 会在大约一半的 TTL 时长自动尝试后台刷新。如需查看有关控制台操作的分步说明，请参阅 Firebase App Check 文档。

将应用与 App Check 集成

前提条件和要求

  • 已安装 Navigation SDK for Android 7.9 版或更高版本的应用。
  • 应用的 SHA-256 证书指纹。
  • 应用的软件包名称。
  • 您必须是 Google Cloud 控制台中相应应用的所有者。
  • Google Cloud 控制台中的应用项目 ID。

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

按照 Firebase 开发者文档中的说明将 Firebase 添加到您的应用。将 google-services.json 文件添加到项目的应用级目录中。

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

将 App Check 依赖项添加到应用的 build.gradle 文件中：

Groovy (build.gradle)

dependencies {
    // Import the Firebase BoM
    implementation platform('com.google.firebase:firebase-bom:34.17.0')
    // Add the dependency for the App Check library with Play Integrity
    implementation 'com.google.firebase:firebase-appcheck-playintegrity'
}

在您的 Application 类或主 activity 中初始化 App Check：

Java

import com.google.firebase.FirebaseApp;
import com.google.firebase.appcheck.FirebaseAppCheck;
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory;

// Initialize Firebase App
FirebaseApp.initializeApp(/* context= */ this);

// Initialize App Check
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
    PlayIntegrityAppCheckProviderFactory.getInstance());

Kotlin

import com.google.firebase.Firebase
import com.google.firebase.appcheck.appCheck
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory
import com.google.firebase.initialize

// Initialize Firebase App
Firebase.initialize(context = this)

// Initialize App Check
Firebase.appCheck.installAppCheckProviderFactory(
    PlayIntegrityAppCheckProviderFactory.getInstance(),
)

第 3 步：添加令牌提供程序

创建 MapsAppCheckTokenProvider 接口的实现。此提供程序使用 MapsAppCheckTokenCallback 从 Firebase App Check 异步获取 App Check 令牌，并将其传递给 Navigation SDK for Android 网络堆栈：

Java

import com.google.android.gms.maps.MapsAppCheckTokenCallback;
import com.google.android.gms.maps.MapsAppCheckTokenProvider;
import com.google.firebase.appcheck.FirebaseAppCheck;

public class NavigationTokenProvider implements MapsAppCheckTokenProvider {
  @Override
  public void fetchToken(MapsAppCheckTokenCallback callback) {
    FirebaseAppCheck.getInstance()
        .getAppCheckToken(false) // forcingRefresh = false
        .addOnSuccessListener(
            tokenResult -> {
              String token = tokenResult.getToken();
              callback.onSuccess(token);
            })
        .addOnFailureListener(
            e -> {
              callback.onFailure();
            });
  }
}

Kotlin

import com.google.android.gms.maps.MapsAppCheckTokenCallback
import com.google.android.gms.maps.MapsAppCheckTokenProvider
import com.google.firebase.appcheck.FirebaseAppCheck

class NavigationTokenProvider : MapsAppCheckTokenProvider {
    override fun fetchToken(callback: MapsAppCheckTokenCallback) {
        FirebaseAppCheck.getInstance()
            .getAppCheckToken(false)
            .addOnSuccessListener { tokenResult ->
                callback.onSuccess(tokenResult.token)
            }
            .addOnFailureListener {
                callback.onFailure()
            }
    }
}

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

使用 MapsApiSettings.setAppCheckTokenProvider() 初始化 Navigation SDK for Android 并注册您的统一令牌提供程序实例：

Java

import com.google.android.gms.maps.MapsApiSettings;

// Register your App Check token provider before initializing Navigation SDK for Android
MapsApiSettings.setAppCheckTokenProvider(context, new NavigationTokenProvider());

Kotlin

import com.google.android.gms.maps.MapsApiSettings

// Register your App Check token provider before initializing Navigation SDK for Android
MapsApiSettings.setAppCheckTokenProvider(context, NavigationTokenProvider())

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

为 Navigation SDK for Android 强制执行 App Check 后，依赖于 Navigation SDK for Android 的应用功能将无法在模拟器或持续集成 (CI) 环境中运行，因为这些环境不符合有效设备的条件。如需在开发和测试期间在此类环境中运行应用，您需要创建应用的调试 build，该 build 使用 App Check 调试提供方，而不是正式版证明提供方。

  1. 将调试提供程序依赖项添加到应用的 build.gradle 文件中：

    Groovy (build.gradle)

    dependencies {
    implementation 'com.google.firebase:firebase-appcheck-debug'
}
  2. 在调试 build 中，将 App Check 配置为使用调试提供程序工厂：

    Java

    import com.google.firebase.appcheck.debug.DebugAppCheckProviderFactory;
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory;

if (BuildConfig.DEBUG) {
    firebaseAppCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance()
    );
} else {
    firebaseAppCheck.installAppCheckProviderFactory(
        PlayIntegrityAppCheckProviderFactory.getInstance()
    );
}

    Kotlin

    import com.google.firebase.Firebase
import com.google.firebase.appcheck.appCheck
import com.google.firebase.appcheck.debug.DebugAppCheckProviderFactory
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory

if (BuildConfig.DEBUG) {
    Firebase.appCheck.installAppCheckProviderFactory(
        DebugAppCheckProviderFactory.getInstance(),
    )
} else {
    Firebase.appCheck.installAppCheckProviderFactory(
        PlayIntegrityAppCheckProviderFactory.getInstance(),
    )
}
  3. 在模拟器或调试设备上启动应用。App Check 会将一个本地调试令牌发送到您的 Logcat 输出中。
  4. 复制此调试令牌并在 Firebase 控制台中注册。如需了解详情，请参阅 Firebase App Check 调试提供程序文档。

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

在启用强制执行之前，请监控应用请求，确保不会干扰合法用户。

  1. 访问 Firebase 控制台中的 App Check 指标界面，查看已验证流量与未验证流量的百分比。
  2. 确定大部分流量都已通过验证，并且合法用户已更新到包含 App Check 实现的应用版本后，即可启用强制执行。
  3. 强制执行后，App Check 会拒绝所有没有有效 App Check 令牌的流量。