بدء استخدام Firebase Crashlytics

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

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

قبل البدء

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

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

    • إذا لم يسبق لك تفعيل "إحصاءات Google" في مشروعك الحالي على Firebase، يمكنك تفعيل "إحصاءات Google" من علامة تبويب عمليات الدمج ضِمن > إعدادات المشروع في وحدة تحكُّم Firebase.

    • إذا كنت بصدد إنشاء مشروع جديد على Firebase، يمكنك تفعيل "إحصاءات Google" أثناء سير عمل إنشاء المشروع.

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

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

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

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

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

    للاستفادة من سجلّات شريط التنقّل، أضِف أيضًا حزمة تطوير البرامج (SDK) لمنصّة Firebase الخاصة بخدمة "إحصاءات Google" إلى تطبيقك (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 التي تستخدم الواجهة الخلفية للبرمجة النصية الأحادية في Unity.

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

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

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

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

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

+iOS (نظام Apple الأساسي)

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

  2. إنشاء تطبيقك

    بالنسبة إلى منصات Apple، يعمل المكوّن الإضافي لمحرِّر Firebase Unity تلقائيًا على ضبط مشروع 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 Studio.

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

    عرض الخيارات المتقدّمة لاستخدام أمر واجهة سطر الأوامر في 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 على ضبط مشروع Xcode تلقائيًا لتحميل ملف الرمز.

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

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

    • +iOS: يمكنك عرض السجلّات في الجزء السفلي من Xcode.

    • Android: يمكنك عرض السجلّات من خلال تشغيل الأمر التالي في الوحدة الطرفية: adb logcat.

  4. انتقِل إلى لوحة بيانات Crashlytics ضمن وحدة تحكُّم Firebase للاطّلاع على العطل في الاختبار.

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


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

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

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