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

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

پس‌از راه‌اندازی کیت توسعه نرم‌افزار Firebase Crashlytics در برنامه‌تان، می‌توانید گزارش‌های خرابی جامع را در کنسول 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 و هم در IDE شما است (مانند افزودن فایل پیکربندی Firebase و کیت توسعه نرم‌افزار Crashlytics). برای تکمیل راه‌اندازی، باید خرابی آزمایشی را اجباری کنید تا اولین گزارش خرابی به 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:35.0.2"))

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

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

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

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