使用 App Check 保護 API 金鑰

Firebase App Check 會封鎖來自非正當應用程式的流量，保護應用程式對 Google Maps Platform 的呼叫。方法是檢查 reCAPTCHA Enterprise 等認證供應商提供的權杖。將應用程式與 App Check 整合，有助於防範惡意要求，避免因未經授權的 API 呼叫而產生費用。

App Check 適合我嗎？

在大多數情況下，我們建議使用 App Check，但在下列情況下，您不需要或不支援 App Check：

• 您使用的是原始 Places SDK。App Check 僅支援 Places SDK (新版)。
• 私人或實驗性應用程式。如果應用程式不開放公開存取，就不需要 App Check。
• 如果應用程式只用於伺服器對伺服器通訊，則不需要 App Check。不過，如果與 GMP 通訊的伺服器是由公開用戶端 (例如行動應用程式) 使用，建議使用 App Check 保護該伺服器，而非 GMP。

導入步驟總覽

概括來說，將應用程式與 App Check 整合的步驟如下：

1. 將 Firebase 新增至應用程式。
2. 新增並初始化 App Check 程式庫。
3. 將權杖供應器新增至應用程式。
4. 初始化 Places 和 App Check API。
5. 啟用偵錯功能。
6. 監控應用程式要求，並決定是否強制執行。

整合 App Check 後，您就能在 Firebase 控制台查看後端流量指標。這些指標會根據要求是否附帶有效的 App Check 權杖，提供要求的詳細資料。詳情請參閱 Firebase App Check 說明文件。

確認大多數要求來自合法來源，且使用者已更新至最新版應用程式 (包含 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 整合

注意：如要更快取得協助，如需這項程序中 Firebase 相關部分的支援，請參閱 Firebase 支援。如需 Google Places API 相關支援，請參閱 Google Maps Platform 支援。

必要條件和規定

• 應用程式已載入最新每週或每季版本的 Maps JS API、Core 和 Places 程式庫。
• 已啟用 Maps JS 和 Places API (新版) 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 網站金鑰和密鑰，才能在 Cloud 控制台啟用 API。如需更多資訊和操作說明，請參閱 reCAPTCHA v3 說明文件。

步驟 3：載入 Maps JS API 程式庫

1. 載入核心、Maps 和 Places 程式庫，如以下程式碼片段所示。如需更多資訊和操作說明，請參閱 Maps JavaScript API Place 類別說明文件。

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

步驟 4：初始化 Places 和 App Check API

1. 使用 Firebase 控制台提供的設定，初始化 App Check。
   • reCAPTCHA v3 操作說明。
   • reCAPTCHA Enterprise 操作說明。
2. 確保向 Maps JS API 提出的要求附有 App Check 權杖：

     async function init() {
       const {Settings} = await google.maps.importLibrary('core');
       const {Map} = await google.maps.importLibrary('maps');
       const {Place} = await google.maps.importLibrary('places');
     
       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);
     
       // Make a Places JS request
       const place = new Place({id: 'ChIJN5Nz71W3j4ARhx5bwpTQEGg'});
       await place.fetchFields({fields: ['*']});
     
       // Load a map
       map = new Map(document.getElementById("map"), {
         center: { lat: 37.4161493, lng: -122.0812166 },
         zoom: 8,
       });
     }  
     

步驟 5：啟用偵錯功能 (選用)

如要在本機開發及測試應用程式，或在持續整合 (CI) 環境中執行應用程式，可以建立應用程式的偵錯版本，並使用偵錯密鑰取得有效的 App Check 權杖。這樣一來，您就不必在偵錯版本中使用實際的認證供應商。

在本機測試應用程式的步驟如下：

• 啟用偵錯服務，以便進行開發。
• 您會從 SDK 的偵錯記錄檔中，收到自動產生的隨機 UUID4 (在 App Check 說明文件中稱為「偵錯權杖」)。將這個權杖新增至 Firebase 控制台。
• 如需更多資訊和操作說明，請參閱 App Check 說明文件。

如要在 CI 環境中執行應用程式，請按照下列步驟操作：

• 從 Firebase 控制台產生隨機 UUID4。
• 將 UUID4 新增為偵錯權杖，然後複製到密鑰儲存庫，CI 測試每次執行時都會存取該儲存庫。
• 如需更多資訊和操作說明，請參閱 App Check 說明文件。

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

在開始強制執行之前，請務必確認不會干擾應用程式的合法使用者。為此，請前往 App Check 指標畫面，查看應用程式流量中已驗證、過時或不合法的百分比。確認大部分流量都已通過驗證後，即可啟用強制執行。

如需更多資訊和操作說明，請參閱 Firebase App Check 說明文件。

強制執行 App Check 前，請確認雲端專案中的所有 Web 服務呼叫都使用 OAuth。