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

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


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

این راهنما نحوه پیکربندی گزارش خرابی با کیت توسعه نرم‌افزار Firebase Crashlytics برای 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:34.19.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 استفاده خواهد کرد.

(جایگزین)  افزودن وابستگی‌های کتابخانه 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:20.1.1")
    implementation("com.google.firebase:firebase-analytics:23.2.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 باید درباره نمادهای موجود در باینری‌های بومی شما بداند. افزایه Crashlytics Gradle شامل تکلیف uploadCrashlyticsSymbolFileBUILD_VARIANT برای خودکارسازی این فرایند است.

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

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

    >./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

  3. هم کیت توسعه نرم‌افزار Crashlytics برای 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 خود را مستقیماً در داشبورد Crashlytics براساس مسیر Google Play فیلتر کنید. این کار به شما امکان می‌دهد داشبوردتان را بهتر روی ساخت‌های خاصی متمرکز کنید.

عیب‌یابی

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


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

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

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

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

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

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

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

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

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