מגדירים את המשחק ב-Unity בעזרת הגדרת תצורה מרחוק ב-Firebase

1. מבוא

אתם יכולים להשתמש בהגדרת תצורה מרחוק ב-Firebase כדי להגדיר זוגות של מפתח/ערך, שנקראים גם פרמטרים, באפליקציה שלכם ולעדכן את הערכים שלהם בענן. כך תוכלו לשנות את המראה וההתנהגות של האפליקציה בלי להפיץ עדכון לאפליקציה.

תשתמשו בפונקציונליות החדשה הזו במשחק לדוגמה, MechaHamster: Level Up with Firebase Edition. משחק הדוגמה הזה הוא גרסה חדשה של משחק Firebase הקלאסי MechaHamster, שבה הוסרה רוב הפונקציונליות המובנית של Firebase. כך יש לכם הזדמנות להטמיע במקומה שימושים חדשים ב-Firebase.

כדי לוודא שהאפליקציה מתנהגת כמו שרוצים, צריך להגדיר הגדרות ברירת מחדל לערכים בקוד של המשחק לדוגמה. אפשר לשנות את הערכים האלה באמצעות ערכים שמגדירים בהגדרת התצורה מרחוק במסוף Firebase.

מה תלמדו

איך מגדירים ערכים של הגדרת התצורה מרחוק בענן ומאחזרים אותם
איך מטמיעים את קוד Unity C# כדי להשתמש באופן אוטומטי בערכים שאוחזרו
איך לאחסן, להטמיע ולשנות ערכים או אובייקטים מורכבים כערכי JSON
איך משתמשים בתנאים של הגדרת תצורה מרחוק כדי להציג וריאציות שונות של ערכים לקבוצות שונות של משתמשים

מה צריך להכין

‫Unity 2019.1.0f1 ואילך עם תמיכה ב-iOS ו/או ב-Android
מכשיר פיזי עם Android או iOS או סימולטור/אמולטור כדי ליצור ולהריץ את המשחק

2. הגדרת סביבת הפיתוח

בקטעים הבאים מוסבר איך להוריד את הקוד של Level Up with Firebase, לפתוח אותו ב-Unity ולהוסיף פרויקט Firebase. משחק הדוגמה הזה, Level Up with Firebase, משמש בכמה מדריכי Codelab אחרים בנושא Firebase + Unity, כך שאולי כבר השלמתם את המשימות שבקטע הזה. אם כן, אפשר לדלג על השלבים האלה ולהמשיך אל הוספת Firebase SDKs for Unity כדי להוסיף הגדרת תצורה מרחוק לקוד של משחק הדוגמה.

הורדת הקוד

משכפלים את מאגר GitHub של ה-codelab הזה משורת הפקודה:

git clone https://github.com/firebase/level-up-with-firebase

לחלופין, אם לא התקנתם את git, אתם יכולים להוריד את המאגר כקובץ ZIP.

פותחים את Level Up with Firebase בכלי לעריכת Unity

מפעילים את Unity Hub ובכרטיסייה Projects לוחצים על החץ לתפריט הנפתח לצד Open.
לוחצים על הוספת פרויקט מדיסק.
עוברים לספרייה שמכילה את הקוד ולוחצים על אישור.
אם תתבקשו, תצטרכו לבחור גרסה של Unity Editor שבה תרצו להשתמש ואת פלטפורמת היעד (Android או iOS).
לוחצים על שם הפרויקט, level-up-with-firebase, והפרויקט ייפתח בכלי Unity Editor.
אם העורך לא נפתח אוטומטית, פותחים את MainGameScene בAssets > Hamster בכרטיסייה Project של Unity Editor.

מידע נוסף על התקנה ושימוש ב-Unity זמין במאמר עבודה ב-Unity.

3. הוספת Firebase לפרויקט ב-Unity

יצירת פרויקט Firebase

נכנסים למסוף Firebase באמצעות חשבון Google.
לוחצים על הלחצן כדי ליצור פרויקט חדש, ואז מזינים שם לפרויקט (לדוגמה, LevelUpWithFirebase).
שם הפרויקט הזה משמש כשם לתצוגה בממשקי Firebase, ומערכת Firebase יוצרת באופן אוטומטי מזהה פרויקט ייחודי על סמך שם הפרויקט הזה. שימו לב: אפשר ללחוץ על סמל העריכה כדי להגדיר את מזהה הפרויקט המועדף, אבל אי אפשר לשנות את המזהה הזה אחרי יצירת הפרויקט.

