הסבר על קריסות במשחקים של Unity באמצעות תכונות מתקדמות של Crashlytics

1. מבוא

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

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

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

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

מה תלמדו

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

מה צריך להכין

• Unity (גרסה מינימלית מומלצת 2019 ואילך) עם אחת מהאפשרויות הבאות או שניהם:
  • תמיכה ב-iOS Build
  • תמיכה ב-Android Build
• (ל-Android בלבד) ה-CLI של Firebase (משמש להעלאת סמלים לדוחות קריסה)
  • פועלים לפי ההוראות להתקנת Firebase CLI.
    אם כבר התקנתם את ה-CLI, צריך לעדכן לגרסה האחרונה.

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

בקטעים הבאים מוסבר איך להוריד את הקוד Level Up with Firebase ולפתוח אותו ב-Unity.

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

להורדת הקוד

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

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

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

פתיחת שדרוג לרמה הבאה עם Firebase בעורך Unity

1. מפעילים את Unity Hub, ובכרטיסייה Projects לוחצים על החץ הנפתח לצד Open (פתיחה).
2. לוחצים על Add project from disk.
3. עוברים לספרייה שמכילה את הקוד ולוחצים על OK.
4. אם מופיעה בקשה, בוחרים את גרסת עורך Unity שבה רוצים להשתמש ואת פלטפורמת היעד (Android או iOS).
5. לוחצים על שם הפרויקט level-up-with-firebase והפרויקט ייפתח בעורך Unity.
6. אם העורך לא פותח אותו באופן אוטומטי, פותחים את MainGameScene בקטע נכסים > Hamster בכרטיסייה Project ב-Unity Editor.
   

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

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

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

1. במסוף Firebase, לוחצים על הוספת פרויקט.
2. כדי ליצור פרויקט חדש, מזינים את שם הפרויקט הרצוי.
   הפעולה הזו גם תגדיר את מזהה הפרויקט (שמוצג מתחת לשם הפרויקט) לפי שם הפרויקט. אפשר גם ללחוץ על סמל עריכה של מזהה הפרויקט כדי להתאים אותו אישית עוד יותר.
3. אם תופיע בקשה, קוראים את התנאים של Firebase ומאשרים אותם.
4. לוחצים על המשך.
5. בוחרים באפשרות Enable Google Analytics for this project (הפעלת Google Analytics עבור הפרויקט הזה) ולוחצים על Continue (המשך).
6. בוחרים חשבון Google Analytics קיים לשימוש או בוחרים באפשרות Create a new account (יצירת חשבון חדש) כדי ליצור חשבון חדש.
7. לוחצים על Create project.
8. אחרי השלמת היצירה, לוחצים על Continue.

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

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

   חשוב: מזהה החבילה של iOS ושם החבילה של Android שצוינו למעלה שונים. המזהה של iOS לא תקין ל-Android ולהפך. חשוב לוודא שאתם משתמשים במזהה הנכון.

4. (אופציונלי) מזינים את הכינוי/ים הספציפיים לפלטפורמה של הפרויקט ב-Unity.
5. לוחצים על רישום האפליקציה וממשיכים לקטע הורדת קובץ תצורה.

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

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

1. מורידים את שני קובצי התצורה הזמינים:
   • ל-Apple (iOS): מורידים את GoogleService-Info.plist.
   • ב-Android: מורידים את הקובץ google-services.json.
2. פותחים את החלון Project (פרויקט) של הפרויקט ב-Unity ומעבירים את שני קובצי התצורה לתיקייה Assets (נכסים).

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

3. במסוף Firebase, בתהליך ההגדרה, לוחצים על הבא וממשיכים לקטע 'הוספת ערכות Firebase SDK ל-Unity'.

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

הוספת ערכות Firebase SDK ל-Unity

1. לוחצים על הורדת Firebase Unity SDK במסוף Firebase.

   הערה: ההורדה של ה-SDK הזה עשויה להימשך זמן מה. שותים קפה או תה – חשוב לשתות באופן קבוע.

