فهم أعطال لعبة Unity باستخدام ميزات Crashlytics المتقدمة فهم أعطال لعبة Unity باستخدام ميزات Crashlytics المتقدمة

1 المقدمة

في هذا الدرس التطبيقي حول التعليمات البرمجية، ستتعلم كيفية استخدام الميزات المتقدمة في Crashlytics والتي ستمنحك رؤية أفضل للحوادث والظروف التي قد تكون سببتها.

ستضيف وظائف جديدة إلى نموذج لعبة MechaHamster: Level Up with Firebase Edition . نموذج اللعبة هذا هو إصدار جديد من لعبة Firebase الكلاسيكية MechaHamster التي تزيل معظم وظائف Firebase المضمنة بها، مما يتيح لك الفرصة لتنفيذ استخدامات جديدة لـ Firebase في مكانها.

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

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

ما ستتعلمه

• أنواع الأخطاء التي يتم اكتشافها تلقائيًا بواسطة Crashlytics.
• أخطاء إضافية يمكن تسجيلها عن قصد.
• كيفية إضافة المزيد من المعلومات إلى هذه الأخطاء لتسهيل فهمها.

ماذا ستحتاج

• Unity (الحد الأدنى للإصدار الموصى به 2019+) مع واحد أو كليهما مما يلي:
  • دعم بناء iOS
  • دعم بناء أندرويد
• (لنظام Android فقط) واجهة سطر أوامر Firebase (المستخدمة لتحميل الرموز لتقارير الأعطال)
  • اتبع الإرشادات لتثبيت Firebase CLI .
    إذا قمت بالفعل بتثبيت واجهة سطر الأوامر (CLI)، فتأكد من التحديث إلى الإصدار الأحدث .

2. قم بإعداد بيئة التطوير الخاصة بك

تصف الأقسام التالية كيفية تنزيل كود Level Up with Firebase وفتحه في Unity.

لاحظ أن نموذج لعبة Level Up with Firebase يتم استخدامه من قبل العديد من مختبرات التعليمات البرمجية الأخرى الخاصة بـ Firebase + Unity، لذلك ربما تكون قد أكملت المهام الواردة في هذا القسم بالفعل. إذا كان الأمر كذلك، فيمكنك الانتقال مباشرة إلى الخطوة الأخيرة في هذه الصفحة: "إضافة Firebase SDKs for Unity".

قم بتنزيل الكود

قم باستنساخ مستودع GitHub الخاص ببرنامج Codelab من سطر الأوامر:

git clone https://github.com/firebase/level-up-with-firebase.git

وبدلاً من ذلك، إذا لم يكن git مثبتًا لديك، فيمكنك تنزيل المستودع كملف ZIP .

افتح Level Up with Firebase في محرر Unity

1. قم بتشغيل Unity Hub، ومن علامة تبويب "المشاريع" ، انقر فوق سهم القائمة المنسدلة بجوار " فتح" .
2. انقر فوق إضافة مشروع من القرص .
3. انتقل إلى الدليل الذي يحتوي على الرمز، ثم انقر فوق موافق .
4. إذا طُلب منك، حدد إصدار محرر Unity الذي تريد استخدامه والنظام الأساسي المستهدف (Android أو iOS).
5. انقر فوق اسم المشروع، Level-up-with-firebase ، وسيتم فتح المشروع في محرر Unity.
6. إذا لم يفتحه المحرر تلقائيًا، فافتح MainGameScene في Assets > Hamster في علامة تبويب Project في Unity Editor.
   

لمزيد من المعلومات حول تثبيت Unity واستخدامه، راجع العمل في Unity .

3. أضف Firebase إلى مشروع Unity الخاص بك

إنشاء مشروع Firebase

1. في وحدة تحكم Firebase ، انقر فوق إضافة مشروع .
2. لإنشاء مشروع جديد، أدخل اسم المشروع المطلوب.
   سيؤدي هذا أيضًا إلى تعيين معرف المشروع (المعروض أسفل اسم المشروع) على شيء يعتمد على اسم المشروع. يمكنك اختياريًا النقر فوق أيقونة التحرير الموجودة على معرف المشروع لتخصيصه بشكل أكبر.
3. إذا طُلب منك، راجع شروط Firebase واقبلها.
4. انقر فوق "متابعة" .
5. حدد خيار تمكين Google Analytics لهذا المشروع ، ثم انقر فوق متابعة .
6. حدد حساب Google Analytics موجودًا لاستخدامه أو حدد إنشاء حساب جديد لإنشاء حساب جديد.
7. انقر فوق إنشاء مشروع .
8. عندما يتم إنشاء المشروع، انقر فوق "متابعة" .

سجل تطبيقك مع Firebase

1. لا يزال في وحدة تحكم Firebase ، من وسط صفحة النظرة العامة على المشروع، انقر فوق أيقونة Unity لبدء سير عمل الإعداد، أو إذا كنت قد أضفت بالفعل تطبيقًا إلى مشروع Firebase الخاص بك، فانقر فوق إضافة تطبيق لعرض خيارات النظام الأساسي.
2. حدد لتسجيل أهداف إنشاء كل من Apple (iOS) وAndroid.
3. أدخل المعرف (المعرفات) الخاص بالنظام الأساسي لمشروع Unity الخاص بك. بالنسبة لهذا الدرس التطبيقي حول التعليمات البرمجية، أدخل ما يلي:
   • بالنسبة إلى Apple (iOS) : أدخل com.google.firebase.level-up في حقل معرف حزمة iOS .
   • لنظام Android : أدخل com.google.firebase.level_up في حقل اسم حزمة Android .

   هام : يختلف معرف حزمة iOS واسم حزمة Android أعلاه. معرف iOS غير صالح لنظام Android والعكس صحيح. تأكد من أنك تستخدم المعرف الصحيح.

