تخصيص تقارير أعطال Firebase في Crashlytics

في لوحة بيانات Crashlytics، يمكنك النقر على مشكلة والحصول على تقرير مفصل عن الحدث. يمكنك تخصيص هذه التقارير لمساعدتك على فهم ما يحدث في تطبيقك بشكل أفضل والظروف المحيطة بالأحداث التي تم إبلاغ Crashlytics بها.

الإبلاغ عن الاستثناءات غير المرصودة

يمكنك تلقائيًا اكتشاف جميع الأخطاء "الفادحة" التي تظهر ضمن إطار عمل Flutter، من خلال إلغاء FlutterError.onError باستخدام FirebaseCrashlytics.instance.recordFlutterFatalError. بدلاً من ذلك، لرصد الاستثناءات "غير الفادحة" أيضًا، استخدِم FirebaseCrashlytics.instance.recordFlutterError بدلاً من FlutterError.onError:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Firebase.initializeApp();
  bool weWantFatalErrorRecording = true;
  FlutterError.onError = (errorDetails) {
    if(weWantFatalErrorRecording){
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    } else {
      FirebaseCrashlytics.instance.recordFlutterError(errorDetails);
    }
  };

  runApp(MyApp());
}

أخطاء غير متزامنة

لا يرصد إطار عمل Flutter الأخطاء غير المتزامنة:

ElevatedButton(
  onPressed: () async {
    throw Error();
  }
  ...
)

لاكتشاف هذه الأخطاء، يمكنك استخدام معالج 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());

}

الأخطاء خارج Flutter

لرصد الأخطاء التي تحدث خارج سياق Flutter، يمكنك تثبيت أداة تقرير الأخطاء على Isolate الحالي:

Isolate.current.addErrorListener(RawReceivePort((pair) async {
  final List<dynamic> errorAndStacktrace = pair;
  await FirebaseCrashlytics.instance.recordError(
    errorAndStacktrace.first,
    errorAndStacktrace.last,
    fatal: true,
  );
}).sendPort);

الإبلاغ عن استثناءات تم رصدها

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

استخدِم طريقة recordError لتسجيل الاستثناءات غير الفادحة في الإجراءات المحظورة لتطبيقك. على سبيل المثال:

await FirebaseCrashlytics.instance.recordError(
  error,
  stackTrace,
  reason: 'a non-fatal error'
);

// Or you can use:
await FirebaseCrashlytics.instance.recordFlutterError(errorDetails);

يمكنك أيضًا تسجيل المزيد من المعلومات حول الخطأ المحتمل باستخدام السمة information:

await FirebaseCrashlytics.instance.recordError(
  error,
  stackTrace,
  reason: 'a non-fatal error',
  information: ['further diagnostic information about the error', 'version 2.0'],
);

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

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

إضافة مفاتيح مخصّصة

تساعدك المفاتيح المخصّصة في معرفة الحالة المحدّدة لتطبيقك التي تؤدي إلى حدوث عُطل. يمكنك ربط أزواج المفتاح/القيمة العشوائية بتقارير الأعطال، ثم استخدام المفاتيح المخصّصة للبحث في تقارير الأعطال وفلترتها في "وحدة تحكُّم Firebase".

  • في لوحة بيانات Crashlytics، يمكنك البحث عن المشاكل التي تتطابق مع مفتاح مخصّص.

  • عند مراجعة مشكلة معيّنة في وحدة التحكّم، يمكنك عرض المفاتيح المخصّصة المرتبطة لكل حدث (علامة التبويب الفرعية المفاتيح) وكذلك فلترة الأحداث حسب مفاتيح مخصَّصة (قائمة الفلترة في أعلى الصفحة).

استخدِم طريقة المثيل setCustomKey لضبط أزواج المفتاح/القيمة. فيما يلي بعض الأمثلة:

// Set a key to a string.
FirebaseCrashlytics.instance.setCustomKey('str_key', 'hello');

// Set a key to a boolean.
FirebaseCrashlytics.instance.setCustomKey("bool_key", true);

// Set a key to an int.
FirebaseCrashlytics.instance.setCustomKey("int_key", 1);

// Set a key to a long.
FirebaseCrashlytics.instance.setCustomKey("int_key", 1L);

// Set a key to a float.
FirebaseCrashlytics.instance.setCustomKey("float_key", 1.0f);

// Set a key to a double.
FirebaseCrashlytics.instance.setCustomKey("double_key", 1.0);

إضافة رسائل سجلّ مخصّصة

لمنح نفسك سياقًا إضافيًا للأحداث التي أدت إلى حدوث تعطُّل، يمكنك إضافة سجلات Crashlytics المخصّصة إلى تطبيقك. ويربط Crashlytics السجلات ببيانات التعطُّل ويعرضها في وحدة تحكُّم Firebase، ضمن علامة التبويب السجلّات في Crashlytics.

استخدِم log للمساعدة في تحديد المشاكل. على سبيل المثال:

FirebaseCrashlytics.instance.log("Higgs-Boson detected! Bailing out");

ضبط معرّفات المستخدمين

