開始使用 Firebase 遠端設定


您可以使用 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 開發人員皆可 依附於主要程式庫模組 (詳情請參閱 這項計畫的常見問題)。

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

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

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

Kotlin+KTX

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

Java

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

單例模式物件是用來儲存應用程式內的預設參數值 更新過的參數值,並且控制系統擷取到 可用的更新

在開發期間,建議您將最小擷取間隔設為較低。詳情請參閱「節流」一節。

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

您可以在 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) 設定的應用程式內參數值。如要取得這些值,請呼叫下列對應至資料類型的方法 ,並提供參數鍵做為引數:

步驟 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();
                }
            });

由於這些更新的參數值會影響應用程式的行為和外觀,因此您應在確保使用者享有順暢體驗的時間點啟用擷取的值,例如使用者下次開啟應用程式時。如需更多資訊和範例,請參閱「遠端設定載入策略」。

步驟 7:即時監聽更新

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

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

  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 次 (較新版本的限制較寬鬆)。

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

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

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

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

後續步驟

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