بدء استخدام Firebase Crashlytics

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

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

قبل البدء

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

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

    • إذا لم يسبق لك تفعيل "إحصاءات Google" في مشروعك الحالي على Firebase، يمكنك تفعيل "إحصاءات Google" من علامة تبويب عمليات الدمج ضِمن > إعدادات المشروع في وحدة تحكُّم Firebase.

    • إذا كنت بصدد إنشاء مشروع جديد على Firebase، يمكنك تفعيل "إحصاءات Google" أثناء سير عمل إنشاء المشروع.

    يُرجى العلم أنّ سجلّات شريط التنقّل متاحة لجميع أنظمة Android وApple الأساسية المتوافقة مع Crashlytics (باستثناء نظام التشغيل WatchOS).

الخطوة 1: إضافة Crashlytics إلى مشروع Flutter

  1. من جذر مشروع Flutter، شغِّل الأمر التالي لتثبيت مكوّن Flutter الإضافي لنظام Crashlytics.

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

    • نظام التشغيل Android: استخدِم واجهة سطر الأوامر في 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 للاطّلاع على العطل التجريبي.

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


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

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