بدء استخدام Firebase Crashlytics

تشرح هذه المقالة للبدء السريع كيفية إعداد Firebase Crashlytics في تطبيقك باستخدام المكوّن الإضافي Crashlytics Flutter لتتمكن من الحصول على تقارير شاملة للأعطال في وحدة تحكُّم Firebase.

يتضمّن إعداد Crashlytics استخدام أداة سطر الأوامر وبيئة التطوير المتكاملة (IDE). لإنهاء الإعداد، سيلزمك فرض استثناء اختباري لإرسال تقرير الأعطال الأول إلى Firebase.

قبل البدء

  1. يمكنك ضبط إعدادات Firebase وإعدادها في مشروع Flutter، إذا لم يسبق لك إجراء ذلك.

  2. إجراء مقترَح: للحصول تلقائيًا على سجلّات شريط التنقّل لفهم إجراءات المستخدم التي تؤدي إلى تعطُّل أو حدث غير خطير أو خطأ ANR، يجب تفعيل "إحصاءات Google" في مشروعك على Firebase.

    • في حال عدم تفعيل "إحصاءات Google" على مشروعك الحالي في Firebase، يمكنك تفعيل "إحصاءات Google" من علامة تبويب عمليات الدمج ضمن > إعدادات المشروع في وحدة تحكُّم Firebase.

    • إذا كنت بصدد إنشاء مشروع جديد على Firebase، فعِّل "إحصاءات Google" أثناء سير عمل إنشاء المشروع.

    يُرجى العِلم أنّ سجلّات شريط التنقل متاحة لجميع أنظمة Android وApple الأساسية المتوافقة مع تطبيق Crashlytics (باستثناء نظام التشغيل WatchOS).

الخطوة 1: إضافة Crashlytics إلى مشروع Flutter

  1. من جذر مشروع Flutter، نفِّذ الأمر التالي لتثبيت المكوّن الإضافي Flutter في تطبيق Crashlytics.

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

    flutter pub add firebase_crashlytics && flutter pub add firebase_analytics

  2. من الدليل الجذري لمشروع Flutter، شغِّل الأمر التالي:

    flutterfire configure

    يؤدّي تشغيل هذا الأمر إلى التأكّد من أنّ إعدادات Firebase الخاصة بتطبيق Flutter محدّثة، وسيضيف المكوّن الإضافي المطلوب من Crashlytics Gradle إلى التطبيق على أجهزة Android.

  3. بعد اكتمال عملية الإنشاء، أعِد إنشاء مشروع Flutter:

    flutter run

  4. (اختياري) إذا كان مشروعك على Flutter يستخدِم العلامة --split-debug-info (بالإضافة إلى علامة --obfuscate أيضًا اختياريًا)، يجب اتّخاذ خطوات إضافية لعرض عمليات تتبُّع تسلسُل استدعاء الدوال البرمجية القابلة للقراءة لتطبيقاتك.

    • أنظمة Apple الأساسية: تأكَّد من أنّ مشروعك يستخدم إعدادات الإصدار المقترَحة (الإصدار 3.12.0 والإصدارات الأحدث من Flutter، والمكوّن الإضافي Crashlytics Flutter 3.3.4 والإصدارات الأحدث) ليتمكّن مشروعك من إنشاء رموز Flutter (ملفات dSYM) وتحميلها تلقائيًا إلى Crashlytics.

    • على أجهزة Android: استخدِم واجهة سطر الأوامر في Firebase (الإصدار 11.9.0 والإصدارات الأحدث) لتحميل رموز تصحيح أخطاء Flutter. عليك تحميل رموز تصحيح الأخطاء قبل الإبلاغ عن عُطل ناتج من إصدار رمز مُشفَّر.

      من الدليل الجذري لمشروع Flutter، نفِّذ الأمر التالي:

      firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/symbols

      • FIREBASE_APP_ID: رقم تعريف تطبيق Android في Firebase (وليس اسم الحزمة)
        مثال على رقم تعريف تطبيق Android في Firebase: 1:567383003300:android:17104a2ced0c9b9b

      • PATH/TO/symbols: الدليل نفسه الذي تمرره إلى علامة --split-debug-info عند إنشاء التطبيق

الخطوة 2: ضبط معالِجات الأعطال

يمكنك تلقائيًا رصد كل الأخطاء التي تظهر ضمن إطار عمل Flutter من خلال تجاوز FlutterError.onError باستخدام FirebaseCrashlytics.instance.recordFlutterFatalError:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Firebase.initializeApp();

  // Pass all uncaught "fatal" errors from the framework to Crashlytics
  FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError;

  runApp(MyApp());
}

لرصد الأخطاء غير المتزامنة التي لا يعالجها إطار عمل Flutter، يمكنك استخدام PlatformDispatcher.instance.onError:

Future<void> main() async {
    WidgetsFlutterBinding.ensureInitialized();
    await Firebase.initializeApp();
    FlutterError.onError = (errorDetails) {
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    };
    // Pass all uncaught asynchronous errors that aren't handled by the Flutter framework to Crashlytics
    PlatformDispatcher.instance.onError = (error, stack) {
      FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
      return true;
    };
    runApp(MyApp());

}

للحصول على أمثلة حول كيفية التعامل مع الأنواع الأخرى من الأخطاء، يُرجى الاطّلاع على تخصيص تقارير الأعطال.

الخطوة 3: فرض عطل في الاختبار لإنهاء عملية الإعداد

لإنهاء إعداد Crashlytics والاطّلاع على البيانات الأولية في لوحة بيانات Crashlytics بوحدة تحكم Firebase، يجب فرض استثناء اختباري ليتم طرحه.

  1. أضِف رمزًا إلى تطبيقك يمكنك استخدامه لفرض طرح استثناء تجريبي.

    إذا أضفت معالج أخطاء يستدعي FirebaseCrashlytics.instance.recordError(error, stack, fatal: true) إلى أعلى مستوى لـ Zone، يمكنك استخدام الرمز التالي لإضافة زر إلى تطبيقك يؤدي الضغط عليه إلى إنشاء استثناء اختبار:

    TextButton(
    onPressed: () => throw Exception(),
    child: const Text("Throw Test Exception"),
),

  2. أنشئ تطبيقك وشغِّله.

  3. فرض استثناء الاختبار لإرسال التقرير الأول لتطبيقك:

    1. افتح تطبيقك من جهاز الاختبار أو المحاكي.

    2. في تطبيقك، اضغط على زر "استثناء الاختبار" الذي أضفته باستخدام الرمز أعلاه.

  4. انتقِل إلى لوحة بيانات Crashlytics في وحدة تحكّم Firebase للاطّلاع على عطل الاختبار.

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


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

الخطوات اللاحقة