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

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

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

• يمكنك الإبلاغ عن الاستثناءات إلى Crashlytics.

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

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

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

تساعدك المفاتيح المخصّصة في الحصول على الحالة المحدّدة لتطبيقك التي أدّت إلى حدوث عطل. يمكنك ربط أزواج عشوائية من المفاتيح والقيم بتقارير الأعطال، ثم استخدام المفاتيح المخصّصة للبحث عن تقارير الأعطال وفلترتها في DevOps & Engagement > 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 & Engagement > Crashlytics dashboard في وحدة تحكّم 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++‎ لا تحتوي إلا على عناوين في مستودع Firebase Android SDK على GitHub.

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

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

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

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

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

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

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

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

بالإضافة إلى الإبلاغ تلقائيًا عن أعطال تطبيقك، 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 & Engagement > Crashlytics في وحدة تحكّم Firebase. يحتوي ملخّص المشكلة على جميع معلومات الحالة التي تحصل عليها عادةً من الأعطال، بالإضافة إلى تفاصيل حسب إصدار Android وجهاز الأجهزة.

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

الحصول على سجلّات مسار التنفيذ

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

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

تسجِّل حزمة تطوير البرامج (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 في وقت التشغيل. تظل قيمة الإلغاء سارية في جميع عمليات تشغيل تطبيقك اللاحقة، ما يتيح لـ Crashlytics جمع التقارير تلقائيًا لهذا المستخدم.

   Kotlin

   Firebase.crashlytics.setCrashlyticsCollectionEnabled(true)

   Java

   FirebaseCrashlytics.getInstance().setCrashlyticsCollectionEnabled(true);

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

إدارة بيانات Crash Insights

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

تستخدِم ميزة Crash Insights بيانات الأعطال المجمّعة لتحديد المؤشرات الشائعة للاستقرار. إذا كنت تفضّل عدم مشاركة بيانات تطبيقك، يمكنك إيقاف ميزة Crash Insights من قائمة Crash Insights في أعلى قائمة المشاكل في لوحة بيانات DevOps & Engagement > Crashlytics dashboard في وحدة تحكّم Firebase console.

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

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