Catch up on everything announced at Firebase Summit, and learn how Firebase can help you accelerate app development and run your app with confidence. Learn More

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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

يصف هذا الدليل كيفية تخصيص تقارير الأعطال باستخدام واجهات برمجة تطبيقات Crashlytics. بشكل افتراضي ، تجمع Crashlytics تلقائيًا تقارير أعطال النظام الأساسي لجميع مستخدمي تطبيقك (يمكنك أيضًا إيقاف الإبلاغ عن الأعطال التلقائية وتمكين إعداد التقارير للمستخدمين بدلاً من ذلك). يوفر Crashlytics خمس آليات تسجيل خارج الصندوق: المفاتيح المخصصة ، والسجلات المخصصة ، ومعرفات المستخدم ، والاستثناءات التي تم القبض عليها وغير المعلنة .

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

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

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

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 ، يمكنك البحث عن المشكلات التي تطابق مفتاحًا مخصصًا.

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

استخدم طريقة المثيل 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 .

تمكين الاشتراك في التقارير

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

  1. قم بإيقاف تشغيل التجميع التلقائي أصلاً:

    منصات آبل

    أضف مفتاحًا جديدًا إلى ملف Info.plist الخاص بك:

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

    ذكري المظهر

    في كتلة 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);
    

إدارة بيانات Crash Insights

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

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