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


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

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

قبل البدء

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

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

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

    • إذا كنت بصدد إنشاء مشروع جديد على 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 plugin 3.3.4 والإصدارات الأحدث) لكي يتمكّن مشروعك من توليد رموز Flutter (ملفات dSYM) وتحميلها تلقائيًا إلى Crashlytics.

    • Android: استخدِم FirebaseCLI (الإصدار 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 لعرض جميع تقاريرك وإحصاءاتك والاطّلاع عليها.

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