חשוב לזכור את מזהה הפרויקט, כי תצטרכו אותו בהמשך כדי לזהות את פרויקט Firebase ב-Firebase CLI. אם שכחתם את המזהה, תמיד תוכלו למצוא אותו בהמשך בהגדרות הפרויקט.
לוחצים על המשך.
אם מוצגת בקשה לעשות זאת, קוראים ומאשרים את התנאים של Firebase, ואז לוחצים על המשך.
(אופציונלי) מפעילים את העזרה מבוססת-AI במסוף Firebase (שנקראת Gemini ב-Firebase).
כדי להשתמש במוצרי Firebase בצורה אופטימלית, צריך להשתמש ב-Google Analytics. לכן, חשוב להשאיר את המתג במצב מופעל באפשרות של Google Analytics. פועלים לפי ההוראות במסך כדי להגדיר את Google Analytics.
לוחצים על יצירת פרויקט, מחכים שהפרויקט יוקצה ולוחצים על המשך.

רישום האפליקציה ב-Firebase

פותחים את מסוף Firebase ובמרכז הדף של סקירת הפרויקט לוחצים על הסמל של Unity כדי להפעיל את תהליך ההגדרה. אם כבר הוספתם אפליקציה לפרויקט Firebase, לוחצים על הוספת אפליקציה כדי להציג את אפשרויות הפלטפורמה.
בוחרים לרשום גם את יעדי ה-build של Apple ‏ (iOS) וגם את יעדי ה-build של Android.
מזינים את המזהים הספציפיים לפלטפורמה של הפרויקט ב-Unity. ב-Codelab הזה, מזינים את הפרטים הבאים:
- ל-Apple‏ (iOS) – מזינים com.google.firebase.level-up בשדה מזהה חבילה ב-iOS.
- ב-Android – מזינים com.google.firebase.level_up בשדה שם החבילה ל-Android.
אפשר להזין כינויים ספציפיים לפלטפורמה של פרויקט Unity.
לוחצים על Register app (רישום האפליקציה) ועוברים לקטע Download config file (הורדת קובץ התצורה).
חוזרים על התהליך עבור כל יעד בנייה שלא ביצעתם בפעם הראשונה.

הוספת קובצי תצורה של Firebase

אחרי שלוחצים על Register app (רישום האפליקציה), תתבקשו להוריד שני קובצי הגדרה (קובץ הגדרה אחד לכל יעד בנייה). כדי להתחבר ל-Firebase, פרויקט Unity צריך את המטא-נתונים של Firebase בקבצים האלה.

מורידים את שני קובצי התצורה הזמינים:
- ל-Apple‏ (iOS): מורידים את הקובץ GoogleService-Info.plist.
- ב-Android: מורידים את הקובץ google-services.json.
פותחים את החלון Project (פרויקט) של הפרויקט ב-Unity ומעבירים את שני קובצי התצורה לתיקייה Assets (נכסים).
חשוב: גם אם אתם מתכננים לפתח רק ל-iOS או ל-Android, כדאי להוריד את שני הקבצים ולהוסיף אותם לפרויקט.
חוזרים למסוף Firebase, בתהליך ההגדרה, לוחצים על הבא וממשיכים להוספת Firebase SDKs for Unity.

הערה: תמיד אפשר להוריד מחדש את הקבצים האלה בשלב מאוחר יותר. כדי לעשות זאת, פותחים את ההגדרות הכלליות של הפרויקט, גוללים למטה לקטע האפליקציות שלך ולוחצים על לחצן ההורדה של קובץ התצורה הרצוי.

הוספת Firebase SDKs for Unity

