بدء استخدام Crashlytics لـ Unity

اختيار النظام الأساسي: ‫iOS+ Android Android NDK Flutter Unity


يوضّح هذا الدليل كيفية بدء استخدام Firebase Crashlytics في مشروع Unity.

بعد إعداد حزمة تطوير البرامج (SDK) Firebase Crashlytics في تطبيقك، يمكنك الحصول على تقارير شاملة عن الأعطال في وحدة تحكّم Firebase.

يتطلّب إعداد Crashlytics تنفيذ مهام في كلّ من وحدة تحكّم Firebase وبيئة التطوير المتكاملة (IDE) (مثل إضافة ملف إعداد Firebase وحزمة تطوير البرامج (SDK) الخاصة بـ Crashlytics). لإنهاء عملية الإعداد، عليك فرض حدوث عُطل تجريبي لإرسال تقرير العُطل الأول إلى Firebase.

قبل البدء

  1. أضِف Firebase إلى مشروع Unity الخاص بك، في حال لم يسبق لك إجراء ذلك. إذا لم يكن لديك مشروع Unity، يمكنك تنزيل نموذج تطبيق.

  2. يُنصح به: للحصول تلقائيًا على سجلّ خطوات المستخدم لفهم إجراءات المستخدم التي أدّت إلى حدوث تعطُّل أو خطأ غير فادح أو حدث ANR، عليك تفعيل Google Analytics في مشروع Firebase.

    • إذا كنت بصدد إنشاء مشروع جديد في Firebase، فعِّل Google Analytics أثناء خطوات إنشاء المشروع.

    • إذا كنت تستخدم مشروعًا حاليًا على Firebase لم يتم تفعيل Google Analytics فيه، يمكنك تفعيله في صفحة الإعدادات > عمليات الدمج في وحدة تحكّم Firebase.

الخطوة 1: إضافة حزمة تطوير البرامج Crashlytics إلى تطبيقك

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

  1. نزِّل حزمة تطوير البرامج (SDK) Firebase Unity، ثم فكّ ضغطها في مكان مناسب. حزمة تطوير البرامج (SDK) Firebase Unity ليست خاصة بنظام أساسي معيّن.

  2. في مشروع Unity المفتوح، انتقِل إلى Assets (الأصول) > Import Package (استيراد حزمة) > Custom Package (حزمة مخصّصة).

  3. من حزمة SDK التي تم فك ضغطها، اختَر استيراد حزمة SDK Crashlytics(FirebaseCrashlytics.unitypackage).

    للاستفادة من سجلّات مسار التنفيذ، أضِف أيضًا حزمة تطوير البرامج (SDK) الخاصة بـ Google Analytics إلى تطبيقك (FirebaseAnalytics.unitypackage). تأكَّد من تفعيل "إحصاءات Google" في مشروعك على Firebase.

  4. في نافذة استيراد حزمة Unity، انقر على استيراد.

الخطوة 2: تهيئة Crashlytics

  1. أنشِئ نصًا برمجيًا جديدًا بلغة C#، ثم أضِفه إلى GameObject في المشهد.

    1. افتح المشهد الأول، ثم أنشئ عنصرًا فارغًا GameObject باسم CrashlyticsInitializer.

    2. انقر على إضافة مكوّن في الفاحص للعنصر الجديد.

    3. اختَر CrashlyticsInit النص البرمجي لإضافته إلى العنصر CrashlyticsInitializer.

  2. ابدأ بإعداد Crashlytics في طريقة Start الخاصة بالنص البرمجي:

    using System.Collections;
using System.Collections.Generic;
using UnityEngine;

// Import Firebase and Crashlytics
using Firebase;
using Firebase.Crashlytics;

public class CrashlyticsInit : MonoBehaviour {
    // Use this for initialization
    void Start () {
        // Initialize Firebase
        Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(task => {
            var dependencyStatus = task.Result;
            if (dependencyStatus == Firebase.DependencyStatus.Available)
            {
                // Create and hold a reference to your FirebaseApp,
                // where app is a Firebase.FirebaseApp property of your application class.
                // Crashlytics will use the DefaultInstance, as well;
                // this ensures that Crashlytics is initialized.
                Firebase.FirebaseApp app = Firebase.FirebaseApp.DefaultInstance;

                // When this property is set to true, Crashlytics will report all
                // uncaught exceptions as fatal events. This is the recommended behavior.
                Crashlytics.ReportUncaughtExceptionsAsFatal = true;

                // Set a flag here for indicating that your project is ready to use Firebase.
            }
            else
            {
                UnityEngine.Debug.LogError(System.String.Format(
                  "Could not resolve all Firebase dependencies: {0}",dependencyStatus));
                // Firebase Unity SDK is not safe to use here.
            }
        });
    }

