بدء استخدام 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: إضافة حزمة تطوير البرامج (SDK) لـ "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).

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

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

الخطوة 2: إعداد Crashlytics

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

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

    2. انقر على Add Component (إضافة مكوّن) في Inspector (المفتّش) للعنصر الجديد.

    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 من Unity، لا حاجة إلى اتّباع هذه الخطوات.

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

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

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

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

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

iOS+ (منصة Apple)

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

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

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

Android

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

    • تصدير المشروع إلى "استوديو Android" لإنشائه

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

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

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

    • ‫FIREBASE_APP_ID: رقم تعريف تطبيق Firebase على Android (وليس اسم الحزمة)
      مثال على رقم تعريف تطبيق Firebase على Android: 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).

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

    الإبلاغ الوصف
    --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. يمكن أن ترتبط هذه الأخطاء المتعلّقة بالذاكرة بتلف الذاكرة داخل تطبيقك، وهو السبب الرئيسي للثغرات الأمنية في التطبيقات. للاستفادة من ميزة تصحيح الأخطاء هذه، تأكَّد من أنّ تطبيقك يستخدم أحدث إصدار من حزمة تطوير البرامج (SDK) لـ Crashlytics في Unity (الإصدار 10.7.0 أو إصدار أحدث) وأنّه تم تفعيل GWP-ASan صراحةً (يتطلّب ذلك منك تعديل ملف بيان تطبيق Android).

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

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