開始使用 Firebase Crashlytics

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

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

事前準備

如果您尚未在 Flutter 專案中設定並初始化 Firebase，請先完成這項作業。
建議做法：如要自動取得導覽標記記錄，瞭解引發當機、不嚴重或 ANR 事件的使用者動作，您必須在 Firebase 專案中啟用 Google Analytics (分析)。
- 如果現有的 Firebase 專案尚未啟用 Google Analytics (分析)，可以前往 Firebase 控制台，在 >「專案設定」中，透過「Integrations」分頁啟用 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 (v.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 控制台中，前往「Project settings」。向下捲動至「Your apps」資訊卡，然後按一下所需的 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 開始提供)。