  // Update is called once per frame
  void Update()
    // ...
}

الخطوة 3: (على أجهزة Android فقط) إعداد عملية تحميل الرموز

هذه الخطوة مطلوبة فقط لتطبيقات Android التي تستخدم IL2CPP.

  • لا يلزم اتّباع هذه الخطوات لتطبيقات Android التي تستخدم Mono scripting backend من Unity.

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

تتضمّن حزمة تطوير البرامج (SDK) Crashlytics لنظام Unity (الإصدار 8.6.1 والإصدارات الأحدث) تلقائيًا ميزة إعداد تقارير الأعطال في NDK، ما يسمح Crashlytics بإعداد تقارير تلقائية عن أعطال IL2CPP في Unity على أجهزة Android. ومع ذلك، لعرض عمليات تتبُّع تسلسل استدعاء الدوال البرمجية التي تم ترميزها لتعطُّل مكتبة مجمّعة من رموز برمجية أصلية في لوحة بيانات Crashlytics، يجب تحميل معلومات الرموز في مدّة التصميم باستخدام واجهة سطر الأوامر Firebase.

لإعداد عملية تحميل الرموز، اتّبِع التعليمات الخاصة بتثبيت واجهة سطر الأوامر Firebase.

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

الخطوة 4: إنشاء مشروعك وتحميل الرموز

‫iOS+ (منصة Apple)

  1. من مربّع الحوار إعدادات الإنشاء، يمكنك تصدير مشروعك إلى مساحة عمل Xcode.

  2. أنشئ تطبيقك.

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

Android

  1. من مربّع الحوار إعدادات الإنشاء، نفِّذ أحد الإجراءات التالية:

    • يمكنك التصدير إلى مشروع "استوديو Android" لإنشاء مشروعك.

    • إنشاء حِزمة APK مباشرةً من Unity Editor
      قبل الإنشاء، تأكَّد من وضع علامة في مربّع الاختيار إنشاء ملف symbols.zip في مربّع الحوار إعدادات الإنشاء.

  2. بعد انتهاء عملية الإنشاء، أنشئ ملف رموز متوافقًا مع Crashlytics وحمِّله إلى خوادم Firebase من خلال تنفيذ أمر Firebase CLI التالي:

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

    • FIREBASE_APP_ID: رقم تعريف تطبيق Android على Firebase (وليس اسم الحزمة)
      مثال على رقم تعريف تطبيق Android على Firebase: 1:567383003300:android:17104a2ced0c9b9b

    • PATH/TO/SYMBOLS: مسار ملف الرموز الذي تم إنشاؤه بواسطة واجهة سطر الأوامر

      • تم تصديرها إلى مشروع "استوديو Android" — PATH/TO/SYMBOLS هو دليل unityLibrary/symbols، الذي يتم إنشاؤه في جذر المشروع الذي تم تصديره بعد إنشاء التطبيق باستخدام Gradle أو "استوديو Android".

      • تم إنشاء حزمة APK مباشرةً من داخل Unity — PATH/TO/SYMBOLS هو مسار ملف الرموز المضغوط الذي تم إنشاؤه في دليل جذر المشروع عند انتهاء عملية الإنشاء (على سبيل المثال: myproject/myapp-1.0-v100.symbols.zip).

    عرض الخيارات المتقدّمة لاستخدام الأمر Firebase CLI لإنشاء ملفات الرموز وتحميلها

    العلم الوصف
    --generator=csym

    يستخدم أداة إنشاء ملفات رموز cSYM القديمة بدلاً من أداة إنشاء Breakpad التلقائية

    لا يُنصح باستخدامه. ننصح باستخدام أداة إنشاء ملفات رموز Breakpad التلقائية.

    --generator=breakpad

    يستخدم أداة إنشاء ملفات رموز Breakpad

    يُرجى العِلم أنّ Breakpad هو الإعداد التلقائي لإنشاء ملفات الرموز. لا تستخدِم هذا الخيار إلا إذا أضفت symbolGenerator { csym() } في إعدادات التصميم وأردت تجاوزه لاستخدام Breakpad بدلاً من ذلك.

    --dry-run

    إنشاء ملفات الرموز بدون تحميلها

    تكون هذه العلامة مفيدة إذا أردت فحص محتوى الملفات التي يتم إرسالها.

    --debug توفير معلومات إضافية لتصحيح الأخطاء

