התאמה אישית של דוחות קריסה ב-Flutter

בחירת פלטפורמה:

‫iOS+‎ Android Flutter Unity

אפשר ללחוץ על בעיה כדי לקבל דוח מפורט על האירוע בלוח הבקרה Crashlytics של Firebase במסוף DevOps & Engagement. אתם יכולים להתאים אישית את הדוחות האלה כדי להבין טוב יותר מה קורה באפליקציה ואת הנסיבות שקשורות לאירועים שמדווחים ל-Crashlytics.

• דיווח על חריגות שלא נתפסו ועל חריגות שנתפסו אל Crashlytics.

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

• קבלת יומני נתיבי ניווט באופן אוטומטי אם האפליקציה משתמשת ב-Firebase SDK ל-Google Analytics. היומנים האלה מאפשרים לכם לראות את פעולות המשתמשים שהובילו לאירוע שנאסף באפליקציה שלכם על ידי Crashlytics.

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

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

דיווח על חריגים

דיווח על חריגים שלא זוהו

כדי לתפוס באופן אוטומטי את כל השגיאות החמורות שמוחזרות במסגרת Flutter, צריך להחליף את FlutterError.onError ב-FirebaseCrashlytics.instance.recordFlutterFatalError. לחלופין, כדי לזהות גם חריגים מסוג לא קריטית, מחליפים את FlutterError.onError ב-FirebaseCrashlytics.instance.recordFlutterError:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Firebase.initializeApp();
  bool weWantFatalErrorRecording = true;
  FlutterError.onError = (errorDetails) {
    if(weWantFatalErrorRecording){
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    } else {
      FirebaseCrashlytics.instance.recordFlutterError(errorDetails);
    }
  };

  runApp(MyApp());
}

שגיאות אסינכרוניות

שגיאות אסינכרוניות לא נתפסות על ידי מסגרת Flutter:

ElevatedButton(
  onPressed: () async {
    throw Error();
  }
  ...
)

כדי לזהות שגיאות כאלה, אפשר להשתמש ב-handler‏ PlatformDispatcher.instance.onError:

Future<void> main() async {
    WidgetsFlutterBinding.ensureInitialized();
    await Firebase.initializeApp();
    FlutterError.onError = (errorDetails) {
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    };
    // Pass all uncaught asynchronous errors that aren't handled by the Flutter framework to Crashlytics
    PlatformDispatcher.instance.onError = (error, stack) {
      FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
      return true;
    };
    runApp(MyApp());

}

שגיאות מחוץ ל-Flutter

כדי לזהות שגיאות שמתרחשות מחוץ להקשר של Flutter, מתקינים מאזין שגיאות ב-Isolate הנוכחי:

Isolate.current.addErrorListener(RawReceivePort((pair) async {
  final List<dynamic> errorAndStacktrace = pair;
  await FirebaseCrashlytics.instance.recordError(
    errorAndStacktrace.first,
    errorAndStacktrace.last,
    fatal: true,
  );
}).sendPort);

דיווח על חריגים שזוהו

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

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

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

await FirebaseCrashlytics.instance.recordError(
  error,
  stackTrace,
  reason: 'a non-fatal error'
);

// Or you can use:
await FirebaseCrashlytics.instance.recordFlutterError(errorDetails);

אפשר גם לרשום ביומן מידע נוסף על השגיאה באמצעות המאפיין information:

await FirebaseCrashlytics.instance.recordError(
  error,
  stackTrace,
  reason: 'a non-fatal error',
  information: ['further diagnostic information about the error', 'version 2.0'],
);

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

החריגים האלה מופיעים כבעיות לא קריטיות בלוח הבקרה DevOps & Engagement > Crashlytics במסוף Firebase. סיכום הבעיה מכיל את כל פרטי המצב שמתקבלים בדרך כלל מקריסות, וגם פירוטים לפי גרסה ומכשיר חומרה.

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

הוספת מפתחות בהתאמה אישית

מקשים בהתאמה אישית עוזרים לכם לקבל את המצב הספציפי של האפליקציה לפני הקריסה. אתם יכולים לשייך צמדים שרירותיים של מפתח וערך לדוחות קריסה, ואז להשתמש במפתחות המותאמים אישית כדי לחפש ולסנן דוחות קריסה בלוח הבקרה DevOps & Engagement > Crashlytics במסוף Firebase.

