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

اختيار النظام الأساسي:

تضبط منصة Firebase Crashlytics تلقائيًا مشروع Flutter لتحميل ملفات الرموز الضرورية التي تضمن إزالة الغموض عن تقارير الأعطال وجعلها قابلة للقراءة.

مع ذلك، هناك حالات يمكن أن تؤدي إلى عدم ضبط المشروع بالكامل. يوضّح هذا الدليل ما تفعله عملية التشغيل الآلي ويقدّم الخطوات الأولى لتصحيح أخطاء إعداد مشروعك.

الأنظمة الأساسية من Apple

مراجعة إعدادات تحميل ملفات dSYM

عند إضافة مكوّن Crashlytics الإضافي لـ Flutter وتنفيذ الأمر flutterfire configure، ستتم محاولة إضافة نص برمجي إلى مساحة عمل Xcode الخاصة بمشروعك، وهو نص برمجي للعثور على ملفات رموز dSYM الضرورية وتحميلها إلى Crashlytics. بدون هذه الملفات، سيظهر لك تنبيه "ملف dSYM غير متوفّر" في لوحة بيانات Crashlytics، وسيتم الاحتفاظ بالاستثناءات في الخلفية إلى أن يتم تحميل الملفات الناقصة.

إذا واجهت هذه المشكلة، تأكَّد أولاً من تثبيت النص البرمجي:

حدِّد موقع ملف مساحة عمل Xcode وافتحه في دليل iOS الخاص بمشروعك (FLUTTER_PROJECT_NAME/ios/Runner.xcworkspace).
حدِّد ما إذا تمت إضافة نص برمجي بعنوان [firebase_crashlytics] Crashlytics Upload Symbols إلى مراحل الإصدار في هدف Runner.

راجِع القسم المناسب أدناه لمعرفة ما إذا كان النص البرمجي غير متوفّر أو متوفّرًا.

النص البرمجي للتحميل التلقائي لملفات dSYM غير متوفّر

إذا كان هذا النص البرمجي غير متوفّر، يمكنك إضافته يدويًا:

حدِّد رقم تعريف تطبيق Firebase لتطبيقك على Apple. إليك مكانان مختلفان يمكنك العثور فيهما على هذا الرقم:
- في وحدة تحكّم Firebase، انتقِل إلى > إعدادات المشروع. انتقِل إلى بطاقة تطبيقاتك ، ثم انقر على تطبيقك على Firebase لنظام التشغيل iOS لعرض معلومات التطبيق، بما في ذلك رقم تعريف التطبيق.
- في الدليل ذي المستوى الأعلى لمشروع Flutter، ابحث عن ملف firebase_options.dart. يتم تصنيف رقم تعريف تطبيق Firebase لتطبيقك على Apple على أنّه appId.
انقر على > مرحلة نص برمجي جديد.

تأكَّد من أنّ مرحلة النص البرمجي الجديدة هذه هي آخر مرحلة إصدار في مشروعك. وإلا، لن تتمكّن Crashlytics من معالجة ملفات dSYM بشكل صحيح.
وسِّع قسم النص البرمجي الجديد.

ملاحظة: بالنسبة إلى الخطوات الفرعية المتبقية، انسخ المسارات والصقها تمامًا كما هو محدّد، وسيحلّها Xcode. ومع ذلك، إذا واجهت مشاكل في حلّ Xcode لهذه المسارات أو في بنية مشروع فريدة، يمكنك تحديد المسارات يدويًا بدلاً من ذلك.
في حقل النص البرمجي (الموجود ضِمن التصنيف Shell )، أضِف النصوص البرمجية التالية:

تعالج هذه النصوص البرمجية ملفات dSYM وتحمّلها إلى Crashlytics.
```
$PODS_ROOT/FirebaseCrashlytics/upload-symbols --build-phase --validate -ai FIREBASE_APP_ID -- $DWARF_DSYM_FOLDER_PATH/App.framework.dSYM
```
```
$PODS_ROOT/FirebaseCrashlytics/upload-symbols --build-phase -ai FIREBASE_APP_ID -- $DWARF_DSYM_FOLDER_PATH/App.framework.dSYM 
```
- FIREBASE_APP_ID: رقم تعريف تطبيقك على Firebase لنظام التشغيل iOS (وليس رقم تعريف حزمة Apple)
  مثال على رقم تعريف تطبيق على Firebase لنظام التشغيل iOS: 1:1234567890:ios:321abc456def7890
