با Firebase Crashlytics شروع کنید


این راهنمای سریع نحوه راه‌اندازی Firebase Crashlytics در برنامه شما با Firebase Crashlytics SDK را شرح می‌دهد تا بتوانید گزارش‌های جامعی از خرابی‌ها را در کنسول Firebase دریافت کنید.

راه‌اندازی Crashlytics نیازمند انجام وظایفی هم در کنسول Firebase و هم در IDE شما است (مانند اضافه کردن فایل پیکربندی Firebase و Crashlytics SDK). برای تکمیل راه‌اندازی، باید یک کرش آزمایشی را مجبور کنید تا اولین گزارش کرش شما را به Firebase ارسال کند.

قبل از اینکه شروع کنی

  1. اگر هنوز Firebase را به پروژه Unity خود اضافه نکرده‌اید، می‌توانید آن را به پروژه Unity خود اضافه کنید . اگر پروژه Unity ندارید، می‌توانید یک برنامه نمونه را دانلود کنید.

  2. توصیه می‌شود : برای اینکه گزارش‌های breadcrumb به طور خودکار اقدامات کاربر را که منجر به خرابی، عدم موفقیت یا رویداد ANR می‌شود، درک کنند، باید Google Analytics در پروژه Firebase خود فعال کنید.

    • اگر پروژه Firebase فعلی شما Google Analytics فعال نکرده است، می‌توانید Google Analytics از تب Integrations فعال کنید. > تنظیمات پروژه در کنسول Firebase .

    • اگر در حال ایجاد یک پروژه جدید Firebase هستید، در طول فرآیند ایجاد پروژه، Google Analytics فعال کنید.

مرحله ۱ : Crashlytics SDK را به برنامه خود اضافه کنید

توجه داشته باشید که وقتی پروژه Unity خود را با پروژه Firebase ثبت کردید، ممکن است قبلاً Firebase Unity SDK را دانلود کرده و بسته‌های توضیح داده شده در مراحل بعدی را اضافه کرده باشید.

  1. کیت توسعه نرم‌افزاری Firebase Unity را دانلود کنید، سپس SDK را در جایی مناسب از حالت فشرده خارج کنید. کیت توسعه Firebase Unity مختص پلتفرم خاصی نیست.

  2. در پروژه باز Unity خود، به مسیر Assets > Import Package > Custom Package بروید.

  3. از SDK استخراج‌شده، گزینه‌ی وارد کردن Crashlytics SDK ( FirebaseCrashlytics.unitypackage ) را انتخاب کنید.

    برای استفاده از گزارش‌های breadcrumb، کیت توسعه نرم‌افزار Firebase برای Google Analytics ( FirebaseAnalytics.unitypackage ) را نیز به برنامه خود اضافه کنید. مطمئن شوید که گوگل آنالیتیکس در پروژه فایربیس شما فعال است .

  4. در پنجره‌ی «وارد کردن بسته‌ی یونیتی» ، روی «وارد کردن» کلیک کنید.

مرحله 2 : مقداردهی اولیه Crashlytics

  1. یک اسکریپت سی‌شارپ جدید ایجاد کنید، سپس آن را به یک GameObject در صحنه اضافه کنید.

    1. صحنه اول خود را باز کنید، سپس یک GameObject خالی با نام CrashlyticsInitializer ایجاد کنید.

    2. برای شیء جدید، روی افزودن مؤلفه در بازرس کلیک کنید.

    3. اسکریپت Crashlytics Init خود را انتخاب کنید تا به شیء 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()
    // ...
}

مرحله ۳ : (فقط اندروید) برای آپلود نماد آماده شوید

این مرحله فقط برای برنامه‌های اندرویدی که از IL2CPP استفاده می‌کنند، لازم است.

  • برای برنامه‌های اندرویدی که از اسکریپت‌نویسی مونو در یونیتی استفاده می‌کنند، نیازی به انجام این مراحل نیست.

  • برای برنامه‌های پلتفرم اپل، این مراحل لازم نیست زیرا افزونه Firebase Unity Editor به طور خودکار پروژه Xcode شما را برای آپلود نمادها پیکربندی می‌کند.

Unity SDK نسخه ۸.۶.۱+ از Crashlytics به طور خودکار شامل گزارش خرابی NDK است که به Crashlytics اجازه می‌دهد تا به طور خودکار خرابی‌های Unity IL2CPP را در اندروید گزارش دهد. با این حال، برای مشاهده‌ی ردپاهای پشته نمادین برای خرابی‌های کتابخانه‌های بومی در داشبورد Crashlytics ، باید اطلاعات نماد را در زمان ساخت با استفاده از Firebase CLI بارگذاری کنید.

برای آماده شدن جهت آپلود نماد، دستورالعمل‌های نصب Firebase CLI را دنبال کنید.

اگر قبلاً CLI را نصب کرده‌اید، حتماً آن را به آخرین نسخه به‌روزرسانی کنید .

مرحله ۴ : پروژه خود را بسازید و نمادها را آپلود کنید

iOS+ (پلتفرم اپل)

  1. از پنجره تنظیمات ساخت (Build Settings) ، پروژه خود را به فضای کاری Xcode اکسپورت کنید.

  2. اپلیکیشن خود را بسازید.

    برای پلتفرم‌های اپل، افزونه‌ی Firebase Unity Editor به طور خودکار پروژه‌ی Xcode شما را طوری پیکربندی می‌کند که برای هر ساخت، یک فایل نماد سازگار با Crashlytics تولید و در سرورهای Firebase آپلود کند.