לוחצים על הורדת Firebase Unity SDK במסוף Firebase.
הערה: יכול להיות שיעבור קצת זמן עד שה-SDK יוריד. אפשר לעיין בשלבים הבאים או לקחת הפסקה קצרה.
פורסים את קובץ ה-ZIP של ה-SDK במקום נוח.
בפרויקט הפתוח ב-Unity, עוברים אל Assets (נכסים) > Import Package (ייבוא חבילה) > Custom Package (חבילה מותאמת אישית).
בתיבת הדו-שיח Import package (ייבוא חבילה), עוברים אל הספרייה שמכילה את ה-SDK שלא נפרס, בוחרים באפשרות FirebaseAnalytics.unitypackage ולוחצים על Open (פתיחה).
בתיבת הדו-שיח ייבוא חבילת Unity שמופיעה, לוחצים על ייבוא.
חוזרים על השלבים הקודמים כדי לייבא את שתי החבילות הבאות:
- FirebaseRemoteConfig.unitypackage
- ‫FirebaseCrashlytics.unitypackage
  Crashlytics הוא כלי קל משקל לדיווח על קריסות בזמן אמת, שעוזר לכם לעקוב אחרי בעיות יציבות שפוגעות באיכות האפליקציה, לתת להן עדיפות ולתקן אותן. אם לא השתמשתם בו בעבר, מומלץ לעבור על תוכנית הלימודים בנושא Crashlytics ל-Unity.
חוזרים למסוף Firebase ובתהליך ההגדרה לוחצים על הבא.

מידע נוסף על הוספת ערכות Firebase SDK לפרויקטים ב-Unity זמין במאמר אפשרויות נוספות להתקנה ב-Unity.

4. הגדרת ברירות מחדל של הגדרת התצורה מרחוק ואחזור ערכים חדשים

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

כדי לאחזר ערכים חדשים מ'הגדרת תצורה מרחוק', צריך להשלים כמה שיטות שלא יושמו וכבר מופיעות בקובץ Assets/Hamster/Scripts/MainGame.cs.

מוסיפים את הצהרות using הבאות אל MainGame.cs:
```
using Firebase.Crashlytics;
using Firebase.Extensions;
using Firebase.RemoteConfig;
```
מודול Firebase.Extensions מכיל כמה הרחבות ל-C# Tasks API שיעזרו לפשט את תהליך ההגדרה באמצעות קריאות חוזרות (callback).
מוסיפים את האתחול של Firebase לשיטה MainGame.cs Start() על ידי החלפת השיטה הקיימת InitializeCommonDataAndStartGame() בשיטה שלא הוטמעה כרגע, InitializeFirebaseAndStartGame():
```
void Start()
{
   Screen.SetResolution(Screen.width / 2, Screen.height / 2, true);
   InitializeFirebaseAndStartGame();
}
```

ב-MainGame.cs, מחפשים את InitializeFirebaseAndStartGame(). מגדירים משתנה של האפליקציה ומחליפים את היישום של השיטה באופן הבא:

public Firebase.FirebaseApp app = null;

// Begins the firebase initialization process and afterwards, opens the main menu.
private void InitializeFirebaseAndStartGame()
{
   Firebase.FirebaseApp.CheckAndFixDependenciesAsync()
   .ContinueWithOnMainThread(
      previousTask =>
      {
         var dependencyStatus = previousTask.Result;
         if (dependencyStatus == Firebase.DependencyStatus.Available) {
         // Create and hold a reference to your FirebaseApp,
         app = Firebase.FirebaseApp.DefaultInstance;
         // Set the recommended Crashlytics uncaught exception behavior.
         Crashlytics.ReportUncaughtExceptionsAsFatal = true;
         SetRemoteConfigDefaults();
         } else {
         UnityEngine.Debug.LogError(
            $"Could not resolve all Firebase dependencies: {dependencyStatus}\n" +
            "Firebase Unity SDK is not safe to use here");
         }
      });
}

קריאות לאתחול של Firebase מחזירות SetRemoteConfigDefaults במקרה של הצלחה, כדי להגדיר ערכי ברירת מחדל בתוך האפליקציה. מחליפים את השיטה SetRemoteConfigDefaults שלא הוטמעה בשיטה הבאה:

private void SetRemoteConfigDefaults()
{
   var defaults = new System.Collections.Generic.Dictionary < string, object > ();
   defaults.Add(
      Hamster.MapObjects.AccelerationTile.AccelerationTileForceKey,
      Hamster.MapObjects.AccelerationTile.AccelerationTileForceDefault);
   defaults.Add(
      Hamster.States.MainMenu.SubtitleOverrideKey,
      Hamster.States.MainMenu.SubtitleOverrideDefault);
   var remoteConfig = FirebaseRemoteConfig.DefaultInstance;
   remoteConfig.SetDefaultsAsync(defaults).ContinueWithOnMainThread(
      previousTask =>
      {
         FetchRemoteConfig(InitializeCommonDataAndStartGame);
      }
   );
}

