شروع کار با Crashlytics برای Flutter

انتخاب پلاتفرم: iOS+ Android Android NDK Flutter Unity


این راهنما نحوه شروع به کار با Firebase Crashlytics را در برنامه Flutter شما شرح می‌دهد.

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

راه‌اندازی Crashlytics شامل استفاده از ابزار خط فرمان و IDE شما می‌شود. برای تکمیل راه‌اندازی، باید استثنای آزمایشی را به‌اجبار ایجاد کنید تا اولین گزارش خرابی‌تان به Firebase ارسال شود.

قبل از شروع

  1. اگر قبلاً این کار را نکرده‌اید، Firebase را در پروژه Flutter خود پیکربندی و مقداردهی اولیه کنید.

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

    • اگر پروژه Firebase جدیدی ایجاد می‌کنید، Google Analytics را درطول گردش کار ایجاد پروژه فعال کنید.

    • اگر از پروژه Firebase موجودی استفاده می‌کنید که Google Analytics در آن فعال نیست، می‌توانید آن را در تنظیمات > صفحه ادغام‌ها کنسول Firebase فعال کنید.

    توجه داشته باشید که گزارش‌های ردپای رخدادها برای همه پلاتفرم‌های Android و Apple که Crashlytics از آن‌ها پشتیبانی می‌کند (به‌جز watchOS) دردسترس است.

مرحله ۱: افزودن Crashlytics به پروژه Flutter

  1. از ریشه پروژه Flutter، فرمان زیر را برای نصب افزونه Flutter برای Crashlytics اجرا کنید.

    برای بهره‌مندی از گزارش‌های ردپای رخدادها، افزونه Flutter برای Google Analytics را نیز به برنامه‌تان اضافه کنید. مطمئن شوید که Google Analytics فعال باشد در پروژه Firebase شما.

    flutter pub add firebase_crashlytics && flutter pub add firebase_analytics

  2. از دایرکتوری ریشه پروژه Flutter، فرمان زیر را اجرا کنید:

    flutterfire configure

    اجرای این فرمان تضمین می‌کند که پیکربندی Firebase برنامه Flutter شما به‌روز است و، برای Android، افزایه Gradle Crashlytics موردنیاز را به برنامه‌تان اضافه می‌کند.

  3. پس‌از تکمیل، پروژه Flutter خود را بازسازی کنید:

    flutter run

  4. (اختیاری) اگر پروژه Flutter شما از پرچم --split-debug-info استفاده می‌کند (و، به‌طور اختیاری، از پرچم --obfuscate نیز استفاده می‌کند)، مراحل بیشتری برای نمایش ردیابی‌های پشته‌ای خوانا برای برنامه‌هایتان لازم است.

    • پلاتفرم‌های Apple: مطمئن شوید که پروژه‌تان از پیکربندی نسخه توصیه‌شده (Flutter 3.12.0+‎ و Crashlytics افزونه Flutter 3.3.4+‎) استفاده می‌کند تا پروژه‌تان بتواند به‌طور خودکار نمادهای Flutter (فایل‌های dSYM) را تولید و در Crashlytics بارگذاری کند.

    • ‫Android: از Firebase CLI (نسخه ۱۱.۹.۰+) برای بارگذاری نمادهای اشکال‌زدایی Flutter استفاده کنید. باید نمادهای اشکال‌زدایی را پیش‌از گزارش خرابی از ساخت کد مبهم بارگذاری کنید.

      از دایرکتوری ریشه پروژه Flutter، دستور زیر را اجرا کنید:

      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: همان دایرکتوری‌ای که هنگام ساختن برنامه به پرچم --split-debug-info ارسال می‌کنید

مرحله ۲: پیکربندی گرداننده‌های خرابی

می‌توانید با لغو کردن FlutterError.onError با FirebaseCrashlytics.instance.recordFlutterFatalError، همه خطاهایی را که در چارچوب Flutter ایجاد می‌شوند به‌طور خودکار دریافت کنید:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Firebase.initializeApp();

  // Pass all uncaught "fatal" errors from the framework to Crashlytics
  FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError;

  runApp(MyApp());
}

برای گرفتن خطاهای ناهمگام که توسط چارچوب Flutter مدیریت نمی‌شوند، از PlatformDispatcher.instance.onError استفاده کنید:

Future<void> main() async {
    WidgetsFlutterBinding.ensureInitialized();
    await Firebase.initializeApp();
    FlutterError.onError = (errorDetails) {
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    };
    // Pass all uncaught asynchronous errors that aren't handled by the Flutter framework to Crashlytics
    PlatformDispatcher.instance.onError = (error, stack) {
      FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
      return true;
    };
    runApp(MyApp());

}

برای مشاهده نمونه‌هایی از نحوه رسیدگی به انواع دیگر خطاها، سفارشی‌سازی گزارش‌های خرابی را ببینید.

مرحله ۳: برای تکمیل راه‌اندازی، خرابی آزمایشی را اجباری کنید

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

  1. کدی به برنامه‌تان اضافه کنید که بتوانید از آن برای اجبار به ایجاد استثنای آزمایشی استفاده کنید.

    اگر یک کنترل‌کننده خطا اضافه کرده‌اید که FirebaseCrashlytics.instance.recordError(error, stack, fatal: true) را به Zone سطح بالا فراخوانی می‌کند، می‌توانید از کد زیر برای افزودن دکمه‌ای به برنامه‌تان استفاده کنید که وقتی فشار داده می‌شود، یک استثنای آزمایشی ایجاد می‌کند:

    TextButton(
    onPressed: () => throw Exception(),
    child: const Text("Throw Test Exception"),
),

  2. برنامه‌تان را بسازید و اجرا کنید.

  3. برای ارسال اولین گزارش برنامه‌تان، استثنای آزمایشی را به‌اجبار ایجاد کنید:

    1. برنامه‌تان را از دستگاه آزمایشی یا شبیه‌ساز باز کنید.

    2. در برنامه‌تان، دکمه استثنای آزمایشی را که بااستفاده از کد بالا اضافه کردید فشار دهید.

  4. در کنسول Firebase، به داشبورد DevOps و تعامل > Crashlytics بروید تا گزارش خرابی آزمایشی را بررسی کنید.

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


همین! Crashlytics اکنون برنامه‌تان را ازنظر خرابی و، در Android، خطاهای غیرمهلک و خطاهای ANR پایش می‌کند. برای مشاهده و بررسی همه گزارش‌ها و آمار، به داشبورد Crashlytics بروید.

مراحل بعدی