4. (اختياري) أدخل اللقب (الأسماء المستعارة) الخاص بالمنصة الخاصة بمشروع Unity الخاص بك.
5. انقر فوق تسجيل التطبيق ، ثم انتقل إلى قسم تنزيل ملف التكوين .

أضف ملفات تكوين Firebase

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

1. قم بتنزيل كلا ملفي التكوين المتاحين:
   • بالنسبة لنظام Apple (iOS) : قم بتنزيل GoogleService-Info.plist .
   • لنظام Android : قم بتنزيل google-services.json .
2. افتح نافذة المشروع في مشروع Unity الخاص بك، ثم انقل ملفي التكوين إلى مجلد الأصول .

   هام: حتى إذا كنت تخطط لإنشاء iOS أو Android فقط، فيجب عليك تنزيل كلا الملفين وإضافتهما إلى مشروعك.

3. مرة أخرى في وحدة تحكم Firebase، في سير عمل الإعداد، انقر فوق "التالي" وتابع إلى إضافة Firebase SDKs for Unity.

ملاحظة: يمكنك دائمًا إعادة تنزيل هذه الملفات في وقت لاحق عن طريق فتح الإعدادات العامة لمشروعك، والتمرير لأسفل إلى قسم تطبيقاتك ، ثم النقر فوق زر التنزيل لملف التكوين المطلوب.

أضف حزم Firebase SDK للوحدة

1. انقر فوق تنزيل Firebase Unity SDK في وحدة تحكم Firebase.

   ملاحظة: قد يستغرق تنزيل SDK هذا بعض الوقت. تناولوا القهوة أو الشاي - ابقوا رطبين يا أصدقائي.

2. قم بفك ضغط SDK في مكان مناسب.
3. في مشروع Unity المفتوح لديك، انتقل إلى Assets > Import Package > Custom Package .
4. في مربع حوار استيراد الحزمة ، انتقل إلى الدليل الذي يحتوي على SDK غير المضغوط، وحدد FirebaseAnalytics.unitypackage ، ثم انقر فوق فتح .
5. من مربع الحوار "استيراد حزمة الوحدة" الذي يظهر، انقر فوق "استيراد" .
6. كرر الخطوات السابقة لاستيراد FirebaseCrashlytics.unitypackage .
7. ارجع إلى وحدة تحكم Firebase، وفي سير عمل الإعداد، انقر فوق التالي .

لمزيد من المعلومات حول إضافة Firebase SDK إلى مشاريع Unity، راجع خيارات تثبيت Unity الإضافية .

4. قم بإعداد Crashlytics في مشروع الوحدة الخاص بك

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

تهيئة Crashlytics SDK

1. في Assets/Hamster/Scripts/MainGame.cs ، قم بإضافة ما يلي using العبارات:

   using Firebase.Crashlytics;
   using Firebase.Extensions;
   

   الوحدة الأولى تسمح لك باستخدام أساليب من Crashlytics SDK والثانية تحتوي على بعض الامتدادات إلى C# Tasks API . بدون using كلا العبارات، لن يعمل الكود التالي.
2. لا يزال في MainGame.cs ، أضف تهيئة Firebase إلى أسلوب Start() الموجود عن طريق استدعاء InitializeFirebaseAndStartGame() :

   void Start()
   {
     Screen.SetResolution(Screen.width / 2, Screen.height / 2, true);
     InitializeFirebaseAndStartGame();
   }
   

3. ومرة أخرى، في MainGame.cs ، ابحث عن InitializeFirebaseAndStartGame() ، وقم بتعريف متغير التطبيق، ثم قم بالكتابة فوق تنفيذ الطريقة كما يلي:

   public Firebase.FirebaseApp app = null;
   
   // Begins the firebase initialization process and afterwards, opens the main menu.
   private void InitializeFirebaseAndStartGame()
   {
     Firebase.FirebaseApp.CheckAndFixDependenciesAsync()
     .ContinueWithOnMainThread(
       previousTask => 
       {
         var dependencyStatus = previousTask.Result;
         if (dependencyStatus == Firebase.DependencyStatus.Available) {
           // Create and hold a reference to your FirebaseApp,
           app = Firebase.FirebaseApp.DefaultInstance;
           // Set the recommended Crashlytics uncaught exception behavior.
           Crashlytics.ReportUncaughtExceptionsAsFatal = true;
           InitializeCommonDataAndStartGame();
         } else {
           UnityEngine.Debug.LogError(
             $"Could not resolve all Firebase dependencies: {dependencyStatus}\n" +
             "Firebase Unity SDK is not safe to use here");
         }
       });
   }
   

يؤدي وضع منطق التهيئة هنا إلى منع تفاعل اللاعب قبل تهيئة تبعيات Firebase.

تمت مناقشة فوائد وتأثيرات الإبلاغ عن الاستثناءات غير المعالجة على أنها قاتلة في الأسئلة الشائعة حول Crashlytics .

قم ببناء مشروعك وتحميل الرموز

ملاحظة: أكمل الخطوات الواردة في هذا القسم لإعداد Crashlytics. بعد ذلك، في المستقبل، أكمل هذه الخطوات في كل مرة تقوم فيها بإنشاء إصدار إصدار أو أي إصدار تريد رؤية آثار المكدس المرمزة له في وحدة تحكم Firebase (في هذا الدرس التطبيقي حول الترميز، بعد كل خطوة).

تختلف خطوات إنشاء الرموز وتحميلها بين تطبيقات iOS وAndroid.

iOS+ (منصة أبل)

