بدء استخدام 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 أثناء خطوات إنشاء المشروع.

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

    يُرجى العِلم أنّ سجلّات تتبُّع الأخطاء متاحة لجميع منصات 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 واجهة سطر الأوامر في 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. في وحدة تحكّم Firebase، انتقِل إلى لوحة بيانات DevOps & Engagement > Crashlytics للبحث عن تقرير عطل الاختبار.

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


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

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