開始使用 Firebase 遠端設定

iOS+ Android 網頁版 Flutter Unity C++

重要事項： 本節說明設定Remote Config 行動和網路用戶端如果是伺服器環境，請參閱 在伺服器環境使用 Remote Config。

您可以使用 Firebase Remote Config 在應用程式中定義參數，並在雲端更新其值，藉此修改應用程式的外觀和行為，而無須發布應用程式更新。本指南將逐步引導您踏出第一步，並提供一些 您可以複製或下載 firebase/quickstart-android GitHub 存放區。

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

1. 如果您尚未將 Firebase 新增至 Android 專案，請新增 Firebase。

2. 就 Remote Config 而言，您必須使用 Google Analytics，才能條件式指定應用程式執行個體的使用者屬性和目標對象。請確認您已在專案中啟用 Google Analytics。

3. 在模組 (應用程式層級) Gradle 檔案 (通常是 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle) 中，加入 Android 的 Remote Config 程式庫依附元件。建議您使用 Firebase Android BoM敬上 管理程式庫版本管理

   此外，設定 Analytics 時，您需要新增 Firebase SDK 給您的應用程式 Google Analytics

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:33.4.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.1.2")
   }
   

   在尋找 Kotlin 專用的程式庫模組嗎？距離開始還有 2023 年 10 月 (Firebase BoM 32.5.0)，Kotlin 和 Java 開發人員皆可 依附於主要程式庫模組 (詳情請參閱 這項計畫的常見問題)。

，瞭解如何調查及移除這項存取權。

注意： 由於 Android SDK 具有 Remote Config REST 的依附元件 API，請務必「不要」停用這個預設啟用的 API 通常都處於相同狀態

步驟 2：取得 Remote Config 單例模式物件

取得 Remote Config 物件例項，並設定最短擷取間距，才能經常更新：

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：設定應用程式內的預設參數值

您可以在 Remote Config 物件中設定應用程式內的預設參數值，讓應用程式在連線至 Remote Config 後端前正常運作，並在後端未設定任何預設值時使用預設值。

重要事項：請勿在 Remote Config 參數鍵或值中儲存機密資料。Remote Config 資料會在傳輸過程中加密，但使用者可以存取 只要是可供應用程式的可用預設或擷取的 Remote Config 參數 用戶端應用程式執行個體。

1. 使用 Map 物件或 XML 資源檔案 儲存在應用程式的 res/xml 資料夾中。Remote Config 快速入門範例應用程式會使用 XML 檔案定義預設參數名稱和值。

   如果已設定 Remote Config 後端參數值， 您可以下載產生的 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. 在「參數」分頁中，開啟 「選單」，然後選取「下載預設值」。

   2. 系統提示時，啟用「.xml for Android」，然後按一下 下載檔案。

2. 使用以下程式碼將這些值新增至 Remote Config 物件 setDefaultsAsync(int)、 如下所示：

   Kotlin+KTX

   remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

   Java

   mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

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

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

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

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

您可以使用 Firebase 控制台或 Remote Config 後端 API，建立新的伺服器端預設值，根據所需的條件邏輯或使用者指定值覆寫應用程式內的值。這個區段 說明透過 Firebase 控制台建立這些值的步驟。

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

步驟 6：擷取並啟用值

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

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

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

   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 字串資源新增至應用程式，讓 Remote Config 可以 初始化。google-services Gradle 外掛程式通常會自動新增這個值，但您可以在從 Firebase 控制台下載的 google-services.json 檔案中找到適當的值。如要進一步瞭解如何從 google-services.json 檔案取得 google_app_id 值，請參閱「處理 JSON 檔案」一文。

步驟 7：即時監聽更新

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

Android v21.3.0 以上版本 (Firebase BoM) 的 Firebase SDK 支援即時更新 v31.2.4+)。

重要事項：即時 Remote Config 也需要 Firebase Remote Config Realtime API，而您應該已啟用該 API。如要確認，請開啟 Google Cloud 控制台，選取專案，然後開啟「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<Boolean>() {
               @Override
               public void onComplete(@NonNull Task<Boolean> task) {
                   displayWelcomeMessage();
               }
           });
       }
       @Override
       public void onError(FirebaseRemoteConfigException error) {
           Log.w(TAG, "Config update error with code: " + error.getCode(), error);
       }
   });
   

2. 下次發布新版 Remote Config 時，執行應用程式並監聽變更的裝置就會呼叫 ConfigUpdateListener。

調節

如果應用程式在短時間內擷取太多次，系統將擷取呼叫 並導致 SDK 傳回限制值 FirebaseRemoteConfigFetchThrottledException。在 SDK 17.0.0 版之前，60 分鐘內的擷取要求上限為 5 次 (較新版本的限制較寬鬆)。

提示：自 Android SDK 21.3.0 以上版本 (Firebase BoM 31.3.0 以上版本) 起， 您可以使用即時的 Remote Config，以便自動從 Remote Config 後端發布後立即執行，且不會達到任何下限 擷取間隔設定。詳情請參閱「即時接收更新」。

在應用程式開發期間，您可能會經常擷取及啟用設定 (每小時多次)，以便在開發及測試應用程式時快速迭代。當伺服器上的設定更新時，即時 Remote Config 更新會自動略過快取。為了適應快速疊代 某個專案最多可有 10 位開發人員，您可以暫時設定一個 FirebaseRemoteConfigSettings 物件的擷取間隔下限較低 (setMinimumFetchIntervalInSeconds)。

Remote Config 的預設擷取間隔下限為 12 小時， 這代表在 12 小時內，系統不會多次從後端擷取設定 則無論實際發出多少擷取呼叫。具體來說，最小擷取間隔會依照以下順序決定：

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

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

請注意，這項設定僅供開發之用， 以及正式環境如果您是 只是與 10 人的小型開發團隊一起測試應用程式 不太可能達到每小時服務端的配額限制。 不過，如果您將應用程式 擷取時間間隔極低的測試使用者 可能會達到這個配額

後續步驟

如果尚未體驗，請前往Remote Config 用途，以及 重要概念和進階策略說明文件，包括：

• 管理 Remote Config 範本版本
• 設定載入策略