1. من مربع حوار إعدادات البناء ، قم بتصدير مشروعك إلى مساحة عمل Xcode.
2. أنشئ تطبيقك.
   بالنسبة لمنصات Apple الأساسية، يقوم المكون الإضافي Firebase Unity Editor تلقائيًا بتكوين مشروع Xcode الخاص بك لإنشاء وتحميل ملف رمز متوافق مع Crashlytics إلى خوادم Firebase لكل إصدار. معلومات الرموز هذه مطلوبة لرؤية تتبعات المكدس المرمزة في لوحة معلومات Crashlytics.

ذكري المظهر

1. (فقط أثناء الإعداد الأولي، وليس لكل إصدار) قم بإعداد الإصدار الخاص بك:
   1. قم بإنشاء مجلد جديد يسمى Builds في جذر دليل المشروع الخاص بك (أي كتابع لدليل الأصول الخاص بك)، ثم قم بإنشاء مجلد فرعي يسمى Android .
   2. في ملف > إعدادات البناء > إعدادات المشغل > التكوين ، اضبط Scripting Backend على IL2CPP.
      • يؤدي IL2CPP بشكل عام إلى أن تكون الإصدارات أصغر حجمًا وأن يكون لها أداء أفضل.
      • يعد IL2CPP أيضًا الخيار الوحيد المتاح على نظام التشغيل iOS، ويتيح تحديده هنا للمنصتين أن يكونا في تكافؤ أفضل ويجعل تصحيح الأخطاء بين الاثنين (إذا اخترت إنشاء كليهما) أكثر بساطة.
2. أنشئ تطبيقك. في ملف > إعدادات البناء ، أكمل ما يلي:
   1. تأكد من تحديد خيار إنشاء الرموز.zip (أو في حالة ظهور قائمة منسدلة، حدد تصحيح الأخطاء ).
   2. أنشئ ملف APK الخاص بك مباشرة من Unity Editor إلى المجلد الفرعي Builds/Android الذي أنشأته للتو.
3. بمجرد الانتهاء من البناء الخاص بك، تحتاج إلى إنشاء ملف رمز متوافق مع Crashlytics وتحميله إلى خوادم Firebase. معلومات الرموز هذه مطلوبة لرؤية آثار المكدس المرمزة لتعطل المكتبة الأصلية في لوحة معلومات Crashlytics.
   
   قم بإنشاء ملف الرموز هذا وتحميله عن طريق تشغيل أمر Firebase CLI التالي:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

   • FIREBASE_APP_ID : معرف تطبيق Firebase Android الخاص بك (وليس اسم الحزمة الخاصة بك). ابحث عن هذه القيمة في ملف google-services.json الذي قمت بتنزيله مسبقًا. إنها قيمة mobilesdk_app_id .
     مثال لمعرف تطبيق Firebase Android: 1:567383003300:android:17104a2ced0c9b9b
   • PATH/TO/SYMBOLS : مسار ملف الرمز المضغوط الذي تم إنشاؤه في دليل Builds/Android عند انتهاء البناء (على سبيل المثال: Builds/Android/myapp-1.0-v100.symbols.zip ).

     ملاحظة: سيتغير اسم الملف هذا عندما يتم إنشاء المشروع بأرقام مختلفة تم تعيينها Version Bundle Version Code في ملف > إعدادات البناء > إعدادات المشغل > التعريف .

فرض تعطل اختباري لإنهاء الإعداد

لإنهاء إعداد Crashlytics والاطلاع على البيانات الأولية في لوحة معلومات Crashlytics بوحدة تحكم Firebase، يلزمك فرض اختبار التعطل.

1. في MainGameScene، ابحث عن EmptyObject GameObject في التسلسل الهرمي للمحرر ، وأضف البرنامج النصي التالي إليه ثم احفظ المشهد. سيؤدي هذا البرنامج النصي إلى تعطل الاختبار بعد ثوانٍ قليلة من تشغيل تطبيقك.

   using System;
   using UnityEngine;
   
   public class CrashlyticsTester : MonoBehaviour {
       // Update is called once per frame
       void Update()
       {
           // Tests your Crashlytics implementation by
           // throwing an exception every 60 frames.
           // You should see reports in the Firebase console
           // a few minutes after running your app with this method.
           if(Time.frameCount >0 && (Time.frameCount%60) == 0)
           {
               throw new System.Exception("Test exception; please ignore");
           }
       }
   }
   

2. أنشئ تطبيقك وقم بتحميل معلومات الرمز بعد انتهاء البناء.
   • iOS : يقوم البرنامج الإضافي Firebase Unity Editor تلقائيًا بتكوين مشروع Xcode الخاص بك لتحميل ملف الرمز الخاص بك.
   • Android : قم بتشغيل أمر Firebase CLI crashlytics:symbols:upload لتحميل ملف الرمز الخاص بك.

   ملاحظة: إذا كانت هذه هي المرة الأولى التي تقوم فيها بإنشاء هدف جوال معين، فقد يستغرق وقت البناء هذا عدة دقائق. ستكون عمليات البناء اللاحقة أسرع بكثير.

3. قم بتشغيل التطبيق الخاص بك. بمجرد تشغيل تطبيقك، شاهد سجل الجهاز وانتظر حتى يتم تشغيل الاستثناء من CrashlyticsTester .
   • iOS : عرض السجلات في الجزء السفلي من Xcode.
   • Android : اعرض السجلات عن طريق تشغيل الأمر التالي في الوحدة الطرفية: adb logcat .
4. تفضل بزيارة لوحة معلومات Crashlytics لعرض الاستثناء! ستراها في جدول المشكلات أسفل لوحة التحكم. لاحقًا في الدرس التطبيقي حول الترميز، ستتعرف على المزيد حول كيفية استكشاف هذه التقارير.
5. بمجرد التأكد من تحميل الحدث إلى Crashlytics، حدد EmptyObject GameObject الذي أرفقته به، وقم بإزالة مكون CrashlyticsTester فقط، ثم احفظ المشهد لاستعادته إلى حالته الأصلية.

