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


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

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

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

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

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

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

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

استخدِم طريقة مثيل setCustomKey لضبط أزواج المفتاح/القيمة. يُرجى العلم أنّه تمّ تحميل setCustomKey بشكل زائد للمَعلمة value لقبول أي وسيطة primitiv أو 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) لمنصة Firebase لنظام التشغيل Android.

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

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

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

  • يمكنك عرض هذه البيانات في علامة تبويب جديدة بعنوان "تتبُّع تسلسل استدعاء الدوال البرمجية للذاكرة" عند النقر على تفاصيل المشكلة في لوحة بيانات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"، لذا للحصول على سجلّات "المسار إلى الصفحة"، عليك أولاً تفعيل "إحصاءات 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 data collection override أثناء التشغيل. تظل قيمة إلغاء الإعدادات محفوظة في جميع عمليات بدء استخدام تطبيقك حتى تتمكّن Crashlytics من جمع التقارير تلقائيًا. لإيقاف reportingتلقائي للأعطال، مرِّر false كقيمة إلغاء. عند ضبطه على false، لا يتم تطبيق القيمة الجديدة إلا بعد التشغيل التالي للتطبيق.

    Kotlin+KTX 

    Firebase.crashlytics.setCrashlyticsCollectionEnabled(true)

    Java 

    FirebaseCrashlytics.getInstance().setCrashlyticsCollectionEnabled(true);

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

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

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