自訂您的 Firebase Crashlytics 崩潰報告

iOS+ Android Flutter Unity

本指南介紹如何使用 Firebase Crashlytics SDK 自定義崩潰報告。默認情況下，Crashlytics 會自動收集應用程序的所有用戶的崩潰報告（您可以關閉自動崩潰報告並為用戶啟用選擇加入報告）。 Crashlytics 提供了四種開箱即用的日誌記錄機制：自定義鍵、自定義日誌、用戶標識符和捕獲的異常。

添加自定義鍵

自定義鍵可幫助您獲取應用程序導致崩潰的特定狀態。您可以將任意鍵/值對與崩潰報告關聯，然後使用自定義鍵在 Firebase 控制台中搜索和過濾崩潰報告。

• 在Crashlytics 儀表板中，您可以搜索與自定義鍵匹配的問題。

• 當您在控制台中查看特定問題時，您可以查看每個事件的關聯自定義鍵（ “鍵”子選項卡），甚至可以按自定義鍵過濾事件（頁面頂部的“過濾器”菜單）。

注意： Crashlytics 最多支持 64 個鍵/值對。達到此閾值後，不會保存其他值。每個鍵/值對的大小最大可達 1 kB。

使用setCustomKey實例方法設置鍵/值對。請注意， setCustomKey已重載，以便value參數接受任何基元或String參數。這裡有些例子：

Kotlin+KTX

val crashlytics = Firebase.crashlytics
crashlytics.setCustomKeys {
    key("my_string_key", "foo") // String value
    key("my_bool_key", true) // boolean value
    key("my_double_key", 1.0) // double value
    key("my_float_key", 1.0f) // float value
    key("my_int_key", 1) // int value
}

Java

FirebaseCrashlytics crashlytics = FirebaseCrashlytics.getInstance();

crashlytics.setCustomKey("my_string_key", "foo" /* string value */);

crashlytics.setCustomKey("my_bool_key", true /* boolean value */);

crashlytics.setCustomKey("my_double_key", 1.0 /* double value */);

crashlytics.setCustomKey("my_float_key", 1.0f /* float value */);

crashlytics.setCustomKey("my_int_key", 1 /* int value */);

您還可以通過調用該鍵並將其設置為不同的值來修改現有鍵的值。例如：

Kotlin+KTX

val crashlytics = Firebase.crashlytics
crashlytics.setCustomKeys {
    key("current_level", 3)
    key("last_UI_action", "logged_in")
}

Java

FirebaseCrashlytics crashlytics = FirebaseCrashlytics.getInstance();

crashlytics.setCustomKey("current_level", 3);
crashlytics.setCustomKey("last_UI_action", "logged_in");

通過將CustomKeysAndValues的實例傳遞給setCustomKeys實例方法來批量添加鍵/值對：

Kotlin+KTX

對於 Kotlin，現有功能比使用CustomKeysAndValues構建器更簡單。

crashlytics.setCustomKeys {
  key("str_key", "hello")
  key("bool_key", true)
  key("int_key", 1)
  key("long_key", 1L)
  key("float_key", 1.0f)
  key("double_key", 1.0)
}

Java

CustomKeysAndValues keysAndValues = new CustomKeysAndValues.Builder()
.putString("string key", "string value")
.putString("string key 2", "string  value 2")
.putBoolean("boolean key", True)
.putBoolean("boolean key 2", False)
.putFloat("float key", 1.01)
.putFloat("float key 2", 2.02)
.build();

FirebaseCrashlytics.getInstance().setCustomKeys(keysAndValues);

添加自定義日誌消息

為了給自己提供有關導致崩潰的事件的更多背景信息，您可以將自定義 Crashlytics 日誌添加到您的應用程序中。 Crashlytics 將日誌與崩潰數據相關聯，並將它們顯示在Firebase 控制台的 Crashlytics 頁面的“日誌”選項卡下。

注意：為了避免減慢您的應用程序速度，Crashlytics 將日誌限制為 64kB，並在會話日誌超過該限制時刪除較舊的日誌條目。

使用log來幫助查明問題。例如：

Kotlin+KTX

Firebase.crashlytics.log("message")

Java

FirebaseCrashlytics.getInstance().log("message");

設置用戶標識符

要診斷問題，了解哪些用戶遇到了給定的崩潰通常很有幫助。 Crashlytics 包含一種在崩潰報告中匿名識別用戶的方法。

要將用戶 ID 添加到報告中，請為每個用戶分配一個 ID 號、令牌或哈希值形式的唯一標識符：

Kotlin+KTX

Firebase.crashlytics.setUserId("user123456789")

Java

FirebaseCrashlytics.getInstance().setUserId("user123456789");

如果您在設置用戶標識符後需要清除它，請將該值重置為空白字符串。清除用戶標識符不會刪除現有的 Crashlytics 記錄。如果您需要刪除與用戶 ID 關聯的記錄，請聯繫 Firebase 支持。

