您可以使用 Firebase Remote Config 在應用程式中定義參數,並在雲端更新其值,藉此修改應用程式的外觀和行為,而無須發布應用程式更新。本指南會逐步引導您完成相關步驟,並提供一些程式碼範例,您可以從 firebase/quickstart-android GitHub 存放區複製或下載這些範例。
步驟 1:在應用程式中新增 Firebase 和遠端設定 SDK
如果您尚未將 Firebase 新增至 Android 專案,請先完成這項作業。
就 Remote Config 而言,您必須使用 Google Analytics,才能條件式指定應用程式執行個體的使用者屬性和目標對象。請確認您已在專案中啟用 Google Analytics。
在模組 (應用程式層級) 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") }
步驟 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 後端前正常運作,並在後端未設定任何預設值時使用預設值。
使用 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 主控台
在「Parameters」分頁中開啟 「Menu」,然後選取「Download default value」。
系統提示時,請啟用「.xml (適用於 Android)」,然後點選「下載檔案」。
使用
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 控制台中建立這些值。
- 在 Firebase 主控台中開啟專案。
- 從選單中選取 Remote Config 以查看 Remote Config 資訊主頁。
- 定義參數時,請使用與您在應用程式中定義的參數相同的名稱。您可以為每個參數設定預設值 (該參數最終會覆寫對應的應用程式內預設值),也可以設定條件值。詳情請參閱「Remote Config 參數與條件」。
步驟 6:擷取並啟用值
- 如要從 Remote Config 後端擷取參數值,請呼叫
fetch()
方法。系統會擷取您在後端設定的所有值,並儲存在 Remote Config 物件中。 如要讓應用程式使用擷取的參數值,請呼叫
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 支援即時更新。
在應用程式中使用
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); } });
下次發布新版 Remote Config 時,執行應用程式並監聽變更的裝置會呼叫
ConfigUpdateListener
。
調節
如果應用程式在短時間內擷取太多次,系統會限制擷取呼叫,而 SDK 會傳回 FirebaseRemoteConfigFetchThrottledException
。在 SDK 17.0.0 版之前,60 分鐘內的擷取要求上限為 5 次 (較新版本的限制較寬鬆)。
在應用程式開發期間,您可能會經常擷取及啟用設定 (每小時多次),以便在開發及測試應用程式時快速迭代。當伺服器上的設定更新時,即時 Remote Config 更新會自動略過快取。如要針對最多 10 位開發人員的專案進行快速迭代,您可以在應用程式中暫時設定 FirebaseRemoteConfigSettings
物件,並設定較低的最短擷取間距 (setMinimumFetchIntervalInSeconds
)。
Remote Config 的預設最小擷取間隔為 12 小時,也就是說,無論實際發出多少擷取呼叫,在 12 小時的時間範圍內,不會從後端擷取兩次以上的設定。具體來說,最小擷取間隔會依照以下順序決定:
fetch(long)
中的參數FirebaseRemoteConfigSettings.setMinimumFetchIntervalInSeconds(long)
中的參數- 預設值為 12 小時
如要將擷取間隔設為自訂值,請使用 FirebaseRemoteConfigSettings.Builder.setMinimumFetchIntervalInSeconds(long)
。
後續步驟
如果您尚未探索,請參閱 Remote Config 用途,並查看一些重要概念和進階策略說明文件,包括: