開始使用 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 時，您必須新增 Firebase SDK 整合 Google Analytics 和 Google Analytics 資源

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

   在尋找 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. 使用 Map 物件或 XML 資源檔案 儲存在應用程式的 res/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. 在參數中 開啟 「選單」， 選取「下載預設值」。

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

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_app_id google-services.json 檔案，請參閱 處理 JSON 檔案。

步驟 7：即時監聽更新

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

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

重要事項：即時遠端設定也需要 Firebase 遠端設定 系統應該已為您啟用 Realtime API。如要進行驗證，請開啟 Google Cloud 控制台 選取您的專案，然後開啟「APIs and Services」(API 和服務) 頁面。API 應該 目前會顯示為已啟用如果找不到或尚未啟用，請按一下「啟用 API，然後」 「服務」，搜尋 Firebase 遠端設定 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 人的小型開發團隊一起測試應用程式 不太可能達到每小時服務端的配額限制。 不過，如果您將應用程式 擷取時間間隔極低的測試使用者 可能會達到這個配額

後續步驟

如果您尚未探索遠端設定，請先探索 用途，以及 重要概念和進階策略說明文件，包括：

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