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

Analytics کیت توسعه نرم‌افزار به‌طور خودکار رویداد 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 به شما کمک می‌کند مشکلات را حل کنید و به شما اطلاع می‌دهد که آیا مشکل شما بخشی از یک روند بزرگ‌تر است یا خیر. برای بسیاری از مشکلات، «اطلاعات آماری خرابی» حتی منابعی را برای کمک به اشکال‌زدایی خرابی ارائه می‌دهد.

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

مراحل بعدی

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