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

انتخاب پلاتفرم:

iOS+ Android Web Flutter Unity

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

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

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

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

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

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

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

هشدار: اگر می‌خواهید مقدار یکتایی (برای مثال، شناسه کاربر یا مُهر زمان) را در پیام استثنای خود بگنجانید، به‌جای افزودن مستقیم مقدار در پیام استثنا، از کلید سفارشی استفاده کنید. افزودن مستقیم مقادیر می‌تواند منجر به مشکلات متعددی شود و ممکن است باعث شود Crashlytics خطاهای گزارش‌دهی را در برنامه‌تان محدود کند.

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

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

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

کلیدهای سفارشی به شما کمک می‌کنند تا وضعیت خاص برنامه‌تان را که منجر به خرابی می‌شود دریافت کنید. می‌توانید جفت‌های کلید-مقدار دلخواه را با گزارش‌های خرابی مرتبط کنید، سپس از کلیدهای سفارشی برای جستجو و فیلتر کردن گزارش‌های خرابی در داشبورد DevOps و تعامل > 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 گزارش‌ها را با داده‌های خرابی شما مرتبط می‌کند و آن‌ها را در برگه گزارش‌ها نمایش می‌دهد وقتی جزئیات یک مشکل را مشاهده می‌کنید (همه مشکلات خود را در داشبورد DevOps و تعامل > Crashlytics در کنسول Firebase ببینید).

توجه: برای جلوگیری از کند شدن برنامه‌تان، Crashlytics گزارش‌ها را به ۶۴ کیلوبایت محدود می‌کند و وقتی گزارش‌های یک جلسه از این حد فراتر می‌رود، ورودی‌های گزارش قدیمی‌تر را حذف می‌کند.

از 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 را به‌عنوان مقدار لغو ارسال کنید که دفعه بعد که کاربر برنامه را راه‌اندازی می‌کند اعمال می‌شود و در همه راه‌اندازی‌های بعدی برای آن کاربر باقی می‌ماند.

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

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

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

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

توجه: غیرفعال کردن هم‌رسانی داده‌ها همچنین اطلاعات آماری مربوط به مشکلات شما را حذف می‌کند. اعمال تغییرات ممکن است تا ۲۴ ساعت طول بکشد.

مراحل بعدی

• برای تجزیه‌وتحلیل و ویژگی‌های پیشرفته، داده‌هایتان را به BigQuery یا Cloud Logging صادر کنید مانند پرس‌وجو از داده‌هایتان، ساختن داشبوردهای سفارشی، و راه‌اندازی هشدارهای سفارشی.