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


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

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

تتوفر crashlytics.h كمكتبة C++ مخصصة للرأس فقط في مستودع GitHub لحزمة تطوير البرامج (SDK) لنظام التشغيل Android من Firebase

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

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

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

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

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

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

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

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

تجدر الإشارة إلى أنّه يمكنك التحكّم في جمع بيانات Google Analytics واستخدامها، بما في ذلك البيانات التي تملأ سجلّات مسار التنقّل.

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

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

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

    <meta-data
    android:name="firebase_crashlytics_collection_enabled"
    android:value="false" />

  2. تفعيل عملية جمع البيانات لمستخدمين محدّدين من خلال طلب بيانات Crashlytics تجاوز المجموعة في وقت التشغيل. تستمر قيمة الإلغاء في جميع عمليات التشغيل. في تطبيقك ليتمكّن "Crashlytics" من جمع التقارير تلقائيًا. لإيقاف reportingتلقائي للأعطال، مرِّر false كقيمة إلغاء. عند الضبط إلى false، لا تنطبق القيمة الجديدة إلى أن يتم تشغيل التطبيق في المرة التالية.

    Kotlin+KTX 

    Firebase.crashlytics.setCrashlyticsCollectionEnabled(true)

    Java 

    FirebaseCrashlytics.getInstance().setCrashlyticsCollectionEnabled(true);

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

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

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