開始使用 Firebase Crashlytics

本快速入門說明如何使用 Crashlytics Flutter 外掛程式，在應用程式中設定 Firebase Crashlytics，以便在 Firebase 主控台中取得完整的當機報告。

設定 Crashlytics 時，您必須同時使用指令列工具和 IDE。如要完成設定，您必須強制擲回測試例外狀況，才能將第一份當機報告傳送至 Firebase。

事前準備

如果您尚未在 Flutter 專案中設定及初始化 Firebase，請先完成這些步驟。
建議：如要自動取得導覽標記記錄，瞭解導致當機、非致命或 ANR 事件的使用者動作，您必須在 Firebase 專案中啟用 Google Analytics。
- 如果現有的 Firebase 專案未啟用 Google Analytics，您可以前往 Firebase 控制台的 >「專案設定」整合分頁標籤，啟用 Google Analytics。
- 如果您要建立新的 Firebase 專案，請在專案建立工作流程中啟用 Google Analytics。
請注意，麵包屑記錄檔適用於 Crashlytics 支援的所有 Android 和 Apple 平台 (watchOS 除外)。

步驟 1：將 Crashlytics 新增至 Flutter 專案

在 Flutter 專案的根目錄中執行下列指令，安裝 Crashlytics 的 Flutter 外掛程式。

如要充分運用麵包屑記錄，請將 Google Analytics 的 Flutter 外掛程式新增至應用程式。請確認 Firebase 專案已啟用 Google Analytics。
```
flutter pub add firebase_crashlytics && flutter pub add firebase_analytics
```
在 Flutter 專案的根目錄中執行下列指令：
```
flutterfire configure
```
執行這項指令可確保 Flutter 應用程式的 Firebase 設定為最新版本，而對於 Android 而言，則會將必要的 Crashlytics Gradle 外掛程式新增至應用程式。
完成後，請重新建構 Flutter 專案：
```
flutter run
```
(選用) 如果您的 Flutter 專案使用 --split-debug-info 標記 (以及選用的 --obfuscate 標記)，就需要額外執行步驟，才能顯示應用程式的可讀堆疊追蹤記錄。
- Apple 平台：請確認專案使用建議的版本設定 (Flutter 3.12.0 以上版本和 Crashlytics Flutter 外掛程式 3.3.4 以上版本)，以便專案自動產生及上傳 Flutter 符號 (dSYM 檔案) 至 Crashlytics。
- Android：使用 Firebase CLI (11.9.0 以上版本) 上傳 Flutter 偵錯符號。您需要在回報模糊處理過的程式碼版本當機事件前，先上傳偵錯符號。
  
  在 Flutter 專案的根目錄中執行下列指令：
```
firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/symbols
```
  - FIREBASE_APP_ID：您的 Firebase Android 應用程式 ID (非套件名稱)
    Firebase Android 應用程式 ID 範例：1:567383003300:android:17104a2ced0c9b9b
    需要找出 Firebase 應用程式 ID 嗎？
    您可以透過以下兩種方式查看 Firebase 應用程式 ID：
    
    在 google-services.json 檔案中，應用程式 ID 為 mobilesdk_app_id 值；或
    
    在 Firebase 主控台中，前往專案設定。向下捲動至「您的應用程式」資訊卡，然後按一下所需的 Firebase 應用程式，找出其應用程式 ID。
  - PATH/TO/symbols：建構應用程式時傳遞至 --split-debug-info 標記的相同目錄

步驟 2：設定當機處理常式

您可以使用 FirebaseCrashlytics.instance.recordFlutterFatalError 覆寫 FlutterError.onError，自動擷取 Flutter 架構中擲回的所有錯誤：

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Firebase.initializeApp();

  // Pass all uncaught "fatal" errors from the framework to Crashlytics
  FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError;

  runApp(MyApp());
}

如要擷取 Flutter 架構未處理的非同步錯誤，請使用 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());

}

如需其他類型錯誤的處理方式範例，請參閱「自訂當機報告」。

步驟 3：強制測試當機以完成設定

您需要強制測試例外狀況，才能完成設定 Crashlytics，並在 Firebase 主控台的 Crashlytics 資訊主頁中查看初始資料。

在應用程式中加入程式碼，用於強制擲回測試例外狀況。

如果您已將會呼叫 FirebaseCrashlytics.instance.recordError(error, stack, fatal: true) 的錯誤處理常式新增至頂層 Zone，您可以使用下列程式碼，在應用程式中新增按鈕，當按下按鈕時，會擲回測試例外狀況：
```
TextButton(
    onPressed: () => throw Exception(),
    child: const Text("Throw Test Exception"),
),
```
建構並執行應用程式。
強制擲回測試例外狀況，以便傳送應用程式的首份報告：
1. 在測試裝置或模擬器中開啟應用程式。
2. 在應用程式中，按下使用上述程式碼新增的測試例外狀況按鈕。
前往 Firebase 主控台的 Crashlytics 資訊主頁，查看測試異常終止情形。

如果您已重新整理控制台，但五分鐘後仍未看到測試異常終止，請啟用偵錯記錄，看看應用程式是否會傳送異常終止報告。

就是這麼簡單！Crashlytics 現在會監控應用程式的當機情形，以及在 Android 裝置上監控非致命錯誤和 ANR。前往Crashlytics資訊主頁查看及查詢所有報表和統計資料。

後續步驟

自訂當機報告設定，新增選擇加入的回報、記錄、鍵和其他非致命錯誤的追蹤功能。
整合 Google Play，即可直接在 Crashlytics 資訊主頁中，依據 Google Play 追蹤記錄篩選 Android 應用程式的當機報告。這樣一來，您就能將資訊主頁的焦點放在特定版本上。
使用 Android Studio 中的「App Quality Insights」視窗，查看程式碼旁的堆疊追蹤和當機統計資料 (適用於 Electric Eel 2022.1.1 以上版本)。