使用 App Check 保護 Navigation SDK for Android

Firebase App Check 會封鎖來自非正當應用程式的流量，保護從應用程式傳送至 Google Maps Platform 的呼叫。方法是向 Play Integrity 等認證供應商要求評估應用程式或裝置的真實性。將應用程式與 App Check 整合，即可防範惡意和未經授權的要求，進而避免帳單出現未授權扣款。App Check 也能大幅改善車隊應用程式生態系統中的即時中斷回報功能，讓所有使用應用程式的司機受惠。詳情請參閱「中斷回報」。

重要事項：App Check 預設不會封鎖未經授權的流量。驗證應用程式指標後，您必須手動啟用強制執行 (請參閱步驟 6：監控應用程式要求並決定是否強制執行)。

使用 App Check 的好處

App Check 會保護 Navigation SDK for Android 的兩個不同部分：主要導航功能和中斷回報。

導覽

App Check 可協助封鎖來自惡意或未授權來源的主要 Navigation SDK for Android 要求。這項措施可直接保護您的專案，避免帳單詐欺和配額用盡。

回報服務中斷

如果應用程式支援即時服務中斷回報和投票功能，強烈建議使用 App Check。啟用 App Check 可確保駕駛人取得最準確的路線，並考量所有即時回饋。

App Check 對報表的重要性：

• 封閉道路的信任門檻較高：道路封閉等影響路線的事件，可能會大幅改變所有駕駛人的路線行為。為避免地圖遭到破壞、出現垃圾內容或不實回報，Google 的道路封閉中斷審查基礎架構會依賴強大的裝置和應用程式完整性信號。
• App Check 如何驗證回報：Android 版 Navigation SDK 傳送的使用者回報和投票包含 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) 決定 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

在應用程式的 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：新增權杖供應商

注意：如果應用程式也使用其他支援 App Check 的 Google Maps Platform SDK (例如 Places SDK)，您可以使用相同的 Firebase App Check 設定，但必須為每個 SDK 實作及註冊專屬的權杖供應器介面。

實作 MapsAppCheckTokenProvider 介面。這個供應器會以非同步方式，從 Firebase App Check 擷取 App Check 權杖，並使用 MapsAppCheckTokenCallback 將權杖傳遞至 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

初始化 Navigation SDK for Android，並使用 MapsApiSettings.setAppCheckTokenProvider() 註冊統一權杖供應器執行個體：

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) 環境中執行，因為這些環境不符合有效裝置的資格。如要在開發和測試期間，於這些環境中執行應用程式，您必須建立應用程式的偵錯版本，並使用 App Check 偵錯服務，而非正式版認證服務。

1. 在應用程式的 build.gradle 檔案中，新增偵錯服務依附元件：

   Groovy (build.gradle)

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

2. 設定 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 權杖的流量。