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


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

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

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

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

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

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

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

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

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

    • Gradle 8.0
    • פלאגין Android Gradle‏ 8.1.0
    • פלאגין Google services Gradle 4.4.1

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

בקובץ Gradle של המודול (ברמת האפליקציה) (בדרך כלל <project>/<app-module>/build.gradle.kts או <project>/<app-module>/build.gradle), מוסיפים את התלות בספריית NDK ל-Android‏ Crashlytics. מומלץ להשתמש ב-Firebase Android BoM כדי לשלוט בניהול הגרסאות של הספריות.

כדי ליהנות מחוויה אופטימלית עם Crashlytics, מומלץ להפעיל את Google Analytics בפרויקט Firebase ולהוסיף את Firebase SDK for Google Analytics לאפליקציה. 

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:34.3.0"))

    // Add the dependencies for the Crashlytics NDK and Analytics libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-crashlytics-ndk")
    implementation("com.google.firebase:firebase-analytics")
}

באמצעות Firebase Android BoM, האפליקציה תמיד תשתמש בגרסאות תואמות של ספריות Firebase ל-Android.

(חלופה)  מוסיפים תלות בספריית Firebase בלי להשתמש ב-BoM

אם בוחרים לא להשתמש ב-Firebase BoM, צריך לציין כל גרסה של ספריית Firebase בשורת התלות שלה.

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

dependencies {
    // Add the dependencies for the Crashlytics NDK and Analytics libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-crashlytics-ndk:20.0.2")
    implementation("com.google.firebase:firebase-analytics:23.0.0")
}

שלב 2: מוסיפים את הפלאגין Crashlytics Gradle לאפליקציה

  1. בקובץ Gradle ברמת הבסיס (ברמת הפרויקט) (<project>/build.gradle.kts או <project>/build.gradle), מוסיפים את פלאגין Gradle‏ Crashlytics לבלוק plugins:

    Kotlin 

    plugins {
    // Make sure that you have the AGP plugin 8.1+ dependency
    id("com.android.application") version "8.1.4" apply false
    // ...

    // Make sure that you have the Google services Gradle plugin 4.4.1+ dependency
    id("com.google.gms.google-services") version "4.4.3" apply false

    // Add the dependency for the Crashlytics Gradle plugin
    id("com.google.firebase.crashlytics") version "3.0.6" apply false
}

    Groovy 

    plugins {
    // Make sure that you have the AGP plugin 8.1+ dependency
    id 'com.android.application' version '8.1.4' apply false
    // ...

    // Make sure that you have the Google services Gradle plugin 4.4.1+ dependency
    id 'com.google.gms.google-services' version '4.4.3' apply false

    // Add the dependency for the Crashlytics Gradle plugin
    id 'com.google.firebase.crashlytics' version '3.0.6' apply false
}

  2. בקובץ Gradle של המודול (ברמת האפליקציה) (בדרך כלל <project>/<app-module>/build.gradle.kts או <project>/<app-module>/build.gradle), מוסיפים את הפלאגין Crashlytics Gradle:

    Kotlin 

    plugins {
  id("com.android.application")
  // ...

  // Make sure that you have the Google services Gradle plugin
  id("com.google.gms.google-services")

  // Add the Crashlytics Gradle plugin
  id("com.google.firebase.crashlytics")
}

    Groovy 

    plugins {
  id 'com.android.application'
  // ...

  // Make sure that you have the Google services Gradle plugin
  id 'com.google.gms.google-services'

  // Add the Crashlytics Gradle plugin
  id 'com.google.firebase.crashlytics'
}

שלב 3: הוספת התוסף Crashlytics אל ה-build

בקובץ Gradle של המודול (ברמת האפליקציה) (בדרך כלל <project>/<app-module>/build.gradle.kts או <project>/<app-module>/build.gradle), מגדירים את התוסף Crashlytics.

Kotlin 

import com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension

// ...

android {
  // ...
  buildTypes {
      getByName("release") {
          // Add this extension
          configure<CrashlyticsExtension> {
              // Enable processing and uploading of native symbols to Firebase servers.
              // By default, this is disabled to improve build speeds.
              // This flag must be enabled to see properly-symbolicated native
              // stack traces in the Crashlytics dashboard.
              nativeSymbolUploadEnabled = true
          }
      }
  }
}

Groovy 

// ...

