תחילת העבודה עם הגדרת תצורה מרחוק ב-Firebase


אפשר להשתמש ב-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: מגדירים ערכי פרמטרים

  1. פותחים את הפרויקט במסוף Firebase.
  2. בוחרים באפשרות Remote Config בתפריט כדי להציג את לוח הבקרה Remote Config.
  3. אתם צריכים להגדיר פרמטרים עם שמות זהים לפרמטרים שהגדרתם באפליקציה, ולהגדיר לכל פרמטר ערך ברירת מחדל (שיחליף בסופו של דבר את ערך ברירת המחדל באפליקציה) וערכים מותנים. למידע נוסף, ראו פרמטרים ותנאים של 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().

בדוגמת הקוד שבהמשך, למשימה הקודמת (fetchTask) מועברת השיטה FetchComplete, שמאפשרת ל-FetchComplete לקבוע אם היא הסתיימה. הקוד משתמש ב-Info.LastFetchStatus כדי לקבוע אם גם ההשלמה בוצעה בהצלחה. אם כן, ערכי הפרמטרים של Remote Config מופעלים באמצעות 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: האזנה לעדכונים בזמן אמת

אחרי שמאחזרים את ערכי הפרמטרים, אפשר להשתמש ב-Remote Config בזמן אמת כדי להאזין לעדכונים מהקצה העורפי Remote Config. Remote Config מאותת למכשירים מחוברים בזמן אמת כשיש עדכונים זמינים, ומאחזר את השינויים באופן אוטומטי אחרי שמפרסמים גרסה חדשה של Remote Config.

עדכונים בזמן אמת נתמכים ב-Firebase Unity SDK בגרסה 11.0.0 ואילך בפלטפורמות Android ו-Apple.

  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;
}

בפעם הבאה שתפרסמו גרסה חדשה של Remote Config, מכשירים שמריצים את האפליקציה ומקשיבים לשינויים יפעילו את פונקציית הטיפול בהשלמה.

השלבים הבאים

אם עדיין לא עשיתם זאת, כדאי לעיין בRemote Config תרחישים לדוגמה ולקרוא את המסמכים בנושא מושגים מרכזיים ואסטרטגיות מתקדמות, כולל: