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

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

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

يتطلّب إعداد 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.12.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.0.5")
    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.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".
  • يسرّنا تلقّي ملاحظاتك. أرسِل إلينا ملاحظاتك حول نافذة AQI من خلال تسجيل تقرير عن خطأ.

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