سفارشی‌سازی گزارش‌های خرابی برای Flutter

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


می‌توانید روی مشکلی کلیک کنید و گزارش رویداد مفصلی را در داشبورد DevOps و تعامل > Crashlytics در کنسول Firebase دریافت کنید. می‌توانید این گزارش‌ها را سفارشی‌سازی کنید تا به شما کمک کند آنچه را در برنامه‌تان اتفاق می‌افتد و شرایط پیرامون رویدادهای گزارش‌شده به Crashlytics را بهتر درک کنید.

گزارش استثناها

گزارش کردن موارد استثنای مشخص‌نشده

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

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

  await Firebase.initializeApp();
  bool weWantFatalErrorRecording = true;
  FlutterError.onError = (errorDetails) {
    if(weWantFatalErrorRecording){
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    } else {
      FirebaseCrashlytics.instance.recordFlutterError(errorDetails);
    }
  };

  runApp(MyApp());
}

خطاهای ناهمگام

خطاهای ناهمگام توسط چارچوب Flutter شناسایی نمی‌شوند:

ElevatedButton(
  onPressed: () async {
    throw Error();
  }
  ...
)

برای گرفتن چنین خطاهایی، می‌توانید از گرداننده 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());

}

خطاهای خارج از Flutter

برای گرفتن خطاهایی که خارج از زمینه Flutter اتفاق می‌افتد، یک شنونده خطا روی Isolate فعلی نصب کنید:

Isolate.current.addErrorListener(RawReceivePort((pair) async {
  final List<dynamic> errorAndStacktrace = pair;
  await FirebaseCrashlytics.instance.recordError(
    errorAndStacktrace.first,
    errorAndStacktrace.last,
    fatal: true,
  );
}).sendPort);

گزارش موارد استثنای پیداشده

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

از روش recordError برای ثبت استثناهای غیرکشنده در بلوک‌های catch برنامه‌تان استفاده کنید. برای مثال:

await FirebaseCrashlytics.instance.recordError(
  error,
  stackTrace,
  reason: 'a non-fatal error'
);

// Or you can use:
await FirebaseCrashlytics.instance.recordFlutterError(errorDetails);

همچنین ممکن است بخواهید اطلاعات بیشتری درباره خطا ثبت کنید که این کار بااستفاده از ویژگی information امکان‌پذیر است:

await FirebaseCrashlytics.instance.recordError(
  error,
  stackTrace,
  reason: 'a non-fatal error',
  information: ['further diagnostic information about the error', 'version 2.0'],
);

این استثناها به‌عنوان مشکلات غیرمهلک در داشبورد DevOps و تعامل > Crashlytics در کنسول Firebase نشان داده می‌شوند. خلاصه مشکل حاوی همه اطلاعات وضعیتی است که معمولاً از خرابی‌ها دریافت می‌کنید، به‌همراه تفکیک براساس نسخه و دستگاه سخت‌افزاری.

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

افزودن کلیدهای سفارشی

کلیدهای سفارشی به شما کمک می‌کنند تا وضعیت خاصی از برنامه‌تان را که منجر به ازکارافتادن می‌شود دریافت کنید. می‌توانید جفت‌های کلید-مقدار دلخواه را با گزارش‌های خرابی مرتبط کنید، سپس از کلیدهای سفارشی برای جستجو و فیلتر کردن گزارش‌های خرابی در داشبورد DevOps و تعامل > Crashlytics در کنسول Firebase استفاده کنید.

  • در داشبورد، می‌توانید مشکلاتی را که با کلید سفارشی مطابقت دارند جستجو کنید.

  • وقتی مشکل خاصی را در داشبورد مرور می‌کنید، می‌توانید کلیدهای سفارشی مرتبط با هر رویداد را مشاهده کنید (زیربرگه کلیدها) و حتی رویدادها را براساس کلیدهای سفارشی فیلتر کنید (منو فیلتر در بالای صفحه).

از روش نمونه setCustomKey برای تنظیم جفت‌های کلید-مقدار استفاده کنید. چند نمونه در زیر آمده است:

// Set a key to a string.
FirebaseCrashlytics.instance.setCustomKey('str_key', 'hello');

// Set a key to a boolean.
FirebaseCrashlytics.instance.setCustomKey("bool_key", true);

// Set a key to an int.
FirebaseCrashlytics.instance.setCustomKey("int_key", 1);

// Set a key to a long.
FirebaseCrashlytics.instance.setCustomKey("int_key", 1L);

// Set a key to a float.
FirebaseCrashlytics.instance.setCustomKey("float_key", 1.0f);

// Set a key to a double.
FirebaseCrashlytics.instance.setCustomKey("double_key", 1.0);

