Navigation SDK for Android | Google for Developers

Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

Firebase App Check 會封鎖來自正當應用程式以外來源的流量，保護應用程式對 Google 地圖平台發出的呼叫。方法是向Play Integrity 等驗證供應商要求評估應用程式或裝置的真實性。將應用程式與 App Check 整合後，即可防範惡意和未經授權的要求，進而避免帳單出現未經授權的費用。此外，App Check 也大幅提升車隊應用程式生態系統的即時中斷回報功能，讓所有使用您應用程式的駕駛人都能受益。詳情請參閱「中斷回報」。

為什麼要使用 App Check？

App Check 可保護 Android Navigation SDK 的兩個不同領域：主要導覽功能和中斷回報。

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，請按照下列步驟操作：

將 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) 會決定 App Check 權杖的效期，權杖過期前必須重新整理。您可以在 Firebase 控制台中，將這段時間設為 30 分鐘到 7 天。建議將時長設為 1 小時，做為安全基準，但 SDK 會在大約一半的 TTL 時長時，自動嘗試背景重新整理。如需逐步操作說明，請參閱 Firebase App Check 說明文件。

將應用程式與 App Check 整合

必要條件和規定

已安裝 Android 版 Navigation SDK 7.9 以上版本的應用程式。
應用程式的 SHA-256 憑證指紋。
應用程式的套件名稱。
您必須是 Google Cloud 控制台中應用程式的擁有者。
Google Cloud 控制台中的應用程式專案 ID。

步驟 1：將 Firebase 新增至應用程式

按照 Firebase 開發人員說明文件中的操作說明，將 Firebase 新增至應用程式。將 google-services.json 檔案新增至專案的應用程式層級目錄。

步驟 2：新增 App Check 程式庫並初始化 App Check

在應用程式的 build.gradle 檔案中新增 App Check 依附元件：

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 類別或主要活動中初始化 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 介面的實作項目。這個供應器會從 Firebase App Check 服務非同步擷取 App Check 權杖，並使用 MapsAppCheckTokenCallback 將權杖傳遞至 Android 網路堆疊的 Navigation SDK：

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() 初始化 Android 版 Navigation SDK，並註冊您的統一權杖供應商執行個體：

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：啟用偵錯功能 (選用)

對 Android 適用的 Navigation SDK 強制執行 App Check 後，應用程式中依附於 Android 適用的 Navigation SDK 的功能，將無法在模擬器或持續整合 (CI) 環境中執行，因為這些環境不符合有效裝置的資格。如要在開發和測試期間於這些環境中執行應用程式，您需要建立應用程式的偵錯版本，並使用 App Check 偵錯提供者，而非實際運作中的認證提供者。

在應用程式的 build.gradle 檔案中新增偵錯供應器依附元件：
Groovy (build.gradle)
```
dependencies {
    implementation 'com.google.firebase:firebase-appcheck-debug'
}
```

在偵錯版本中，設定 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(),
    )
}

在模擬器或偵錯裝置上啟動應用程式。App Check 會將本機偵錯權杖列印至 logcat 輸出內容。
請複製這個偵錯權杖，並在 Firebase 控制台中註冊。詳情請參閱 Firebase App Check 偵錯供應商說明文件。

步驟 6：監控應用程式要求並決定強制執行方式

啟用強制執行前，請先監控應用程式要求，確保不會中斷正當使用者的作業。

前往 Firebase 控制台的 App Check 指標畫面，查看已驗證和未驗證流量的百分比。
確認大部分流量都經過驗證，且正當使用者已更新至含有 App Check 實作的應用程式版本後，即可啟用強制執行。
強制執行後，App Check 會拒絕所有不具備有效 App Check 權杖的流量。

使用 App Check 保護 Android 版 Navigation SDK

為什麼要使用 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：監控應用程式要求並決定強制執行方式