自訂 Firebase Crashlytics 當機報告


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 控制台中顯示為非致命問題。問題摘要包含您通常會從當機事件取得的所有狀態資訊,以及依版本和硬體裝置分類的詳細資料。

Crashlytics 會在專用背景執行緒中處理例外狀況,盡量減少對應用程式效能的影響。為減少使用者的網路流量,Crashlytics 會視需要限制傳送至裝置的報表數量。

新增自訂鍵

您可以使用自訂鍵,取得導致當機情況的應用程式特定狀態。您可以將任意鍵/值組合與當機報告建立關聯,然後使用自訂鍵在 Firebase 主控台中搜尋及篩選當機報告。

  • 您可以在 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 會將記錄檔與當機資料建立關聯,並在 Firebase 控制台Crashlytics「Logs」分頁中顯示這些資料。

使用 log 找出問題所在。例如:

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

設定使用者 ID

如要診斷問題,通常需要瞭解哪些使用者發生特定異常終止情形。Crashlytics 提供匿名識別當機報告中使用者的方法。

如要在報表中新增 User-ID,請為每位使用者指派專屬 ID,形式可為 ID 編號、符記或雜湊值:

FirebaseCrashlytics.instance.setUserIdentifier("12345");

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

取得導覽標記記錄

導覽標記記錄可讓您進一步瞭解使用者與應用程式互動時,導致當機、非致命錯誤或 ANR 事件的情形。嘗試重現問題並進行偵錯時,這些記錄可能會很有幫助。

麵包屑記錄由 Google Analytics 提供支援,因此如要取得麵包屑記錄,您必須為 Firebase 專案啟用 Google Analytics,並Google Analytics 的 Firebase SDK 新增至應用程式。滿足這些需求後,您查看問題詳細資料時,系統就會在「Logs」分頁中,自動將麵包屑記錄與事件資料一併顯示。

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 自動收集報表。如要停用自動當機回報功能,請傳遞 false 做為覆寫值。將值設為 false 時,必須等到下次執行應用程式時,新值才會套用。

    FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);
    

管理當機深入分析資料

當機深入分析功能會將您的去識別化堆疊追蹤與其他 Firebase 應用程式的追蹤記錄進行比較,協助您解決問題,並讓您瞭解問題是否屬於更廣泛的趨勢。針對許多問題,Crash Insights 甚至會提供資源,協助您偵錯當機情形。

Crash Insights 會使用匯總的當機資料,找出常見的穩定性趨勢。如果您不想分享應用程式資料,可以在 Firebase 控制台Crashlytics 問題清單頂端,透過「Crash Insights」選單選擇停用這項功能。