Firebase 遠端配置入門


您可以使用 Firebase Remote Config 在應用程式中定義參數並在雲端中更新其值，從而無需分發應用程式更新即可修改應用程式的外觀和行為。本指南將引導您完成入門步驟並提供一些範例程式碼，所有這些程式碼都可以從firebase/quickstart-android GitHub 儲存庫複製或下載。

步驟 1：將 Firebase 和遠端配置 SDK 新增至您的應用

  1. 如果您尚未將 Firebase 新增至您的 Android 專案中，請將其新增至您的 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:32.6.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 程式庫的相容版本。

    （替代方法）在不使用 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:21.6.0")
    implementation("com.google.firebase:firebase-analytics:21.5.0")
}
    正在尋找 Kotlin 特定的庫模組？從2023 年 10 月（Firebase BoM 32.5.0）開始，Kotlin 和 Java 開發人員都可以依賴主庫模組（有關詳細信息，請參閱有關此計劃的常見問題解答）。

步驟 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物件或儲存在應用程式的res/xml資料夾中的XML 資源檔案定義一組參數名稱和預設參數值。遠端配置快速入門範例應用程式使用XML 檔案來定義預設參數名稱和值。

    如果您已經配置了遠端配置後端參數值，則可以下載包含所有預設值的產生的 XML 檔案並將其儲存到應用程式的res/xml目錄中：

    休息

    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. 出現提示時，為 Android 啟用 .xml ，然後按一下「下載檔案」 。

  2. 使用setDefaultsAsync(int)將這些值新增至遠端配置對象，如下所示：

    Kotlin+KTX

    remoteConfig.setDefaultsAsync(R.xml.remote_config_defaults)

    Java

    mFirebaseRemoteConfig.setDefaultsAsync(R.xml.remote_config_defaults);

第 4 步：取得要在應用程式中使用的參數值

現在您可以從遠端配置物件取得參數值。如果您在後端設定值，取得它們，然後啟動它們，則這些值可供您的應用程式使用。否則，您將取得使用setDefaultsAsync(int)配置的應用程式內參數值。若要取得這些值，請呼叫下面列出的映射到應用程式所需的資料類型的方法，並提供參數鍵作為參數：

步驟5：在遠端配置後端設定參數值

使用 Firebase 控制台或遠端設定後端 API ，您可以建立新的伺服器端預設值，根據您所需的條件邏輯或使用者定位覆寫應用程式內值。本部分介紹了建立這些值的 Firebase 控制台步驟。

  1. 在Firebase 控制台中，開啟您的專案。
  2. 從選單中選擇遠端配置以查看遠端配置儀表板。
  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();
            }
        });

由於這些更新的參數值會影響應用程式的行為和外觀，因此您應該在確保使用者獲得流暢體驗的時間（例如使用者下次開啟應用程式時）啟動所獲取的值。如需更多資訊和範例，請參閱遠端設定載入策略。

步驟7：即時監聽更新

取得參數值後，您可以使用即時遠端配置來偵聽來自遠端配置後端的更新。當更新可用時，即時遠端設定會向連接的裝置發出訊號，並在您發布新的遠端設定版本後自動取得變更。

適用於 Android v21.3.0+ 的 Firebase SDK (Firebase BoM 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() {
            @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 個提取請求（較新版本有更寬鬆的限制）。

在應用程式開發期間，您可能希望非常頻繁地（每小時多次）獲取和啟動配置，以便您在開發和測試應用程式時快速迭代。當伺服器上的配置更新時，即時遠端配置更新會自動繞過快取。為了適應最多 10 名開發人員的專案的快速迭代，您可以在應用程式中臨時設定具有較低最小提取間隔 ( setMinimumFetchIntervalInSeconds ) 的FirebaseRemoteConfigSettings物件。

遠端配置的預設最小獲取間隔為 12 小時，這表示在 12 小時視窗內不會多次從後端取得配置，無論實際進行了多少次獲取呼叫。具體來說，最小獲取間隔是按以下順序決定：

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

若要將最小提取間隔設為自訂值，請使用FirebaseRemoteConfigSettings.Builder.setMinimumFetchIntervalInSeconds(long) 。

下一步

如果您還沒有，請探索遠端配置用例，並查看一些關鍵概念和高級策略文檔，包括：