5. تمكين وفهم قائمة التصحيح

لقد أضفت حتى الآن Crashlytics إلى مشروع Unity الخاص بك، وانتهيت من الإعداد، وأكدت أن Crashlytics SDK يقوم بتحميل الأحداث إلى Firebase. ستقوم الآن بإنشاء قائمة في مشروع Unity الخاص بك والتي ستوضح كيفية استخدام وظائف Crashlytics الأكثر تقدمًا في لعبتك. يحتوي مشروع Level Up with Firebase Unity بالفعل على قائمة تصحيح مخفية ستجعلها مرئية وتكتب الوظيفة الخاصة بها.

تمكين قائمة التصحيح

يوجد زر الوصول إلى قائمة التصحيح في مشروع Unity الخاص بك، ولكنه غير ممكّن حاليًا. يجب عليك تمكين الزر للوصول إليه من القائمة الجاهزة MainMenu :

1. في محرر الوحدة، افتح المبنى الجاهز المسمى MainMenu .
2. في التسلسل الهرمي للهيكل الجاهز، ابحث عن الكائن الفرعي المعطل المسمى DebugMenuButton ، ثم حدده.
3. قم بتمكين DebugMenuButton عن طريق تحديد المربع الموجود في الزاوية العلوية اليسرى على يسار حقل النص الذي يحتوي على DebugMenuButton .
4. حفظ الجاهزة.
5. قم بتشغيل اللعبة إما في المحرر أو على جهازك. يجب أن تكون القائمة متاحة الآن.

هام : بما أن أساليب التعطل لم يتم تنفيذها حاليًا، فإن النقر على الأزرار الخاصة بها سيؤدي إلى ظهور System.NotImplementedException وعدم القيام بأي شيء بخلاف ذلك.

قم بمعاينة وفهم نصوص الطريقة لقائمة التصحيح

لاحقًا في هذا الدرس التطبيقي حول التعليمات البرمجية، ستكتب نصوص الطرق لبعض أساليب تصحيح أخطاء Crashlytics التي تم تكوينها مسبقًا. في مشروع Level Up with Firebase Unity، يتم تعريف التوابع واستدعائها من DebugMenu.cs .

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

افتح DebugMenu.cs ، ثم ابحث عن الطرق التالية:

طرق إنشاء مشكلات Crashlytics والتعليق عليها:

• CrashNow
• LogNonfatalError
• LogStringsAndCrashNow
• SetAndOverwriteCustomKeyThenCrash
• SetLogsAndKeysBeforeANR

طرق تسجيل أحداث Analytics للمساعدة في تصحيح الأخطاء:

• LogProgressEventWithStringLiterals
• LogIntScoreWithBuiltInEventAndParams

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

6. ضمان تسليم تقارير الأعطال في التطوير

قبل البدء في تنفيذ طرق تصحيح الأخطاء هذه ومعرفة مدى تأثيرها على تقارير الأعطال، تأكد من فهمك لكيفية إبلاغ Crashlytics بالأحداث.