5. מאחזרים ומפעילים ערכים חדשים (לפי הצורך)

עכשיו צריך להשלים את השיטה הקיימת FetchRemoteConfig. הפעולה הזו תשרשר קריאות לשיטות של הגדרת תצורה מרחוק FetchAsync (שמאחזרת ערכים חדשים מהגדרת תצורה מרחוק) ו-ActivateAsync (שמפעילה את הערכים שהתקבלו כדי להפוך אותם לזמינים בקוד) באמצעות פרמטר של קריאה חוזרת בשם onFetchAndActivateSuccessful.

קוד ההפעלה שהוספנו בשלב הקודם קורא ל-FetchRemoteConfig עם InitializeCommonDataAndStartGame כקריאה חוזרת כדי להפעיל את המשחק בסוף הרצף. אפשר להעביר פונקציות קריאה חוזרת חלופיות אל FetchRemoteConfig כדי להפעיל את האחזור עם תוצאות שונות. דוגמה (שתוטמע בהמשך) היא העברה של שיטה שפותחת תפריטי ממשק משתמש חדשים, שתלויים בערכים של הגדרת התצורה מרחוק. כתוצאה מכך, התפריטים ייפתחו רק אחרי שהערכים האלה יאוחזרו ויופעלו.

מדביקים את הקוד הבא ב-FetchRemoteConfig:

public void FetchRemoteConfig(System.Action onFetchAndActivateSuccessful)
{
   if(app==null)
   {
      Debug.LogError($"Do not use Firebase until it is properly initialized by calling {nameof(InitializeFirebaseAndStartGame)}.");
      return;
   }

   Debug.Log("Fetching data...");
   var remoteConfig = FirebaseRemoteConfig.DefaultInstance;
   remoteConfig.FetchAsync(System.TimeSpan.Zero).ContinueWithOnMainThread(
      previousTask=>
      {
         if (!previousTask.IsCompleted)
         {
         Debug.LogError($"{nameof(remoteConfig.FetchAsync)} incomplete: Status '{previousTask.Status}'");
         return;
         }
         ActivateRetrievedRemoteConfigValues(onFetchAndActivateSuccessful);
      });
}

לאחר מכן, משלימים את השיטה ActivateRetrievedRemoteConfigValues שמקבלת קריאה חוזרת שהועברה, onFetchAndActivateSuccessful. כשההפעלה מסתיימת, המערכת מפעילה את הקריאה החוזרת שצוינה:

private void ActivateRetrievedRemoteConfigValues(System.Action onFetchAndActivateSuccessful)
{
   var remoteConfig = FirebaseRemoteConfig.DefaultInstance;
   var info = remoteConfig.Info;
   if(info.LastFetchStatus == LastFetchStatus.Success)
   {
      remoteConfig.ActivateAsync().ContinueWithOnMainThread(
         previousTask =>
         {
         Debug.Log($"Remote data loaded and ready (last fetch time {info.FetchTime}).");
         onFetchAndActivateSuccessful();
         });
   }
}

כש-SetRemoteConfigDefaults קורא ל-ActivateRetrievedRemoteConfigValues במורד הזרם מהקשר האתחול, ActivateRetrievedRemoteConfigValues קורא לנקודת ההתחלה הקודמת, InitializeCommonDataAndStartGame, כדי להתחיל את המשחק על ידי פתיחת התפריט הראשי.

6. הגדרת אסטרטגיית טעינה של הגדרת תצורה מרחוק

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

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

כשבוחנים את מערכת התפריטים של Mechahamster, הדרך הקלה ביותר להוסיף רענון של תפריטים שחוסמים את ממשק המשתמש היא להפעיל אותה לפני שהתפריט הראשי ממשיך (במיוחד כשניגשים אליו אחרי שיוצאים מתפריט אחר) ולהעביר את שיטת התצוגה של ממשק המשתמש כקריאה חוזרת (callback) של onFetchAndActivateSuccessful. אפשר לעשות את אותו הדבר בתפריט Level Select.

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