android {
  // ...
  buildTypes {
      release {
          // Add this extension
          firebaseCrashlytics {
              // Enable processing and uploading of native symbols to Firebase servers.
              // By default, this is disabled to improve build speeds.
              // This flag must be enabled to see properly-symbolicated native
              // stack traces in the Crashlytics dashboard.
              nativeSymbolUploadEnabled true
          }
      }
  }
}

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

כדי ליצור קובצי Stack Trace שניתן לקרוא אותם מקריסות של NDK, ‏ Crashlytics צריך לדעת על הסמלים בקבצים הבינאריים המקוריים שלכם. התוסף Crashlytics Gradle כולל את המשימה uploadCrashlyticsSymbolFileBUILD_VARIANT לאוטומציה של התהליך הזה.

  1. כדי שתוכלו לגשת למשימה של העלאה אוטומטית של סמלים, ודאו שהערך של nativeSymbolUploadEnabled מוגדר ל-true בקובץ Gradle של המודול (ברמת האפליקציה).

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

    >./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

  3. גם Crashlytics SDK for NDK וגם Crashlytics Gradle plugin תלויים בנוכחות של מזהה ה-build של GNU באובייקטים המשותפים המקוריים.

    כדי לוודא שהמזהה הזה קיים, מריצים את הפקודה readelf -n בכל קובץ בינארי. אם מזהה ה-build לא מופיע, מוסיפים את -Wl,--build-id לדגלים של מערכת ה-build כדי לפתור את הבעיה.

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

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

  1. מוסיפים לאפליקציה קוד שאפשר להשתמש בו כדי לגרום לקריסת בדיקה.

    אפשר להשתמש בקוד הבא ב-MainActivity של האפליקציה כדי להוסיף לאפליקציה לחצן שגורם לקריסה כשלוחצים עליו. התווית של הלחצן היא Test Crash (בדיקת קריסה).

    Kotlin 

    val crashButton = Button(this)
crashButton.text = "Test Crash"
crashButton.setOnClickListener {
   throw RuntimeException("Test Crash") // Force a crash
}

addContentView(crashButton, ViewGroup.LayoutParams(
       ViewGroup.LayoutParams.MATCH_PARENT,
       ViewGroup.LayoutParams.WRAP_CONTENT))

    Java 

    Button crashButton = new Button(this);
crashButton.setText("Test Crash");
crashButton.setOnClickListener(new View.OnClickListener() {
   public void onClick(View view) {
       throw new RuntimeException("Test Crash"); // Force a crash
   }
});

addContentView(crashButton, new ViewGroup.LayoutParams(
       ViewGroup.LayoutParams.MATCH_PARENT,
       ViewGroup.LayoutParams.WRAP_CONTENT));

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

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

    1. פותחים את האפליקציה במכשיר הבדיקה או באמולטור.

    2. באפליקציה, לוחצים על הלחצן Test Crash (בדיקת קריסה) שהוספתם באמצעות הקוד שלמעלה.

    3. אחרי שהאפליקציה קורסת, מפעילים אותה מחדש כדי שהיא תוכל לשלוח את דוח הקריסה ל-Firebase.

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

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


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

השלבים הבאים

  • (מומלץ) כדי לקבל עזרה בניפוי באגים בקריסות שנגרמות משגיאות זיכרון נייטיב, אוספים דוחות GWP-ASan. השגיאות האלה שקשורות לזיכרון יכולות להיות משויכות להשחתת זיכרון באפליקציה, שזה הגורם העיקרי לפרצות אבטחה באפליקציות. כדי להשתמש בתכונת הניפוי באגים הזו, צריך לוודא שבאפליקציה הופעלה באופן מפורש GWP-ASan ושהיא משתמשת בגרסה העדכנית ביותר של Crashlytics SDK ל-NDK (גרסה 18.3.6 ואילך או Firebase BoM גרסה 31.3.0 ואילך).

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

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

פתרון בעיות

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


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

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

אפשרות: העלאת סמלים למודולים של ספריות ולתלות חיצונית

האפשרות הזו יכולה לעזור במקרים הבאים:

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

אפשרות: העלאת סמלים לגרסאות build שאינן Gradle או לספריות מקוריות לא נגישות ולא מוסרות

האפשרות הזו יכולה לעזור במקרים הבאים:

  • אם אתם משתמשים בתהליך build שאינו Gradle

  • אם ספריות Native לא מופשטות מסופקות לכם באופן שלא מאפשר גישה אליהן במהלך בניית Gradle