2. מבטלים את האריזה של ה-SDK במקום נוח.
3. בפרויקט Unity הפתוח, עוברים אל Assets (נכסים) > ייבוא חבילה > חבילה מותאמת אישית.
4. בתיבת הדו-שיח Import package, עוברים לספרייה שמכילה את ה-SDK ללא האפסור, בוחרים באפשרות FirebaseAnalytics.unitypackage ולוחצים על Open.
5. בתיבת הדו-שיח Import Unity Package שמופיעה, לוחצים על Import.
6. חוזרים על השלבים הקודמים כדי לייבא את FirebaseCrashlytics.unitypackage.
7. חוזרים למסוף Firebase ולוחצים על הבא בתהליך ההגדרה.

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

4. הגדרת Crashlytics בפרויקט ב-Unity

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

איך מפעילים את Crashlytics SDK

1. ב-Assets/Hamster/Scripts/MainGame.cs, מוסיפים את הצהרות using הבאות:

   using Firebase.Crashlytics;
   using Firebase.Extensions;
   

   המודול הראשון מאפשר להשתמש בשיטות מ-Crashlytics SDK והמודול השני מכיל כמה תוספים ל-C# Tasks API. בלי שתי ההצהרות using, הקוד הבא לא יפעל.
2. עדיין ב-MainGame.cs, מוסיפים את האתחול של Firebase לשיטה הקיימת Start() באמצעות קריאה ל-InitializeFirebaseAndStartGame():

   void Start()
   {
     Screen.SetResolution(Screen.width / 2, Screen.height / 2, true);
     InitializeFirebaseAndStartGame();
   }
   

3. שוב, ב-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;
           InitializeCommonDataAndStartGame();
         } else {
           UnityEngine.Debug.LogError(
             $"Could not resolve all Firebase dependencies: {dependencyStatus}\n" +
             "Firebase Unity SDK is not safe to use here");
         }
       });
   }
   

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

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

פיתוח הפרויקט והעלאת סמלים

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

השלבים ליצירה ולהעלאה של סמלים שונים באפליקציות ל-iOS ול-Android.

iOS+‏ (פלטפורמת Apple)

1. בתיבת הדו-שיח Build Settings (הגדרות Build), מייצאים את הפרויקט לסביבת עבודה של Xcode.
2. יוצרים את האפליקציה.
   בפלטפורמות של Apple, הפלאגין של Firebase Unity Editor מגדיר באופן אוטומטי את פרויקט ה-Xcode ליצירה ולהעלאה של קובץ סמלים שתואם ל-Crashlytics לשרתי Firebase בכל גרסת build. פרטי הסמלים האלה נדרשים כדי להציג דוחות קריסות סימבוליים במרכז הבקרה של Crashlytics.

Android

