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

اختيار المنصة:

+iOS Android الويب Flutter Unity

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

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

منصات Apple

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

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

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

1. ابحث عن ملف مساحة عمل Xcode وافتحه في دليل iOS الخاص بمشروعك (FLUTTER_PROJECT_NAME/ios/Runner.xcworkspace).

2. تحديد ما إذا تمت إضافة نص برمجي للتشغيل بعنوان [firebase_crashlytics] Crashlytics Upload Symbols إلى مراحل إنشاء هدف Runner.

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

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

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

1. ابحث عن معرّف تطبيق Firebase لتطبيق Apple. إليك مكانان مختلفان يمكنك العثور فيهما على هذا المعرّف:

   • في وحدة تحكّم Firebase، انتقِل إلى > إعدادات المشروع. انتقِل إلى بطاقة تطبيقاتك، ثم انقر على تطبيق Apple في Firebase لعرض معلومات التطبيق، بما في ذلك رقم تعريف التطبيق.

   • في الدليل ذي المستوى الأعلى لمشروع Flutter، ابحث عن ملف firebase_options.dart. يُشار إلى معرّف تطبيق Firebase لتطبيق Apple الخاص بك بالتصنيف appId.

2. انقر على > New Run Script Phase (مرحلة تشغيل نص برمجي جديدة).

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

3. وسِّع قسم تشغيل النص البرمجي الجديد.

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

4. في حقل النص البرمجي (الموجود أسفل التصنيف 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 المطلوب للعثور على معرّفه.

5. في قسم ملفات الإدخال، أضِف المسارات لمواقع الملفات التالية:

   ${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 في المواقع المحدّدة عن ملفات الإدخال هذه للتأكّد من أنّ ملفات الإصدار متاحة للنص البرمجي للتشغيل. بالإضافة إلى ذلك، في حال تفعيل User Script Sandboxing، يسمح Xcode فقط للنص البرمجي للتشغيل بالوصول إلى الملفات المحدّدة في Input Files.

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

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

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

1. ابحث عن معرّف تطبيق Firebase لتطبيق Apple. إليك مكانان مختلفان يمكنك العثور فيهما على هذا المعرّف:

   • في وحدة تحكّم Firebase، انتقِل إلى > إعدادات المشروع. انتقِل إلى بطاقة تطبيقاتك، ثم انقر على تطبيق Apple في Firebase لعرض معلومات التطبيق، بما في ذلك رقم تعريف التطبيق.

   • في الدليل ذي المستوى الأعلى لمشروع Flutter، ابحث عن ملف firebase_options.dart. يُشار إلى معرّف تطبيق Firebase لتطبيق Apple الخاص بك بالتصنيف appId.

2. عند تشغيل النص البرمجي upload-symbols، استخدِم -ai FIREBASE_APPLE_APP_ID بدلاً من -gsp /path/to/GoogleService-Info.plist.

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

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

تأكَّد من أنّ مشروعك يستخدم إعدادات الإصدار المقترَحة (الإصدار 3.12.0 من Flutter أو الإصدارات الأحدث والمكوّن الإضافي 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'

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

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

استخدِم واجهة سطر الأوامر (CLI) في 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 لتحديد المشاكل وحلّها في التقارير المبهمة.