بدء استخدام Crashlytics لنظام Flutter

اختيار المنصة: iOS+ Android Android NDK Flutter Unity


يشرح هذا الدليل كيفية البدء باستخدام Firebase Crashlytics في تطبيق Flutter.

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

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

قبل البدء

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

  2. ملاحظة مهمة: للحصول تلقائيًا على سجلّات مسار التنفيذ لفهم إجراءات المستخدم التي أدّت إلى حدوث عطل أو خطأ غير فادح أو حدث "التطبيق لا يستجيب"، عليك تفعيل 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 محدّثة، ويضيف مكوّن Gradle الإضافي المطلوب إلى تطبيقك على Android.Crashlytics

  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 واجهة سطر الأوامر في 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 للاطّلاع على العطل التجريبي.CrashlyticsFirebase

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


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

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