開始使用 Firebase 遠端設定


您可以使用 Firebase Remote Config 在應用程式中定義參數,並在雲端更新其值,藉此修改應用程式的外觀和行為,而無須發布應用程式更新。本指南會逐步引導您完成相關步驟,並提供一些程式碼範例,您可以從 firebase/quickstart-android GitHub 存放區複製或下載這些範例。

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

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

  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 時,您需要將 Google Analytics 的 Firebase SDK 新增至應用程式。

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:33.5.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 程式庫版本。

    (替代做法)  使用 BoM 新增 Firebase 程式庫依附元件

    如果選擇不使用 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.1")
        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 物件或儲存在應用程式 res/xml 資料夾中的 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. 「Parameters」分頁中開啟「Menu」,然後選取「Download default value」

    2. 系統提示時,請啟用「.xml (適用於 Android)」,然後點選「下載檔案」

  2. 使用 setDefaultsAsync(int) 將這些值新增至 Remote Config 物件,如下所示:

    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 31.2.4 以上版本) 的 Firebase SDK 支援即時更新。

  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 用途,並查看一些重要概念和進階策略說明文件,包括: