شروع به کار با Crashlytics برای Android NDK

انتخاب پلاتفرم: iOS+ Android Android NDK Flutter Unity


اگر از کتابخانه‌های بومی در برنامه Android خود استفاده می‌کنید، می‌توانید با چند به‌روزرسانی کوچک در پیکربندی ساخت برنامه‌تان، ردیابی‌های پشته کامل و گزارش‌های خرابی دقیق را برای کد بومی خود از Firebase Crashlytics فعال کنید.

این راهنما نحوه پیکربندی گزارش‌دهی خرابی با Firebase Crashlytics SDK برای NDK را شرح می‌دهد.

اگر به‌دنبال نحوه شروع به کار با Crashlytics در پروژه‌های Unity خود هستید، راهنمای شروع به کار Unity را بررسی کنید.

قبل از شروع

  1. اگر قبلاً این کار را نکرده‌اید، Firebase را به پروژه Android خود اضافه کنید. اگر برنامه Android ندارید، می‌توانید برنامه نمونه بارگیری کنید.

  2. توصیه‌شده: برای دریافت خودکار گزارش‌های ردپای رخدادها جهت درک کنش‌های کاربر که منجر به خرابی، رویداد غیرکشنده، یا ANR می‌شود، باید Google Analytics را در پروژه Firebase خود فعال کنید.

    • اگر پروژه Firebase جدیدی ایجاد می‌کنید، Google Analytics را درطول گردش کار ایجاد پروژه فعال کنید.

    • اگر از پروژه Firebase موجودی استفاده می‌کنید که Google Analytics در آن فعال نیست، می‌توانید آن را در تنظیمات > صفحه ادغام‌ها کنسول Firebase فعال کنید.

  3. مطمئن شوید برنامه‌تان حداقل نسخه‌های لازم زیر را داشته باشد:

    • Gradle 8.0
    • افزایه Android Gradle نسخه ۸.۱.۰
    • افزایه Gradle خدمات Google نسخه ۴.۴.۱

مرحله ۱: کیت توسعه نرم‌افزار Crashlytics برای NDK را به برنامه‌تان اضافه کنید

در فایل Gradle (سطح برنامه) واحد (معمولاً <project>/<app-module>/build.gradle.kts یا <project>/<app-module>/build.gradle)، وابستگی را برای Crashlytics کتابخانه NDK برای Android اضافه کنید. توصیه می‌کنیم از Firebase Android BoM برای کنترل نسخه‌بندی کتابخانه استفاده کنید.

برای داشتن تجربه بهینه با Crashlytics، توصیه می‌کنیم Google Analytics را فعال کنید در پروژه Firebase خود و افزودن کیت توسعه نرم‌افزار Firebase برای 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 استفاده خواهد کرد.

(جایگزین)  افزودن وابستگی‌های کتابخانه 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:21.0.0")
    implementation("com.google.firebase:firebase-analytics:24.0.0")
}

مرحله ۲: افزونه 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.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)، افزایه Gradle Crashlytics را اضافه کنید:

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

مرحله ۳: افزونه Crashlytics را به ساخت خود اضافه کنید

در فایل 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
          }
      }
  }
}

مرحله ۴: راه‌اندازی بارگذاری خودکار نمادهای بومی

برای تولید ردیابی‌های پشته خوانا از خرابی‌های NDK،‏ Crashlytics باید از نمادهای موجود در باینری‌های بومی شما مطلع باشد. افزونه Gradle Crashlytics شامل تکلیف uploadCrashlyticsSymbolFileBUILD_VARIANT برای خودکارسازی این فرایند است.

  1. برای اینکه بتوانید به تکلیف بارگذاری خودکار نماد دسترسی داشته باشید، مطمئن شوید که nativeSymbolUploadEnabled در فایل Gradle واحدتان (سطح برنامه) روی true تنظیم شده باشد.

  2. برای اینکه نام‌های روش در ردیابی پشته شما نشان داده شود، باید صریحاً تکلیف uploadCrashlyticsSymbolFileBUILD_VARIANT را پس‌از هر ساخت کتابخانه NDK خود فراخوانی کنید. برای مثال:

    >./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

  3. هم Crashlytics SDK برای NDK و هم افزونه Crashlytics Gradle به وجود شناسه ساخت GNU در اشیای هم‌رسانی‌شده بومی بستگی دارند.

    می‌توانید با اجرای readelf -n روی هر باینری، وجود این شناسه را درستی‌سنجی کنید. اگر شناسه ساخت وجود ندارد، -Wl,--build-id را به پرچم‌های سیستم ساختتان اضافه کنید تا مشکل برطرف شود.

مرحله ۵: برای تکمیل راه‌اندازی، خرابی آزمایشی را اجباری کنید

