مقدمة

في ما يلي دليل لتصحيح أخطاء عملية الترجمة والإنشاء لألعاب Unity باستخدام حزمة تطوير البرامج (SDK) لمنصّة Firebase في 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. أضِف حزمة تطوير البرامج (SDK) لمنصّة Firebase Unity ك.unitypackage أو
      2. راجِع أحد البدائل في خيارات تثبيت Unity الإضافية ونفِّذه.
   2. تأكَّد من أنّ كل منتج من منتجات Firebase في مشروعك وEDM4U:
      • استخدام الإصدار نفسه
      • تم تثبيتها إما كـ .unitypackage حصريًا أو من خلال "مدير حِزم Unity" حصريًا.

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

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

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

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

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

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

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

إذا ظهرت لك رسالة خطأ عند تشغيل لعبتك في المحرِّر على نظام التشغيل Mac OS مفادها "لا يمكن فتح ملف FirebaseCppApp-<version>.bundle لأنّه لا يمكن التحقّق من المطوّر"، عليك الموافقة على ملف الحِزمة هذا في قائمة "الأمان والخصوصية " على نظام التشغيل Mac.

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

في قائمة الأمان، في منتصف الصفحة تقريبًا، يظهر قسم يشير إلى أنّه "تم حظر استخدام FirebaseCppApp-<version>.bundle لأنّه ليس من مطوّر محدّد".

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

ارجع إلى 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 للتأكّد من تثبيت حِزم SDK لمنصّة Firebase وبرنامج EDM4U من خلال طريقة واحدة فقط.
2. قد تعتمد بعض المكوّنات الإضافية التي طوّرتها Google، مثل Google Play، والمكوّنات الإضافية التابعة لجهات خارجية على EDM4U. وقد تتضمّن هذه المكونات الإضافية EDM4U في حِزم .unitypackage أو حِزم Unity Package Manager (UPM). تأكّد من توفّر نسخة واحدة فقط من EDM4U في مشروعك. إذا كانت أي حِزم UPM تعتمد على EDM4U، من الأفضل الاحتفاظ بإصدارات UPM من EDM4U فقط، والتي يمكن العثور عليها في صفحة Google APIs for Unity Archive.

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

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

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

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

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

مشاكل "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 Studio، تتوفّر أدوات بحث إضافية تسهّل إنشاء عمليات بحث فعّالة.

iOS

فحص السجلات

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

مشاكل Swift

إذا صادفت سجلات أخطاء تشير إلى Swift، يمكنك الرجوع إلى قسم مدير التبعيات الخارجي في Unity لمعرفة كيفية التعامل معها.

خطوات إضافية

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