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


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

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

قبل البدء

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

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

    • إذا لم يتم تفعيل Google Analytics في مشروعك الحالي على Firebase، يمكنك تفعيل 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 محدّثة، كما يضيف إلى تطبيقك المكوّن الإضافي Crashlytics Gradle المطلوب لنظام التشغيل Android.

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

    flutter run

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

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

    • Android: استخدِم Firebase CLI (الإصدار 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 Console للاطّلاع على عُطل الاختبار.

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


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

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