開始使用 Firebase 遠端設定

iOS+ Android 網頁版 Flutter Unity C++

重要事項： 本節說明如何透過行動和網路用戶端設定遠端設定。如果是伺服器環境，請參閱「在伺服器環境中使用遠端設定」一文。

您可以使用 Firebase 遠端設定在應用程式中定義參數，並在雲端更新參數的值，這樣就能修改應用程式的外觀和行為，而不必發布應用程式更新。本指南將引導您逐步完成設定，並提供部分程式碼範例，您可以在 firebase/quickstart-android GitHub 存放區複製或下載這些程式碼範例。

步驟 1：在應用程式中加入 Firebase 和遠端設定 SDK

1. 如果您尚未將 Firebase 新增至 Android 專案，請先完成這項作業。

2. 就遠端設定而言，Google Analytics (分析) 必須指定對使用者屬性和目標對象應用程式執行個體的條件式指定。請確認您已在專案中啟用 Google Analytics (分析)。

3. 在模組 (應用程式層級) Gradle 檔案 (通常是 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle) 中，新增 Android 遠端設定程式庫的依附元件。建議您使用 Firebase Android BoM 來控管程式庫版本管理。

   此外，在設定 Analytics (分析) 時，必須將 Google Analytics (分析) 專用 Firebase SDK 加進應用程式。

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:32.8.1"))
   
       // Add the dependencies for the Remote Config and Analytics libraries
       // When using the BoM, you don't specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-config")
       implementation("com.google.firebase:firebase-analytics")
   }
   

   如果使用 Firebase Android BoM，應用程式就會一律使用相容的 Firebase Android 程式庫版本。

   (替代方法) 新增 Firebase 程式庫依附元件，「不必」使用 BoM

   如果選擇不使用 Firebase BoM，請務必在依附元件行中指定各個 Firebase 程式庫版本。

   請注意，如果在應用程式中使用多個 Firebase 程式庫，強烈建議您使用 BoM 管理程式庫版本，確保所有版本都相容。

   dependencies {
       // Add the dependencies for the Remote Config and Analytics libraries
       // When NOT using the BoM, you must specify versions in Firebase library dependencies
       implementation("com.google.firebase:firebase-config:21.6.3")
       implementation("com.google.firebase:firebase-analytics:21.6.2")
   }
   

   在尋找 Kotlin 專用的程式庫模組嗎？自 2023 年 10 月 (Firebase BoM 32.5.0) 起，Kotlin 和 Java 開發人員都可以依賴主程式庫模組 (詳情請參閱這項計畫的常見問題)。

注意： 由於 Android SDK 在遠端設定 REST API 中具有依附元件，因此請務必「不要」停用該 API (在一般專案中預設啟用的 API)。

步驟 2：取得遠端設定單例模式物件

取得遠端設定物件執行個體，並設定擷取間隔下限以允許經常重新整理：

Kotlin+KTX

val remoteConfig: FirebaseRemoteConfig = Firebase.remoteConfig
val configSettings = remoteConfigSettings {
    minimumFetchIntervalInSeconds = 3600
}
remoteConfig.setConfigSettingsAsync(configSettings)
MainActivity.kt

Java

FirebaseRemoteConfig mFirebaseRemoteConfig = FirebaseRemoteConfig.getInstance();
FirebaseRemoteConfigSettings configSettings = new FirebaseRemoteConfigSettings.Builder()
        .setMinimumFetchIntervalInSeconds(3600)
        .build();
mFirebaseRemoteConfig.setConfigSettingsAsync(configSettings);
MainActivity.java

單例模式物件是用來儲存應用程式內的預設參數值、從後端擷取更新的參數值，並控制擷取值提供給應用程式的時機。

在開發期間，建議您設定相對較低的擷取時間間隔。詳情請參閱「節流」。

步驟 3：設定應用程式內預設參數值

您可以在遠端設定物件中設定應用程式內預設參數值，讓應用程式在連線至遠端設定後端前可正常運作，如此如果後端未設定任何預設值，即可使用預設值。

重要事項： 請勿將機密資料儲存在遠端設定參數鍵或值中。遠端設定資料會在傳輸過程中加密，但使用者可以存取任何預設或已擷取的遠端設定參數，且提供給用戶端應用程式執行個體使用。

