بدء استخدام 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).

    للاستفادة من سجلّات خطوات المستخدم، يُرجى أيضًا إضافة حزمة تطوير البرامج (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.
      قبل إنشاء التطبيق، تأكَّد من وضع علامة في مربّع الاختيار Create symbols.zip في مربّع الحوار Build Settings.

  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، انتقِل إلى عمليات التطوير والتفاعل > لوحة بيانات Crashlytics للتحقّق من تقرير الأعطال التجريبي.

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


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

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

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

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

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