بدء استخدام 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. تأكَّد من أنّ تطبيقك يتضمّن الحد الأدنى من الإصدارات المطلوبة التالية:

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

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

للاستفادة من سجلّ خطوات المستخدم، أضِف أيضًا حزمة 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 block:

   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 ومعدّل الاهتمام بالتطبيق > لوحة بيانات Crashlytics للبحث عن تقرير الأعطال التجريبي.

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

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

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

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

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

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

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

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