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

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

• يمكنك قياس حالة تطبيقك لتسجيل المفاتيح المخصّصة ورسائل السجلّ المخصّصة ومعرّفات المستخدمين.

• الإبلاغ عن استثناءات إلى Crashlytics

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

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

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

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

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

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

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

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
}

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 */);

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

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

FirebaseCrashlytics crashlytics = FirebaseCrashlytics.getInstance();

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

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

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)
}

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 للمساعدة في تحديد المشاكل. على سبيل المثال:

Firebase.crashlytics.log("message")

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

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

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

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

Firebase.crashlytics.setUserId("user123456789")

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 في وحدة تحكّم Firebase، يمكنك إجراء ما يلي باستخدام هذه البيانات:

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

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

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

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

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

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

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

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

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

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
}

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
}

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

تعالج Crashlytics الاستثناءات في سلسلة محادثات مخصّصة في الخلفية للحدّ من تأثيرها في أداء تطبيقك. ولتقليل عدد الزيارات التي يجريها المستخدمون على الشبكة، تجمع 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 Console.

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

• تصدير بياناتك إلى BigQuery أو Cloud Logging للاستفادة من التحليلات والميزات المتقدّمة، مثل طلب البيانات وإنشاء لوحات بيانات مخصّصة وإعداد تنبيهات مخصّصة