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

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

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

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

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

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

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

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

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

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

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

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

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

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.2.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.

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

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

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

פתרון בעיות

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

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

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

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

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

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

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

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

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

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