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

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

بعد إعداد Firebase Crashlytics SDK في تطبيقك، يمكنك الحصول على تقارير شاملة عن الأعطال في وحدة تحكّم Firebase. باستخدام Crashlytics لنظام التشغيل Android، يمكنك الحصول على تقارير عن الأعطال والأخطاء غير المميتة وأخطاء "التطبيق لا يستجيب" (ANR).

يتطلّب إعداد 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: إضافة حزمة تطوير البرامج (SDK) الخاصة بـ Crashlytics إلى تطبيقك

للاستفادة من سجلّات مسار التنفيذ، أضِف أيضًا Firebase SDK لـ Google Analytics إلى تطبيقك. تأكَّد من تفعيل "إحصاءات Google" في مشروع Firebase.

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

    // 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.0.6")
    implementation("com.google.firebase:firebase-analytics:23.2.0")
}

الخطوة 2: إضافة Crashlytics Gradle plugin إلى تطبيقك

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.4.4" apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id("com.google.firebase.crashlytics") version "3.0.7" 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.4.4' apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id 'com.google.firebase.crashlytics' version '3.0.7' 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".
  • يسرّنا معرفة رأيك، لذا يُرجى إرسال ملاحظاتك بشأن نافذة "مؤشر جودة الهواء" من خلال تقديم تقرير عن خطأ.

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