開始使用 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:33.1.0"))
   
       // 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:22.0.0")
       implementation("com.google.firebase:firebase-analytics:22.0.1")
   }
   

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

注意： 由於 Android SDK 對遠端設定 REST 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：即時監聽更新

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

Firebase SDK for Android 21.3.0 以上版本 (Firebase BoM v31.2.4 以上版本) 支援即時更新功能。

重要事項：系統應該已為您啟用 Firebase 遠端設定 Realtime API，才能使用即時遠端設定功能。如要進行驗證，請開啟 Google Cloud 控制台並選取專案，然後開啟「API 和服務」頁面。API 應會顯示為已啟用。如果缺少或未啟用該 API，請按一下「啟用 API 和服務」，搜尋並啟用「Firebase Remote Config Realtime 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)。

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

後續步驟

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

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