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

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


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

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

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

قبل البدء

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

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

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

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

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

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

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

  2. في مشروع Unity المفتوح، انتقِل إلى Assets > Import Package > Custom Package.

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

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

  4. في نافذة Import Unity Package ، انقر على Import.

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

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

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

    2. انقر على Add Component في المراقب للكائن الجديد.

    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 لتحميل الرموز.

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

لإعداد عملية تحميل الرموز، اتّبِع تعليمات تثبيت CLIFirebase.

إذا سبق لك تثبيت CLI، تأكَّد من التحديث إلى أحدث إصدار.

.

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

iOS+ (منصّة Apple)

  1. من مربّع حوار Build Settings ، يمكنك تصدير مشروعك إلى مساحة عمل 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 عن طريق تشغيل أمر 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: مسار ملف الرموز الذي أنشأه CLI

      • تم التصدير إلى مشروع "استوديو 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 لإجراء تحليل متقدّم والاستفادة من ميزات متقدّمة، مثل الاستعلام عن بياناتك وإنشاء لوحات بيانات مخصّصة وإعداد تنبيهات مخصّصة.