بدء استخدام Crashlytics لنظام التشغيل Android

يوضّح هذا الدليل كيفية بدء استخدام Firebase Crashlytics في تطبيق Android.

بعد إعداد حزمة تطوير البرامج (SDK) لـ "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 وحزمة تطوير البرامج (SDK) لخدمة Crashlytics). لإكمال عملية الإعداد، عليك فرض عطل تجريبي لإرسال أول تقرير أعطال إلى Firebase.

1. أضِف Firebase إلى مشروع Android الخاص بك، في حال لم يسبق لك إجراء ذلك. إذا لم يكن لديك تطبيق Android، يمكنك تنزيل نموذج تطبيق.

2. مقترَح: للحصول تلقائيًا على سجلّات خطوات المستخدم لفهم الإجراءات التي أدّت إلى حدوث تعطّل أو حدث غير خطير أو حدث ANR، عليك تفعيل "Google Analytics" في مشروع Firebase.

   • إذا كنت بصدد إنشاء مشروع جديد في Firebase، فعِّل Google Analytics أثناء خطوات إنشاء المشروع.

   • إذا كنت تستخدم مشروع Firebase حاليًا لم يتم تفعيل Google Analytics فيه، يمكنك تفعيله في صفحة settings الإعدادات > عمليات الدمج ضمن وحدة تحكّم Firebase.

3. تأكَّد من أنّ تطبيقك يتضمّن الإصدارات الأدنى المطلوبة التالية:

   • ‫Gradle 8.0
   • الإصدار 8.1.0 من المكوّن الإضافي لنظام Gradle المتوافق مع Android
   • الإصدار 4.4.1 من المكوّن الإضافي Gradle لخدمات Google

الخطوة 1: إضافة حزمة تطوير البرامج (SDK) لـ "Crashlytics" إلى تطبيقك

للاستفادة من سجلّات خطوات المستخدم، يُرجى أيضًا إضافة حزمة Firebase SDK الخاصة بخدمة "Google Analytics" إلى تطبيقك، والتأكّد من تفعيل "إحصاءات Google" في مشروع 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")
}

الخطوة 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.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)، أضِف المكوّن الإضافي 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'
   }

الخطوة 3: فرض عطل تجريبي لإنهاء عملية الإعداد

لإكمال إعداد 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، انتقِل إلى عمليات التطوير والتفاعل > لوحة بيانات Crashlytics للتحقّق من تقرير الأعطال التجريبي.

   إذا أعدت تحميل وحدة التحكّم وما زال العطل التجريبي لا يظهر بعد خمس دقائق، يمكنك تفعيل تسجيل تصحيح الأخطاء لمعرفة ما إذا كان تطبيقك يرسل تقارير الأعطال.

هذا كل ما في الأمر! تراقب أداة Crashlytics الآن تطبيقك بحثًا عن الأعطال والأخطاء غير الفادحة وأخطاء ANR. انتقِل إلى لوحة بيانات Crashlytics للاطّلاع على جميع التقارير والإحصاءات والتحقيق فيها.

الخطوات التالية

• خصِّص إعدادات تقارير الأعطال من خلال إضافة ميزة الموافقة على إعداد التقارير والسجلّات والمفاتيح وتتبُّع الأخطاء غير الفادحة.

• يمكنك دمج تطبيقك مع Google Play لتتمكّن من فلترة تقارير الأعطال في تطبيق Android حسب قناة الإصدار في Google Play مباشرةً في لوحة بيانات Crashlytics. يتيح لك ذلك تركيز لوحة البيانات بشكل أفضل على إصدارات محدّدة.

• في "استوديو Android"، يمكنك عرض بيانات "Crashlytics" وفلترتها.

  • استخدِم نافذة أداة "تحليل جودة التطبيق" (AQI) في "استوديو Android" لعرض بيانات Crashlytics إلى جانب الرمز البرمجي، بدون الحاجة إلى التنقّل بين لوحة البيانات Crashlytics وبيئة التطوير المتكاملة (IDE) لبدء تصحيح الأخطاء في أهم المشاكل.
  • يمكنك الاطّلاع على كيفية استخدام نافذة "مؤشر جودة التطبيق" في مستندات "استوديو Android".
  • تسرّنا معرفة رأيك. أرسِل إلينا ملاحظاتك حول نافذة "مؤشر جودة الهواء" من خلال تقديم تقرير خطأ.

• تصدير بياناتك إلى BigQuery أو Cloud Logging للاستفادة من الميزات والتحليلات المتقدّمة، مثل الاستعلام عن بياناتك وإنشاء لوحات بيانات مخصّصة وإعداد تنبيهات مخصّصة