مقدمة

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

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

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

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

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

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

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

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

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

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

في قائمة الأمان، في منتصف الصفحة تقريبًا، هناك قسم مكتوب فيه "تم حظر استخدام "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 Package Manager.

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

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

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

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

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

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

مشاكل "Single 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، يُرجى الرجوع إلى قسم External Dependency Manager for Unity بشأنها.

الخطوات التالية

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