1. 請使用儲存在應用程式 res/xml 資料夾中的 Map 物件或 XML 資源檔案，定義一組參數名稱和預設參數值。遠端設定快速入門導覽課程範例應用程式使用 XML 檔案定義預設參數名稱和值。

   如果您已設定遠端設定後端參數值，可以下載包含所有預設值的 XML 檔案，並將其儲存到應用程式的 res/xml 目錄：

   REST

   curl --compressed -D headers -H "Authorization: Bearer token" -X GET https://firebaseremoteconfig.googleapis.com/v1/projects/my-project-id/remoteConfig:downloadDefaults?format=XML -o remote_config_defaults.xml
   

   Firebase 控制台

   1. 在「Parameters」分頁中，開啟 「Menu」，然後選取「Download default value」。

   2. 系統提示時，啟用「.xml for Android」，然後點選「Download file」。

2. 使用 setDefaultsAsync(int) 將這些值新增至遠端設定物件，如下所示：

   Kotlin+KTX

   remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

   Java

   mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

步驟 4：取得要用於應用程式的參數值

您現在可以透過遠端設定物件取得參數值。如果您在後端設定值，請擷取並啟用這些值，您的應用程式就能使用這些值。否則，則會使用 setDefaultsAsync(int) 設定應用程式內參數值。如要取得這些值，請呼叫下列方法，該方法對應至應用程式預期的資料類型，並提供參數鍵做為引數：

• getBoolean()
• getDouble()
• getLong()
• getString()

步驟 5：在遠端設定後端設定參數值

使用 Firebase 主控台或遠端設定後端 API 即可建立新的伺服器端預設值，根據您想要的條件邏輯或使用者指定目標來覆寫應用程式內的值。本節說明建立這些值的 Firebase 控制台步驟。

1. 在 Firebase 控制台開啟專案。
2. 從選單中選取「Remote Config」，查看遠端設定資訊主頁。
3. 定義與您在應用程式中定義的參數名稱相同的參數。您可以為每個參數設定預設值 (最終覆寫對應的應用程式內預設值)，此外也可以設定條件值。詳情請參閱遠端設定參數與條件。

步驟 6：擷取並啟用值

1. 如要從遠端設定後端擷取參數值，請呼叫 fetch() 方法。系統會擷取您在後端設定的任何值，並儲存在遠端設定物件中。

2. 如要讓應用程式取得擷取的參數值，請呼叫 activate() 方法。

   如果您想在單一呼叫中擷取及啟用值，可以使用 fetchAndActivate() 要求從遠端設定後端擷取值，並提供給應用程式：

   Kotlin+KTX

   remoteConfig.fetchAndActivate()
       .addOnCompleteListener(this) { task ->
           if (task.isSuccessful) {
               val updated = task.result
               Log.d(TAG, "Config params updated: $updated")
               Toast.makeText(
                   this,
                   "Fetch and activate succeeded",
                   Toast.LENGTH_SHORT,
               ).show()
           } else {
               Toast.makeText(
                   this,
                   "Fetch failed",
                   Toast.LENGTH_SHORT,
               ).show()
           }
           displayWelcomeMessage()
       }

   Java

   mFirebaseRemoteConfig.fetchAndActivate()
           .addOnCompleteListener(this, new OnCompleteListener<Boolean>() {
               @Override
               public void onComplete(@NonNull Task<Boolean> task) {
                   if (task.isSuccessful()) {
                       boolean updated = task.getResult();
                       Log.d(TAG, "Config params updated: " + updated);
                       Toast.makeText(MainActivity.this, "Fetch and activate succeeded",
                               Toast.LENGTH_SHORT).show();
   
                   } else {
                       Toast.makeText(MainActivity.this, "Fetch failed",
                               Toast.LENGTH_SHORT).show();
                   }
                   displayWelcomeMessage();
               }
           });

這些更新後的參數值會影響應用程式的行為與外觀，因此建議您一次啟用擷取的值，以確保使用者享有流暢的使用體驗，例如使用者下次開啟您的應用程式時。詳情請參閱遠端設定載入策略。

注意： 如果您的應用程式不是使用 Gradle 進行建構，您必須手動將正確的 google_app_id 字串資源新增至應用程式，以便遠端設定進行初始化。google-services Gradle 外掛程式通常會自動新增此屬性，但您可以在從 Firebase 控制台下載的 google-services.json 檔案中找到適當的值。如要進一步瞭解如何從 google-services.json 檔案取得 google_app_id 值，請參閱「處理 JSON 檔案」一文。

步驟 7：聽取即時動態

