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

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

يتطلب إعداد Crashlytics مهامًا في كل من وحدة تحكُّم Firebase بيئة التطوير المتكاملة (IDE) (مثل إضافة ملف إعداد Firebase وأداة Crashlytics SDK). لإنهاء عملية الإعداد، ستحتاج إلى فرض إرسال عطل تجريبي لإرسال أول إلى 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 الأساسي لأنّ Firebase Unity يعمل المكوّن الإضافي للمحرر على تهيئة مشروع Xcode تلقائيًا لتحميل الرموز.

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

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

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

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

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

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

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

    بالنسبة إلى أنظمة Apple الأساسية، يتمّ تلقائيًا استخدام المكوّن الإضافي لبرنامج Unity Editor من Firebase تقوم بتهيئة مشروع Xcode لإنشاء وتحميل ملف رموز متوافق مع Crashlytics على خوادم Firebase لكل إصدار

Android

  1. من مربع الحوار إعدادات التصميم، نفِّذ أحد الإجراءات التالية:

    • التصدير إلى مشروع على "استوديو Android" لإنشاء مشروعك أو

    • يمكنك إنشاء حِزمة APK مباشرةً من خلال Unity Editor.
      قبل إنشاء الرمز، تأكّد من أنّ مربّع الاختيار Create 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 CLI لإنشاء ملفات الرموز وتحميلها

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

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

    لا ننصح باستخدامها. ننصح باستخدام المخطَّط التلقائي منشئ ملف رمز لوحة الإيقاف

    --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، شغِّل واجهة سطر الأوامر crashlytics:symbols:upload في Firebase لتحميل ملف الرموز.

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