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

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

  2. في مشروع Unity المفتوح، انتقِل إلى مواد العرض > استيراد حزمة > الحزمة المخصّصة.

  3. من حزمة SDK غير المضغوطة، اختَر استيراد حزمة تطوير البرامج (SDK) الخاصة بـ Crashlytics (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 الأساسي، لا حاجة إلى هذه الخطوات لأنّ المكوّن الإضافي لبرنامج Unity Editor من Firebase يضبط مشروع Xcode تلقائيًا لتحميل الرموز.

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

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

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

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

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

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

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

    بالنسبة إلى أنظمة Apple الأساسية، يعمل المكوّن الإضافي لمنصة Unity Editor من Firebase على إعداد مشروع 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".

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

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

    الإبلاغ الوصف
    --generator=csym

    تستخدم منشئ ملفات رمز cSYM القديم بدلاً من المنشئ التلقائي لأداة Breakpad

    لا ننصح باستخدامها. وننصحك باستخدام أداة إنشاء الملفات التلقائية التي تستخدم رمز لوحة الإيقاف.

    --generator=breakpad

    لاستخدام أداة إنشاء ملفات رموز Breakpad

    يُرجى العِلم أنّ الطريقة التلقائية لإنشاء ملفات الرموز هي Breakpad. لا تستخدِم هذه العلامة إلا إذا كنت قد أضفت symbolGenerator { csym() } في إعدادات تصميمك وأردت إلغاءها لاستخدام لوحة الإيقاف بدلاً من ذلك.

    --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: يعمل المكوّن الإضافي لمنصة Unity Editor من Firebase على تهيئة مشروع 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. ويتيح لك ذلك تركيز لوحة البيانات بشكل أفضل على إصدارات معيّنة.