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

iOS+‎ Android Flutter Unity

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

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

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

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

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

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

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

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

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

ملاحظة: يمكن أن يتضمّن Crashlytics 64 زوجًا من المفتاح/القيمة كحدّ أقصى. بعد بلوغ هذا الحدّ، لن يتم حفظ القيم الإضافية. يمكن أن يصل حجم كل زوج مفتاح/قيمة إلى 1 كيلوبايت.

استخدِم طريقة 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 السجلّات ببيانات الأعطال وتعرضها في صفحة Crashlytics ضمن وحدة تحكّم Firebase، ضِمن علامة التبويب السجلّات.

ملاحظة: لتجنُّب إبطاء تطبيقك، يقتصر حجم السجلات في Crashlytics على 64 كيلوبايت، ويتم حذف إدخالات السجلّ القديمة عندما تتجاوز سجلّات الجلسة هذا الحدّ.

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

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

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

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

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

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

ملاحظة: لا يخزِّن 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
}

تحذير: تجنَّب تضمين قيمة فريدة (مثل معرّف مستخدم أو طابع زمني) في رسالة الخطأ، واستخدِم مفتاحًا مخصّصًا بدلاً من ذلك. يمكن أن تؤدي إضافة قيم مباشرةً إلى حدوث عدة مشاكل، وقد تتسبّب في أن يحدّ Crashlytics من إعداد تقارير الأخطاء في تطبيقك.

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

   Kotlin

   Firebase.crashlytics.setCrashlyticsCollectionEnabled(true)

   Java

   FirebaseCrashlytics.getInstance().setCrashlyticsCollectionEnabled(true);

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

ملاحظة: عند إيقاف جمع البيانات لأحد المستخدمين، سيخزّن Crashlytics معلومات الأعطال محليًا على الجهاز. في حال تفعيل ميزة جمع البيانات لاحقًا، سيتم إرسال أي معلومات عن الأعطال مخزَّنة على الجهاز إلى Crashlytics لمعالجتها.

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

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

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

ملاحظة: يؤدي إيقاف مشاركة البيانات إلى إزالة الإحصاءات حول المشاكل التي تواجهك. قد يستغرق تنفيذ التغييرات مدة تصل إلى 24 ساعة.