自訂 Firebase Crashlytics 當機報告

iOS 以上版本 Android Flutter Unity

在 Crashlytics 資訊主頁中，您可以查看問題並取得詳細的事件報表。您可以自訂這些報表，進一步瞭解應用程式的動態，以及向 Crashlytics 回報事件的情況。

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

• 向 Crashlytics 回報例外狀況。

• 如果您的應用程式使用 Google Analytics (分析) 專用 Firebase 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 將記錄限制為 64 kB，並在工作階段記錄檔超出限制時刪除較舊的記錄項目。

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

Kotlin+KTX

Firebase.crashlytics.log("message")

Java

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

設定使用者 ID

如要診斷問題，瞭解哪些使用者遇到了特定當機問題，通常會很有幫助。Crashlytics 可讓您在當機報告中以匿名方式識別使用者。

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

Kotlin+KTX

Firebase.crashlytics.setUserId("user123456789")

Java

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

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

(僅限 Android NDK) 在 NDK 當機報告中新增中繼資料

您可以選擇在 C++ 程式碼中加入 crashlytics.h 標頭，將中繼資料加入 NDK 當機報告，例如自訂金鑰、自訂記錄和使用者 ID。上方頁面將說明所有選項。

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 以上版本) (Firebase BoM v31.3.0+)，就可以取得 GWP-ASan 記憶體報告。如要測試 GWP-ASan 設定，請參閱 Android 說明文件中的原生程式碼範例。

回報不嚴重的例外狀況

除了自動回報應用程式的當機問題外，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 會將記錄的例外狀況批次處理，並在應用程式下次啟動時傳送這些例外狀況。

取得導覽標記記錄

導覽標記記錄可讓您進一步瞭解造成當機、一般錯誤或 ANR 事件的使用者與應用程式的互動。嘗試重現及偵錯問題時，這些記錄非常實用。

導覽標記記錄由 Google Analytics (分析) 提供技術支援，因此如要取得導覽標記記錄，您需要為 Firebase 專案啟用 Google Analytics (分析)，並將 Google Analytics (分析) 專用 Firebase SDK 新增至應用程式。符合這些規定後，系統就會在您查看問題詳細資料時，自動將導覽標記記錄與事件資料一併納入「記錄」分頁中。

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

導覽標記記錄也會填入您在使用者工作階段中手動記錄的所有自訂事件，包括事件的參數資料。這項資料有助於顯示引發當機、一般錯誤或 ANR 事件的一系列使用者動作。

請注意，您可以控管 Google Analytics (分析) 資料的收集和使用方式，包括填入導覽標記記錄的資料。

啟用自選回報功能

根據預設，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 進行處理。

管理當機深入分析資料

當機分析功能可將匿名堆疊追蹤與其他 Firebase 應用程式的追蹤記錄進行比較，讓您瞭解問題是否出在更大趨勢，進而解決問題。許多問題甚至會提供相關資源來協助偵錯。

當機深入分析會使用匯總的當機資料，找出常見的穩定性趨勢。 如果您不想分享應用程式的資料，可以在 Firebase 控制台的 Crashlytics 問題清單頂端，從「Crash Insights」選單選擇不採用 Crash Insights。

注意： 停用資料共用功能也會一併移除問題相關的深入分析。變更最多可能需要 24 小時才會生效。