تستخدم 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 & Engagement > Crashlytics في Firebase Console. يحتوي ملخّص المشكلة على جميع معلومات الحالة التي تحصل عليها عادةً من الأعطال، بالإضافة إلى تقسيمات حسب الإصدار وجهاز الأجهزة.

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

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

تساعدك المفاتيح المخصّصة في الحصول على الحالة المحدّدة لتطبيقك قبل حدوث عُطل. يمكنك ربط أزواج مفتاح/قيمة عشوائية بتقارير الأعطال، ثم استخدام المفاتيح المخصّصة للبحث عن تقارير الأعطال وفلترتها في لوحة بيانات DevOps & Engagement > 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 Console.

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

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