برای تکمیل راه‌اندازی Crashlytics و دیدن داده‌های اولیه در داشبورد Crashlytics در کنسول Firebase، باید یک خرابی آزمایشی را اجباراً ایجاد کنید.

  1. کدی را به برنامه‌تان اضافه کنید که بتوانید از آن برای ایجاد خرابی آزمایشی استفاده کنید.

    می‌توانید از کد زیر در MainActivity برنامه‌تان استفاده کنید تا دکمه‌ای به برنامه‌تان اضافه کنید که با فشار دادن آن، برنامه از کار بیفتد. دکمه با برچسب «آزمایش خرابی» مشخص شده است.

    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. در برنامه‌تان، دکمه «آزمایش خرابی» را که بااستفاده از کد بالا اضافه کردید فشار دهید.

    3. پس‌از خرابی برنامه، آن را بازراه‌اندازی کنید تا برنامه بتواند گزارش خرابی را به Firebase ارسال کند.

  4. در کنسول Firebase، به داشبورد DevOps و تعامل > Crashlytics بروید تا گزارش خرابی آزمایشی را بررسی کنید.

    اگر کنسول را بازآوری کرده‌اید و هنوز خرابی آزمایشی را پس‌از پنج دقیقه نمی‌بینید، ثبت اشکال‌زدایی را فعال کنید تا ببینید آیا برنامه‌تان گزارش‌های خرابی را ارسال می‌کند یا نه.


همین! Crashlytics اکنون برنامه شما را ازنظر خرابی پایش می‌کند و می‌توانید گزارش‌ها و آمار خرابی را در داشبورد Crashlytics مشاهده و بررسی کنید.

مراحل بعدی

  • (توصیه‌شده) با جمع‌آوری گزارش‌های GWP-ASan، برای اشکال‌زدایی خرابی‌های ناشی از خطاهای حافظه محلی راهنمایی دریافت کنید. این خطاهای مربوط به حافظه می‌تواند با خرابی حافظه در برنامه شما مرتبط باشد که علت اصلی آسیب‌پذیری‌های امنیتی برنامه است. برای بهره‌مندی از این ویژگی اشکال‌زدایی، مطمئن شوید که برنامه‌تان GWP-ASan را به‌طور صریح فعال کرده باشد و از جدیدترین Crashlytics کیت توسعه نرم‌افزار برای NDK (نسخه ۱۸.۳.۶+ یا Firebase BoM نسخه ۳۱.۳.۰+) استفاده کند.

  • راه‌اندازی گزارش خرابی را سفارشی‌سازی کنید با افزودن گزارش‌دهی موافقت‌شده، گزارش‌ها، کلیدها، و ردیابی خطاهای غیرمهلک.

  • با Google Play ادغام کنید تا بتوانید گزارش‌های خرابی برنامه Android خود را براساس دسته هدف Google Play مستقیماً در داشبورد Crashlytics فیلتر کنید. این کار به شما امکان می‌دهد داشبوردتان را بهتر روی ساخت‌های خاص متمرکز کنید.

عیب‌یابی

اگر ردیابی‌های پشته متفاوتی در کنسول Firebase و در logcat می‌بینید، به راهنمای عیب‌یابی مراجعه کنید.


گزینه‌های جایگزین برای بارگذاری نمادها

گردش کار اصلی در این صفحه بالا برای ساخت‌های استاندارد Gradle قابل‌اجرا است. بااین‌حال، برخی‌از برنامه‌ها از پیکربندی یا ابزار متفاوتی استفاده می‌کنند (برای مثال، فرایند ساخت متفاوتی نسبت‌به Gradle). در این شرایط، گزینه‌های زیر ممکن است برای بارگذاری موفقیت‌آمیز نمادها مفید باشد.

گزینه: بارگذاری نمادها برای واحدهای کتابخانه و وابستگی‌های خارجی

این گزینه می‌تواند در شرایط زیر مفید باشد:

  • اگر از فرایند ساخت NDK سفارشی‌شده در Gradle استفاده می‌کنید
  • اگر کتابخانه‌های بومی شما در یک واحد ویژگی/کتابخانه ساخته شده‌اند یا توسط شخص ثالثی ارائه شده‌اند
  • اگر تکلیف بارگذاری خودکار نماد ناموفق است یا خرابی‌های بدون نماد در Crashlytics داشبورد می‌بینید

گزینه: بارگذاری نمادها برای ساخت‌های غیرGradle یا کتابخانه‌های بومی غیرقابل‌دسترس و حذف‌نشده

این گزینه می‌تواند در شرایط زیر مفید باشد:

  • اگر از فرایند ساخت دیگری به‌غیراز Gradle استفاده می‌کنید

  • اگر کتابخانه‌های بومی غیرپاک‌سازی‌شده شما به‌گونه‌ای به شما ارائه شده‌اند که درطول ساخت Gradle دردسترس نیستند