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

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

• استثنائاتِ دریافت‌شده و نشده را به Crashlytics گزارش دهید.

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

• اگر برنامه شما از Firebase SDK برای Google Analytics استفاده می‌کند، به طور خودکار گزارش‌های breadcrumb را دریافت کنید. این گزارش‌ها به شما امکان مشاهده اقدامات کاربر را می‌دهند که منجر به یک رویداد جمع‌آوری‌شده توسط Crashlytics در برنامه شما می‌شود.

• گزارش خرابی خودکار را غیرفعال کنید و گزارش اختیاری را برای کاربران خود فعال کنید . توجه داشته باشید که به طور پیش‌فرض، 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'],
);

این استثنائات به عنوان مشکلات غیرمهلک در کنسول 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 تماس بگیرید .

دریافت گزارش‌های breadcrumb

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

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

کیت توسعه نرم‌افزار (SDK) مربوط به Analytics به طور خودکار رویداد screen_view را ثبت می‌کند که به گزارش‌های breadcrumb امکان می‌دهد فهرستی از صفحات مشاهده شده قبل از رویداد crash، non-fatal یا ANR را نمایش دهند. گزارش breadcrumb screen_view حاوی پارامتر firebase_screen_class است.

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

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

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

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

   FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);
   

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

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

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

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