תחילת העבודה עם Firebase Crashlytics

במדריך הזה מוסבר איך להגדיר את Firebase Crashlytics באפליקציה באמצעות Firebase Crashlytics SDK כדי לקבל דוחות מקיפים על קריסות ב-Firebase Console.

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

לפני שמתחילים

1. אם עדיין לא עשיתם זאת, מוסיפים את Firebase לפרויקט Unity. אם אין לכם פרויקט Unity, אתם יכולים להוריד אפליקציה לדוגמה.

2. מומלץ: כדי לקבל באופן אוטומטי יומני נתיב ולהבין את פעולות המשתמש שהובילו לקריסה, לאירוע לא קטלני או לאירוע ANR, צריך להפעיל את האפשרות Google Analytics בפרויקט Firebase.

   • אם בפרויקט הקיים שלכם ב-Firebase לא הפעלתם את Google Analytics, תוכלו להפעיל את Google Analytics דרך הכרטיסייה Integrations (שילובים) בקטע settings > Project settings (הגדרות הפרויקט) במסוף Firebase.

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

שלב 1: מוסיפים את Crashlytics SDK לאפליקציה

שימו לב: כשרושמים את פרויקט Unity בפרויקט Firebase, יכול להיות שכבר הורדתם את Firebase Unity SDK והוספתם את החבילות שמתוארות בשלבים הבאים.

1. מורידים את Firebase Unity SDK ומחלצים את הקבצים למיקום נוח. ערכת ה-SDK‏ Firebase Unity לא ספציפית לפלטפורמה.

2. בפרויקט הפתוח ב-Unity, מנווטים אל Assets (נכסים) > Import Package (ייבוא חבילה) > Custom Package (חבילה מותאמת אישית).

3. מתוך ה-SDK שחולץ, בוחרים לייבא את Crashlytics SDK (FirebaseCrashlytics.unitypackage).

   כדי ליהנות מיומני נתיב, צריך להוסיף לאפליקציה את Firebase SDK for Google Analytics (FirebaseAnalytics.unitypackage). חשוב לוודא שGoogle Analytics מופעל בפרויקט Firebase.

4. בחלון Import Unity Package (ייבוא חבילת Unity), לוחצים על Import (ייבוא).

שלב 2: הפעלת Crashlytics

1. יוצרים סקריפט חדש של C# ‎ ואז מוסיפים אותו ל-GameObject בסצנה.

   1. פותחים את הסצנה הראשונה ויוצרים רכיב ריק GameObject בשם CrashlyticsInitializer.

   2. לוחצים על Add Component (הוספת רכיב) בInspector (כלי הבדיקה) של האובייקט החדש.

   3. בוחרים את סקריפט CrashlyticsInit כדי להוסיף אותו לאובייקט CrashlyticsInitializer.

2. מפעילים את Crashlytics בפונקציה Start של הסקריפט:

   using System.Collections;
   using System.Collections.Generic;
   using UnityEngine;
   
   // Import Firebase and Crashlytics
   using Firebase;
   using Firebase.Crashlytics;
   
   public class CrashlyticsInit : MonoBehaviour {
       // Use this for initialization
       void Start () {
           // Initialize Firebase
           Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(task => {
               var dependencyStatus = task.Result;
               if (dependencyStatus == Firebase.DependencyStatus.Available)
               {
                   // Create and hold a reference to your FirebaseApp,
                   // where app is a Firebase.FirebaseApp property of your application class.
                   // Crashlytics will use the DefaultInstance, as well;
                   // this ensures that Crashlytics is initialized.
                   Firebase.FirebaseApp app = Firebase.FirebaseApp.DefaultInstance;
   
                   // When this property is set to true, Crashlytics will report all
                   // uncaught exceptions as fatal events. This is the recommended behavior.
                   Crashlytics.ReportUncaughtExceptionsAsFatal = true;
   
                   // Set a flag here for indicating that your project is ready to use Firebase.
               }
               else
               {
                   UnityEngine.Debug.LogError(System.String.Format(
                     "Could not resolve all Firebase dependencies: {0}",dependencyStatus));
                   // Firebase Unity SDK is not safe to use here.
               }
           });
       }
   
     // Update is called once per frame
     void Update()
       // ...
   }

