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

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

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

  • أوقِف الإبلاغ التلقائي عن الأعطال وفعِّل تقارير الموافقة للمستخدمين. يجمع Crashlytics تلقائيًا تقارير الأعطال لجميع مستخدمي التطبيق تلقائيًا.

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

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

  • في لوحة بيانات Crashlytics، يمكنك البحث عن المشاكل التي تتطابق مع مفتاح مخصّص.

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

استخدِم طريقة المثيل setCustomKey لضبط أزواج المفتاح/القيمة. يُرجى العِلم أنّ setCustomKey تحميل المعلَمة value بشكل زائد لقبول أي وسيطة أساسية أو String. وإليك بعض الأمثلة:

Kotlin+KTX

val crashlytics = Firebase.crashlytics
crashlytics.setCustomKeys {
    key("my_string_key", "foo") // String value
    key("my_bool_key", true) // boolean value
    key("my_double_key", 1.0) // double value
    key("my_float_key", 1.0f) // float value
    key("my_int_key", 1) // int value
}

Java

FirebaseCrashlytics crashlytics = FirebaseCrashlytics.getInstance();

crashlytics.setCustomKey("my_string_key", "foo" /* string value */);

crashlytics.setCustomKey("my_bool_key", true /* boolean value */);

crashlytics.setCustomKey("my_double_key", 1.0 /* double value */);

crashlytics.setCustomKey("my_float_key", 1.0f /* float value */);

crashlytics.setCustomKey("my_int_key", 1 /* int value */);

يمكنك أيضًا تعديل قيمة مفتاح حالي عن طريق استدعاء المفتاح وضبطه على قيمة مختلفة. على سبيل المثال:

Kotlin+KTX

val crashlytics = Firebase.crashlytics
crashlytics.setCustomKeys {
    key("current_level", 3)
    key("last_UI_action", "logged_in")
}

Java

FirebaseCrashlytics crashlytics = FirebaseCrashlytics.getInstance();

crashlytics.setCustomKey("current_level", 3);
crashlytics.setCustomKey("last_UI_action", "logged_in");

أضف أزواج المفتاح/القيمة بشكل مجمّع من خلال تمرير مثيل CustomKeysAndValues إلى طريقة مثيل setCustomKeys:

Kotlin+KTX

بالنسبة إلى لغة Kotlin، تُعد الوظائف الحالية أبسط من استخدام أداة إنشاء CustomKeysAndValues.

crashlytics.setCustomKeys {
  key("str_key", "hello")
  key("bool_key", true)
  key("int_key", 1)
  key("long_key", 1L)
  key("float_key", 1.0f)
  key("double_key", 1.0)
}

Java

CustomKeysAndValues keysAndValues = new CustomKeysAndValues.Builder()
.putString("string key", "string value")
.putString("string key 2", "string  value 2")
.putBoolean("boolean key", True)
.putBoolean("boolean key 2", False)
.putFloat("float key", 1.01)
.putFloat("float key 2", 2.02)
.build();

FirebaseCrashlytics.getInstance().setCustomKeys(keysAndValues);

إضافة رسائل سجلّ مخصّصة

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

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

Kotlin+KTX

Firebase.crashlytics.log("message")

Java

FirebaseCrashlytics.getInstance().log("message");

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

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

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

Kotlin+KTX

Firebase.crashlytics.setUserId("user123456789")

Java

FirebaseCrashlytics.getInstance().setUserId("user123456789");

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

(Android NDK فقط) إضافة البيانات الوصفية إلى تقارير أعطال NDK

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

تتوفّر "crashlytics.h" كمكتبة C++ رأسية فقط في مستودع Firebase SDK لنظام التشغيل Android GitHub.

اقرأ التعليقات في ملف العنوان للحصول على إرشادات حول استخدام واجهات برمجة تطبيقات NDK C++.

تضمين تقارير GWP-ASan لتصحيح أخطاء تلف الذاكرة

يمكن أن يساعدك Crashlytics في تصحيح أخطاء الأعطال الناتجة عن أخطاء الذاكرة الأصلية من خلال جمع تقارير GWP-ASan. يمكن أن ترتبط هذه الأخطاء المتعلقة بالذاكرة بتلف الذاكرة داخل تطبيقك، وهو السبب الرئيسي للثغرات الأمنية في التطبيقات.

  • يمكنك عرض هذه البيانات في علامة التبويب الجديدة "تتبُّع تسلسل استدعاء الدوال البرمجية في الذاكرة" عند النقر على تفاصيل المشكلة في لوحة بيانات Crashlytics.

  • يمكنك أيضًا استخدام إشارة "تقرير GWP-ASan" الجديد والفلتر لعرض جميع المشاكل المتعلقة بهذه البيانات بسرعة.

يمكنك الحصول على تقارير الذاكرة من GWP-ASan في حال تفعيل GWP-ASan بشكل صريح في تطبيقك واستخدام حزمة Crashlytics SDK لـ NDK v18.3.6 (Firebase BoM v31.3.0 أو الإصدارات الأحدث). ويمكنك اختبار إعداد GWP-ASan باستخدام مثال الرمز الأصلي في مستندات Android.

الإبلاغ عن الاستثناءات غير الفادحة

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

استخدِم طريقة recordException لتسجيل الاستثناءات غير الفادحة في مجموعات catch المحظورة في تطبيقك. على سبيل المثال:

Kotlin+KTX

try {
    methodThatThrows()
} catch (e: Exception) {
    Firebase.crashlytics.recordException(e)
    // handle your exception here
}

Java

try {
    methodThatThrows();
} catch (Exception e) {
    FirebaseCrashlytics.getInstance().recordException(e);
    // handle your exception here
}

تظهر جميع الاستثناءات المسجَّلة كمشاكل غير فادحة في وحدة تحكُّم Firebase. يحتوي ملخص المشكلة على جميع معلومات الحالة التي تحصل عليها عادةً من حالات التعطُّل، بالإضافة إلى التقسيمات حسب إصدار Android وجهازه.

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

الحصول على سجلّات شريط التنقّل

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

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

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

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

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

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

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

  1. في المجموعة application من ملف AndroidManifest.xml، أضِف علامة meta-data لإيقاف ميزة الجمع التلقائي للبيانات:

    <meta-data
        android:name="firebase_crashlytics_collection_enabled"
        android:value="false" />
    
  2. يمكنك تفعيل عملية جمع البيانات لمستخدمين محدَّدين من خلال استدعاء ميزة "تجاوز جمع البيانات في Crashlytics" في وقت التشغيل. وتستمر قيمة التجاوز في جميع عمليات إطلاق التطبيق حتى يتمكّن تطبيق Crashlytics من جمع التقارير تلقائيًا. لإيقاف ميزة "إعداد تقارير الأعطال التلقائية"، أدخِل false كقيمة الإلغاء. عند الضبط على false، لا تنطبق القيمة الجديدة حتى عملية التشغيل التالية للتطبيق.

    Kotlin+KTX

    Firebase.crashlytics.setCrashlyticsCollectionEnabled(true)

    Java

    FirebaseCrashlytics.getInstance().setCrashlyticsCollectionEnabled(true);

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

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

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