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

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

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

يتطلّب إعداد Crashlytics تنفيذ مهام في كلّ من وحدة تحكّم Firebase وبيئة التطوير المتكاملة (IDE) (مثل إضافة ملف إعداد 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.17.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.0")
    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.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.5.0' 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 console، عليك فرض حدوث عطل اختباري.

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 لإجراء تحليل متقدّم والاستفادة من ميزات متقدّمة، مثل طلب بياناتك وإنشاء لوحات بيانات مخصّصة وإعداد تنبيهات مخصّصة.