• במרכז הבקרה, אפשר לחפש בעיות שתואמות למפתח מותאם אישית.

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

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

משתמשים ב-instance method‏ setCustomKey כדי להגדיר צמדי מפתח/ערך. ריכזנו כאן כמה דוגמאות:

// Set a key to a string.
FirebaseCrashlytics.instance.setCustomKey('str_key', 'hello');

// Set a key to a boolean.
FirebaseCrashlytics.instance.setCustomKey("bool_key", true);

// Set a key to an int.
FirebaseCrashlytics.instance.setCustomKey("int_key", 1);

// Set a key to a long.
FirebaseCrashlytics.instance.setCustomKey("int_key", 1L);

// Set a key to a float.
FirebaseCrashlytics.instance.setCustomKey("float_key", 1.0f);

// Set a key to a double.
FirebaseCrashlytics.instance.setCustomKey("double_key", 1.0);

הוספה של הודעות יומן מותאמות אישית

כדי לקבל יותר הקשר לגבי האירועים שהובילו לקריסה, אפשר להוסיף יומנים מותאמים אישית לאפליקציה. Crashlytics משייך את היומנים לנתוני הקריסה ומציג אותם בכרטיסייה יומנים כשמציגים את פרטי הבעיה (אפשר לראות את כל הבעיות בלוח הבקרה DevOps & Engagement > Crashlytics במסוף Firebase).Crashlytics

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

מומלץ להשתמש בlog כדי לזהות בעיות. לדוגמה:

FirebaseCrashlytics.instance.log("Higgs-Boson detected! Bailing out");

הגדרת מזהי משתמשים

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

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

FirebaseCrashlytics.instance.setUserIdentifier("12345");

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

אחזור יומנים של נתיבי ניווט

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

היומנים של נתיבי הניווט מבוססים על Google Analytics, ולכן כדי לקבל אותם צריך להפעיל את Google Analytics בפרויקט Firebase ולהוסיף את Firebase SDK ל-Google Analytics לאפליקציה. אחרי שממלאים את הדרישות האלה, היומנים של נתיבי הניווט נכללים אוטומטית בנתוני האירועים בכרטיסייה יומנים כשמציגים את פרטי הבעיה (אפשר לראות את כל הבעיות בלוח הבקרה Crashlytics של DevOps & Engagement > Firebase).

ערכת ה-SDK של Analytics מתעדת באופן אוטומטי את האירוע screen_view, וכך מאפשרת לראות ביומני ה-breadcrumb רשימה של המסכים שנצפו לפני הקריסה, האירוע הלא קטלני או האירוע מסוג ANR. יומן של נתיב ניווט מכיל פרמטר firebase_screen_class.screen_view

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

חשוב לדעת שאתם יכולים לשלוט באיסוף ובשימוש בנתוני Google Analytics, כולל הנתונים שמאכלסים את יומני הנתיבים.

הפעלת דיווח על הסכמה

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

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

1. כדי להשבית את האיסוף האוטומטי באופן מקורי:

   פלטפורמות של Apple

   מוסיפים מפתח חדש לקובץ Info.plist:

   • מקש: FirebaseCrashlyticsCollectionEnabled
   • ערך: false

   Android

   בבלוק application בקובץ AndroidManifest.xml, מוסיפים תג meta-data כדי להשבית את האיסוף האוטומטי:

   <meta-data
       android:name="firebase_crashlytics_collection_enabled"
       android:value="false" />
   

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

   FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);
   

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

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

ניהול נתונים ב-Crash Insights

התובנות לגבי קריסות עוזרות לכם לפתור בעיות על ידי השוואה בין עקבות מחסנית (stack traces) אנונימיים שלכם לבין עקבות מאפליקציות אחרות ב-Firebase, ומודיעות לכם אם הבעיה שלכם היא חלק ממגמה רחבה יותר. במקרים רבים, Crash Insights אפילו מספק מקורות מידע שיעזרו לכם לנפות באגים בקריסה.

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

הערה: השבתת שיתוף הנתונים תגרום גם להסרת התובנות לגבי הבעיות שלכם. יכול להיות שיעברו עד 24 שעות עד שהשינויים ייכנסו לתוקף.

השלבים הבאים

• ייצוא הנתונים אל BigQuery או Cloud Logging לניתוח מתקדם ולתכונות כמו יצירת שאילתות על הנתונים, בניית מרכזי בקרה בהתאמה אישית והגדרת התראות מותאמות אישית.