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

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

اختيار المنصة:

يمكنك النقر على مشكلة والحصول على تقرير مفصّل عن الحدث في لوحة بيانات DevOps والتفاعل > Crashlytics في وحدة تحكّم Firebase. يمكنك تخصيص هذه التقارير لمساعدتك في فهم ما يحدث في تطبيقك والظروف المحيطة بالأحداث التي يتم إبلاغ "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'],
);

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

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

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

تساعدك المفاتيح المخصّصة في معرفة الحالة المحدّدة لتطبيقك قبل تعطّله. يمكنك ربط أزواج عشوائية من المفاتيح والقيم بتقارير الأعطال، ثم استخدام المفاتيح المخصّصة للبحث عن تقارير الأعطال وفلترتها في لوحة بيانات DevOps والتفاعل > Crashlytics ضمن وحدة تحكّم Firebase.

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

استخدِم طريقة مثيل 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 السجلات ببيانات الأعطال ويعرضها في علامة التبويب السجلات عند عرض تفاصيل مشكلة (يمكنك الاطّلاع على جميع المشاكل في لوحة بيانات DevOps والتفاعل > Crashlytics في وحدة تحكّم Firebase).

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

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

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

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

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

FirebaseCrashlytics.instance.setUserIdentifier("12345");

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

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

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

تسجِّل حزمة تطوير البرامج (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 في وقت التشغيل. تستمر قيمة الإلغاء في جميع عمليات التشغيل اللاحقة لتطبيقك، وبالتالي يمكن لخدمة "Crashlytics" جمع التقارير تلقائيًا لهذا المستخدم.
```
FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);
```
إذا أوقف المستخدم لاحقًا جمع البيانات، يمكنك تمرير القيمة false كقيمة تجاوز، وسيتم تطبيقها في المرة التالية التي يشغّل فيها المستخدم التطبيق وستستمر في جميع عمليات التشغيل اللاحقة لهذا المستخدم.

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

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

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

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

تصدير بياناتك إلى BigQuery أو Cloud Logging للاستفادة من الميزات والتحليلات المتقدّمة، مثل الاستعلام عن بياناتك وإنشاء لوحات بيانات مخصّصة وإعداد تنبيهات مخصّصة