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

بشكلٍ تلقائي، تُعدّل أداة 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، انتقِل إلى > إعدادات المشروع. انتقِل للأسفل إلى بطاقة تطبيقاتك، ثم انقر على تطبيق Apple على Firebase لعرض معلومات التطبيق، بما في ذلك رقم تعريف التطبيق.
- في الدليل ذي المستوى الأعلى لمشروع Flutter، ابحث عن ملف firebase_options.dart. تم تصنيف معرّف تطبيق Firebase لتطبيقك على Apple على أنّه GOOGLE_APP_ID.
انقر على > مرحلة جديدة لتشغيل النص البرمجي.

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

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

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

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

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

Android

التحقّق من إعدادات التبعيات

يحاول الأمر flutterfire configure إضافة التبعيات اللازمة إلى ملفات إنشاء Gradle الخاصة بمشروعك. في حال عدم توفّر هذه التبعيات، قد يتم تشويش تقارير الأعطال فيconsole 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 CLI (الإصدار 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 لتحديد المشاكل وحلّها في التقارير المشوشة.