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

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

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

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

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

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

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

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

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

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

استخدِم طريقة مثيل 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 لحزمة Firebase Android SDK.

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

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
}

تظهر جميع الاستثناءات المسجّلة كمشاكل غير خطيرة في لوحة بيانات DevOps والتفاعل > Crashlytics في وحدة تحكّم Firebase. يحتوي ملخّص المشكلة على جميع معلومات الحالة التي تحصل عليها عادةً من الأعطال، بالإضافة إلى تفاصيل حسب إصدار 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 الأخرى وإعلامك بما إذا كانت مشكلتك جزءًا من مؤشر أكبر. بالنسبة إلى العديد من المشاكل، توفّر ميزة "إحصاءات الأعطال" مراجع لمساعدتك في تصحيح أخطاء الأعطال.

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

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

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