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


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

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

قبل البدء

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

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

    • إذا لم يكن مشروعك الحالي في Firebase يحتوي على Google Analytics مُفعَّل، يمكنك تفعيل "Google Analytics" من في علامة التبويب عمليات الدمج على إعدادات المشروع في وحدة التحكم Firebase.

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

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

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

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

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

    flutter pub add firebase_crashlytics && flutter pub add firebase_analytics

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

    flutterfire configure

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

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

    flutter run

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

    • أنظمة Apple الأساسية: تأكد من أن مشروعك يستخدم ضبط الإصدار (Flutter 3.12.0 أو الإصدارات الأحدث 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: رقم تعريف تطبيق Firebase لنظام التشغيل Android (وليس اسم الحزمة)
        مثال على رقم تعريف تطبيق Firebase لنظام التشغيل Android: 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 لعرض جميع تقاريرك وإحصاءاتك والاطّلاع عليها.

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