اندروید

  1. از پنجره تنظیمات ساخت ، یکی از موارد زیر را انجام دهید:

    • برای ساخت پروژه خود، آن را به یک پروژه اندروید استودیو منتقل کنید؛ یا

    • APK خود را مستقیماً از ویرایشگر Unity بسازید.
      قبل از ساخت، مطمئن شوید که کادر انتخاب Create symbols.zip در کادر محاوره‌ای Build Settings علامت زده شده باشد.

  2. پس از اتمام ساخت، یک فایل نماد سازگار با Crashlytics ایجاد کنید و با اجرای دستور Firebase CLI زیر، آن را در سرورهای Firebase آپلود کنید: 

    firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/SYMBOLS

    • FIREBASE_APP_ID : شناسه برنامه اندروید Firebase شما (نه نام بسته شما)
      مثالی از شناسه برنامه اندروید فایربیس: 1:567383003300:android:17104a2ced0c9b9b

    • PATH/TO/SYMBOLS : مسیر فایل نماد تولید شده توسط رابط خط فرمان (CLI)

      • صادر شده به یک پروژه اندروید استودیو - PATH/TO/SYMBOLS دایرکتوری unityLibrary/symbols است که پس از ساخت برنامه از طریق Gradle یا اندروید استودیو، در ریشه پروژه صادر شده ایجاد می‌شود.

      • APK را مستقیماً از داخل Unity ساختید - PATH/TO/SYMBOLS مسیر فایل نماد فشرده شده‌ای است که پس از اتمام ساخت، در دایرکتوری ریشه پروژه ایجاد شده است (برای مثال: myproject/myapp-1.0-v100.symbols.zip ).

    گزینه‌های پیشرفته برای استفاده از دستور Firebase CLI برای تولید و آپلود فایل نماد را مشاهده کنید

    پرچم توضیحات
    --generator=csym

    به جای مولد پیش‌فرض Breakpad، از مولد فایل نماد قدیمی cSYM استفاده می‌کند.

    برای استفاده توصیه نمی‌شود. توصیه می‌کنیم از مولد فایل نماد پیش‌فرض Breakpad استفاده کنید.

    --generator=breakpad

    از مولد فایل نماد Breakpad استفاده می‌کند

    توجه داشته باشید که پیش‌فرض برای تولید فایل نماد، Breakpad است. فقط در صورتی از این پرچم استفاده کنید که ... را اضافه کرده باشید. symbolGenerator { csym() } در پیکربندی ساخت خود دارید و می‌خواهید آن را لغو کنید تا به جای آن از Breakpad استفاده کنید.

    --dry-run

    فایل‌های نماد را تولید می‌کند اما آنها را آپلود نمی‌کند

    این پرچم در صورتی مفید است که بخواهید محتوای فایل‌های ارسالی را بررسی کنید.

    --debug اطلاعات اشکال‌زدایی اضافی ارائه می‌دهد

مرحله ۵ : برای اتمام راه‌اندازی، یک کرش آزمایشی را اعمال کنید

برای تکمیل راه‌اندازی Crashlytics و مشاهده داده‌های اولیه در داشبورد Crashlytics کنسول Firebase ، باید یک crash آزمایشی را اجباری کنید.

  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 شما را برای آپلود فایل نماد شما پیکربندی می‌کند.

    • اندروید : برای برنامه‌های اندروید شما که از IL2CPP استفاده می‌کنند، دستور crashlytics:symbols:upload Firebase CLI را اجرا کنید تا فایل نماد شما آپلود شود.

  3. برنامه خود را اجرا کنید. پس از اجرای برنامه، گزارش دستگاه را مشاهده کنید و منتظر بمانید تا استثنا از CrashlyticsTester فعال شود.

    • iOS+ : مشاهده گزارش‌ها در پنل پایین Xcode.

    • اندروید : با اجرای دستور زیر در ترمینال، گزارش‌ها را مشاهده کنید: adb logcat .

  4. برای مشاهده‌ی خرابی آزمایشی خود، به داشبورد Crashlytics در کنسول Firebase بروید.

    اگر کنسول را رفرش کرده‌اید و هنوز بعد از پنج دقیقه خطای آزمایشی را مشاهده نمی‌کنید، گزارش اشکال‌زدایی (debug logging) را فعال کنید تا ببینید آیا برنامه شما گزارش‌های خرابی را ارسال می‌کند یا خیر.


And that's it! Crashlytics is now monitoring your app for crashes. Visit the Crashlytics dashboard to view and investigate all your reports and statistics.

مراحل بعدی

  • (Recommended) For Android apps that use IL2CPP, get help debugging crashes caused by native memory errors by collecting GWP-ASan reports . These memory-related errors can be associated with memory corruption within your app, which is the leading cause of app security vulnerabilities. To take advantage of this debugging feature, make sure your app uses the latest Crashlytics SDK for Unity (v10.7.0+) and has GWP-ASan explicitly enabled (requires you to modify your Android App Manifest ).
  • Integrate with Google Play so that you can filter your Android app's crash reports by Google Play track directly in the Crashlytics dashboard. This allows you to better focus your dashboard on specific builds.