שלב 3: (Android בלבד) הגדרת העלאה של סמלים

השלב הזה נדרש רק באפליקציות ל-Android שמשתמשות ב-IL2CPP.

• אין צורך לבצע את השלבים האלה באפליקציות ל-Android שמשתמשות ב-Mono scripting backend של Unity.

• באפליקציות לפלטפורמת Apple, השלבים האלה לא נדרשים כי הפלאגין Firebase Unity Editor מגדיר באופן אוטומטי את פרויקט Xcode להעלאת סמלים.

‫Crashlytics Unity SDK 8.6.1+‎ כולל באופן אוטומטי דיווח על קריסות ב-NDK, שמאפשר ל-Crashlytics לדווח באופן אוטומטי על קריסות של Unity IL2CPP ב-Android. עם זאת, כדי לראות בלוח הבקרה Crashlytics את עקבות מחסנית (stack traces) עם סימבולים לקריסות של ספריות מקוריות, צריך להעלות מידע על סימבולים בזמן הבנייה באמצעות Firebase CLI.

כדי להגדיר העלאת סמלים, פועלים לפי ההוראות להתקנת Firebase CLI.

אם כבר התקנתם את ה-CLI, חשוב לעדכן לגרסה האחרונה.

שלב 4: יוצרים את הפרויקט ומעלים סמלים

‫iOS+‎ (פלטפורמת אפל)

1. בתיבת הדו-שיח Build Settings (הגדרות בנייה), מייצאים את הפרויקט לסביבת עבודה של Xcode.

2. יוצרים את האפליקציה.

   בפלטפורמות של Apple, התוסף Firebase Unity Editor מגדיר באופן אוטומטי את פרויקט Xcode כדי ליצור ולהעלות קובץ סמלים שתואם ל-Crashlytics לשרתי Firebase לכל בנייה.

Android

1. בתיבת הדו-שיח Build Settings (הגדרות בנייה), מבצעים אחת מהפעולות הבאות:

   • לייצא לפרויקט Android Studio כדי לבנות את הפרויקט, או

   • יוצרים את קובץ ה-APK ישירות מכלי העריכה של Unity.
     לפני שמבצעים Build, מוודאים שתיבת הסימון Create symbols.zip מסומנת בתיבת הדו-שיח Build Settings.

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

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

   • ‫FIREBASE_APP_ID: מזהה האפליקציה שלכם ב-Firebase ל-Android (לא שם החבילה)
     דוגמה למזהה אפליקציה ב-Firebase ל-Android: 1:567383003300:android:17104a2ced0c9b9b

     צריך למצוא את מזהה האפליקציה ב-Firebase?

     יש שתי דרכים לאתר את מזהה האפליקציה ב-Firebase:

     • בקובץ google-services.json, מזהה האפליקציה הוא הערך mobilesdk_app_id.

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

   • ‫PATH/TO/SYMBOLS: הנתיב לקובץ הסמלים שנוצר על ידי ה-CLI

     • ייצוא לפרויקט Android Studio – ‫PATH/TO/SYMBOLS היא הספרייה unityLibrary/symbols, שנוצרת בשורש הפרויקט המיוצא אחרי שבונה את האפליקציה באמצעות Gradle או Android Studio.

     • יצירת ה-APK ישירות מתוך Unity –‏ PATH/TO/SYMBOLS היא הנתיב של קובץ הסמלים הדחוס שנוצר בספריית השורש של הפרויקט בסיום ה-build (לדוגמה: myproject/myapp-1.0-v100.symbols.zip).

   הצגת אפשרויות מתקדמות לשימוש בפקודה Firebase של CLI ליצירה ולהעלאה של קובץ סמלים

   Flag	תיאור
   --generator=csym	הכלי משתמש במחולל קובצי הסמלים מדור קודם cSYM במקום במחולל ברירת המחדל Breakpad לא מומלץ לשימוש. מומלץ להשתמש בברירת המחדל של מחולל קובצי הסמלים של Breakpad.
   --generator=breakpad	שימוש בכלי ליצירת קובצי סמלים של Breakpad הערה: ברירת המחדל ליצירת קובץ סמלים היא Breakpad. משתמשים בדגל הזה רק אם הוספתם את symbolGenerator { csym() } להגדרת ה-build ורוצים לבטל את ההגדרה הזו כדי להשתמש ב-Breakpad במקום זאת.
   --dry-run	יוצר את קובצי הסמלים אבל לא מעלה אותם התג הזה שימושי אם רוצים לבדוק את התוכן של הקבצים שנשלחים.
   --debug	מספק מידע נוסף לצורך ניפוי באגים