כדי להפעיל את האפשרות הזו באפליקציה, צריך להשלים את השיטות הרלוונטיות בתפריט הראשי ובקבצים של בחירת הרמה, שיחסמו את התצוגה של ממשק המשתמש עד להשלמת הפעולות FetchAsync ו-ActivateAsync:

פותחים את Assets/Hamster/Scripts/States/MainMenu.cs ומחליפים את השיטה הקיימת Resume בשיטה הבאה:

public override void Resume(StateExitValue results) {
   CommonData.mainGame.SelectAndPlayMusic(CommonData.prefabs.menuMusic, true);
   CommonData.mainGame.FetchRemoteConfig(InitializeUI);
}

שומרים את הקובץ.
פותחים את Assets/Hamster/Scripts/States/BaseLevelSelect.cs ומחליפים את השיטה הקיימת Resume בשיטה הבאה:
```
public override void Resume(StateExitValue results) {
   CommonData.mainGame.FetchRemoteConfig(ShowUI);
}
```
שומרים את הקובץ.

7. ניפוי באגים או אימות של התנהגויות אחזור

בשלב הזה, מומלץ לבצע בדיקה לאבחון בעיות או לאימות. התהליך הבא יאפשר לכם לבדוק באופן ידני את האפליקציה ואת האופן שבו היא מאחזרת ומפעילה ערכים של הגדרת תצורה מרחוק (אם בכלל).

המידע יודפס כחלק מיומני הסימולטור, המכשיר או הכלי לעריכה. ב-iOS, אפשר לראות את היומנים של המכשיר והסימולטור ב-Xcode. ב-Android, כדי לראות את היומנים מריצים את הפקודה adb logcat. אם מריצים את הקוד ב-Unity על ידי לחיצה על Play בעורך, היומנים מופיעים בכרטיסייה Console.

בונים מחדש את האפליקציה ומריצים אותה (בכלי העריכה, באמצעות מכשיר או סימולטור).
אחרי שמופיע התפריט הראשי של המשחק, בודקים את פלט היומן של המשחק, שאמור לכלול את היומנים שנוצרו על ידי Debug.Log ב-FetchRemoteConfig וב-ActivateRetrievedRemoteConfigValues. צריכות להופיע ההודעות 'שליפת נתונים...' ו'הנתונים המרוחקים נטענו ומוכנים'. שימו לב לחותמות הזמן בתחילת ההודעות.
במשחק, לוחצים על רישיון.
מקישים על אישור.
מחכים שהתפריט הראשי של המשחק יופיע.
בודקים את פלט היומן של המשחק, שצריך להיות דומה לזה שבשלב הקודם, עם חותמות זמן חדשות (שמתאימות לשעה שהוגדרה בשעון המערכת שבו מריצים את המשחק).
במשחק, לוחצים על הפעלה.
לוחצים על Let's Roll.
מזיזים את הכדור לשער באמצעות מקשי החיצים במקלדת, ואז ייפתח התפריט 'השלמת השלב'.
לוחצים על Levels (עוצמות).
מחכים עד שהתפריט בחירת רמה ייטען.
בודקים שוב את הפלט של יומן המשחק. הוא צריך להתאים להודעות ביומן מהשלבים הקודמים, עם חותמות זמן חדשות יותר (שמתאימות לשעה שמוגדרת בשעון המערכת שבו מריצים את המשחק).

אם אחד מהם לא מופיע באפליקציה, יכול להיות שחלק כלשהו בתהליך האחזור וההפעלה (או במכשיר) לא מוגדר כראוי. אם היומן הראשון לא מופיע, יכול להיות שהמשחק לא יופעל. כדאי לעיין במסוף העריכה או ביומנים של המכשיר או האמולטור כדי לראות אזהרות ושגיאות לגבי הפרויקט או הסביבה ולבדוק אותן – יכול להיות שהבעיה פשוטה כמו חיבור לאינטרנט.

אם יומני הרישום הראשוניים מטעינת התפריט מופיעים, אבל אחד מהיומנים הבאים לא מופיע, צריך לבדוק את השיטות Resume ב-Assets/Hamster/Scripts/States/MainMenu.cs וב-Assets/Hamster/Scripts/States/BaseLevelSelect.cs או להטמיע אותן מחדש.

