تخصيص تقارير الأعطال على Android

اختيار المنصة: +iOS Android Flutter Unity


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

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

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

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

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

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

Kotlin 

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 

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

بالنسبة إلى 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 السجلات ببيانات الأعطال ويعرضها في علامة التبويب السجلات عند عرض تفاصيل مشكلة (يمكنك الاطّلاع على جميع المشاكل في لوحة بيانات DevOps والتفاعل > Crashlytics في وحدة تحكّم Firebase).

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

Kotlin 

Firebase.crashlytics.log("message")

Java 

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

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

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

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

Kotlin 

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. يمكن أن ترتبط هذه الأخطاء المتعلّقة بالذاكرة بتلف الذاكرة داخل تطبيقك، وهو السبب الرئيسي للثغرات الأمنية في التطبيق.

في لوحة بيانات DevOps والتفاعل > Crashlytics ضمن وحدة تحكّم Firebase، يمكنك إجراء ما يلي باستخدام هذه البيانات:

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

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

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

الإبلاغ عن الاستثناءات غير الخطيرة

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

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

Kotlin 

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
}

بالإضافة إلى ذلك، يمكنك أيضًا إرفاق مفاتيح مخصّصة بالاستثناء غير الفادح المحدّد. على سبيل المثال:

Kotlin 

try {
    methodThatThrows()
} catch (e: Exception) {
    Firebase.crashlytics.recordException(e) {
        key("string key", "string value")
        key("boolean key", true)
        key("float key", Float.MAX_VALUE)
    }
    // handle your exception here
}

Java 

try {
    methodThatThrows();
} catch (Exception e) {
    CustomKeysAndValues keysAndValues = new CustomKeysAndValues.Builder()
            .putString("string key", "string value")
            .putBoolean("boolean key", true)
            .putFloat("float key", Float.MAX_VALUE)
            .build();
    FirebaseCrashlytics.getInstance().recordException(e, keysAndValues);
    // handle your exception here
}

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

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

الحصول على سجلّات خطوات المستخدم

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

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

تسجِّل حزمة تطوير البرامج (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" جمع التقارير تلقائيًا لهذا المستخدم.

    Kotlin 

    Firebase.crashlytics.setCrashlyticsCollectionEnabled(true)

    Java 

    FirebaseCrashlytics.getInstance().setCrashlyticsCollectionEnabled(true);

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

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

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

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

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