تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

إرسال تقارير إلى Crashlytics بشأن الاستثناءات غير المرصودة والاستثناءات المرصودة
يمكنك إعداد تطبيقك لتسجيل المفاتيح المخصّصة ورسائل السجلّ المخصّصة ومعرّفات المستخدمين.
الحصول تلقائيًا على سجلّات مسار التنفيذ إذا كان تطبيقك يستخدم حزمة تطوير البرامج (SDK) لمنصة Firebase لإصدار Google Analytics تتيح لك هذه السجلات الاطّلاع على إجراءات المستخدمين التي أدّت إلى حدث تمّ جمعه باستخدام Crashlytics في تطبيقك.
أوقِف ميزة إعداد تقارير الأعطال التلقائية وفعِّل ميزة إعداد التقارير التي تتطلّب موافقة المستخدم. يُرجى العِلم أنّ 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 لتسجيل الاستثناءات غير القاتلة في أقسام catch في تطبيقك. على سبيل المثال:

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 Analytics�

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

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

يُرجى العِلم أنّه يمكنك التحكّم في جمع بيانات Google Analytics واستخدامها، بما في ذلك البيانات التي يتم إدخالها في سجلات مسار التنقل.

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

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

إيقاف عملية جمع البيانات بشكل تلقائي:

منصات Apple

أضِف مفتاحًا جديدًا إلى ملف Info.plist:
- المفتاح: FirebaseCrashlyticsCollectionEnabled
- القيمة: false
Android

في القسم application من ملف AndroidManifest.xml، أضِف العلامة meta-data لإيقاف عملية الجمع التلقائي للبيانات:
```
<meta-data
    android:name="firebase_crashlytics_collection_enabled"
    android:value="false" />
```
يمكنك تفعيل عملية الجمع لمستخدمين محدّدين من خلال استدعاء Crashlytics data collection override في وقت التشغيل. تظل قيمة الإلغاء سارية في جميع عمليات تشغيل تطبيقك اللاحقة، وبالتالي يمكن أن تجمع Crashlytics التقارير تلقائيًا لهذا المستخدم.
```
FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);
```
إذا أوقف المستخدم لاحقًا خيار جمع البيانات، يمكنك تمرير false كقيمة إلغاء، وسيتم تطبيقها في المرة التالية التي يشغّل فيها المستخدم التطبيق، وستظل سارية في جميع عمليات التشغيل اللاحقة لهذا المستخدم.

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

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

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