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

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


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

پس‌از راه‌اندازی افزایه Crashlytics Flutter در برنامه‌تان، می‌توانید گزارش‌های خرابی جامع را در کنسول 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 داشبورد مراجعه کنید.

مراحل بعدی