開始使用 Firebase 遠端設定


您可以使用 Firebase 遠端設定在應用程式中定義參數，並在雲端更新參數的值，這樣就能在不發布應用程式更新的情況下修改應用程式的外觀與行為。

遠端設定程式庫可用來儲存應用程式內的預設參數值、從遠端設定後端擷取更新後的參數值，並控管應用程式可以使用擷取的值的時機。詳情請參閱遠端設定載入策略。

本指南將逐步引導您開始使用，並提供一些程式碼範例，這些程式碼範例均可從 firebase/quickstart-unity GitHub 存放區複製或下載。

步驟 1：在應用程式中新增遠端設定

使用遠端設定之前，您需要先完成以下步驟：

  • 註冊 Unity 專案，然後將其設為使用 Firebase。

    • 如果 Unity 專案已使用 Firebase，則系統會註冊並設定 Firebase。

    • 如果您沒有 Unity 專案，可以下載範例應用程式。

  • 將 Firebase Unity SDK (具體來說是 FirebaseRemoteConfig.unitypackage) 新增至 Unity 專案。

請注意，將 Firebase 新增至 Unity 專案，涉及在 Firebase 主控台和開放式 Unity 專案中執行的工作 (例如，從控制台下載 Firebase 設定檔，然後將它們移至 Unity 專案中)。

步驟 2：設定應用程式內預設參數值

您可以在遠端設定物件中設定應用程式內預設參數值，讓應用程式在連線至遠端設定後端前可正常運作，如此如果後端未設定任何預設值，即可使用預設值。

方法是建立字串字典，並在其中填入鍵/值組合，代表要新增的預設值。如果您已設定遠端設定後端參數值，可以下載包含這些鍵/值組合的檔案，並使用該檔案建構字串字典。詳情請參閱「下載遠端設定範本預設值」。

(呼叫 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：取得要在應用程式中使用的參數值

您現在可以透過遠端設定物件取得參數值。如果您在遠端設定後端設定這些值、擷取並啟用這些值，應用程式就能使用這些值。否則，請使用 SetDefaultsAsync() 設定應用程式內參數值。

如要取得這些值，請使用 GetValue()，並提供參數鍵做為引數。這會回傳 ConfigValue，其中包含的屬性，可將值轉換為各種基礎類型。

步驟 4：設定參數值

  1. 在 Firebase 控制台開啟專案。
  2. 從選單中選取「遠端設定」，查看遠端設定資訊主頁。
  3. 定義與您在應用程式中定義的參數名稱相同的參數。您可以為每個參數設定預設值 (最終覆寫應用程式內預設值) 和條件值。詳情請參閱「遠端設定參數和條件」一文。

步驟 5：擷取並啟用值 (視需要)

如要從遠端設定後端擷取參數值，請呼叫 FetchAsync() 方法。系統會擷取您在後端設定的任何值，並儲存在遠端設定物件中。

// 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() 啟用遠端設定參數值。

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：聽取即時動態

擷取參數值後，您可以使用即時遠端設定監聽來自遠端設定後端的更新。有可用的更新時，即時遠端設定會向已連結的裝置發出信號，並在您發布新的遠端設定版本後自動擷取變更。

Android 和 Apple 平台適用的 Firebase Unity SDK 11.0.0 以上版本支援即時更新。

  1. 在應用程式中新增 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;
}

下次發布新版本的遠端設定時，執行應用程式並監聽變更的裝置都會呼叫完成處理常式。

後續步驟

如果您尚未瞭解遠端設定的用途，請先查看一些重要概念和進階策略說明文件，包括：