（僅限 Android NDK）將元數據添加到 NDK 崩潰報告

您可以選擇在 C++ 代碼中包含crashlytics.h標頭，以將元數據添加到 NDK 崩潰報告，例如自定義鍵、自定義日誌、用戶標識符。所有這些選項均在本頁上方進行了描述。

crashlytics.h在Firebase Android SDK GitHub 存儲庫中作為純標頭 C++ 庫提供。

閱讀頭文件中的註釋，了解有關使用 NDK C++ API 的說明。

包含 GWP-ASan 報告以調試內存損壞問題

Crashlytics 可以通過收集 GWP-ASan 報告來幫助您調試由本機內存錯誤引起的崩潰。這些與內存相關的錯誤可能與應用程序內的內存損壞有關，這是應用程序安全漏洞的主要原因。

• 當您單擊Crashlytics 儀表板中的問題詳細信息時，您可以在新的“內存堆棧跟踪”選項卡中查看此數據。

• 您還可以使用新的“GWP-ASan 報告”信號和過濾器來快速查看此數據的所有問題。

如果您在應用中明確啟用 GWP-ASan並使用適用於 NDK v18.3.6+ (Firebase BoM v31.3.0+) 的 Crashlytics SDK，則可以獲得 GWP-ASan 內存報告。您可以使用Android 文檔中的示例本機代碼來測試 GWP-ASan 設置。

報告非致命異常

除了自動報告應用程序的崩潰之外，Crashlytics 還允許您記錄非致命異常，並在下次應用程序啟動時將其發送給您。

注意： Crashlytics 僅存儲最近記錄的八個異常。如果您的應用程序引發超過八個異常，則較舊的異常將丟失。

使用recordException方法在應用程序的catch塊中記錄非致命異常。例如：

Kotlin+KTX

try {
    methodThatThrows()
} catch (e: Exception) {
    Firebase.crashlytics.recordException(e)
    // handle your exception here
}

Java

try {
    methodThatThrows();
} catch (Exception e) {
    FirebaseCrashlytics.getInstance().recordException(e);
    // handle your exception here
}

警告：如果您想要在異常消息中包含唯一值（例如，用戶 ID 或時間戳），請使用自定義鍵，而不是直接在異常消息中添加該值。直接添加值可能會導致多個問題，並可能導致 Crashlytics 限制應用程序中的報告錯誤。

所有記錄的異常在 Firebase 控制台中均顯示為非致命問題。問題摘要包含您通常從崩潰中獲得的所有狀態信息，以及按 Android 版本和硬件設備劃分的故障信息。

Crashlytics 在專用後台線程上處理異常，以盡量減少對應用程序的性能影響。為了減少用戶的網絡流量，Crashlytics 將記錄的異常批量處理在一起，並在下次應用程序啟動時發送它們。

啟用選擇加入報告

默認情況下，Crashlytics 會自動收集應用程序的所有用戶的崩潰報告。為了讓用戶更好地控制他們發送的數據，您可以通過禁用自動報告來啟用選擇加入報告，並且僅當您在代碼中選擇時才將數據發送到 Crashlytics：

1. 在AndroidManifest.xml文件的application程序塊中，添加meta-data標記以關閉自動收集：

   <meta-data
       android:name="firebase_crashlytics_collection_enabled"
       android:value="false" />
   

2. 通過在運行時調用 Crashlytics 數據收集覆蓋來為選定用戶啟用收集。覆蓋值在應用程序啟動時持續存在，因此 Crashlytics 可以自動收集報告。要選擇退出自動崩潰報告，請傳遞false作為覆蓋值。當設置為false時，新值直到下次運行應用程序時才會應用。

   Kotlin+KTX

   Firebase.crashlytics.setCrashlyticsCollectionEnabled(true)

   Java

   FirebaseCrashlytics.getInstance().setCrashlyticsCollectionEnabled(true);

注意：禁用數據收集時，Crashlytics 會將崩潰信息存儲在設備本地。如果隨後啟用數據收集，則設備上存儲的任何崩潰信息都將發送到 Crashlytics 進行處理。

管理崩潰洞察數據

Crash Insights 通過將匿名堆棧跟踪與其他 Firebase 應用的跟踪進行比較來幫助您解決問題，並讓您知道您的問題是否屬於更大趨勢的一部分。對於許多問題，Crash Insights 甚至提供資源來幫助您調試崩潰。

崩潰洞察使用聚合的崩潰數據來識別常見的穩定性趨勢。如果您不想共享應用的數據，可以從Firebase 控制台Crashlytics 問題列表頂部的Crash Insights菜單中選擇退出 Crash Insights。

注意：禁用數據共享也會消除對您的問題的洞察。更改最多可能需要 24 小時才能生效。