擷取參數值後，您可以使用即時遠端設定監聽來自遠端設定後端的更新。有可用的更新時，即時遠端設定會向已連結的裝置發出信號，並在您發布新的遠端設定版本後自動擷取變更。

Android 版 Firebase SDK 21.3.0 以上版本 (Firebase BoM 31.2.4 以上版本) 支援即時更新。

重要事項：如要使用即時遠端設定功能，您也必須先啟用 Firebase 遠端設定 Realtime API。如要確認，請開啟 Google Cloud 控制台並選取您的專案，然後開啟「API 和服務」頁面。API 應會顯示為已啟用。如果缺少這個 API 或尚未啟用，請按一下「啟用 API 和服務」，搜尋「Firebase Remote Config Realtime API」並啟用該 API。

1. 在應用程式中使用 addOnConfigUpdateListener()，開始監聽更新，並自動擷取任何新的參數值。導入 onUpdate() 回呼以啟用更新後的設定。

   Kotlin+KTX

   remoteConfig.addOnConfigUpdateListener(object : ConfigUpdateListener {
       override fun onUpdate(configUpdate : ConfigUpdate) {
          Log.d(TAG, "Updated keys: " + configUpdate.updatedKeys);
   
          if (configUpdate.updatedKeys.contains("welcome_message")) {
              remoteConfig.activate().addOnCompleteListener {
                  displayWelcomeMessage()
              }
          }
       }
   
       override fun onError(error : FirebaseRemoteConfigException) {
           Log.w(TAG, "Config update error with code: " + error.code, error)
       }
   })
   

   Java

   mFirebaseRemoteConfig.addOnConfigUpdateListener(new ConfigUpdateListener() {
       @Override
       public void onUpdate(ConfigUpdate configUpdate) {
           Log.d(TAG, "Updated keys: " + configUpdate.getUpdatedKeys());
   
           mFirebaseRemoteConfig.activate().addOnCompleteListener(new OnCompleteListener() {
               @Override
               public void onComplete(@NonNull Task task) {
                   displayWelcomeMessage();
               }
           });
       }
   
       @Override
       public void onError(FirebaseRemoteConfigException error) {
           Log.w(TAG, "Config update error with code: " + error.getCode(), error);
       }
   });
   

2. 下次發布新版本的遠端設定時，執行應用程式並監聽變更的裝置會呼叫 ConfigUpdateListener。

調節

如果應用程式在短時間內擷取太多次，擷取呼叫就會受到限制，且 SDK 會傳回 FirebaseRemoteConfigFetchThrottledException。在 SDK 17.0.0 以下版本之前，60 分鐘內最多只能發出 5 個擷取要求 (較新的版本較寬鬆)。

提示：從 Android SDK v21.3.0 以上版本 (Firebase BoM v31.3.0 以上版本) 開始，您可以使用即時遠端設定，在更新發布後從遠端設定後端自動擷取更新後的參數值，略過任何最短擷取間隔設定。詳情請參閱「監聽即時更新」。

在應用程式開發期間，您可能會想要頻繁 (每小時多次) 擷取及啟用設定，以便在開發及測試應用程式時迅速進行疊代。當伺服器上的設定更新時，即時遠端設定更新會自動略過快取。如想因應最多有 10 名開發人員的專案快速疊代，您可以在應用程式中暫時設定 FirebaseRemoteConfigSettings 物件，並設定最短擷取時間間隔 (setMinimumFetchIntervalInSeconds)。

遠端設定的預設擷取時間間隔為 12 小時。這表示無論實際發出多少擷取呼叫，設定在 12 小時內都不會從後端多次擷取設定。具體來說，最小擷取間隔順序如下：

1. fetch(long) 中的參數
2. FirebaseRemoteConfigSettings.setMinimumFetchIntervalInSeconds(long) 中的參數
3. 預設值是 12 小時

如要將最短擷取間隔設為自訂值，請使用 FirebaseRemoteConfigSettings.Builder.setMinimumFetchIntervalInSeconds(long)。

請注意，這項設定僅適用於開發用途，不適用於在實際工作環境中執行的應用程式。如果您只是想請一小群開發團隊來測試應用程式，就不太可能達到每小時的服務端配額限制。但是，如果您將應用程式推送給數千名測試使用者，但擷取時間間隔過低，應用程式就可能會達到這個配額。

後續步驟

如果您尚未瞭解遠端設定的用途，請先查看一些重要概念和進階策略說明文件，包括：

• 管理遠端設定範本版本
• 設定載入策略