您可以使用 Firebase 遠端設定在應用程式中定義參數,並在雲端更新參數的值,這樣就能修改應用程式的外觀和行為,而不必發布應用程式更新。本指南將引導您逐步完成設定,並提供部分程式碼範例,您可以在 firebase/quickstart-android GitHub 存放區複製或下載這些程式碼範例。
步驟 1:在應用程式中加入 Firebase 和遠端設定 SDK
如果您尚未將 Firebase 新增至 Android 專案,請先完成這項作業。
就遠端設定而言,Google Analytics (分析) 必須指定對使用者屬性和目標對象應用程式執行個體的條件式指定。請確認您已在專案中啟用 Google Analytics (分析)。
在模組 (應用程式層級) 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.8.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 程式庫版本。
(替代方法) 新增 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:21.6.3") implementation("com.google.firebase:firebase-analytics:21.6.2") }
步驟 2:取得遠端設定單例模式物件
取得遠端設定物件執行個體,並設定擷取間隔下限以允許經常重新整理:
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:設定應用程式內預設參數值
您可以在遠端設定物件中設定應用程式內預設參數值,讓應用程式在連線至遠端設定後端前可正常運作,如此如果後端未設定任何預設值,即可使用預設值。
請使用儲存在應用程式
res/xml
資料夾中的 Map 物件或 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 控制台
使用
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 控制台步驟。
- 在 Firebase 控制台開啟專案。
- 從選單中選取「Remote Config」,查看遠端設定資訊主頁。
- 定義與您在應用程式中定義的參數名稱相同的參數。您可以為每個參數設定預設值 (最終覆寫對應的應用程式內預設值),此外也可以設定條件值。詳情請參閱遠端設定參數與條件。
步驟 6:擷取並啟用值
- 如要從遠端設定後端擷取參數值,請呼叫
fetch()
方法。系統會擷取您在後端設定的任何值,並儲存在遠端設定物件中。 如要讓應用程式取得擷取的參數值,請呼叫
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 版 Firebase SDK 21.3.0 以上版本 (Firebase BoM 31.2.4 以上版本) 支援即時更新。
在應用程式中使用
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); } }); 下次發布新版本的遠端設定時,執行應用程式並監聽變更的裝置會呼叫
ConfigUpdateListener
。
調節
如果應用程式在短時間內擷取太多次,擷取呼叫就會受到限制,且 SDK 會傳回 FirebaseRemoteConfigFetchThrottledException
。在 SDK 17.0.0 以下版本之前,60 分鐘內最多只能發出 5 個擷取要求 (較新的版本較寬鬆)。
在應用程式開發期間,您可能會想要頻繁 (每小時多次) 擷取及啟用設定,以便在開發及測試應用程式時迅速進行疊代。當伺服器上的設定更新時,即時遠端設定更新會自動略過快取。如想因應最多有 10 名開發人員的專案快速疊代,您可以在應用程式中暫時設定 FirebaseRemoteConfigSettings
物件,並設定最短擷取時間間隔 (setMinimumFetchIntervalInSeconds
)。
遠端設定的預設擷取時間間隔為 12 小時。這表示無論實際發出多少擷取呼叫,設定在 12 小時內都不會從後端多次擷取設定。具體來說,最小擷取間隔順序如下:
fetch(long)
中的參數FirebaseRemoteConfigSettings.setMinimumFetchIntervalInSeconds(long)
中的參數- 預設值是 12 小時
如要將最短擷取間隔設為自訂值,請使用 FirebaseRemoteConfigSettings.Builder.setMinimumFetchIntervalInSeconds(long)
。
後續步驟
如果您尚未瞭解遠端設定的用途,請先查看一些重要概念和進階策略說明文件,包括: