مقدمة

في ما يلي دليل لتصحيح أخطاء عملية التجميع والإنشاء لألعاب Unity باستخدام حزمة Firebase SDK لـ Unity. ويصف كيفية التحقيق في العديد من المشاكل الأكثر شيوعًا التي قد تواجهها وحلّها أثناء ضبط لعبتك وإنشائها لمنصة جديدة أو بعد إجراء تحديث. تم ترتيب الأخطاء حسب وقت ظهورها المحتمل في العملية. يُرجى الرجوع إليها بالترتيب واتّباع الخطوات بعد حلّ كل خطأ.

بالإضافة إلى هذا المستند، يُرجى الرجوع إلى الأسئلة الشائعة حول Firebase لـ Unity لمزيد من المعلومات.

مشاكل تجميع "وضع التشغيل"

يمكن أن تحدث الفئة الأولى من مشاكل الإنشاء أثناء الاختبار في المحرّر قبل محاولة بدء إنشاء إصدار للأجهزة الجوّالة. يتناول هذا القسم جميع أخطاء Firebase التي تحدث قبل "وضع التشغيل" وأثناءه.

عندما يبدأ Unity أو يرصد تغييرات في التبعيات أو الرموز أو مواد العرض الأخرى، سيحاول إعادة إنشاء المشروع. إذا تعذّر تجميع المشروع في ذلك الوقت، سيسجِّل المحرّر أخطاء التجميع في وحدة التحكّم، وإذا حاولت الدخول إلى "وضع التشغيل"، ستظهر لك نافذة منبثقة تحتوي على رسالة خطأ في علامة التبويب المشهد في Unity، وهي All compiler errors have to be fixed before you can enter playmode!.

تصحيح أخطاء مشاكل التجميع المرتبطة بـ Firebase

الأنواع والفئات والطرق والأعضاء غير المتوفّرة

تحدث العديد من مشاكل Firebase بسبب عدم قدرة المحرّر والمجمِّع على العثور على الأنواع والفئات والطرق والأعضاء اللازمة. تشمل الأعراض الشائعة لذلك صيغًا مختلفة من ما يلي:

The type or namespace name ‘<CLASS OR NAMESPACE NAME>' could not be found. Are you missing a using directive or an assembly reference?

The type or namespace name <TYPE OR NAMESPACE NAME> does not exist in the namespace ‘Firebase<.OPTIONAL NESTED NAMESPACE NAME PATH>' (are you missing an assembly reference?)

‘<CLASS NAME>' does not contain a definition for ‘<MEMBER VARIABLE OR METHOD NAME>'

خطوات الحلّ:

1. عند استخدام فئات Firebase أو طُرقها في الرمز، تأكَّد من إتاحتها من خلال استخدام توجيهات using الصحيحة لمنتجات Firebase المطلوبة.

   1. أمثلة من MechaHamster: Level Up With Firebase Edition:
      1. using Firebase.RemoteConfig;
      2. using Firebase.Crashlytics;

2. تأكَّد من استيراد حِزم Firebase المناسبة:

   1. لاستيراد الحِزم المناسبة، يمكنك:
      1. أضف حزمة Firebase Unity SDK كملفات .unitypackages أو
      2. الاطّلاع على أحد البدائل وتنفيذه في خيارات تثبيت Unity الإضافية
   2. تأكَّد من أنّ كل منتج من منتجات Firebase في مشروعك وEDM4U:
      • يستخدم الإصدار نفسه
      • تم تثبيته إما كملفات .unitypackage فقط أو من خلال "إدارة حِزم Unity" فقط.

3. إذا استوردت حزمة Firebase Unity SDK قبل الإصدار "10.0.0" كملفات .unitypackage، يحتوي أرشيف zip الخاص بحزمة Firebase Unity SDK على حِزم لكل من دعم ‎ .NET 3.x و‎ .NET 4.x. تأكَّد من تضمين مستوى ‎ .NET Framework المتوافق فقط في مشروعك:

   1. تمت مناقشة التوافق بين إصدارات Unity Editor ومستويات ‎ .NET Framework في مقالة إضافة Firebase إلى مشروع Unity.
   2. إذا استوردت حِزم Firebase عن طريق الخطأ على مستوى ‎ .NET Framework غير الصحيح أو كنت بحاجة إلى التبديل من استخدام .unitypackages إلى أحد خيارات تثبيت Unity الإضافية ، فإنّ الطريقة الأسهل هي إزالة كل حزمة من حِزم Firebase من خلال الطُرق المذكورة في قسم نقل البيانات هذا، ثم إعادة استيراد جميع حِزم Firebase مرة أخرى.

4. تأكَّد من أنّ المحرّر يعيد إنشاء مشروعك وأنّ محاولاتك تشغيل اللعبة تعكس أحدث حالة لمشروعك:

   1. يكون Unity Editor مضبوطًا تلقائيًا على إعادة الإنشاء كلما تم رصد تغييرات في مواد العرض أو الإعدادات.
   2. من المحتمل أن تكون هذه الوظيفة غير مفعّلة وأن يكون Unity Editor مضبوطًا على التحديث اليدوي أو إعادة التجميع. تحقَّق من ذلك وحاوِل إجراء تحديث يدوي إذا كان هذا هو الحال.

أخطاء وقت التشغيل في "وضع التشغيل"

إذا بدأت لعبتك، ولكن واجهت مشاكل في Firebase أثناء التشغيل، جرِّب ما يلي:

تأكَّد من الموافقة على حِزم Firebase في "الأمان والخصوصية" على نظام التشغيل Mac OS

إذا ظهر لك مربّع حوار عند بدء تشغيل لعبتك في المحرّر على نظام التشغيل Mac OS، وكان نصّه "FirebaseCppApp-<version>.bundle Cannot be opened because the developer cannot be verified."، عليك الموافقة على ملف الحزمة المحدّد هذا في قائمة "الأمان والخصوصية" على جهاز Mac.

لإجراء ذلك، انقر على رمز Apple > الإعدادات المفضَّلة للنظام > الأمان والخصوصية.

في قائمة "الأمان"، في منتصف الصفحة تقريبًا، هناك قسم مكتوب فيه ""FirebaseCppApp-<version>.bundle" was blocked from use because it is not from an identified developer."

انقر على الزر السماح على أي حال.

ارجع إلى Unity وانقر على تشغيل مرة أخرى.

سيظهر لك بعد ذلك تحذير مشابه للأول:

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

تأكَّد من أنّ مشروعك يحتوي على ملفات إعداد صالحة ويستخدمها

1. تأكَّد من ضبط إعدادات الإنشاء على الهدف الذي تريده (iOS أو Android) في ملف > إعدادات الإنشاء. لمناقشة أكثر تفصيلاً، يُرجى قراءة مستندات إعدادات الإنشاء في Unity.
2. نزِّل ملف الإعداد لتطبيقك (google-services.json لنظام Android أو GoogleService-Info.plist لنظام iOS) والهدف من الإنشاء من وحدة تحكّم Firebase في إعدادات المشروع > تطبيقاتك: إذا كانت لديك هذه الملفات، احذفها في مشروعك واستبدلها بأحدث إصدار، مع التأكّد من كتابة أسمائها تمامًا كما هو موضّح أعلاه بدون "(1)" أو أرقام أخرى مرفقة بأسماء الملفات.
3. إذا كانت وحدة التحكّم تحتوي على رسالة بشأن الملفات في Assets/StreamingAssets/، تأكَّد من عدم ظهور أي رسائل في وحدة التحكّم تشير إلى أنّ Unity لم يتمكّن من تعديل الملفات هناك.
4. تأكَّد من إنشاء الملف Assets/StreamingAssets/google-services-desktop.json وأنّه يطابق ملف الإعداد الذي تم تنزيله.
   • إذا لم يتم إنشاؤه تلقائيًا ولم يكن StreamingAssets/ موجودًا، فأنشئ الدليل يدويًا في الدليل Assets.
   • تحقَّق مما إذا كان Unity قد أنشأ الآن الملف google-services-desktop.json.

تأكَّد من أنّ كل منتج من منتجات Firebase وEDM4U تم تثبيتهما من خلال .unitypackage أو "إدارة حِزم Unity" فقط

1. تحقَّق من كل من المجلد Assets/ و"إدارة حِزم Unity" للتأكّد من أنّ حِزم Firebase SDK وEDM4U تم تثبيتهما من خلال إحدى الطريقتَين فقط.
2. قد تعتمد بعض المكوّنات الإضافية التي طوّرتها Google، مثل Google Play، والمكوّنات الإضافية التابعة لجهات خارجية على EDM4U. قد تتضمّن هذه المكوّنات الإضافية EDM4U في .unitypackage أو حِزم "إدارة حِزم Unity" (UPM). تأكَّد من وجود نسخة واحدة فقط من EDM4U في مشروعك. إذا كانت أي حِزم UPM تعتمد على EDM4U، من الأفضل الاحتفاظ بإصدارات UPM فقط من EDM4U، والتي يمكن العثور عليها في صفحة أرشيف Google APIs for Unity.

تأكَّد من أنّ كل منتج من منتجات Firebase في مشروعك يستخدم الإصدار نفسه.

1. إذا تم تثبيت حِزم Firebase SDK من خلال ملف .unitypackage، تحقَّق مما إذا كانت جميع مكتبات FirebaseCppApp ضِمن Assets/Firebase/Plugins/x86_64/ تستخدم الإصدار نفسه.
2. إذا تم تثبيت حِزم Firebase SDK من خلال "إدارة حِزم Unity" (UPM)، افتح النوافذ > إدارة الحِزم، وابحث عن "Firebase" وتأكَّد من أنّ جميع حِزم Firebase تستخدم الإصدار نفسه.
3. إذا كان مشروعك يحتوي على إصدارات مختلفة من حِزم Firebase SDK، ننصحك بإزالة جميع حِزم Firebase SDK بالكامل قبل إعادة تثبيتها، ولكن هذه المرة باستخدام الإصدارات نفسها. الطريقة الأسهل هي إزالة كل حزمة من حِزم Firebase من خلال الطُرق المذكورة في قسم نقل البيانات هذا.

