דף זה תורגם על ידי Cloud Translation API.

מגדירים את המשחק ב-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.
אם העורך לא נפתח אוטומטית, פותחים את 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 יורד. אפשר לראות תצוגה מקדימה של השלבים הבאים או לקחת הפסקה קצרה.
פותחים את ה-SDK במקום נוח.
בפרויקט הפתוח ב-Unity, עוברים אל Assets (נכסים) > Import Package (ייבוא חבילה) > Custom Package (חבילה מותאמת אישית).
בתיבת הדו-שיח Import package (ייבוא חבילה), עוברים לספרייה שמכילה את ה-SDK שלא נפרס, בוחרים באפשרות FirebaseAnalytics.unitypackage ולוחצים על Open (פתיחה).
בתיבת הדו-שיח Import Unity Package (ייבוא חבילת Unity) שמופיעה, לוחצים על Import (ייבוא).
חוזרים על השלבים הקודמים כדי לייבא את שתי החבילות הבאות:
- 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 שיעזרו לכם לנהל את תהליך האתחול באמצעות קריאות חוזרות (callbacks) בצורה פשוטה יותר.
מוסיפים את האתחול של 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. הפעולה הזו תשרשר קריאות לשיטות של Remote Config‏ FetchAsync (שמאחזרת ערכים חדשים מ-Remote Config) ו-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 מתקשר אל נקודת ההתחלה הקודמת, InitializeCommonDataAndStartGame, כדי להתחיל את המשחק על ידי פתיחת התפריט הראשי.

6. הגדרת אסטרטגיית טעינה של Remote Config

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

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

כשבוחנים את מערכת התפריטים של 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. צריכות להופיע ההודעות 'שליפת נתונים…' ו'הנתונים המרוחקים נטענו ומוכנים'. שימו לב לחותמות הזמן בתחילת ההודעות האלה.
במשחק, לוחצים על רישיון.
לוחצים על אישור.
מחכים שהתפריט הראשי של המשחק יופיע.
בודקים את פלט היומן של המשחק, שצריך להיות דומה לזה שמופיע בשלב הקודם, עם חותמות זמן חדשות (שמתאימות לשעה שמוגדרת בשעון המערכת שבו מריצים את המשחק).
במשחק, לוחצים על הפעלה.
מקישים על קדימה.
מזיזים את הכדור לשער באמצעות מקשי החיצים במקלדת, ואז ייפתח התפריט 'השלמת השלב'.
מקישים על רמות.
מחכים שהתפריט בחירת רמה ייטען.
בודקים שוב את פלט היומן של המשחק. הוא צריך להיות זהה להודעות ביומן מהשלבים הקודמים, עם חותמות זמן חדשות יותר (שמתאימות לשעה שמוגדרת בשעון המערכת שבו מריצים את המשחק).

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

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

מייבאים את הגדרת התצורה מרחוק על ידי הוספת 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, פותחים את הפרויקט.
בתפריט, בוחרים באפשרות Remote Config כדי להציג את לוח הבקרה של Remote Config.

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

שם הפרמטר (מפתח)	סוג הנתונים	ערך ברירת המחדל
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 בהתאם לפלטפורמה שבה נעשה שימוש, פועלים לפי השלבים הבאים.

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

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

איך זה עובד

כדי להאזין לעדכונים, האפליקציה צריכה להטמיע שיטה שנרשמת לאירוע 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. כל הכבוד!

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

מה נכלל

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

השלבים הבאים

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