الخطوة 5: فرض تعطُّل تجريبي لإنهاء عملية الإعداد

لإكمال عملية إعداد Crashlytics والاطّلاع على البيانات الأولية في لوحة بيانات Crashlytics ضمن وحدة تحكّم Firebase، عليك فرض حدوث عُطل تجريبي.

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

    using System;
using UnityEngine;

public class CrashlyticsTester : MonoBehaviour {

    int updatesBeforeException;

    // Use this for initialization
    void Start () {
      updatesBeforeException = 0;
    }

    // Update is called once per frame
    void Update()
    {
        // Call the exception-throwing method here so that it's run
        // every frame update
        throwExceptionEvery60Updates();
    }

    // A method that tests your Crashlytics implementation by throwing an
    // exception every 60 frame updates. You should see reports in the
    // Firebase console a few minutes after running your app with this method.
    void throwExceptionEvery60Updates()
    {
        if (updatesBeforeException > 0)
        {
            updatesBeforeException--;
        }
        else
        {
            // Set the counter to 60 updates
            updatesBeforeException = 60;

            // Throw an exception to test your Crashlytics implementation
            throw new System.Exception("test exception please ignore");
        }
    }
}

  2. أنشئ تطبيقك وحمِّل معلومات الرموز بعد انتهاء عملية الإنشاء.

    • نظام التشغيل iOS والإصدارات الأحدث: يضبط مكوّن Firebase Unity Editor الإضافي مشروع Xcode تلقائيًا لتحميل ملف الرموز.

    • Android: بالنسبة إلى تطبيقات Android التي تستخدم IL2CPP، شغِّل أمر Firebase CLI crashlytics:symbols:upload لتحميل ملف الرموز.

  3. شغِّل تطبيقك. وبعد تشغيله، راقِب سجلّ الجهاز وانتظِر ظهور الاستثناء من CrashlyticsTester.

    • نظام التشغيل iOS والإصدارات الأحدث: يمكنك عرض السجلّات في اللوحة السفلية من Xcode.

    • Android: يمكنك عرض السجلات من خلال تنفيذ الأمر التالي في نافذة الأوامر: adb logcat.

  4. في Firebaseوحدة التحكّم، انتقِل إلى DevOps & Engagement > Crashlyticsلوحة البيانات للبحث عن تقرير تعطل الاختبار.

    إذا أعَدت تحميل الصفحة في "وحدة التحكّم" ولم يظهر تعطُّل الاختبار بعد خمس دقائق، يمكنك تفعيل تسجيل بيانات تصحيح الأخطاء لمعرفة ما إذا كان تطبيقك يرسل تقارير الأعطال.


هذا كل ما في الأمر. تتتبّع Crashlytics الآن تطبيقك بحثًا عن الأعطال. انتقِل إلى لوحة بيانات Crashlytics للاطّلاع على جميع تقاريرك وإحصاءاتك والتحقيق فيها.

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

  • (يُنصح به) بالنسبة إلى تطبيقات Android التي تستخدم IL2CPP، يمكنك الحصول على المساعدة في تصحيح أخطاء الأعطال الناتجة عن أخطاء الذاكرة الأصلية من خلال جمع تقارير GWP-ASan. يمكن أن ترتبط هذه الأخطاء المتعلقة بالذاكرة بتلف الذاكرة داخل تطبيقك، وهو السبب الرئيسي للثغرات الأمنية في التطبيقات. للاستفادة من ميزة تصحيح الأخطاء هذه، تأكَّد من أنّ تطبيقك يستخدم أحدث إصدار من Crashlytics حزمة SDK لـ Unity (الإصدار 10.7.0 أو إصدار أحدث) وأنّه تم تفعيل GWP-ASan بشكلٍ صريح (يتطلّب ذلك تعديل ملف بيان تطبيق Android).

  • تخصيص إعدادات تقرير الأعطال من خلال إضافة ميزة إعداد التقارير التي تتطلّب موافقة المستخدم والسجلّات والمفاتيح وتتبُّع الأخطاء غير الفادحة

  • تصدير بياناتك إلى BigQuery أو Cloud Logging للاستفادة من التحليلات والميزات المتقدّمة، مثل طلب البيانات وإنشاء لوحات بيانات مخصّصة وإعداد تنبيهات مخصّصة