گزارش‌های خرابی Firebase Crashlytics خود را سفارشی کنید

این راهنما نحوه سفارشی کردن گزارش‌های خرابی خود را با استفاده از Crashlytics API توضیح می‌دهد. به‌طور پیش‌فرض، Crashlytics به‌طور خودکار گزارش‌های خرابی بومی پلتفرم را برای همه کاربران برنامه‌تان جمع‌آوری می‌کند (همچنین می‌توانید گزارش خودکار خرابی را غیرفعال کنید و به‌جای آن ، گزارش انتخابی را برای کاربرانتان فعال کنید). Crashlytics پنج مکانیسم ورود به سیستم را ارائه می‌کند: کلیدهای سفارشی ، گزارش‌های سفارشی ، شناسه‌های کاربر ، استثناهای دستگیر شده و کشف نشده .

برای برنامه‌های Flutter، گزارش‌های مرگ‌بار به‌طور هم‌زمان و بدون نیاز به راه‌اندازی مجدد برنامه توسط کاربر به Crashlytics ارسال می‌شود. گزارش‌های غیرکشنده روی دیسک نوشته می‌شوند تا همراه با گزارش مرگبار بعدی یا زمانی که برنامه راه‌اندازی مجدد شود، ارسال شود.

استثناهای کشف نشده را گزارش کنید

می‌توانید به‌طور خودکار تمام خطاهای «مرگبار» را که در چارچوب Flutter ایجاد می‌شوند، با نادیده گرفتن FlutterError.onError با FirebaseCrashlytics.instance.recordFlutterFatalError دریافت کنید. از طرف دیگر، برای گرفتن استثناهای «غیر کشنده»، 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 اتفاق می‌افتند، یک شنونده خطا را در 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'],
);

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

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

کلیدهای سفارشی را اضافه کنید

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

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

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

برای تنظیم جفت کلید/مقدار از روش نمونه 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 گزارش‌ها را با داده‌های خرابی شما مرتبط می‌کند و آنها را در کنسول Firebase در زیر برگه Crashlytics Logs نمایش می‌دهد.

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

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

تعیین شناسه های کاربر

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

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

FirebaseCrashlytics.instance.setUserIdentifier("12345");

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

فعال کردن گزارش انتخابی

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

  1. غیرفعال کردن مجموعه خودکار به صورت بومی:

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

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

    • کلید: FirebaseCrashlyticsCollectionEnabled
    • مقدار: false

    اندروید

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

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

  2. با فراخوانی لغو مجموعه داده های Crashlytics در زمان اجرا، مجموعه را برای کاربران منتخب فعال کنید.

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

    FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);

داده‌های Crash Insights را مدیریت کنید

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

Crash Insights از داده‌های خرابی انبوه برای شناسایی روندهای رایج پایداری استفاده می‌کند. اگر ترجیح می‌دهید داده‌های برنامه خود را به اشتراک نگذارید، می‌توانید از منوی Crash Insights در بالای فهرست مشکلات Crashlytics در کنسول Firebase، از Crash Insights انصراف دهید.