بالنسبة لمشاريع Unity، تتم كتابة أحداث الأعطال والاستثناءات في لعبتك على القرص على الفور. بالنسبة للاستثناءات التي لم يتم اكتشافها والتي لا تؤدي إلى تعطل لعبتك (على سبيل المثال، استثناءات C# التي لم يتم اكتشافها في منطق اللعبة)، يمكنك جعل Crashlytics SDK يبلغ عنها كأحداث قاتلة عن طريق تعيين خاصية Crashlytics.ReportUncaughtExceptionsAsFatal على القيمة true حيث تقوم بتهيئة Crashlytics في مشروع Unity الخاص بك . يتم الإبلاغ عن هذه الأحداث إلى Crashlytics في الوقت الفعلي دون الحاجة إلى قيام المستخدم النهائي بإعادة تشغيل اللعبة. لاحظ أنه يتم دائمًا الإبلاغ عن الأعطال الأصلية كأحداث قاتلة ويتم إرسالها عندما يقوم المستخدم النهائي بإعادة تشغيل اللعبة.

ملاحظة: للإبلاغ عن الاستثناءات التي لم يتم اكتشافها كأحداث قاتلة، يجب أن يستخدم مشروع Unity الخاص بك Firebase Crashlytics Unity SDK v10.4.0 والإصدارات الأحدث.

بالإضافة إلى ذلك، كن على دراية بالاختلافات الصغيرة - ولكن الهامة - التالية بين كيفية قيام بيئات التشغيل المختلفة بإرسال معلومات Crashlytics إلى Firebase:

محاكي iOS:

• يتم الإبلاغ عن معلومات Crashlytics فقط إذا قمت بفصل Xcode عن جهاز المحاكاة. إذا تم إرفاق Xcode، فإنه يلتقط الأخطاء في المراحل الأولية، مما يمنع تسليم المعلومات.

الأجهزة المادية المحمولة (Android وiOS):

• خاص بنظام التشغيل Android: يتم الإبلاغ عن أخطاء ANR فقط على نظام التشغيل Android 11+. يتم الإبلاغ عن حالات ANR والأحداث غير المميتة في الجولة التالية.

محرر الوحدة:

• لا يتم تسجيل معلومات Crashlytics الواردة من المحرر في وضع التشغيل أو بشكل مستقل أو تحميلها إلى Firebase. علاوة على ذلك، فإن سير عمل تطوير Firebase Desktop لا يدعم Crashlytics .

اختبر تعطل لعبتك بلمسة زر واحدة في CrashNow()

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

1. لتوضيح أن هذا الأمر تلقائي بالفعل: افتح DebugMenu.cs ، ثم قم بالكتابة فوق الأسلوب CrashNow() كما يلي:

   void CrashNow()
   {
       TestCrash();
   }
   

2. أنشئ تطبيقك.
3. (Android فقط) قم بتحميل الرموز الخاصة بك عن طريق تشغيل أمر Firebase CLI التالي:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

4. اضغط على زر "التعطل الآن "، وانتقل إلى الخطوة التالية من الدرس التطبيقي حول التعليمات البرمجية لمعرفة كيفية عرض تقرير الأعطال وتفسيره.

7. فهم تقارير المشكلات في وحدة تحكم Firebase

عندما يتعلق الأمر بعرض تقارير الأعطال، هناك المزيد الذي تحتاج إلى معرفته حول كيفية تحقيق أقصى استفادة منها. ستظهر كل طريقة من الطرق التي تكتبها كيفية إضافة أنواع مختلفة من المعلومات إلى تقارير Crashlytics.

1. اضغط على زر Crash Now ، ثم أعد تشغيل التطبيق.
2. انتقل إلى لوحة تحكم Crashlytics . قم بالتمرير لأسفل إلى جدول المشكلات أسفل لوحة المعلومات حيث تقوم Crashlytics بتجميع الأحداث التي لها نفس السبب الجذري في "المشكلات".
3. انقر على المشكلة الجديدة المدرجة في جدول المشكلات . يؤدي القيام بذلك إلى عرض ملخص الحدث حول كل حدث فردي تم إرساله إلى Firebase.
   
   يجب أن تشاهد شيئًا مثل لقطة الشاشة التالية. لاحظ كيف يعرض ملخص الحدث بشكل بارز تتبع المكدس للمكالمة التي أدت إلى التعطل.

البيانات الوصفية الإضافية

علامة التبويب المفيدة الأخرى هي علامة التبويب Unity Metadata . يُعلمك هذا القسم بسمات الجهاز الذي وقع عليه الحدث، بما في ذلك الميزات المادية وطراز/مواصفات وحدة المعالجة المركزية وجميع أنواع مقاييس وحدة معالجة الرسومات.

فيما يلي مثال حيث قد تكون المعلومات الموجودة في علامة التبويب هذه مفيدة:
تخيل أن لعبتك تستخدم التظليل بكثافة لتحقيق مظهر معين، ولكن ليس كل الهواتف تحتوي على وحدات معالجة رسومات قادرة على عرض هذه الميزة. يمكن أن تمنحك المعلومات الموجودة في علامة التبويب Unity Metadata فكرة أفضل عن الأجهزة التي يجب أن يختبرها تطبيقك عند تحديد الميزات التي سيتم توفيرها تلقائيًا أو تعطيلها بالكامل.

على الرغم من أن خطأ أو تعطلًا قد لا يحدث أبدًا على جهازك ، نظرًا للتنوع الهائل لأجهزة Android في البرية، إلا أنه يساعد على فهم "النقاط الساخنة" المحددة لأجهزة جمهورك بشكل أفضل.

8. قم برمي الاستثناء والتقاطه وتسجيله

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

1. في Assets/Hamster/Scripts/States/DebugMenu.cs ، قم بإلحاق ما يلي بعبارات using :

   // Import Firebase
   using Firebase.Crashlytics;
   

2. لا تزال في DebugMenu.cs ، قم بالكتابة فوق LogNonfatalError() كما يلي:

   void LogNonfatalError()
   {
       try
       {
           throw new System.Exception($"Test exception thrown in {nameof(LogNonfatalError)}");
       }
       catch(System.Exception exception)
       {
           Crashlytics.LogException(exception);
       }
   }
   

3. أنشئ تطبيقك.
4. (Android فقط) قم بتحميل الرموز الخاصة بك عن طريق تشغيل أمر Firebase CLI التالي:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

5. اضغط على زر تسجيل الأخطاء غير الفادحة ، ثم أعد تشغيل التطبيق.
6. انتقل إلى لوحة معلومات Crashlytics ، ومن المفترض أن ترى شيئًا مشابهًا لما رأيته في الخطوة الأخيرة من هذا الدرس التطبيقي حول التعليمات البرمجية.
7. ومع ذلك، هذه المرة، قم بتقييد عامل تصفية نوع الحدث على الأخطاء غير الفادحة بحيث تعرض فقط الأخطاء غير الفادحة، مثل الخطأ الذي قمت بتسجيله للتو.
   

9. قم بتسجيل السلاسل في Crashlytics لفهم تدفق تنفيذ البرنامج بشكل أفضل

هل سبق لك أن حاولت معرفة السبب في أن سطرًا من التعليمات البرمجية يتم استدعاؤه من مسارات متعددة، مئات إن لم يكن آلاف المرات في كل جلسة، يمكن أن يولد استثناءً أو يتعطل فجأة؟ على الرغم من أنه قد يكون من الجيد الاطلاع على التعليمات البرمجية في IDE وإلقاء نظرة على القيم عن كثب، فماذا لو حدث هذا فقط بين نسبة صغيرة جدًا من المستخدمين لديك؟ والأسوأ من ذلك، ماذا ستفعل إذا لم تتمكن من تكرار هذا الانهيار بغض النظر عما تفعله؟

في مثل هذه المواقف، وجود بعض السياق يمكن أن يحدث فرقًا كبيرًا. باستخدام Crashlytics.Log ، لديك القدرة على كتابة السياق الذي تحتاجه. فكر في هذه الرسائل باعتبارها تلميحات لنفسك في المستقبل حول ما قد يحدث.

على الرغم من أنه يمكن استخدام السجلات بطرق لا تعد ولا تحصى، إلا أنها عادة ما تكون مفيدة للغاية لتسجيل المواقف التي يكون فيها ترتيب و/أو غياب المكالمات جزءًا من المعلومات ذات الأهمية الحيوية.

1. في Assets/Hamster/Scripts/States/DebugMenu.cs ، قم بالكتابة فوق LogStringsAndCrashNow() كما يلي:

   void LogStringsAndCrashNow()
   {
       Crashlytics.Log($"This is the first of two descriptive strings in {nameof(LogStringsAndCrashNow)}");
       const bool RUN_OPTIONAL_PATH = false;
       if(RUN_OPTIONAL_PATH)
       {
           Crashlytics.Log(" As it stands, this log should not appear in your records because it will never be called.");
       }
       else
       {
           Crashlytics.Log(" A log that will simply inform you which path of logic was taken. Akin to print debugging.");
       }
       Crashlytics.Log($"This is the second of two descriptive strings in {nameof(LogStringsAndCrashNow)}");
       TestCrash();
   }
   

2. أنشئ تطبيقك.
3. (Android فقط) قم بتحميل الرموز الخاصة بك عن طريق تشغيل أمر Firebase CLI التالي:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

4. اضغط على زر Log Strings and Crash Now ، ثم أعد تشغيل التطبيق.
5. ارجع إلى لوحة تحكم Crashlytics ، وانقر على أحدث إصدار مدرج في جدول المشكلات . مرة أخرى يجب أن ترى شيئًا مشابهًا للإصدارات السابقة.
   
6. ومع ذلك، إذا قمت بالنقر فوق علامة التبويب "السجلات" ضمن ملخص الحدث ، فستحصل على عرض مثل هذا:
   

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

هام: لتجنب إبطاء تطبيقك، تحدد Crashlytics حجم السجلات بـ 64 كيلو بايت وتحذف إدخالات السجل الأقدم عندما يتجاوز سجل الجلسة هذا الحد.

10. اكتب واستبدل مفتاحًا مخصصًا

لنفترض أنك تريد فهم العطل المطابق للمتغيرات المعينة لعدد صغير من القيم أو التكوينات بشكل أفضل. قد يكون من الجيد أن تكون قادرًا على التصفية، بناءً على مجموعة المتغيرات والقيم المحتملة التي تبحث عنها، في أي وقت محدد.

علاوة على تسجيل السلاسل العشوائية، تقدم Crashlytics شكلاً آخر من أشكال تصحيح الأخطاء عندما يكون من المفيد معرفة الحالة الدقيقة لبرنامجك أثناء تعطله: المفاتيح المخصصة.

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

بالإضافة إلى كونها سجلاً لآخر حالة مسجلة لبرنامجك، يمكن بعد ذلك استخدام هذه المفاتيح كمرشحات قوية لمشكلات Crashlytics.

1. في Assets/Hamster/Scripts/States/DebugMenu.cs ، قم بالكتابة فوق SetAndOverwriteCustomKeyThenCrash() كما يلي:

   void SetAndOverwriteCustomKeyThenCrash()
   {
       const string CURRENT_TIME_KEY = "Current Time";
       System.TimeSpan currentTime = System.DateTime.Now.TimeOfDay;
       Crashlytics.SetCustomKey(
           CURRENT_TIME_KEY,
           DayDivision.GetPartOfDay(currentTime).ToString() // Values must be strings
           );
   
       // Time Passes
       currentTime += DayDivision.DURATION_THAT_ENSURES_PHASE_CHANGE;
   
       Crashlytics.SetCustomKey(
           CURRENT_TIME_KEY,
           DayDivision.GetPartOfDay(currentTime).ToString()
           );
       TestCrash();
   }
   

2. أنشئ تطبيقك.
3. (Android فقط) قم بتحميل الرموز الخاصة بك عن طريق تشغيل أمر Firebase CLI التالي:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

4. اضغط على زر Set Custom Key and Crash ، ثم أعد تشغيل التطبيق.
5. ارجع إلى لوحة تحكم Crashlytics ، وانقر على أحدث إصدار مدرج في جدول المشكلات . مرة أخرى يجب أن ترى شيئًا مشابهًا للإصدارات السابقة.
6. ومع ذلك، هذه المرة، انقر فوق علامة التبويب "المفاتيح" في ملخص الحدث حتى تتمكن من عرض قيمة المفاتيح بما في ذلك Current Time :
   

   هام : يتم ملء مفتاح crash_info_entry_0 تلقائيًا فقط بواسطة Crashlytics عندما يتم تشغيل تطبيقك بواسطة جهاز محاكاة iOS.

لماذا تريد استخدام مفاتيح مخصصة بدلاً من السجلات المخصصة؟

• تعد السجلات جيدة في تخزين البيانات التسلسلية، لكن المفاتيح المخصصة تكون أفضل إذا كنت تريد القيمة الأحدث فقط.
• في وحدة تحكم Firebase، يمكنك بسهولة تصفية المشكلات حسب قيم المفاتيح في مربع بحث جدول المشكلات .

وعلى غرار السجلات، فإن المفاتيح المخصصة لها حد. يدعم Crashlytics ما يصل إلى 64 زوجًا من قيمة المفتاح كحد أقصى. بعد الوصول إلى هذا الحد، لا يتم حفظ القيم الإضافية. يمكن أن يصل حجم كل زوج من أزواج المفاتيح إلى 1 كيلو بايت.

11. (Android فقط) استخدم المفاتيح والسجلات المخصصة لفهم وتشخيص خطأ ANR

هام : تتعلق فئة المشكلات التالية بشكل أساسي بنظام Android 11 والإصدارات الأحدث. إذا لم يتطابق هذا مع حالة استخدام التطوير الخاصة بك، فتخطى هذا القسم.

أحد أصعب فئات المشكلات التي يجب تصحيحها لمطوري Android هو خطأ التطبيق لا يستجيب (ANR). تحدث أخطاء ANR عندما يفشل التطبيق في الاستجابة للإدخال لأكثر من 5 ثوانٍ. إذا حدث هذا، فهذا يعني أن التطبيق إما تجمد، أو أنه يعمل ببطء شديد. يتم عرض مربع حوار للمستخدمين، ويمكنهم اختيار "الانتظار" أو "إغلاق التطبيق".

تمثل أخطاء ANR تجربة سيئة للمستخدم ويمكن أن تؤثر (كما هو مذكور في رابط ANR أعلاه) على قابلية اكتشاف تطبيقك في متجر Google Play. نظرًا لتعقيدها، ولأنها غالبًا ما تنتج عن تعليمات برمجية متعددة الخيوط ذات سلوك مختلف تمامًا على طرز الهواتف المختلفة، فإن إعادة إنتاج أخطاء ANR أثناء تصحيح الأخطاء غالبًا ما تكون صعبة للغاية، إن لم تكن شبه مستحيلة. وعلى هذا النحو، فإن التعامل معها بشكل تحليلي واستنتاجي هو عادة النهج الأفضل.

في هذه الطريقة، سوف نستخدم مجموعة من Crashlytics.LogException و Crashlytics.Log و Crashlytics.SetCustomKey لتكملة التسجيل التلقائي للمشكلات وتزويدنا بمزيد من المعلومات.

هام: لاحظ أن رمز الحظر يتم تشغيله على مؤشر ترابط واجهة المستخدم الخاص بـ UnityPlayerActivity . يعد هذا أمرًا غير طبيعي إلى حد ما في Unity، نظرًا لأن الخيط ليس هو نفس موضوع Unity الرئيسي وهو المكان الافتراضي حيث يتم تشغيل رمز اللعبة. يمكن أن يكون تصحيح أخطاء ANR أمرًا صعبًا بشكل خاص لأنها يمكن أن تكون ناجمة عن المكونات الإضافية أو التعليمات البرمجية الأخرى التي يتم تشغيلها بشكل غير اصطلاحي على سلسلة واجهة المستخدم.

1. في Assets/Hamster/Scripts/States/DebugMenu.cs ، قم بالكتابة فوق SetLogsAndKeysBeforeANR() كما يلي:

   void SetLogsAndKeysBeforeANR()
   {
       System.Action<string,long> WaitAndRecord =
       (string methodName, long targetCallLength)=>
       {
           System.Diagnostics.Stopwatch stopWatch = new System.Diagnostics.Stopwatch();
           const string CURRENT_FUNCTION = "Current Async Function";
   
           // Initialize key and start timing
           Crashlytics.SetCustomKey(CURRENT_FUNCTION, methodName);
           stopWatch.Start();
   
           // The actual (simulated) work being timed.
           BusyWaitSimulator.WaitOnSimulatedBlockingWork(targetCallLength);
   
           // Stop timing
           stopWatch.Stop();
   
           if(stopWatch.ElapsedMilliseconds>=BusyWaitSimulator.EXTREME_DURATION_MILLIS)
           {
             Crashlytics.Log($"'{methodName}' is long enough to cause an ANR.");
           }
           else if(stopWatch.ElapsedMilliseconds>=BusyWaitSimulator.SEVERE_DURATION_MILLIS)
           {
             Crashlytics.Log($"'{methodName}' is long enough it may cause an ANR");
           }
       };
   
       WaitAndRecord("DoSafeWork",1000L);
       WaitAndRecord("DoSevereWork",BusyWaitSimulator.SEVERE_DURATION_MILLIS);
       WaitAndRecord("DoExtremeWork",2*BusyWaitSimulator.EXTREME_DURATION_MILLIS);
   }
   

2. أنشئ تطبيقك.
3. قم بتحميل الرموز الخاصة بك عن طريق تشغيل أمر Firebase CLI التالي:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

4. اضغط على الزر المسمى Set Logs And Keys → ANR ، ثم أعد تشغيل التطبيق.
5. ارجع إلى لوحة معلومات Crashlytics ، ثم انقر فوق الإصدار الجديد في جدول المشكلات لعرض ملخص الحدث . إذا تمت المكالمة بشكل صحيح، فيجب أن ترى شيئًا مثل هذا:
   
   
   كما ترون، حدد Firebase الانتظار المزدحم في سلسلة الرسائل باعتباره السبب الرئيسي وراء قيام تطبيقك بتشغيل ANR.
   
6. إذا نظرت إلى السجلات الموجودة في علامة التبويب "السجلات" في ملخص الأحداث ، فسوف ترى أن الطريقة الأخيرة التي تم تسجيلها على أنها كاملة هي DoSevereWork .
   
   
   على النقيض من ذلك، فإن الطريقة الأخيرة المدرجة كبداية هي DoExtremeWork ، مما يشير إلى حدوث ANR أثناء هذه الطريقة، وتم إغلاق اللعبة قبل أن تتمكن من تسجيل DoExtremeWork .
   
   

هام : إذا كنت لا ترى خطأ ANR على Android وبدلاً من ذلك رأيت خطأ يشير إلى InvalidOperationException ، فاقرأ السجلات. تم تضمين هذا الخطأ المخصص كجزء من هذا الدرس التطبيقي حول التعليمات البرمجية. اتبع التعليمات — التي تم تسجيلها بواسطة الاستثناء — لمعالجتها. أعد البناء والنشر والتكرار، وستحصل في النهاية على الخطأ المقصود.

لماذا فعل هذا؟

• يعد إعادة إنتاج أخطاء ANR أمرًا صعبًا للغاية، لذا فإن القدرة على الحصول على معلومات غنية حول منطقة الكود والمقاييس أمر مهم للغاية للعثور عليها بشكل استنتاجي.
• باستخدام المعلومات المخزنة في المفاتيح المخصصة، أنت تعرف الآن أي سلسلة محادثات غير متزامنة استغرقت وقتًا أطول للتشغيل، وأي منها كانت معرضة لخطر تشغيل أخطاء ANR. سيُظهر لك هذا النوع من البيانات المنطقية والرقمية ذات الصلة المواضع الأكثر أهمية في التعليمات البرمجية الخاصة بك لتحسينها.

12. تداخل أحداث التحليلات لإثراء التقارير بشكل أكبر

يمكن أيضًا استدعاء الطرق التالية من قائمة التصحيح، ولكن بدلاً من إنشاء المشكلات بنفسها، فإنها تستخدم Google Analytics كمصدر آخر للمعلومات لفهم طريقة عمل لعبتك بشكل أفضل.

على عكس الطرق الأخرى التي كتبتها في هذا الدرس التطبيقي حول الترميز، يجب عليك استخدام هذه الطرق مع الطرق الأخرى. قم باستدعاء هذه الطرق (عن طريق الضغط على الزر المقابل لها في قائمة التصحيح) بأي ترتيب عشوائي تريده قبل تشغيل إحدى الطرق الأخرى. وبعد ذلك، عند فحص المعلومات الموجودة في مشكلة Crashlytics المحددة، سترى سجلاً مرتبًا لأحداث Analytics. يمكن استخدام هذه البيانات في إحدى الألعاب لفهم مزيج من تدفق البرنامج أو إدخال المستخدم بشكل أفضل، اعتمادًا على كيفية استخدامك لتطبيقك.

ملاحظة : فيما يلي حالات استخدام بسيطة للغاية لبرنامج Analytics. إن عمق التحليلات يقع خارج نطاق هذا الدرس التطبيقي حول التعليمات البرمجية. إذا كنت ترغب في معرفة المزيد، أو فهم ما يتم تسجيله بدقة من خلال هذه العناصر بشكل أفضل، أو معرفة كيفية تصحيح أخطاء عملية إعداد التقارير، راجع بدء استخدام Google Analytics for Unity .

1. في Assets/Hamster/Scripts/States/DebugMenu.cs ، استبدل التطبيقات الحالية للطرق التالية:

   public void LogProgressEventWithStringLiterals()
   {
         Firebase.Analytics.FirebaseAnalytics.LogEvent("progress", "percent", 0.4f);
   }
   

   public void LogIntScoreWithBuiltInEventAndParams()
   {
         Firebase.Analytics.FirebaseAnalytics
           .LogEvent(
             Firebase.Analytics.FirebaseAnalytics.EventPostScore,
             Firebase.Analytics.FirebaseAnalytics.ParameterScore,
             42
           );
   }
   

2. قم ببناء لعبتك ونشرها، ثم أدخل إلى قائمة التصحيح .
3. (Android فقط) قم بتحميل الرموز الخاصة بك عن طريق تشغيل أمر Firebase CLI التالي:

   firebase crashlytics:symbols:upload --app=<FIREBASE_APP_ID> <PATH/TO/SYMBOLS>
   

4. اضغط على أحد الأزرار التالية على الأقل مرة واحدة أو أكثر لاستدعاء الوظائف المذكورة أعلاه:
   • حدث سلسلة السجل
   • حدث تسجيل الدخول
5. اضغط على زر التعطل الآن .
6. أعد تشغيل لعبتك لتحميل حدث التعطل إلى Firebase.
7. عندما تقوم بتسجيل تسلسلات عشوائية مختلفة لأحداث Analytics ثم تجعل لعبتك تنشئ حدثًا تنشئ Crashlytics تقريرًا منه (كما فعلت للتو)، تتم إضافتها إلى علامة تبويب السجلات في ملخص أحداث Crashlytics مثل هذا:
   

هام: يمكن أن تستغرق الأحداث المخصصة وقتًا أطول للظهور في لوحة تحكم Analytics في وحدة تحكم Firebase مقارنة بالوقت الذي يستغرقه ظهورها في سجل الأعطال داخل لوحة تحكم Crashlytics. كما أن أحداث Analytics قد لا تظهر في كلا المكانين فورًا بعد تسجيلها.

13. المضي قدما

وبهذا، يجب أن يكون لديك أساس نظري أفضل يمكنك من خلاله استكمال تقارير الأعطال التي يتم إنشاؤها تلقائيًا. تتيح لك هذه المعلومات الجديدة استخدام الحالة الحالية، وسجلات الأحداث الماضية، وأحداث Google Analytics الحالية لتحليل تسلسل الأحداث والمنطق الذي أدى إلى نتائجها بشكل أفضل.

إذا كان تطبيقك يستهدف Android 11 (مستوى واجهة برمجة التطبيقات 30) أو أعلى، ففكر في دمج GWP-ASan ، وهي ميزة مخصصة للذاكرة الأصلية مفيدة لتصحيح الأخطاء الناتجة عن أخطاء الذاكرة الأصلية مثل أخطاء use-after-free وأخطاء heap-buffer-overflow . للاستفادة من ميزة تصحيح الأخطاء هذه، قم بتمكين GWP-ASan بشكل صريح .

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

انتقل إلى أداة لعبة Unity الخاصة بك باستخدام الدرس التطبيقي للتكوين عن بعد ، حيث ستتعرف على استخدام Remote Config واختبار A/B في Unity.