بدء استخدام 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 من المكوّن الإضافي لخدمات Google في Gradle

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

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

الخطوة 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وحدة التحكّم، انتقِل إلى DevOps & Engagement > Crashlyticsلوحة البيانات للبحث عن تقرير تعطل الاختبار.

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

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

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

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

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

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

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

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