هل تحتاج إلى العثور على رقم تعريف تطبيقك على Firebase؟
إليك طريقتان للعثور على رقم تعريف تطبيقك على Firebase:
- في ملف GoogleService-Info.plist ، يكون رقم تعريف التطبيق هو قيمة GOOGLE_APP_ID ؛ أو
- في وحدة تحكّم Firebase، انتقِل إلى إعدادات المشروع. انتقِل إلى بطاقة تطبيقاتك ، ثم انقر على تطبيق Firebase المقصود للعثور على رقم تعريف التطبيق.
في قسم ملفات الإدخال ، أضِف مسارات مواقع الملفات التالية:
```
${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 نفسه. يُرجى العِلم أنّ الملفات الثنائية للتطبيق لا يتم تحميلها.

النص البرمجي للتحميل التلقائي لملفات dSYM متوفّر

إذا كان النص البرمجي متوفّرًا، يُرجى الرجوع إلى الدليل الخاص بأجهزة Apple لتحديد مشاكل ملفات dSYM وحلّها. عليك اتّخاذ الخطوات الإضافية التالية إذا اخترت تحميل ملفات dSYM من خلال العملية الموضّحة:

حدِّد رقم تعريف تطبيق Firebase لتطبيقك على Apple. إليك مكانان مختلفان يمكنك العثور فيهما على هذا الرقم:
- في وحدة تحكّم Firebase، انتقِل إلى > إعدادات المشروع. انتقِل إلى بطاقة تطبيقاتك ، ثم انقر على تطبيقك على Firebase لنظام التشغيل iOS لعرض معلومات التطبيق، بما في ذلك رقم تعريف التطبيق.
- في الدليل ذي المستوى الأعلى لمشروع Flutter، ابحث عن ملف firebase_options.dart. يتم تصنيف رقم تعريف تطبيق Firebase لتطبيقك على Apple على أنّه appId.
عند تنفيذ النص البرمجي upload-symbols ، استخدِم -ai FIREBASE_APPLE_APP_ID بدلاً من -gsp /path/to/GoogleService-Info.plist.

مراجعة إعدادات الإصدار لكل من Flutter وCrashlytics (في حال استخدام العلامة `--split-debug-info`)

إذا كان مشروع Flutter يستخدم العلامة --split-debug-info (والعلامة --obfuscate اختياريًا)، يجب اتّخاذ خطوات إضافية لعرض تتبُّع تسلسل استدعاء الدوال القابل للقراءة لتطبيقك.

تأكَّد من أنّ مشروعك يستخدم إعدادات الإصدار المقترَحة (Flutter 3.12.0 والإصدارات الأحدث ومكوّن Crashlytics الإضافي لـ Flutter 3.3.4 والإصدارات الأحدث) حتى يتمكّن مشروعك من إنشاء رموز Flutter (ملفات dSYM) وتحميلها تلقائيًا إلى Crashlytics.

Android

مراجعة إعدادات التبعيات

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

تأكَّد من ظهور السطرَين التاليَين في ملف build.gradle على مستوى المشروع وفي ملف build.gradle على مستوى التطبيق:

في ملف الإصدار على مستوى المشروع (android/build.gradle)، ابحث عن السطر التالي:

dependencies {
// ... other dependencies

classpath 'com.google.gms:google-services:4.3.5'
classpath 'com.google.firebase:firebase-crashlytics-gradle:2.7.1'
}

في ملف الإصدار على مستوى التطبيق (android/app/build.gradle)، ابحث عن السطر التالي:

// ... other imports

android {
// ... your android config
}

dependencies {
// ... your dependencies
}

// This section must appear at the bottom of the file
apply plugin: 'com.google.gms.google-services'
apply plugin: 'com.google.firebase.crashlytics'

التأكّد من استخدام واجهة سطر الأوامر لتحميل رموز Flutter (في حال استخدام العلامة `--split-debug-info`)

استخدِم Firebase واجهة سطر الأوامر في Firebase (الإصدار 11.9.0 والإصدارات الأحدث) لتحميل رموز تصحيح أخطاء Flutter . عليك تحميل رموز تصحيح الأخطاء قبل الإبلاغ عن عطل من إصدار رمز تم إخفاؤه.

من الدليل الجذري لمشروع Flutter، نفِّذ الأمر التالي:

firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/symbols

FIREBASE_APP_ID: رقم تعريف تطبيقك على Firebase لنظام التشغيل Android (وليس اسم الحزمة)
مثال على رقم تعريف تطبيق على Firebase لنظام التشغيل Android: 1:567383003300:android:17104a2ced0c9b9b
هل تحتاج إلى العثور على رقم تعريف تطبيقك على Firebase؟
إليك طريقتان للعثور على رقم تعريف تطبيقك على Firebase:
- في ملف google-services.json ، يكون رقم تعريف التطبيق هو قيمة mobilesdk_app_id ؛ أو
- في وحدة تحكّم Firebase، انتقِل إلى إعدادات المشروع. انتقِل إلى بطاقة تطبيقاتك ، ثم انقر على تطبيق Firebase المقصود للعثور على رقم تعريف التطبيق.
PATH/TO/symbols: الدليل نفسه الذي تمرّره إلى العلامة --split-debug-info عند إنشاء التطبيق

إذا استمرت المشاكل، يُرجى الرجوع إلى الـ دليل الخاص بأجهزة Android لتحديد مشاكل التقارير التي تم إخفاؤها وحلّها.