الحصول على تقارير أعطال قابلة للقراءة في لوحة بيانات 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 إلى مراحل الإنشاء (Build Phases) الخاصة بهدف Runner.

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

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

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

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

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

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

2. انقر على > مرحلة جديدة لتشغيل البرنامج النصي.

   تأكَّد من أنّ مرحلة تشغيل البرنامج النصي الجديدة هذه هي آخر مرحلة إنشاء في مشروعك. وإلا، لن يتمكّن 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 في المواقع المحدّدة عن ملفات الإدخال هذه للتأكّد من توفّر ملفات الإنشاء لبرنامج التشغيل. بالإضافة إلى ذلك، إذا تم تفعيل وضع الحماية لنصوص المستخدمين البرمجية، لن يسمح Xcode إلا للنص البرمجي بتنفيذ الوصول إلى الملفات المحدّدة في ملفات الإدخال.

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

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

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

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

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

   • في الدليل ذي المستوى الأعلى لمشروع Flutter، ابحث عن ملف firebase_options.dart. يتم تصنيف معرّف تطبيق Apple في Firebase على أنّه 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 والإصدار 3.3.4 من المكوّن الإضافي Crashlytics Flutter أو الإصدارات الأحدث) حتى يتمكّن مشروعك من إنشاء رموز 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)

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

استخدِم 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.