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

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

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

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

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

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

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

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

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

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

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

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

כדי ליהנות מחוויה אופטימלית עם 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.6.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.

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.2.1")
    implementation("com.google.firebase:firebase-analytics:22.1.2")
}

שלב 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 בקובץ 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).

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
          }
      }
  }
}

// ...

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 צריך להיות מידע על הסמלים בקובצי הבינארי הנוכחיים. הפלאגין Crashlytics של Gradle כולל את המשימה uploadCrashlyticsSymbolFileBUILD_VARIANT כדי לבצע אוטומציה של התהליך הזה.

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

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

   >./gradlew app:assembleBUILD_VARIANT\
              app:uploadCrashlyticsSymbolFileBUILD_VARIANT

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

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

שלב 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 או לספריות מקוריות לא שהוסר מהן הקוד שאינו נדרש (stripped) ולא ניתן לגשת אליהן

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

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

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