بدء استخدام 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 في مكان مناسب. حزمة SDK لنظام التشغيل Firebase Unity ليست مرتبطة بنظام أساسي معيّن.

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

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

    للاستفادة من سجلّات مسار التنقّل، أضِف أيضًا حزمة تطوير البرامج (SDK) لمنصّة Firebase لنظام التشغيل 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 تلقائيًا لتحميل الرموز.

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

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

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

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

iOS والإصدارات الأحدث (نظام التشغيل Apple)

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

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

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

Android

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

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

    • يمكنك إنشاء حزمة APK مباشرةً من "أداة تحرير Unity".
      قبل الإنشاء، تأكَّد من وضع علامة في مربّع الاختيار Create symbols.zip في مربّع الحوار إعدادات الإنشاء.

  2. بعد الانتهاء من عملية الإنشاء، أنشئ ملفًا لرمز متوافق معCrashlytics وحمِّله إلى خوادم Firebase من خلال تنفيذ الأمر التالي لFirebase CLI:

    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 أمر سطر الأوامر لإنشاء ملفات الرموز وتحميلها

    الإبلاغ الوصف
    --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. أنشئ تطبيقك وحمِّل معلومات الرموز بعد اكتمال عملية الإنشاء.

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