8. הוספת קוד למעקב

אחרי שהגדרתם את ערכי הפרמטרים בתוך האפליקציה ב-SetDefaultsAsync() והפכתם את הגרסאות העדכניות ביותר לזמינות באמצעות FetchAsync() ו-ActivateAsync(), תוכלו להפנות לערכים האלה ולהשתמש בהם בקוד.

אחרי שמגדירים ערכים בקצה העורפי של הגדרת התצורה מרחוק, מאחזרים אותם ומפעילים אותם (או עושים את שתי הפעולות בבת אחת), הערכים האלה זמינים לאפליקציה. כדי להשתמש בערכים האלה, קוראים ל-GetValue(string key) ובוחרים מפתח פרמטר כארגומנט. הפונקציה מחזירה ConfigValue, שיש לה מאפיינים לגישה לערך כסוגים שונים נתמכים: string, bool, long, double. בפרויקט הזה וברוב התרחישים לדוגמה של משחקים, צריך להמיר את שני הסוגים האחרונים ל-int ול-float, שהם יותר אידיומטיים. כדי לוודא שההמרות האלה לא יגרמו לבעיות, צריך לוודא שהערכים הראשוניים שהוגדרו ב-הגדרת תצורה מרחוק נמצאים בטווח התקין של הסוגים שבהם תשתמשו בקוד האפליקציה.

מייבאים את הגדרת התצורה מרחוק על ידי הוספת using Firebase.RemoteConfig; לחלק העליון של הקבצים הבאים:
- Assets/Hamster/Scripts/States/MainMenu.cs
- Assets/Hamster/Scripts/MapObjects/AccelerationTile.cs
מחליפים את השיטה Start של AccelerationTile.cs:
```
private void Start() {
   var remoteConfig = FirebaseRemoteConfig.DefaultInstance;
   Acceleration = (float)remoteConfig.GetValue(AccelerationTileForceKey).DoubleValue;
}
```
בעקבות השינוי הזה, כמות הכוח שמועברת על ידי משבצת התאוצה תשתנה לכמות שתתקבל מ-Remote Config.

עורכים את גוף השיטה InitializeUI של MainMenu.cs:

‫

private void InitializeUI() {
   if (menuComponent == null) {
      menuComponent = SpawnUI<Menus.MainMenuGUI>(StringConstants.PrefabMainMenu);
   }

   var remoteConfig = FirebaseRemoteConfig.DefaultInstance;
   var subtitleOverride = JsonUtility.FromJson<Menus.MainMenuGUI.SubtitleOverride>(
      remoteConfig.GetValue(SubtitleOverrideKey).StringValue);
   // Only sets values if all fields of the override are non-default.
   if(subtitleOverride != null && subtitleOverride.IsValidOverride())
   {
      menuComponent.MenuSubtitleText.text = subtitleOverride.text;
      menuComponent.MenuSubtitleText.fontSize = subtitleOverride.fontSize;
      menuComponent.MenuSubtitleText.color = subtitleOverride.textColor;
   }
   ShowUI();
}

כאן, subtitleOverride מוגדר לשנות את הכתוביות במסך התפריט הראשי אם כל השדות שלו בענן מוגדרים כערכים שונים מערכי ברירת המחדל של הסוג.

9. הגדרת ערכי פרמטרים מרחוק

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

במסוף Firebase, פותחים את הפרויקט.
בתפריט, בוחרים באפשרות הגדרת תצורה מרחוק כדי להציג את לוח הבקרה של הגדרת תצורה מרחוק.

לכל אחד מהפרמטרים שהגדרתם באפליקציה ומופיעים בטבלה הבאה, לוחצים על הוספת פרמטר, מדביקים את שם הפרמטר (המפתח), בוחרים את סוג הנתונים שמופיע בטבלה, משביתים את האפשרות שימוש בברירת המחדל באפליקציה ומדביקים את ערך ברירת המחדל החדש:

שם הפרמטר (מפתח)	סוג הנתונים	ערך ברירת המחדל
acceleration_tile_force	מספר	100
subtitle_override	JSON	`{"text":"We overwrote the subtitle","fontSize":8,"textColor":{"r":0.0,"g":255.0,"b":0.0,"a":255.0}}`

עורך פרמטרים של הגדרת תצורה מרחוק עם הערך acceleration_tile_force

