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

این راهنما نحوه شروع کار با Firebase Crashlytics در برنامه Android را توضیح می‌دهد.

پس‌از راه‌اندازی Firebase Crashlytics SDK در برنامه‌تان، می‌توانید گزارش‌های خرابی جامع را در کنسول Firebase دریافت کنید. با Crashlytics برای Android، گزارش‌هایی برای خرابی‌ها، خطاهای غیرمهلک، و خطاهای «برنامه پاسخ نمی‌دهد» (ANR) دریافت می‌کنید.

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`. Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me set up Firebase Crashlytics for my app.

قبل از شروع

راه‌اندازی Crashlytics هم در کنسول Firebase و هم در محیط توسعه یکپارچه شما (مثل افزودن فایل پیکربندی Firebase و کیت توسعه نرم‌افزار Crashlytics SDK) نیازمند انجام تکلیف است. برای تکمیل راه‌اندازی، باید خرابی آزمایشی اجباری ایجاد کنید تا اولین گزارش خرابی را به Firebase ارسال کنید.

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

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

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

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

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

   • ‫Gradle 8.0
   • افزایه Android Gradle نسخه ۸.۱.۰
   • افزایه Gradle سرویس‌های Google نسخه ۴.۴.۱

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

برای بهره‌مندی از گزارش‌های ردیابی، «کیت توسعه نرم‌افزار Firebase» را نیز برای Google Analytics به برنامه‌تان اضافه کنید. مطمئن شوید که Google Analytics در پروژه Firebase شما فعال باشد.

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:34.19.0"))

    // Add the dependencies for the Crashlytics and Analytics libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-crashlytics")
    implementation("com.google.firebase:firebase-analytics")
}

بااستفاده از Firebase Android BoM، برنامه شما همیشه از نسخه‌های سازگار کتابخانه‌های Firebase Android استفاده خواهد کرد.

dependencies {
    // Add the dependencies for the Crashlytics and Analytics libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-crashlytics: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 و دیدن داده‌های اولیه در داشبورد 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 اکنون برنامه شما را برای خرابی‌ها، خطاهای غیرمهلک، و خطاهای ANR پایش می‌کند. برای مشاهده و بررسی همه گزارش‌ها و آمار خود، به Crashlytics داشبورد مراجعه کنید.

مراحل بعدی

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

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

• در «استودیو Android»، داده‌های Crashlytics را مشاهده و فیلتر کنید.

  • از پنجره اطلاعات آماری کیفیت برنامه (AQI) در «استودیو Android» استفاده کنید تا Crashlytics داده‌ها را در کنار کدتان مشاهده کنید — دیگر نیازی نیست برای شروع اشکال‌زدایی مشکلات برتر، بین Crashlytics داشبورد و IDE جابه‌جا شوید.
  • در مستندات «استودیو Android»، با نحوه استفاده از پنجره AQI آشنا شوید.
  • مشتاقیم نظرتان را بشنویم! با ثبت گزارش اشکال، بازخوردتان را درباره پنجره «شاخص کیفیت هوا» برای ما ارسال کنید.

• داده‌هایتان را به BigQuery یا Cloud Logging صادر کنید تا از تجزیه‌وتحلیل و ویژگی‌های پیشرفته، مثل پرسش از داده‌ها، ساختن داشبوردهای سفارشی، و راه‌اندازی هشدارهای سفارشی بهره‌مند شوید.