您可以使用 Firebase Remote Config 在應用程式中定義參數,並在雲端更新參數值,不必發布應用程式更新,就能修改應用程式的外觀和行為。
Remote Config 程式庫用於儲存應用程式內預設參數值、從 Remote Config 後端擷取更新的參數值,以及控管擷取的值何時可供應用程式使用。詳情請參閱「遠端設定載入策略」。
本指南將逐步說明如何開始使用,並提供一些程式碼範例,您都可以從 firebase/quickstart-unity GitHub 存放區複製或下載。
步驟 1:在應用程式中新增 Remote Config
如要使用 Remote Config, 請先完成下列步驟:
註冊 Unity 專案並設定使用 Firebase。
如果 Unity 專案已使用 Firebase,則專案已註冊並設定 Firebase。
如果沒有 Unity 專案,可以下載範例應用程式。
將 Firebase Unity SDK (具體來說是
FirebaseRemoteConfig.unitypackage
) 新增至 Unity 專案。
請注意,將 Firebase 新增至 Unity 專案時,您需要在Firebase控制台和開啟的 Unity 專案中執行工作 (例如從控制台下載 Firebase 設定檔,然後移至 Unity 專案)。
步驟 2:設定應用程式內預設參數值
您可以在 Remote Config 物件中設定應用程式預設參數值,讓應用程式在連線至 Remote Config 後端前正常運作,並在後端未設定任何值時提供預設值。
如要這麼做,請建立字串字典,並填入代表要新增預設值的鍵/值組合。如果您已設定 Remote Config 後端參數值,可以下載包含這些鍵/值組合的檔案,並用來建構字串字典。詳情請參閱「下載範本預設值」。Remote Config
(呼叫 SetDefaultsAsync()
時,非字串屬性會轉換為屬性的類型)。
System.Collections.Generic.Dictionary<string, object> defaults = new System.Collections.Generic.Dictionary<string, object>(); // These are the values that are used if we haven't fetched data from the // server // yet, or if we ask for values that the server doesn't have: defaults.Add("config_test_string", "default local string"); defaults.Add("config_test_int", 1); defaults.Add("config_test_float", 1.0); defaults.Add("config_test_bool", false); Firebase.RemoteConfig.FirebaseRemoteConfig.DefaultInstance.SetDefaultsAsync(defaults) .ContinueWithOnMainThread(task => {
步驟 3:取得要在應用程式中使用的參數值
現在您可以從 Remote Config 物件取得參數值。如果您在 Remote Config 後端設定值、擷取這些值,然後啟用這些值,應用程式就能使用這些值。否則,您會取得使用 SetDefaultsAsync()
設定的應用程式內參數值。
如要取得這些值,請使用 GetValue()
,並將參數鍵做為引數提供。這會傳回 ConfigValue
,其中包含可將值轉換為各種基本型別的屬性。
步驟 4:設定參數值
- 在 Firebase 控制台中開啟專案。
- 選取選單中的 Remote Config,即可查看 Remote Config 資訊主頁。
- 定義的參數名稱必須與應用程式中定義的參數名稱相同。您可以為每個參數設定預設值 (最終會覆寫應用程式中的預設值) 和條件值。詳情請參閱Remote Config參數和條件。
步驟 5:擷取並啟用值 (視需要)
如要從 Remote Config 後端擷取參數值,請呼叫 FetchAsync()
方法。系統會擷取您在後端設定的所有值,並快取在 Remote Config 物件中。
// Start a fetch request. // FetchAsync only fetches new data if the current data is older than the provided // timespan. Otherwise it assumes the data is "recent enough", and does nothing. // By default the timespan is 12 hours, and for production apps, this is a good // number. For this example though, it's set to a timespan of zero, so that // changes in the console will always show up immediately. public Task FetchDataAsync() { DebugLog("Fetching data..."); System.Threading.Tasks.Task fetchTask = Firebase.RemoteConfig.FirebaseRemoteConfig.DefaultInstance.FetchAsync( TimeSpan.Zero); return fetchTask.ContinueWithOnMainThread(FetchComplete); }
在上述程式碼中,FetchComplete
是簽名與 ContinueWithOnMainThread()
的其中一個多載參數相符的方法。
在下列程式碼範例中,FetchComplete
方法會傳遞上一個工作 (fetchTask
),讓 FetchComplete
判斷工作是否完成。程式碼會使用 Info.LastFetchStatus
判斷完成作業是否也成功。如果是,系統會使用 ActivateAsync()
啟用 Remote Config 參數值。
private void FetchComplete(Task fetchTask) {
if (!fetchTask.IsCompleted) {
Debug.LogError("Retrieval hasn't finished.");
return;
}
var remoteConfig = FirebaseRemoteConfig.DefaultInstance;
var info = remoteConfig.Info;
if(info.LastFetchStatus != LastFetchStatus.Success) {
Debug.LogError($"{nameof(FetchComplete)} was unsuccessful\n{nameof(info.LastFetchStatus)}: {info.LastFetchStatus}");
return;
}
// Fetch successful. Parameter values must be activated to use.
remoteConfig.ActivateAsync()
.ContinueWithOnMainThread(
task => {
Debug.Log($"Remote data loaded and ready for use. Last fetch time {info.FetchTime}.");
});
}
使用 FetchAsync()
擷取的值會在擷取完成時在本機快取,但要等到叫用 ActivateAsync()
時才會提供。這樣一來,您就能確保系統不會在計算期間或可能導致問題或異常行為的其他時間套用新值。
步驟 6:即時收聽最新資訊
擷取參數值後,您可以使用即時 Remote Config 監聽 Remote Config 後端的更新。有更新時,系統會向連線裝置傳送即時Remote Config信號,並在您發布新Remote Config版本後自動擷取變更。
Firebase Unity SDK 11.0.0 以上版本支援 Android 和 Apple 平台的即時更新。
- 在應用程式中新增
OnConfigUpdateListener
,開始監聽更新並自動擷取任何新的或更新的參數值。接著,建立ConfigUpdateListenerEventHandler
來處理更新事件。下列範例會監聽更新,並使用新擷取的值顯示更新的歡迎訊息。
// Invoke the listener. void Start() { Firebase.RemoteConfig.FirebaseRemoteConfig.DefaultInstance.OnConfigUpdateListener += ConfigUpdateListenerEventHandler; } // Handle real-time Remote Config events. void ConfigUpdateListenerEventHandler( object sender, Firebase.RemoteConfig.ConfigUpdateEventArgs args) { if (args.Error != Firebase.RemoteConfig.RemoteConfigError.None) { Debug.Log(String.Format("Error occurred while listening: {0}", args.Error)); return; } Debug.Log("Updated keys: " + string.Join(", ", args.UpdatedKeys)); // Activate all fetched values and then display a welcome message. remoteConfig.ActivateAsync().ContinueWithOnMainThread( task => { DisplayWelcomeMessage(); }); } // Stop the listener. void OnDestroy() { Firebase.RemoteConfig.FirebaseRemoteConfig.DefaultInstance.OnConfigUpdateListener -= ConfigUpdateListenerEventHandler; }
下次發布新版 Remote Config 時,執行應用程式並監聽變更的裝置會呼叫完成處理常式。
後續步驟
如果您尚未探索Remote Config 應用情境,請參閱一些重要概念和進階策略說明文件,包括: