تخصيص تقارير أعطال 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++ تتضمن عنوانًا فقط في مستودع GitHub لحزمة تطوير البرامج (SDK) لنظام التشغيل Android من Firebase.

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

تضمين تقارير GWP-ASan لتصحيح مشاكل تلف الذاكرة

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

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

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

يمكنك الحصول على تقارير الذاكرة من GWP-ASan إذا فعّلت GWP-ASan بشكلٍ صريح في تطبيقك واستخدمت حزمة Crashlytics SDK للإصدار 18.3.6 من حزمة Crashlytics أو إصدارات أحدث (إصدار Firebase BoM الإصدار 31.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.