לוחצים על Save כדי לשמור את השינויים.
לוחצים על Publish (פרסום) כדי לפרסם את ההגדרה החדשה ולהפוך את הערכים החדשים לזמינים במשחק.
מריצים את האפליקציה שוב אחרי שמגדירים את הפרמטרים המרוחקים האלה, ומתבוננים באופן שבו הם מבטלים את ברירות המחדל המקוריות.
טיפ: לגבי ערכים שקשה יותר לצפות בהם, כמו ערכים פיזיקליים, אפשר לעדכן את הקוד כדי לרשום ביומן את הערך של ConfigValue.Source כדי לקבוע אם הערכים הם ערכי ברירת המחדל שהוגדרו או שהם נמשכו משרת הגדרת התצורה מרחוק.

10. שימוש בתנאים של הגדרת התצורה מרחוק להצגת וריאנטים

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

אחד מהשימושים הנפוצים בתנאים הוא שינוי תוכן בין פלטפורמות iOS ו-Android. כדי להטמיע תנאי שמאפשר להציג ערך שונה עבור subtitle_override בהתאם לפלטפורמה שבה נעשה שימוש, פועלים לפי השלבים הבאים.

פותחים את הכרטיסייה הגדרת תצורה מרחוק של הפרויקט במסוף Firebase.
לוחצים על לחצן העריכה של subtitle_override.
בפינה הימנית התחתונה, לוחצים על הוספת איש קשר חדש.
בתפריט הנפתח שמופיע, מעבירים את העכבר מעל ערך מותנה ולוחצים על יצירת תנאי חדש $עורך הפרמטרים של הגדרת התצורה מרחוק:\nאפשרות של ערך מותנה$ .
כשמוצגת בקשה, נותנים לתנאי את השם is iOS אם המיקוד הוא ל-iOS, או את השם is Android אם המיקוד הוא ל-Android. אם אתם מטargetים את שניהם, פשוט בוחרים אחד מהם כאן ומשתמשים בו בשאר ה-codelab.
בקטע התנאי חל אם..., לוחצים על התפריט הנפתח בחירה... ובוחרים באפשרות פלטפורמה. לאחר מכן, בוחרים את הפלטפורמה המתאימה.
לוחצים על יצירת תנאי כדי ליצור את התנאי. תיבת הדו-שיח 'עריכת פרמטר' מופיעה שוב, ועכשיו אפשר להגדיר ערך:
- אם אתם מטרגטים מכשירי Android, מגדירים את הערך ל:
```
{"text":"Level Up Android Version","fontSize":8,"textColor":{"r":0.0,"g":255.0,"b":0.0,"a":255.0}}
```
- אם אתם מטרגטים את iOS, מגדירים את הערך ל:
```
{"text":"Level Up iOS Version","fontSize":8,"textColor":{"r":0.0,"g":255.0,"b":0.0,"a":255.0}}
```
לוחצים על Save כדי לשמור את השינויים.
לוחצים על Publish (פרסום) כדי לפרסם את ההגדרה החדשה ולהפוך את הערכים החדשים לזמינים במשחק.

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

11. הגדרת 'הגדרת תצורה מרחוק' לקבלת עדכונים בזמן אמת

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

איך זה עובד

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

הטמעה של הגדרת תצורה מרחוק בזמן אמת

כדי להמחיש איך זה עובד במשחק, מבצעים את השינויים הבאים בקוד.

יצירת handler לעדכון הגדרות

השלב הראשון בשימוש באירוע Config Update הוא ליצור שיטה שיכולה להאזין לו. מציבים את השיטה הבאה ב-Assets/Hamster/Scripts/MainGame.cs:

   void ActivateValuesOnConfigUpdate( object sender, ConfigUpdateEventArgs args)
   {
      if (args.Error != RemoteConfigError.None) {
         Debug.Log($"Error occurred while listening: {args.Error}");
         return;
      }

      Debug.Log("Updated keys: " + string.Join(", ", args.UpdatedKeys));
      // Activate all fetched values and then logs.
      var remoteConfig = FirebaseRemoteConfig.DefaultInstance;
      remoteConfig.ActivateAsync().ContinueWithOnMainThread(
         task => {
            Debug.Log($"Keys from {nameof(ActivateValuesOnConfigUpdate)} activated.");
         });
   }

