با Firebase Crashlytics شروع کنید


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

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

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

قبل از اینکه شروع کنی

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

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

    • اگر پروژه Firebase فعلی شما Google Analytics فعال نکرده است، می‌توانید Google Analytics از تب Integrations فعال کنید. > تنظیمات پروژه در کنسول Firebase .

    • اگر در حال ایجاد یک پروژه جدید Firebase هستید، در طول فرآیند ایجاد پروژه، Google Analytics فعال کنید.

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

    • گریدل ۸.۰
    • افزونه اندروید گریدل ۸.۱.۰
    • افزونه Gradle سرویس‌های گوگل نسخه ۴.۴.۱

مرحله 1 : Crashlytics SDK for NDK را به برنامه خود اضافه کنید

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

برای یک تجربه بهینه با Crashlytics ، توصیه می‌کنیم Google Analytics در پروژه Firebase خود فعال کنید و Firebase SDK را برای Google Analytics به برنامه خود اضافه کنید.

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:34.4.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 استفاده خواهد کرد.

(جایگزین) اضافه کردن وابستگی‌های کتابخانه 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.0.3")
    implementation("com.google.firebase:firebase-analytics:23.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.4.4" apply false

    // Add the dependency for the Crashlytics Gradle plugin
    id("com.google.firebase.crashlytics") version "3.0.6" 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.4' apply false

    // Add the dependency for the Crashlytics Gradle plugin
    id 'com.google.firebase.crashlytics' version '3.0.6' 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'
}

مرحله ۳ : افزونه 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 شامل وظیفه uploadCrashlyticsSymbolFile BUILD_VARIANT برای خودکارسازی این فرآیند است.

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

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

    >./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

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

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

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

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

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

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

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

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

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


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

مراحل بعدی

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

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

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

عیب‌یابی

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


گزینه‌های جایگزین برای آپلود نمادها

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

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

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

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

گزینه : نمادهای مربوط به نسخه‌های غیر Gradle یا کتابخانه‌های بومیِ بدون محدودیت دسترسی را آپلود کنید

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

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

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