自訂 Flutter 的當機報告

選取平台：

iOS+ Android Flutter Unity

您可以在 控制台的「DevOps 與參與度」 > 「Crashlytics 資訊主頁」中，點選問題並取得詳細的事件報表。Firebase您可以自訂這些報表，進一步瞭解應用程式的運作情形，以及向 Crashlytics 回報的事件相關情況。

• 向 Crashlytics 回報未偵測到的例外狀況和偵測到的例外狀況。

• 檢測應用程式，記錄自訂鍵、自訂記錄訊息和使用者 ID。

• 如果應用程式使用 Google Analytics 的 Firebase SDK，系統會自動取得當機前使用者動作記錄。這些記錄可讓您瞭解使用者在應用程式中採取哪些動作，進而觸發 Crashlytics 收集的事件。

• 關閉自動當機回報功能，並為使用者啟用選擇加入回報功能。請注意，根據預設，Crashlytics 會自動為所有應用程式使用者收集平台原生當機報告。

回報例外狀況

回報未偵測到的例外狀況

只要使用 FirebaseCrashlytics.instance.recordFlutterFatalError 覆寫 FlutterError.onError，即可自動擷取 Flutter 架構中擲回的所有「致命」錯誤。或者，如要一併擷取「非致命」例外狀況，請使用 FirebaseCrashlytics.instance.recordFlutterError 覆寫 FlutterError.onError：

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 控制台的「DevOps & Engagement」 >「Crashlytics 資訊主頁」。問題摘要包含您通常從當機取得的所有狀態資訊，以及依版本和硬體裝置細分的資訊。

Crashlytics 會在專屬背景執行緒上處理例外狀況，盡可能降低對應用程式效能的影響。為減少使用者的網路流量，Crashlytics 會視需要限制從裝置傳送的報告數量。

新增自訂鍵

你可以使用自訂鍵，取得導致當機情況的應用程式特定狀態。您可以將任意鍵/值組合與當機報告建立關聯，然後使用自訂鍵，在 Firebase 控制台的「DevOps & Engagement」>「Crashlytics」資訊主頁中搜尋及篩選當機報告。

• 在資訊主頁中，您可以搜尋符合自訂鍵的問題。

• 在資訊主頁中查看特定問題時，您可以查看每個事件的相關自訂鍵 (「Keys」子分頁)，甚至可以依自訂鍵篩選事件 (頁面頂端的「Filter」選單)。

使用 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 會將記錄與當機資料建立關聯，並在您查看問題詳細資料時，將記錄顯示在「Logs」分頁中 (如要查看所有問題，請前往 Firebase 控制台的「DevOps & Engagement」 >「Crashlytics dashboard」)。

使用 log 有助於找出問題。例如：

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

設定使用者 ID

如要診斷問題，通常需要知道哪些使用者遇到特定當機情況。Crashlytics 提供一種方法，可在當機報告中匿名識別使用者。

如要在報表中加入使用者 ID，請以 ID 號碼、權杖或雜湊值的形式，為每位使用者指派專屬 ID：

FirebaseCrashlytics.instance.setUserIdentifier("12345");

如果設定使用者 ID 後需要清除，請將值重設為空白字串。清除使用者 ID 不會移除現有的 Crashlytics 記錄。如需刪除與使用者 ID 相關聯的記錄，請與 Firebase 支援團隊聯絡。

取得當機前使用者動作記錄

當機前使用者動作記錄可協助您進一步瞭解使用者在發生當機、非致命錯誤或 ANR 事件前，與應用程式的互動情形。在嘗試重現及偵錯問題時，這些記錄會很有幫助。

當機前使用者動作記錄由 Google Analytics 提供，因此您必須為 Firebase 專案啟用 Google Analytics，並在應用程式中新增 Google Analytics 的 Firebase SDK，才能取得這類記錄。符合這些條件後，當您查看問題詳細資料時，當機前使用者動作記錄就會自動包含在「記錄」分頁的事件資料中 (您可以在 Firebase 控制台的「開發運作和參與度」>「Crashlytics 資訊主頁」中查看所有問題)。

Analytics SDK 會自動記錄 screen_view 事件，讓當機前使用者動作記錄顯示當機、一般錯誤或 ANR 事件發生前，使用者瀏覽過的畫面清單。screen_view 當機前使用者動作記錄包含 firebase_screen_class 參數。

當機前使用者動作記錄也會填入您在使用者工作階段中手動記錄的任何自訂事件，包括事件的參數資料。這項資料可協助您瞭解導致當機、一般錯誤或 ANR 事件的一連串使用者動作。

請注意，您可以控管 Google Analytics 資料的收集和使用方式，包括填入當機前使用者動作記錄的資料。

啟用選擇加入報表

根據預設，Crashlytics 會自動收集所有應用程式使用者的當機報告。如要讓使用者進一步控管傳送的資料，您可以停用自動回報功能，並在程式碼中選擇僅將資料傳送至 Crashlytics，藉此啟用選擇加入回報功能。

1. 原生停用自動收集功能：

   Apple 平台

   在 Info.plist 檔案中新增金鑰：

   • 鍵：FirebaseCrashlyticsCollectionEnabled
   • 值：false

   Android

   在 AndroidManifest.xml 檔案的 application 區塊中，新增 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 會使用匯總的當機資料，找出常見的穩定性趨勢。如果不想分享應用程式資料，可以前往 Firebase 控制台的 DevOps 與參與度 > Crashlytics 資訊主頁 資訊主頁，在問題清單頂端的 當機深入分析 選單中，選擇不採用當機深入分析功能。

後續步驟

• 將資料匯出至 BigQuery 或 Cloud Logging，即可使用進階分析和功能，例如查詢資料、建立自訂資訊主頁，以及設定自訂快訊。