Navigation SDK for Android | Google for Developers

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

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

为何要使用 App Check？

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

App Check 有助于屏蔽来自恶意来源或未经授权的来源的主要 Navigation SDK for Android 请求。这可以直接保护您的项目免遭结算欺诈和配额耗尽，从而使您受益。

中断报告

如果您的应用支持实时中断报告和投票功能，强烈建议您使用 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 集成：

将 Firebase 添加到您的应用。
添加 App Check 库并初始化 App Check。
添加令牌提供方。此步骤会调用您选择的证明提供方来验证设备或应用的完整性。
初始化 Navigation 和 App Check API。
启用调试功能。这在开发期间或持续集成 (CI) 环境中非常有用。
在启用强制执行之前，请监控应用请求。这样，您就可以无缝强制执行 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()
            }
    }
}

使用 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 调试提供方，而不是生产证明提供方。

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

Groovy (build.gradle)

dependencies {
    implementation 'com.google.firebase:firebase-appcheck-debug'
}

将 App Check 配置为在调试 build 中使用调试提供方工厂：

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(),
    )
}

在模拟器或调试设备上启动应用。App Check 会将本地调试令牌输出到 logcat 输出中。
复制此调试令牌并在 Firebase 控制台中注册。如需了解详情，请参阅 Firebase App Check 调试提供方文档。

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

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

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

使用 App Check 保护 Navigation SDK for Android

为何要使用 App Check？

导航

中断报告

App Check 适合我吗？

实现步骤概览

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

将应用与 App Check 集成

前提条件和要求

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

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

Groovy (build.gradle)

Java

Kotlin

第 3 步：添加令牌提供方

Java

Kotlin

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

Java

Kotlin

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

Groovy (build.gradle)

Java

Kotlin

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