لتشخيص مشكلة ما، يكون من المفيد غالبًا معرفة المستخدمين الذين واجهوا عطلاً معيّنًا. يتضمن Crashlytics طريقة لتحديد هوية المستخدمين في تقارير الأعطال بشكل مجهول.

لإضافة أرقام تعريف المستخدمين إلى تقاريرك، عليك تخصيص معرّف فريد لكل مستخدم على شكل رقم تعريف أو رمز مميّز أو قيمة مجزّأة:

FirebaseCrashlytics.instance.setUserIdentifier("12345");

إذا احتجت في أي وقت إلى محو معرّف المستخدم بعد تعيينه، يمكنك إعادة ضبط القيمة على سلسلة فارغة. لا يؤدي محو معرّف المستخدم إلى إزالة سجلات Crashlytics الحالية. إذا كنت بحاجة إلى حذف السجلات المرتبطة برقم تعريف المستخدم، يمكنك التواصل مع فريق دعم Firebase.

الحصول على سجلّات شريط التنقّل

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

يتم تشغيل سجلات شريط التنقّل من خلال "إحصاءات Google"، لذا للحصول على سجلّات شريط التنقّل، عليك تفعيل "إحصاءات Google" لمشروعك في Firebase وإضافة حزمة تطوير البرامج (SDK) لمنصة Firebase لخدمة "إحصاءات Google" إلى تطبيقك. وبعد استيفاء هذه المتطلبات، يتم تضمين سجلّات شريط التنقّل تلقائيًا مع بيانات الحدث ضمن علامة التبويب السجلات عند عرض تفاصيل مشكلة.

حزمة تطوير البرامج (SDK) لخدمة "إحصاءات Google" تسجِّل تلقائيًا حدث screen_view، ما يتيح لسجلّات شريط التنقّل عرض قائمة بالشاشات التي تم عرضها قبل حدث التعطّل أو غير الفادح أو حدث ANR. يحتوي سجلّ شريط التنقّل screen_view على معلَمة firebase_screen_class.

تتم تعبئة سجلات شريط التنقّل أيضًا بأي أحداث مخصّصة تسجّلها يدويًا ضمن جلسة المستخدم، بما في ذلك بيانات مَعلمة الحدث. يمكن أن تساعد هذه البيانات في عرض سلسلة من إجراءات المستخدم التي تؤدي إلى حدوث عطل أو حدث غير خطير أو حدث ANR.

تجدر الإشارة إلى أنّه يمكنك التحكّم في جمع بيانات "إحصاءات Google" واستخدامها، التي تتضمّن البيانات التي تعمل على تعبئة سجلات شريط التنقّل.

تفعيل إعداد تقارير الموافقة

يجمع Crashlytics تلقائيًا تقارير الأعطال لجميع مستخدمي التطبيق. لمنح المستخدمين مزيدًا من التحكم في البيانات التي يرسلونها، يمكنك تفعيل إعداد التقارير عن طريق إيقاف إعداد التقارير التلقائية وعدم إرسال البيانات إلى Crashlytics إلا إذا اخترت ذلك في الرمز:

  1. إيقاف ميزة "الجمع التلقائي للبيانات" محليًا:

    منصات Apple

    إضافة مفتاح جديد إلى ملف "Info.plist":

    • المفتاح: FirebaseCrashlyticsCollectionEnabled
    • القيمة: false

    Android

    في المجموعة application من ملف AndroidManifest.xml، أضِف علامة meta-data لإيقاف ميزة الجمع التلقائي للبيانات:

    <meta-data
    android:name="firebase_crashlytics_collection_enabled"
    android:value="false" />

  2. يمكنك تفعيل عملية جمع البيانات لمستخدمين محدَّدين من خلال استدعاء ميزة "تجاوز جمع البيانات في Crashlytics" في وقت التشغيل.

    وتستمر قيمة الإلغاء في جميع عمليات إطلاق تطبيقك حتى يتمكّن تطبيق Crashlytics من جمع التقارير تلقائيًا. لإيقاف ميزة "إعداد تقارير الأعطال التلقائية"، عليك ضبط false كقيمة الإلغاء. عند الضبط على false، لن تنطبق القيمة الجديدة حتى التشغيل التالي للتطبيق.

    FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);

إدارة بيانات "إحصاءات الأعطال"

تساعدك أداة "إحصاءات الأعطال" في حل المشاكل من خلال مقارنة عمليات تتبُّع تسلسل استدعاء الدوال البرمجية المجهولة الهوية بتتبُّع تسلسل استدعاء الدوال البرمجية من تطبيقات Firebase الأخرى وإعلامك بما إذا كانت مشكلتك جزءًا من اتجاه أوسع نطاقًا. توفّر أداة "إحصاءات الأعطال" موارد لمساعدتك في إصلاح العطل، وذلك على مستوى العديد من المشاكل.

تستخدم أداة "إحصاءات الأعطال" بيانات الأعطال المجمَّعة لتحديد مؤشرات الثبات الشائعة. إذا كنت تفضّل عدم مشاركة بيانات تطبيقك، يمكنك إيقاف ميزة "إحصاءات الأعطال" من قائمة إحصاءات الأعطال في أعلى قائمة مشاكل Crashlytics في وحدة تحكُّم Firebase.