افزودن پیام‌های گزارش سفارشی

برای اینکه زمینه بیشتری درباره رویدادهای منتهی به خرابی داشته باشید، می‌توانید گزارش‌های سفارشی Crashlytics را به برنامه‌تان اضافه کنید. Crashlytics گزارش‌ها را با داده‌های خرابی شما مرتبط می‌کند و وقتی جزئیات مشکلی را مشاهده می‌کنید، آن‌ها را در برگه گزارش‌ها نمایش می‌دهد (همه مشکلاتتان را در داشبورد Crashlytics DevOps و تعامل > در کنسول Firebase ببینید).

از log برای کمک به شناسایی دقیق مشکلات استفاده کنید. برای مثال:

FirebaseCrashlytics.instance.log("Higgs-Boson detected! Bailing out");

تنظیم شناسه‌های کاربر

برای تشخیص مشکل، اغلب مفید است که بدانید کدام‌یک از کاربران شما یک ازکارافتادگی خاص را تجربه کرده‌اند. Crashlytics شامل روشی برای شناسایی ناشناس کاربران در گزارش‌های خرابی شما است.

برای افزودن شناسه کاربر به گزارش‌هایتان، به هر کاربر یک شناسه یکتا در قالب شماره شناسه، توکن، یا مقدار درهم‌سازی‌شده اختصاص دهید:

FirebaseCrashlytics.instance.setUserIdentifier("12345");

اگر پس‌از تنظیم شناسه کاربر نیاز به پاک کردن آن داشتید، مقدار را به رشته خالی بازنشانی کنید. پاک کردن شناسه کاربر، سوابق Crashlytics موجود را حذف نمی‌کند. اگر لازم است سوابق مرتبط با شناسه کاربر را حذف کنید، با پشتیبانی Firebase تماس بگیرید.

دریافت گزارش‌های ردپای رخدادها

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

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

Analytics SDK به‌طور خودکار رویداد screen_view را ثبت می‌کند که به گزارش‌های ردپای رخدادها امکان می‌دهد فهرستی از صفحه‌های مشاهده‌شده قبل‌از خرابی، غیرکشنده، یا رویداد ANR را نشان دهد. گزارش ردپای رخدادهای screen_view حاوی پارامتر firebase_screen_class است.

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

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

فعال کردن گزارش‌دهی با موافقت

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

  1. جمع‌آوری خودکار را به‌طور بومی خاموش کنید:

    پلاتفرم‌های Apple

    کلید جدیدی به فایل Info.plist اضافه کنید:

    • کلید: FirebaseCrashlyticsCollectionEnabled
    • ارزش: false

    Android

    در بلوک application فایل AndroidManifest.xml، برچسب meta-data را برای خاموش کردن جمع‌آوری خودکار اضافه کنید:

    <meta-data
    android:name="firebase_crashlytics_collection_enabled"
    android:value="false" />

  2. با فراخوانی لغو جمع‌آوری داده Crashlytics در زمان اجرا، جمع‌آوری را برای کاربران منتخب فعال کنید. مقدار لغو در همه راه‌اندازی‌های بعدی برنامه‌تان باقی می‌ماند تا Crashlytics بتواند به‌طور خودکار گزارش‌های آن کاربر را جمع‌آوری کند.

    FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);

    اگر کاربر بعداً از جمع‌آوری داده انصراف دهد، می‌توانید false را به‌عنوان مقدار لغو ارسال کنید که دفعه بعدی که کاربر برنامه را راه‌اندازی می‌کند اعمال می‌شود و در همه راه‌اندازی‌های بعدی برای آن کاربر باقی می‌ماند.

مدیریت داده‌های «اطلاعات آماری خرابی»

«اطلاعات آماری خرابی» با مقایسه ردیابی‌های پشته ناشناس‌سازی‌شده شما با ردیابی‌های سایر برنامه‌های Firebase و اطلاع‌رسانی به شما درباره اینکه آیا مشکل شما بخشی از یک روند بزرگ‌تر است یا نه، به شما کمک می‌کند مشکلات را حل کنید. برای بسیاری از مشکلات، «اطلاعات آماری خرابی» حتی منابعی را برای کمک به اشکال‌زدایی خرابی ارائه می‌دهد.

«اطلاعات آماری خرابی» از داده‌های انبوهشی خرابی برای شناسایی روندهای پایداری رایج استفاده می‌کند. اگر ترجیح می‌دهید داده‌های برنامه‌تان را هم‌رسانی نکنید، می‌توانید از منوِ اطلاعات آماری خرابی در بالای فهرست مشکل در داشبورد DevOps و تعامل > Crashlytics در کنسول Firebase از «اطلاعات آماری خرابی» انصراف دهید.

مراحل بعدی