الحصول على تقارير أعطال قابلة للقراءة في لوحة بيانات Crashlytics

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

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

تأكَّد من قدرة Xcode على معالجة ملفات dSYM وتحميل الملفات تلقائيًا.

عند إعداد Crashlytics في تطبيقك، تكون قد ضبطت تشغيل النص البرمجي لمعالجة أنظمة dSYM وتحميل الملفات تلقائيًا.

عليك التأكّد من أنّ إعدادات النص البرمجي للتشغيل في Crashlytics محدَّثة بالمتطلبات الجديدة التي بدأت مع Xcode 15. إذا لم تكن الإعدادات محدّثة، قد يظهر لك الخطأ التالي:
error: Info.plist Error Unable to process Info.plist at path ....

على وجه التحديد، يتطلب Xcode 15 والإصدارات الأحدث منك توفير مجموعة أكثر اكتمالاً من مواقع الملفات. بالنسبة إلى النص البرمجي لتشغيل Crashlytics (firebase-ios-sdk/Crashlytics/run)، تأكّد من توفّر الإعداد التالي:

انقر على علامة التبويب مراحل الإنشاء، ثم وسِّع قسم تشغيل النص البرمجي.
في قسم ملفات الإدخال، تأكد من أن لديك المسارات لمواقع الملفات التالية:
```
${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}
```
```
${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${PRODUCT_NAME}
```
```
${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Info.plist
```
```
$(TARGET_BUILD_DIR)/$(UNLOCALIZED_RESOURCES_FOLDER_PATH)/GoogleService-Info.plist
```
```
$(TARGET_BUILD_DIR)/$(EXECUTABLE_PATH)
```
فهم سبب أهمية مواقع هذه الملفات

يبحث Xcode في المواقع المحدّدة عن ملفات الإدخال هذه للتأكّد من توفّر ملفات الإصدار للنص البرمجي للتشغيل. بالإضافة إلى ذلك، في حال تفعيل وضع الحماية للنص البرمجي للمستخدم، لا تسمح خدمة Xcode إلا للنص البرمجي للتشغيل بالوصول إلى الملفات المحدّدة في ملفات الإدخال.
- يتيح تحديد موقع ملفات dSYM الخاصة بالمشروع إلى Crashlytics معالجة أنظمة dSYM.
- ومن خلال تحديد موقع ملف GoogleService-Info.plist الذي تم إنشاؤه في تطبيقك، سيتمكّن Crashlytics من ربط أنظمة dSYM بتطبيقك على Firebase.
- يسمح تحديد موقع الملف القابل للتنفيذ في تطبيقك بتشغيل النص البرمجي لمنع عمليات التحميل المكررة لنظام dSYM نفسه. يُرجى العِلم أنّه لا يتم تحميل الملفات الثنائية للتطبيق ..

التحقق مما إذا كان Xcode يقوم بإنتاج dSYMs

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

افتح مشروعك في Xcode، ثم حدد ملف المشروع في Xcode Navigator.
اختَر الهدف الرئيسي من الإصدار.
افتح علامة التبويب إعدادات الإنشاء للهدف، ثم انقر على الكل.
البحث عن debug information format
اضبط تنسيق معلومات تصحيح الأخطاء على DWARF باستخدام ملف dSYM لجميع أنواع التصميم.
إعادة إنشاء تطبيقك

من المفترض أن تظهر تقارير الأعطال الآن في لوحة بيانات Crashlytics. إذا استمرت المشكلة أو واجهت أخطاء أخرى، حاوِل تحديد موقع نظام dSYM وتحميلها إلى Crashlytics يدويًا.

تحديد موقع أجهزة dSYM على جهاز محلي

شغِّل الأمر التالي لعرض جميع أرقام التعريف الفريدة العالمية لـ dSYMs على جهازك وابحث عن نظام dSYM المفقود:

mdfind -name .dSYM | while read -r line; do dwarfdump -u "$line"; done

بعد العثور على dSYM، حمِّله يدويًا إلى Crashlytics. إذا لم يعرض الأمر mdfind أي نتائج، يمكنك البحث في دليل Products حيث يتوفّر .app (يتوفّر دليل Products تلقائيًا في Derived Data). وإذا تم طرح تطبيقك في مرحلة الإنتاج، يمكنك أيضًا البحث عن dSYM في دليل .xcarchive على القرص:

في Xcode، افتح نافذة Organization (المنظّم) ثم اختَر تطبيقك من القائمة. يعرض Xcode قائمة بأرشيفات مشروعك.
انقر مع الضغط على مفتاح Control على أرشيف لعرضه في Finder (الباحث). اضغط على Control وانقر عليه مرة أخرى، ثم انقر على Show Package Contents (إظهار محتويات الحزمة).
ضمن .xcarchive يوجد دليل dSYMs يحتوي على dSYMs تم إنشاؤها كجزء من عملية الأرشفة لـ Xcode.

تحميل dSYM

يتيح Crashlytics استخدام طرق متعدّدة لتحميل ملفات dSYMs، إمّا تلقائيًا أو يدويًا.

(إجراء يُنصح به) معالجة أنظمة dSYM تلقائيًا وتحميل الملفات

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

تحميل ملفات dSYM يدويًا

إذا تعذّر إجراء عمليات التحميل التلقائية، يمكنك تحميل ملفات dSYM يدويًا باستخدام أحد الخيارات التالية.

الخيار 1: استخدِم خيار "السحب والإفلات" المستند إلى وحدة التحكّم لتحميل ملف ZIP يحتوي على ملفات dSYM (انتقِل إلى وحدة تحكُّم Firebase > Crashlytics > علامة التبويب dSYMs).
الخيار 2: استخدم النص البرمجي upload-symbols الذي يمكنك الاتصال به من أي مكان في عملية التصميم لتحميل ملفات dSYM يدويًا. لتشغيل النص البرمجي upload-symbols، استخدِم أيًا من الخيارَين التاليَين:
- الخيار (أ): تضمين السطر التالي في عملية التصميم:
```
find dSYM_DIRECTORY -name "*.dSYM" | xargs -I \{\} $PODS_ROOT/FirebaseCrashlytics/upload-symbols -gsp /PATH/TO/GoogleService-Info.plist -p PLATFORM \{\}
```
- الخيار "ب": تشغيل النص البرمجي مباشرةً من الوحدة الطرفية:
```
/PATH/TO/PODS/DIRECTORY/FirebaseCrashlytics/upload-symbols -gsp /PATH/TO/GoogleService-Info.plist -p ios /PATH/TO/dSYMs
```
للاطّلاع على ملاحظات الاستخدام وتعليمات إضافية حول هذا النص البرمجي، يمكنك تشغيل upload-symbols باستخدام المعلَمة --help.