בשיטה הזו, כשהערכים החדשים מופעלים, רשימה של המפתחות המעודכנים והודעת הצלחה מודפסות ביומן.

כדי להפעיל את ActivateValuesOnConfigUpdate כשקוראים לאירוע, צריך לרשום אותו לאירוע. מחליפים את השיטה InitializeCommonDataAndStartGame() ב-Assets/Hamster/Scripts/MainGame.cs בשיטה הבאה:

   void InitializeCommonDataAndStartGame()
   {
      CommonData.prefabs = FindObjectOfType<PrefabList>();
      CommonData.mainCamera = FindObjectOfType<CameraController>();
      CommonData.mainGame = this;

      Screen.orientation = ScreenOrientation.LandscapeLeft;

      musicPlayer = CommonData.mainCamera.GetComponentInChildren<AudioSource>();

      CommonData.gameWorld = FindObjectOfType<GameWorld>();

      // Set up volume settings.
      MusicVolume = PlayerPrefs.GetInt(StringConstants.MusicVolume, MaxVolumeValue);
      // Set the music to ignore the listeners volume, which is used for sound effects.
      CommonData.mainCamera.GetComponentInChildren<AudioSource>().ignoreListenerVolume = true;
      SoundFxVolume = PlayerPrefs.GetInt(StringConstants.SoundFxVolume, MaxVolumeValue);

      // Subscribes to on config update after first initial fetch and activate
      FirebaseRemoteConfig.DefaultInstance.OnConfigUpdateListener += ActivateValuesOnConfigUpdate;

      stateManager.PushState(new States.MainMenu());
   }

השורה החדשה (שמסיימת ב-+= ActivateValuesOnConfigUpdate;) רושמת את הגורם המטפל באירועים לאירוע.

ביטול ההרשמה כשמשמידים את האובייקט שבבעלותו נמצא ה-handler

כדי למנוע שגיאות של הפניה לערך null, אובייקטים עם שיטות שרשומות לאירועים צריכים לבטל את הרישום של השיטה הזו כשהם מושמדים. מוסיפים את השיטה הבאה ל-Assets/Hamster/Scripts/MainGame.cs:

   private void OnDestroy() 
   {
      FirebaseRemoteConfig.DefaultInstance.OnConfigUpdateListener -= ActivateValuesOnConfigUpdate;
   }

בדיקת הפונקציונליות החדשה

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

משנים את `acceleration_tile_force` ומתבוננים

אחרי שמפעילים את האפליקציה, בקטע 'הגדרת תצורה מרחוק' במסוף Firebase:

לוחצים על לחצן העריכה לצד acceleration_tile_force.

משנים את הערך ל-120 ולוחצים על שמירה.

לוחצים על הלחצן פרסום השינויים.

בודקים את היומן.
אם מופיעה הודעה ביומן שמתחילה במילים "Error occurred while listening" (אירעה שגיאה במהלך ההאזנה), קוראים את שאר ההודעה ומנסים לבצע ניפוי באגים באמצעות הודעת השגיאה שמופיעה.
אם מופיע יומן שמתחיל ב-Updated keys (מפתחות מעודכנים), האפליקציה קיבלה את הערכים שהשתנו.
אם לא מופיע אף אחד מהם, כדאי לעיין בשאר היומנים, לחזור על ההוראות שבקטע יצירת handler לעדכון הגדרות, לבדוק מחדש ולעיין שוב ביומנים כדי לראות אם יש בעיה.

12. כל הכבוד!

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

מה נכלל

איך מגדירים ומאחזרים ערכים של הגדרת התצורה מרחוק
איך להטמיע את הקוד ב-Unity C# כדי להשתמש בערכים שאוחזרו
איך לאחסן, להטמיע ולשנות ערכים או אובייקטים מורכבים כערכי JSON
איך משתמשים בתנאים של הגדרת התצורה מרחוק כדי להציג וריאנטים שונים של ערכים

השלבים הבאים

כדאי לקרוא על העדיפות של ערכי פרמטרים כדי להבין טוב יותר את הלוגיקה של הערכים שמוחזרים על ידי מופע של אפליקציה כשהיא משתמשת בפרמטר עם כמה ערכים (בגלל תנאים או מיקום).