תחילת העבודה עם Crashlytics ל-Android NDK

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

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

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

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

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

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

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

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

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

   • ‫Gradle בגרסה 8.0
   • פלאגין של Android Gradle‏ ‎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:35.0.2"))

    // 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:21.0.0")
    implementation("com.google.firebase:firebase-analytics:24.0.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.5.0" apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id("com.google.firebase.crashlytics") version "3.0.8" 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.5.0' apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id 'com.google.firebase.crashlytics' version '3.0.8' 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.

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

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

2. כדי ששמות השיטות יופיעו בדוחות הקריסות, צריך להפעיל באופן מפורש את המשימה uploadCrashlyticsSymbolFileBUILD_VARIANT אחרי כל גרסה של ספריית ה-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 של האפליקציה כדי להוסיף לה לחצן שגורם לקריסה כשלוחצים עליו. הכפתור מסומן בתווית "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. במסוף Firebase, נכנסים לדף DevOps & Engagement (DevOps ומעורבות) > לוח הבקרה של Crashlytics כדי לבדוק את דוח הקריסה לבדיקה.

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

וזהו! ‫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, עיינו במדריך לפתרון בעיות.

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

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

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

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

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

אפשרות: העלאת סמלים ל-builds שאינם של Gradle או לספריות Native לא מופשטות שאינן נגישות

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

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

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