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

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