أخطاء الإنشاء في أداة الحلّ والجهاز المستهدف

إذا كانت لعبتك تعمل في المحرّر (الذي تم ضبطه على هدف الإنشاء المناسب الذي اخترته)، تأكَّد بعد ذلك من أنّ أداة External Dependency Manager for Unity (EDM4U) تم ضبطها بشكل صحيح وتعمل.

يحتوي مستودع EDM4U على GitHub على دليل تفصيلي لهذا الجزء من العملية، ويجب مراجعته واتّباعه قبل المتابعة.

مشاكل "ملف dex واحد" والتصغير (إلزامي في حال استخدام Cloud Firestore)

أثناء إنشاء تطبيق Android، قد تواجه عملية إنشاء فاشلة مرتبطة بملف dex واحد. تبدو رسالة الخطأ مشابهة لما يلي (إذا كان مشروعك مضبوطًا على استخدام نظام التصميم Gradle):

Cannot fit requested classes in a single dex file.

تُستخدم ملفات .dex لتخزين مجموعة من تعريفات الفئات والبيانات الملحقة المرتبطة بها لتطبيقات Android. يقتصر ملف dex واحد على الإشارة إلى 65,536 طريقة، وستفشل عمليات الإنشاء إذا كان إجمالي عدد الطرق من جميع مكتبات Android في مشروعك يتجاوز هذا الحد.

يمكن تطبيق الخطوتَين التاليتَين بالتسلسل، ولا تفعِّل ميزة multidex إلا إذا لم يؤدِّ التصغير إلى حلّ المشكلة.

تفعيل التصغير

طرحت Unity ميزة التصغير في الإصدار 2017.2 لإزالة الرموز غير المستخدَمة، ما يمكن أن يقلّل إجمالي عدد الطرق التي تتم الإشارة إليها في ملف dex واحد. * يمكن العثور على الخيار في إعدادات المشغّل > Android > إعدادات النشر > التصغير. * قد تختلف الخيارات في إصدارات Unity المختلفة، لذا يُرجى الرجوع إلى مستندات Unity الرسمية.

تفعيل ميزة multidex

إذا كان عدد الطرق التي تتم الإشارة إليها لا يزال يتجاوز الحدّ بعد تفعيل التصغير، هناك خيار آخر وهو تفعيل multidex. هناك طرق متعددة لتحقيق ذلك في Unity:

• إذا كانت قالب Gradle مخصّص ضِمن إعدادات المشغّل مفعّلة، عدِّل الملف mainTemplate.gradle.
• إذا كنت تستخدم "استوديو Android" لإنشاء المشروع الذي تم تصديره، عدِّل ملف build.gradle على مستوى الوحدة.

يتوفّر المزيد من التفاصيل في دليل مستخدم multidex.

فهم أخطاء وقت التشغيل على جهاز الاختبار وحلّها

إذا كانت لعبتك تعمل في المحرّر ويمكن إنشاؤها وتثبيتها على جهاز الاختبار، ولكن واجهت أخطاء وقت التشغيل، افحص السجلات التي تم إنشاؤها على الجهاز وحقِّق فيها.

يوضّح هذا القسم كيفية التحقيق في السجلات بحثًا عن الأخطاء المحتملة وأحد هذه الأخطاء التي تحدث فقط في وقت التشغيل على الجهاز أو المحاكي.

Android

مُحاكي

• افحص السجلات المعروضة في وحدة تحكّم المحاكي أو اعرض نافذة Logcat.

الجهاز

تعرَّف على adb وadb logcat وكيفية استخدامهما.

• على الرغم من أنّه يمكنك استخدام الأدوات المختلفة في بيئة سطر الأوامر لفلترة الناتج، يمكنك بدلاً من ذلك الاطّلاع على خيارات logcat.

• إليك طريقة بسيطة لبدء جلسة ADB من البداية:

  adb logcat -c && adb logcat <OPTIONS>

  حيث OPTIONS هي أي علامات تمرِّرها إلى سطر الأوامر لفلترة الناتج.

استخدام Logcat من خلال "استوديو Android"

عند استخدام Logcat من خلال "استوديو Android"، تتوفّر أدوات بحث إضافية تجعل عمليات البحث المنتجة أسهل.

iOS

فحص السجلات

إذا كنت تستخدم جهازًا فعليًا، اربطه بجهاز الكمبيوتر. افحص lldb في Xcode.

مشاكل Swift

إذا ظهرت لك سجلات أخطاء تشير إلى Swift، يُرجى الرجوع إلى قسم External Dependency Manager for Unity بشأنها.

الخطوات الإضافية

إذا كانت لعبتك لا تزال تواجه مشاكل في التجميع أو الإنشاء أو التشغيل مرتبطة بـ Firebase، يُرجى التحقيق في صفحة المشاكل في حزمة Firebase SDK لـ Unity والنظر في تسجيل مشكلة جديدة. بالإضافة إلى ذلك، يُرجى الرجوع إلى صفحة دعم Firebase للتعرّف على الخيارات الإضافية.