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

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


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

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

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

قبل البدء

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

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

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


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

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