Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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

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

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

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

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

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

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

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

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

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

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

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

FirebaseCrashlytics.instance.setUserIdentifier("12345");

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

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

تستند سجلّات مسار التنفيذ إلى "إحصاءات Google"، لذا للحصول على سجلّات مسار التنفيذ، عليك تفعيل "إحصاءات Google" لمشروع Firebase و إضافة Firebase SDK لخدمة Google Analytics إلى تطبيقك. بعد استيفاء هذه المتطلبات، يتم تضمين سجلّات مسار التنفيذ تلقائيًا مع بيانات الحدث ضمن علامة التبويب السجلّات عند الاطّلاع على التفاصيل لمشكلة معيّنة (يمكنك الاطّلاع على جميع مشاكلك في لوحة بيانات DevOps & Engagement > Crashlytics dashboard في وحدة تحكّم 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 كقيمة للإلغاء، وسيتم تطبيقها في المرة التالية التي يشغّل فيها المستخدم التطبيق وستظل سارية في جميع عمليات التشغيل اللاحقة لهذا المستخدم.

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

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

تستخدم ميزة Crash Insights بيانات الأعطال المجمّعة لتحديد المؤشرات الشائعة للاستقرار. إذا كنت تفضّل عدم مشاركة بيانات تطبيقك، يمكنك إيقاف ميزة Crash Insights من قائمة Crash Insights في أعلى قائمة المشاكل في لوحة بيانات DevOps & Engagement > Crashlytics dashboard في وحدة تحكّم Firebase console.

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

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