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


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

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

قبل البدء

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

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

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

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

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

يُرجى العِلم أنّه عند تسجيل مشروع Unity باستخدام مشروع Firebase، ربما تكون قد نزّلت حزمة تطوير البرامج 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، وهي أداة خلفية للبرمجة النصية في Unity.

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

تتضمّن حزمة تطوير البرامج (SDK) من Unity الإصدار 8.6.1 والإصدارات الأحدث تلقائيًا ميزة إعداد تقارير الأعطال في NDK، ما يتيح لـ Crashlytics إعداد تقارير تلقائية عن الأعطال في IL2CPP على Android.Crashlytics ومع ذلك، لعرض عمليات تتبُّع تسلسل استدعاء الدوال البرمجية التي تم تحويلها إلى رموز لكي يتمكّن الكمبيوتر من قراءتها، وذلك في ما يتعلّق بالأعطال في المكتبة الأصلية، ضِمن لوحة بيانات 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 التالي في واجهة سطر الأوامر:

    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).

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

    Flag الوصف
    --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. انتقِل إلى لوحة بيانات Crashlytics في وحدة تحكّم Firebase للاطّلاع على عُطل الاختبار.

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


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

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

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