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

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


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

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

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

قبل البدء

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

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

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

    • إذا كنت تستخدم مشروع Firebase حاليًا لم يتم تفعيل Google Analytics فيه، يمكنك تفعيله في صفحة الإعدادات > عمليات الدمج في Firebase Console.

    يُرجى العِلم أنّ سجلّات تتبُّع الأخطاء متاحة لجميع منصات 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 CLI (الإصدار 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 dashboard of the Firebase console، عليك فرض ظهور استثناء اختبار.

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

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

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

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

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

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

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

  4. في Firebase Console، انتقِل إلى لوحة بيانات DevOps والتفاعل > Crashlytics للبحث عن تقرير العطل الاختباري.

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


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

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