שלב 5: הפעלת קריסה של בדיקה כדי לסיים את ההגדרה

כדי לסיים את ההגדרה של Crashlytics ולראות נתונים ראשוניים בלוח הבקרה של Crashlytics ב-Firebase Console, צריך לגרום לקריסת בדיקה.

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

   using System;
   using UnityEngine;
   
   public class CrashlyticsTester : MonoBehaviour {
   
       int updatesBeforeException;
   
       // Use this for initialization
       void Start () {
         updatesBeforeException = 0;
       }
   
       // Update is called once per frame
       void Update()
       {
           // Call the exception-throwing method here so that it's run
           // every frame update
           throwExceptionEvery60Updates();
       }
   
       // A method that tests your Crashlytics implementation by throwing an
       // exception every 60 frame updates. You should see reports in the
       // Firebase console a few minutes after running your app with this method.
       void throwExceptionEvery60Updates()
       {
           if (updatesBeforeException > 0)
           {
               updatesBeforeException--;
           }
           else
           {
               // Set the counter to 60 updates
               updatesBeforeException = 60;
   
               // Throw an exception to test your Crashlytics implementation
               throw new System.Exception("test exception please ignore");
           }
       }
   }

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

   • ‫iOS+‎: התוסף Firebase Unity Editor מגדיר באופן אוטומטי את פרויקט Xcode להעלאת קובץ הסמלים.

   • ‫Android: באפליקציות ל-Android שמשתמשות ב-IL2CPP, מריצים את הפקודה Firebase CLI crashlytics:symbols:upload כדי להעלות את קובץ הסמלים.

3. מריצים את האפליקציה. כשהאפליקציה פועלת, צופים ביומן המכשיר ומחכים שהחריגה תופעל מ-CrashlyticsTester.

   • ‫iOS+‎: הצגת יומנים בחלונית התחתונה של Xcode.

   • ‫Android: כדי להציג את היומנים, מריצים את הפקודה הבאה במסוף: adb logcat.

4. עוברים אל מרכז הבקרה של Crashlytics במסוף Firebase כדי לראות את קריסת הבדיקה.

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

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

השלבים הבאים

• (מומלץ) באפליקציות ל-Android שמשתמשות ב-IL2CPP, אפשר לאסוף דוחות GWP-ASan כדי לקבל עזרה בניפוי באגים בקריסות שנגרמות משגיאות זיכרון נייטיב. השגיאות האלה שקשורות לזיכרון יכולות להיות משויכות להשחתת זיכרון באפליקציה, שזה הגורם העיקרי לפרצות אבטחה באפליקציות. כדי להשתמש בתכונת הניפוי באגים הזו, צריך לוודא שהאפליקציה משתמשת בגרסה העדכנית ביותר של Crashlytics SDK ל-Unity (גרסה 10.7.0 ואילך) ושהאפשרות GWP-ASan מופעלת באופן מפורש (לשם כך צריך לשנות את קובץ המניפסט של אפליקציית Android).

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

• משלבים עם Google Play כדי לסנן את דוחות קריסת האפליקציה ל-Android לפי Google Play ולעקוב ישירות בלוח הבקרה של Crashlytics. כך תוכלו להתמקד בלוח הבקרה בגרסאות ספציפיות.