1. (רק במהלך ההגדרה הראשונית, לא בכל גרסה זמנית) מגדירים את הגרסה הזמנית:
   1. יוצרים תיקייה חדשה בשם Builds ברמה הבסיסית (root) של ספריית הפרויקט (כלומר, כקובץ אח"כ לספריית נכסים), ואז יוצרים תיקיית משנה בשם Android.
   2. בקובץ > הגדרות Build > הגדרות הנגן > Configuration, קביעת הקצה העורפי של Scripting ל-IL2CPP.
      • בדרך כלל, IL2CPP גורם לגרסת build קטנה יותר עם ביצועים טובים יותר.
      • IL2CPP היא גם האפשרות היחידה שזמינה ב-iOS ובחירה בה כאן מאפשרת התאמה טובה יותר בין שתי הפלטפורמות ומפשטת את ההבדלים בין שתי הפלטפורמות (אם בוחרים ליצור את שתיהן).
2. יוצרים את האפליקציה בקובץ > Build Settings (הגדרות Build):
   1. מוודאים שהאפשרות Create icon.zip מסומנת (או אם מוצג תפריט נפתח, בוחרים באפשרות ניפוי באגים).
   2. יוצרים את קובץ ה-APK ישירות מתוך Unity Editor בתיקיית המשנה Builds/Android שיצרתם זה עתה.
3. בסיום ה-build, צריך ליצור קובץ סמלים שתואם ל-Crashlytics ולהעלות אותו לשרתים של Firebase. פרטי הסמלים האלה נדרשים כדי לראות דוחות קריסות סימבוליים של קריסות של ספריות נייטיב במרכז הבקרה של Crashlytics.
   
   כדי ליצור ולהעלות את קובץ הסמלים הזה, מריצים את הפקודה הבאה של Firebase CLI:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

   • FIREBASE_APP_ID: מזהה האפליקציה שלכם ל-Android ב-Firebase (לא שם החבילה). מוצאים את הערך הזה בקובץ google-services.json שהורדתם מקודם. זהו הערך של mobilesdk_app_id.
     מזהה אפליקציה לדוגמה ב-Firebase ל-Android: 1:567383003300:android:17104a2ced0c9b9b
   • PATH/TO/SYMBOLS: הנתיב של קובץ הסמל המוצפן שנוצר בספרייה Builds/Android בסיום ה-build (לדוגמה: Builds/Android/myapp-1.0-v100.symbols.zip).

     הערה: שם הקובץ ישתנה כשיוצרים את הפרויקט עם מספרים שונים שמוגדרים ל-Version ול-Bundle Version Code בקטע File (קובץ) > Build Settings (הגדרות build) > Player Settings (הגדרות נגן) > Identification (זיהוי).

אילוץ קריסת בדיקה כדי לסיים את ההגדרה

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

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

   using System;
   using UnityEngine;
   
   public class CrashlyticsTester : MonoBehaviour {
       // Update is called once per frame
       void Update()
       {
           // Tests your Crashlytics implementation by
           // throwing an exception every 60 frames.
           // You should see reports in the Firebase console
           // a few minutes after running your app with this method.
           if(Time.frameCount >0 && (Time.frameCount%60) == 0)
           {
               throw new System.Exception("Test exception; please ignore");
           }
       }
   }
   

2. יוצרים את האפליקציה ומעלים את פרטי הסמלים בסיום ה-build.
   • iOS: הפלאגין של Firebase Unity Editor מגדיר באופן אוטומטי את פרויקט ה-Xcode להעלאת קובץ הסמלים.
   • Android: מריצים את הפקודה crashlytics:symbols:upload של Firebase CLI כדי להעלות את קובץ הסמל.

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

3. מריצים את האפליקציה. אחרי שהאפליקציה פועלת, בודקים את יומן המכשיר ומחכים להפעלה של החריגה מ-CrashlyticsTester.
   • iOS: הצגת היומנים בחלונית התחתונה של Xcode.
   • Android: כדי להציג את היומנים, מריצים את הפקודה הבאה במסוף: adb logcat.
4. אתם יכולים להיכנס ללוח הבקרה של Crashlytics כדי לראות את החריגה. הוא יופיע בטבלה בעיות שבתחתית מרכז הבקרה. בהמשך ב-Codelab, נלמד איך להכיר את הדוחות האלה.
5. אחרי שמוודאים שהאירוע הועלה ל-Crashlytics, בוחרים את ה-EmptyObject GameObject שאליו צירפתם אותו, מסירים רק את הרכיב CrashlyticsTester ואז שומרים את הסצנה כדי לשחזר אותה למצב המקורי שלה.

5. הפעלה והסבר על תפריט ניפוי הבאגים

עד עכשיו הוספתם את Crashlytics לפרויקט ב-Unity, סיימתם את ההגדרה ואימתתם ש-Crashlytics SDK מעלה אירועים ל-Firebase. עכשיו ניצור תפריט בפרויקט ב-Unity, שבו נראה איך להשתמש בפונקציות מתקדמות יותר של Crashlytics במשחק. בפרויקט Unity‏ Level Up with Firebase כבר יש תפריט נסתרות לניפוי באגים, שתצטרכו להפוך אותו לגלוש ולכתוב את הפונקציונליות שלו.

הפעלת תפריט ניפוי הבאגים

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

1. פותחים את ה-Prefab בשם MainMenu. ב-Unity Editor.
2. בהיררכיה של טרום-השהיה, מחפשים את אובייקט המשנה המושבת בשם DebugMenuButton ובוחרים אותו.
3. כדי להפעיל את DebugMenuButton, מסמנים את התיבה בפינה הימנית העליונה, מימין לשדה הטקסט שמכיל את DebugMenuButton.
4. שומרים את הרכיב המועדף.
5. מריצים את המשחק בכלי העריכה או במכשיר. עכשיו התפריט אמור להיות נגיש.

חשוב: מאחר ששיטות ההתרסקות לא מיושמות כרגע, הקשה על הלחצנים המתאימים תגרום להצגת השגיאה System.NotImplementedException, ולא תעשה דבר אחר.

תצוגה מקדימה והסבר על גופי השיטות בתפריט לניפוי באגים

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

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

פותחים את DebugMenu.cs ומחפשים את השיטות הבאות:

שיטות ליצירה של בעיות ב-Crashlytics ולהוספת הערות אליהן:

• CrashNow
• LogNonfatalError
• LogStringsAndCrashNow
• SetAndOverwriteCustomKeyThenCrash
• SetLogsAndKeysBeforeANR

שיטות לרישום אירועים ב-Analytics כדי לעזור בניפוי באגים:

• LogProgressEventWithStringLiterals
• LogIntScoreWithBuiltInEventAndParams

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

6. איך מוודאים שדוחות קריסה נשלחים במהלך הפיתוח

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

בפרויקטים של Unity, אירועי קריסה וחריגות במשחק נכתבים לדיסק באופן מיידי. אם מדובר בחריגות שלא תועדו ולא גרמו לקריסה של המשחק (לדוגמה, חריגות ב-C# שלא תועדו בלוגיקה של המשחק), אפשר להגדיר ל-Crashlytics SDK לדווח עליהן כאירועים קטלניים. לשם כך, מגדירים את המאפיין Crashlytics.ReportUncaughtExceptionsAsFatal לערך true במקום שבו מפעילים את Crashlytics בפרויקט Unity. האירועים האלה מדווחים ל-Crashlytics בזמן אמת, ללא צורך שמשתמש קצה יפעיל מחדש את המשחק. חשוב לשים לב שקריסות מקוריות תמיד מדווחות כאירועים חמורים, ונשלחות יחד כאשר משתמש הקצה מפעיל את המשחק מחדש.

הערה: כדי לדווח על חריגות לא מזוהות כאירועים חמורים, בפרויקט Unity צריך להשתמש ב-Firebase Crashlytics Unity SDK מגרסה 10.4.0 ואילך.

בנוסף, חשוב לשים לב להבדלים הקטנים אך המשמעותיים הבאים בין האופן שבו סביבות זמן הריצה השונות שולחות מידע מ-Crashlytics ל-Firebase:

סימולטור iOS:

• פרטי Crashlytics מדווחים אך ורק אם מנתקים את Xcode מהסימולטור. אם מצורף Xcode, הוא מאתר את השגיאות ב-upstream ומונע את העברת המידע.

מכשירים פיזיים ניידים (Android ו-iOS):

• ספציפיים ל-Android: מקרי ANR מדווחים רק ב-Android מגרסה 11 ואילך. מקרי ANR ואירועים לא חמורים ידווחו בהפעלה הבאה.

Unity Editor:

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

איך בודקים אם המשחק קורס בלחיצה על לחצן ב-CrashNow()

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

1. כדי להוכיח שהפעולה הזו אכן אוטומטית: פותחים את הקובץ DebugMenu.cs ומחליפים את השיטה CrashNow() באופן הבא:

   void CrashNow()
   {
       TestCrash();
   }
   

2. יוצרים את האפליקציה
3. (Android בלבד) מעלים את הסמלים על ידי הפעלת הפקודה הבאה ב-CLI של Firebase:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

4. מקישים על הלחצן Crash Now (הפעלת קריסה עכשיו) וממשיכים לשלב הבא של הקודלה כדי ללמוד איך להציג את דוח הקריסה ולפרש אותו.

7. הסבר על דוחות על בעיות במסוף Firebase

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

1. מקישים על הלחצן תאונה עכשיו ואז מפעילים מחדש את האפליקציה.
2. עוברים אל מרכז הבקרה של Crashlytics. גוללים למטה לטבלה בעיות שבתחתית לוח הבקרה. מערכת Crashlytics מקבצת אירועים שיש להם את אותו שורש בעיה ל'בעיות'.
3. לוחצים על הבעיה החדשה שמפורטת בטבלה בעיות. פעולה זו תציג את סיכום האירוע של כל אירוע ספציפי שנשלח אל Firebase.
   
   אתם אמורים לראות משהו כמו תמונת המסך הבאה. שימו לב שסיכום האירוע כולל את מעקב הסטאק של הקריאה שהובילה לקריסה.

מטא-נתונים נוספים

הכרטיסייה מטא-נתונים של Unity היא עוד כרטיסייה שימושית. בקטע הזה מפורט מידע על המאפיינים של המכשיר שבו התרחש האירוע, כולל תכונות פיזיות, המפרט או הדגם של המעבד (CPU) וכל מיני מדדים של GPU.

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

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

8. השלכת חריגה, לכידה שלה ורישום ביומן

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

1. בקובץ Assets/Hamster/Scripts/States/DebugMenu.cs, מוסיפים את הקוד הבא להצהרות using:

   // Import Firebase
   using Firebase.Crashlytics;
   

2. עדיין ב-DebugMenu.cs, מחליפים את LogNonfatalError() באופן הבא:

   void LogNonfatalError()
   {
       try
       {
           throw new System.Exception($"Test exception thrown in {nameof(LogNonfatalError)}");
       }
       catch(System.Exception exception)
       {
           Crashlytics.LogException(exception);
       }
   }
   

3. יוצרים את האפליקציה.
4. (Android בלבד) כדי להעלות את הסמלים, מריצים את הפקודה הבאה ב-CLI של Firebase:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

5. מקישים על הלחצן רישום שגיאה לא חמורה ואז מפעילים מחדש את האפליקציה.
6. עוברים אל מרכז הבקרה של Crashlytics. עכשיו אתם אמורים לראות משהו שדומה למה שראיתם בשלב האחרון של ה-Codelab הזה.
7. עם זאת, הפעם הגבילו את המסנן סוג האירוע לערך לא חמורים, כך שיוצגו רק שגיאות לא חמורות, כמו השגיאה שתועדה כרגע.
   

9. רישום מחרוזות ביומן ב-Crashlytics כדי להבין טוב יותר את תהליך ביצוע התוכנית

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

במצבים כאלה, הקשר מסוים יכול לעשות את כל ההבדל. בעזרת Crashlytics.Log, אפשר לכתוב את ההקשר הרצוי. כדאי לחשוב על ההודעות האלה כעל רמזים לעצמכם בעתיד לגבי מה שעשוי לקרות.

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

1. ב-Assets/Hamster/Scripts/States/DebugMenu.cs, מחליפים את LogStringsAndCrashNow() באופן הבא:

   void LogStringsAndCrashNow()
   {
       Crashlytics.Log($"This is the first of two descriptive strings in {nameof(LogStringsAndCrashNow)}");
       const bool RUN_OPTIONAL_PATH = false;
       if(RUN_OPTIONAL_PATH)
       {
           Crashlytics.Log(" As it stands, this log should not appear in your records because it will never be called.");
       }
       else
       {
           Crashlytics.Log(" A log that will simply inform you which path of logic was taken. Akin to print debugging.");
       }
       Crashlytics.Log($"This is the second of two descriptive strings in {nameof(LogStringsAndCrashNow)}");
       TestCrash();
   }
   

2. יוצרים את האפליקציה
3. (Android בלבד) כדי להעלות את הסמלים, מריצים את הפקודה הבאה ב-CLI של Firebase:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

4. מקישים על הלחצן Log String (מחרוזות יומן) ו-Crash Now ואז מפעילים מחדש את האפליקציה.
5. חוזרים אל מרכז הבקרה של Crashlytics ולוחצים על הבעיה החדשה ביותר שמופיעה בטבלה בעיות. שוב, אמורה להופיע הודעה דומה לבעיות הקודמות.
   
6. עם זאת, אם לוחצים על הכרטיסייה יומנים בסיכום אירועים, מופיעה תצוגה כזו:
   

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

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

10. כתיבת מפתח בהתאמה אישית ושינוי שלו

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

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

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

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

1. ב-Assets/Hamster/Scripts/States/DebugMenu.cs, מחליפים את SetAndOverwriteCustomKeyThenCrash() באופן הבא:

   void SetAndOverwriteCustomKeyThenCrash()
   {
       const string CURRENT_TIME_KEY = "Current Time";
       System.TimeSpan currentTime = System.DateTime.Now.TimeOfDay;
       Crashlytics.SetCustomKey(
           CURRENT_TIME_KEY,
           DayDivision.GetPartOfDay(currentTime).ToString() // Values must be strings
           );
   
       // Time Passes
       currentTime += DayDivision.DURATION_THAT_ENSURES_PHASE_CHANGE;
   
       Crashlytics.SetCustomKey(
           CURRENT_TIME_KEY,
           DayDivision.GetPartOfDay(currentTime).ToString()
           );
       TestCrash();
   }
   

2. יוצרים את האפליקציה
3. (Android בלבד) מעלים את הסמלים באמצעות הפקודה הבאה ב-CLI של Firebase:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

4. מקישים על הלחצן Set Custom Key and Crash ומפעילים מחדש את האפליקציה.
5. חוזרים למרכז הבקרה של Crashlytics ולוחצים על הבעיה החדשה ביותר שמופיעה בטבלה בעיות. שוב, אתם אמורים לראות משהו דומה לבעיות הקודמות.
6. הפעם, לוחצים על הכרטיסייה Keys (מפתחות) בקטע Event summary (סיכום האירוע) כדי להציג את הערך של מפתחות, כולל Current Time:
   

   חשוב: המפתח של crash_info_entry_0 מאוכלס באופן אוטומטי ב-Crashlytics רק כשהאפליקציה מופעלת על ידי הסימולטור של iOS.

למה כדאי להשתמש במפתחות מותאמים אישית במקום ביומנים מותאמים אישית?

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

עם זאת, בדומה ליומנים, למפתחות מותאמים אישית יש מגבלה. מערכת Crashlytics תומכת ב-64 צמדי מפתח/ערך לכל היותר. כשתגיעו לסף הזה, ערכים נוספים לא יישמרו. כל צמד מפתח/ערך יכול להיות בגודל של עד 1KB.

11. (Android בלבד) שימוש במפתחות וביומני נתונים מותאמים אישית כדי להבין ולנתח בעיות ANR

חשוב: סוג הבעיה הבא רלוונטי בעיקר ל-Android מגרסה 11 ואילך. אם התיאור הזה לא מתאים לתרחיש לדוגמה של הפיתוח, דלגו על הקטע הזה.

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

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

בשיטה הזו, נשתמש בשילוב של Crashlytics.LogException, Crashlytics.Log ו-Crashlytics.SetCustomKey כדי להשלים את הרישום האוטומטי של בעיות ביומן ולספק לנו מידע נוסף.

חשוב: חשוב לזכור שהקוד החוסם פועל בשרשור ממשק המשתמש של UnityPlayerActivity. זה לא טבעי ב-Unity, כי ה-thread לא זהה ל-Unity Main Thread, שהוא ברירת המחדל שבה פועל קוד המשחק. ניפוי הבאגים של שגיאות ANR יכול להיות מסובך במיוחד, כי הן יכולות להיגרם מיישומי פלאגין או מקוד אחר שפועל באופן לא אידיומטי בשרשור בממשק המשתמש.

1. ב-Assets/Hamster/Scripts/States/DebugMenu.cs, מחליפים את SetLogsAndKeysBeforeANR() באופן הבא:

   void SetLogsAndKeysBeforeANR()
   {
       System.Action<string,long> WaitAndRecord =
       (string methodName, long targetCallLength)=>
       {
           System.Diagnostics.Stopwatch stopWatch = new System.Diagnostics.Stopwatch();
           const string CURRENT_FUNCTION = "Current Async Function";
   
           // Initialize key and start timing
           Crashlytics.SetCustomKey(CURRENT_FUNCTION, methodName);
           stopWatch.Start();
   
           // The actual (simulated) work being timed.
           BusyWaitSimulator.WaitOnSimulatedBlockingWork(targetCallLength);
   
           // Stop timing
           stopWatch.Stop();
   
           if(stopWatch.ElapsedMilliseconds>=BusyWaitSimulator.EXTREME_DURATION_MILLIS)
           {
             Crashlytics.Log($"'{methodName}' is long enough to cause an ANR.");
           }
           else if(stopWatch.ElapsedMilliseconds>=BusyWaitSimulator.SEVERE_DURATION_MILLIS)
           {
             Crashlytics.Log($"'{methodName}' is long enough it may cause an ANR");
           }
       };
   
       WaitAndRecord("DoSafeWork",1000L);
       WaitAndRecord("DoSevereWork",BusyWaitSimulator.SEVERE_DURATION_MILLIS);
       WaitAndRecord("DoExtremeWork",2*BusyWaitSimulator.EXTREME_DURATION_MILLIS);
   }
   

2. יוצרים את האפליקציה.
3. כדי להעלות את הסמלים, מריצים את הפקודה הבאה של Firebase CLI:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

4. מקישים על הלחצן Set Logs And Keys → ANR (הגדרת יומנים ומפתחות → ANR) ומפעילים מחדש את האפליקציה.
5. חוזרים ללוח הבקרה של Crashlytics ולוחצים על הבעיה החדשה בטבלה בעיות כדי להציג את סיכום האירועים. אם השיחה בוצעה כמו שצריך, אמורים להופיע משהו כזה:
   
   
   כמו שאפשר לראות, מערכת Firebase זיהתה את זמן ההמתנה הלא תקין בשרשור בתור הסיבה העיקרית לכך שהאפליקציה הפעילה שגיאת ANR.
   
6. אם תסתכלו ביומנים בכרטיסייה יומנים שבסיכום האירועים, תראו שהשיטה האחרונה שתועדה היא DoSevereWork.
   
   
   לעומת זאת, השיטה האחרונה שנרשמה כשהיא התחילה היא DoExtremeWork, שמציין ששגיאת ה-ANR התרחשה בשיטה הזו, והמשחק נסגר לפני שהוא הצליח לתעד DoExtremeWork.
   
   

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

מדוע לעשות זאת?

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

12. שילוב אירועים ב-Analytics להעשרת הדוחות

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

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

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

1. ב-Assets/Hamster/Scripts/States/DebugMenu.cs, מחליפים את ההטמעות הקיימות של השיטות הבאות:

   public void LogProgressEventWithStringLiterals()
   {
         Firebase.Analytics.FirebaseAnalytics.LogEvent("progress", "percent", 0.4f);
   }
   

   public void LogIntScoreWithBuiltInEventAndParams()
   {
         Firebase.Analytics.FirebaseAnalytics
           .LogEvent(
             Firebase.Analytics.FirebaseAnalytics.EventPostScore,
             Firebase.Analytics.FirebaseAnalytics.ParameterScore,
             42
           );
   }
   

2. יוצרים ופורסים את המשחק, ואז נכנסים לתפריט ניפוי הבאגים.
3. (Android בלבד) מעלים את הסמלים באמצעות הפקודה הבאה ב-CLI של Firebase:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

4. כדי להפעיל את הפונקציות שלמעלה, לוחצים לפחות על אחד מהלחצנים הבאים פעם אחת או יותר:
   • אירוע של מחרוזת ביומן
   • Log Int Event
5. לוחצים על הלחצן גרימה לקריסה.
6. כדי להעלות את אירוע הקריסה ל-Firebase, צריך להפעיל מחדש את המשחק.
7. כשמתעדים רצפים שרירותיים שונים של אירועי Analytics ולאחר מכן מבקשים מהמשחק ליצור אירוע ש-Crashlytics יוצר ממנו דוח (כפי שקורה בדיוק), הם נוספים לכרטיסייה יומנים בסיכום האירועים של Crashlytics, באופן הבא:
   

חשוב: יכול להיות שאירועים בהתאמה אישית לא יופיעו במרכז הבקרה של Analytics במסוף Firebase אחרי משך הזמן שיחלוף עד שהם יופיעו ביומן קריסה במרכז הבקרה של Crashlytics. בנוסף, יכול להיות שאירועים ב-Analytics לא יופיעו בשני המקומות מיד אחרי שתתעדו אותם.

13. המשך

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

אם האפליקציה שלכם מטרגטת ל-Android 11 (רמת API 30) ואילך, מומלץ לשלב את GWP-ASan, תכונה של מנהל זיכרון נייטיב ששימושית לניפוי באגים של קריסות שנגרמות על ידי שגיאות זיכרון נייטיב, כמו באגים מסוג use-after-free ו-heap-buffer-overflow. כדי להשתמש בתכונה הזו לניפוי באגים, צריך להפעיל באופן מפורש את GWP-ASan.

השלבים הבאים

ממשיכים לקודלאב הטמעת כלי למדידת ביצועים במשחק ב-Unity באמצעות Remote Config, שבו מוסבר איך משתמשים ב-Remote Config וב-A/B Testing ב-Unity.