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

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


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

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

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

قبل البدء

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

  2. مقترَح: للحصول تلقائيًا على سجلّات خطوات المستخدم لفهم الإجراءات التي أدّت إلى حدوث تعطّل أو حدث غير خطير أو حدث ANR، عليك تفعيل "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: تأكَّد من أنّ مشروعك يستخدم إعدادات الإصدار المقترَحة (Flutter 3.12.0 والإصدارات الأحدث وCrashlytics المكوّن الإضافي Flutter 3.3.4 والإصدارات الأحدث) ليتمكّن مشروعك من إنشاء رموز 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. في وحدة تحكّم Firebase، انتقِل إلى عمليات التطوير والتفاعل > لوحة بيانات Crashlytics للتحقّق من تقرير الأعطال التجريبي.

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


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

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