קבלת דוחות קריסה של Android NDK

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

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

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

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

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

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

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

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

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

    • Gradle 8.0
    • פלאגין Android Gradle גרסה 8.1.0
    • פלאגין Gradle של שירותי Google 4.4.1

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

בקובץ Gradle של המודול (ברמת האפליקציה) (בדרך כלל <project>/<app-module>/build.gradle.kts או <project>/<app-module>/build.gradle), מוסיפים את התלות בספריית ה-NDK Crashlytics ל-Android. מומלץ להשתמש ב-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:33.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, האפליקציה שלכם תשתמש תמיד בגרסאות תואמות של ספריות Android של Firebase.

(חלופה)  מוסיפים יחסי תלות לספריות של 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:19.1.0")
    implementation("com.google.firebase:firebase-analytics:22.1.0")
}
מחפשים מודול ספרייה ספציפי ל-Kotlin? מתחיל בעוד אוקטובר 2023 (Firebase BoM 32.5.0), גם מפתחי Kotlin וגם מפתחי Java יכולים תלויות במודול הספרייה הראשי (לקבלת פרטים נוספים, אפשר לעיין שאלות נפוצות על היוזמה).

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

  1. בקובץ Gradle ברמת הבסיס (ברמת הפרויקט) (<project>/build.gradle.kts או <project>/build.gradle), מוסיפים את הפלאגין Crashlytics ל-Gradle לבלוק 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.2" apply false

    // Add the dependency for the Crashlytics Gradle plugin
    id("com.google.firebase.crashlytics") version "3.0.2" 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.2' apply false

    // Add the dependency for the Crashlytics Gradle plugin
    id 'com.google.firebase.crashlytics' version '3.0.2' 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)

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

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: מגדירים העלאה אוטומטית של סמלים מותאמים

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

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

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

    >./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

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

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

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

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

  1. מוסיפים לאפליקציה קוד שבעזרתו אפשר לאלץ קריסה לצורך בדיקה.

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

    Kotlin+KTX 

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

    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. כך תוכלו להתמקד טוב יותר בלוחות הבקרה ב-builds ספציפיים.

פתרון בעיות

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


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

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

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

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

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

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

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

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

  • אם ספריות ה-Native של הילדים סופקו לכם בדרך כלשהי, אין גישה אליהם במהלך ה-build של Gradle