如果您的 Android 應用程式含有原生程式庫,您可以透過對應用程式建構設定進行一些小更新,為 Firebase Crashlytics 啟用原生程式碼的完整堆疊追蹤和詳細當機報告。
本指南說明如何使用 NDK 的 Firebase Crashlytics SDK 設定當機回報功能。
如果您想瞭解如何在 Unity 專案中開���使用 Crashlytics,請參閱 Unity 入門指南。
事前準備
如果您尚未將 Firebase 新增至 Android 專案,請先新增。如果您沒有 Android 應用程式,可以下載範例應用程式。
建議:如要自動取得導覽標記記錄,瞭解導致當機、非致命或 ANR 事件的使用者動作,您必須在 Firebase 專案中啟用 Google Analytics。
如果現有的 Firebase 專案未啟用 Google Analytics,您可以前往 Firebase 控制台的
>「專案設定」整合分頁標籤,啟用 Google Analytics。 如果您要建立新的 Firebase 專案,請在專案建立工作流程中啟用 Google Analytics。
請確認應用程式具備以下最低必要版本:
- Gradle 8.0
- Android Gradle 外掛程式 8.1.0 版
- Google 服務 Gradle 外掛程式 4.4.1 版
步驟 1:在應用程式中加入 NDK 適用的 Crashlytics SDK
在模組 (應用程式層級) Gradle 檔案 (通常是<project>/<app-module>/build.gradle.kts
或 <project>/<app-module>/build.gradle
) 中,加入 Android 專用的 Crashlytics NDK 程式庫依附元件。建議您使用 Firebase Android BoM 來控制程式庫版本。
為提供最佳的 Crashlytics 體驗,建議您在 Firebase 專案中啟用 Google Analytics,並將 Google Analytics 專用 Firebase SDK 新增至應用程式。
dependencies { // Import the BoM for the Firebase platform implementation(platform("com.google.firebase:firebase-bom:33.7.0")) // Add the dependencies for the Crashlytics NDK and Analytics libraries // When using the BoM, you don't specify versions in Firebase library dependencies implementation("com.google.firebase:firebase-crashlytics-ndk") implementation("com.google.firebase:firebase-analytics") }
只要使用 Firebase Android BoM,應用程式就會一��使用相容的 Firebase Android 程式庫版本。
(替代做法) 不使用 BoM 新增 Firebase 程式庫依附元件
如果您選擇不使用 Firebase BoM,���必須在依附元件行��指定每個 Firebase 程式庫版本。
請注意,如果您在應用程式中使用多個 Firebase 程式庫,強烈建議您使用 BoM 來管理程式庫版本,確保所有版本皆相容。
dependencies { // Add the dependencies for the Crashlytics NDK and Analytics libraries // When NOT using the BoM, you must specify versions in Firebase library dependencies implementation("com.google.firebase:firebase-crashlytics-ndk:19.3.0") implementation("com.google.firebase:firebase-analytics:22.1.2") }
步驟 2:將 Crashlytics Gradle 外掛程式新增至應用程式
在根層級 (專案層級) Gradle 檔案 (
<project>/build.gradle.kts
或<project>/build.gradle
) 中,將 Crashlytics Gradle 外掛程式新增至plugins
區塊:Kotlin
plugins { // Make sure that you have the AGP plugin 8.1+ dependency id("com.android.application") version "8.1.4" apply false // ... // Make sure that you have the Google services Gradle plugin 4.4.1+ dependency id("com.google.gms.google-services") version "4.4.2" apply false // Add the dependency for the Crashlytics Gradle plugin id("com.google.firebase.crashlytics") version "3.0.2" apply false }
Groovy
plugins { // Make sure that you have the AGP plugin 8.1+ dependency id 'com.android.application' version '8.1.4' apply false // ... // Make sure that you have the Google services Gradle plugin 4.4.1+ dependency id 'com.google.gms.google-services' version '4.4.2' apply false // Add the dependency for the Crashlytics Gradle plugin id 'com.google.firebase.crashlytics' version '3.0.2' apply false }
在模組 (應用程式層級) Gradle 檔案 (通常是
<project>/<app-module>/build.gradle.kts
或<project>/<app-module>/build.gradle
) 中,新增 Crashlytics Gradle 外掛程式:Kotlin
plugins { id("com.android.application") // ... // Make sure that you have the Google services Gradle plugin id("com.google.gms.google-services") // Add the Crashlytics Gradle plugin id("com.google.firebase.crashlytics") }
Groovy
plugins { id 'com.android.application' // ... // Make sure that you have the Google services Gradle plugin id 'com.google.gms.google-services' // Add the Crashlytics Gradle plugin id 'com.google.firebase.crashlytics' }
步驟 3:在建構中加入 Crashlytics 擴充功能
在模組 (應用程式層級) Gradle 檔案 (通常是 <project>/<app-module>/build.gradle.kts
或 <project>/<app-module>/build.gradle
) 中,設定 Crashlytics 擴充功能。
Kotlin
import com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension
// ...
android {
// ...
buildTypes {
getByName("release") {
// Add this extension
configure<CrashlyticsExtension> {
// Enable processing and uploading of native symbols to Firebase servers.
// By default, this is disabled to improve build speeds.
// This flag must be enabled to see properly-symbolicated native
// stack traces in the Crashlytics dashboard.
nativeSymbolUploadEnabled = true
}
}
}
}
Groovy
// ...
android {
// ...
buildTypes {
release {
// Add this extension
firebaseCrashlytics {
// Enable processing and uploading of native symbols to Firebase servers.
// By default, this is disabled to improve build speeds.
// This flag must be enabled to see properly-symbolicated native
// stack traces in the Crashlytics dashboard.
nativeSymbolUploadEnabled true
}
}
}
}
步驟 4:設定原生符號的自動上傳功能
如要從 NDK 當機情形產生可讀取的堆疊追蹤記錄,Crashlytics 需要瞭解原生二進位檔中的符號。Crashlytics Gradle 外掛程式包含 uploadCrashlyticsSymbolFileBUILD_VARIANT
工作,可自動執行這項程序。
為便您存取自動上傳符號的工作,請確認模組 (應用程式層級) Gradle 檔案中的
nativeSymbolUploadEnabled
已設為true
。如要讓方法名稱顯示在堆疊追蹤中,您必須在每次建構 NDK 程式庫後,明確叫用
uploadCrashlyticsSymbolFileBUILD_VARIANT
工作。例如:>./gradlew app:assembleBUILD_VARIANT\ app:uploadCrashlyticsSymbolFileBUILD_VARIANT
NDK 適用的 Crashlytics SDK 和 Crashlytics Gradle 外掛程式都需要在原生共用物件中找到 GNU 建構 ID。
您可以對每個二進位檔執行
,驗證是否有這個 ID。如果沒有版本 ID,請將readelf -n
新增至建構系統的標記,以便修正問題。-Wl,--build-id
步驟 5:強制測試當機以完成設定
您需要強制測試當機,才能完成設定 Crashlytics,並在 Firebase 控制台的 Crashlytics ��訊主頁中看見初始資料。
在應用程式中新增可用於強制測試當機的程式碼。
您可以在應用程式的
MainActivity
中使用以下程式碼,為應用程式新增按鈕,當按下按鈕時會導致應用程式當機。按鈕標示為「Test Crash」。Kotlin+KTX
val crashButton = Button(this) crashButton.text = "Test Crash" crashButton.setOnClickListener { throw RuntimeException("Test Crash") // Force a crash } addContentView(crashButton, ViewGroup.LayoutParams( ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT))
Java
Button crashButton = new Button(this); crashButton.setText("Test Crash"); crashButton.setOnClickListener(new View.OnClickListener() { public void onClick(View view) { throw new RuntimeException("Test Crash"); // Force a crash } }); addContentView(crashButton, new ViewGroup.LayoutParams( ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT));
建構並執行應用程式。
強制執行測試當機,以便傳送應用程式的首份當機報告:
在測試裝置或模擬器中開啟應用程式。
在應用程式中,按下您使用上述程式碼新增的「Test Crash」按鈕。
應用程式當機後,請重新啟動應用程式,以便應用程式將當機報告傳送至 Firebase。
前往 Firebase 主控台的 Crashlytics 資訊主頁,查看測試異常終止情形。
如果您已重新整理控制台,但五分鐘後仍未看到測試異常終止,請啟用偵錯記錄,看看應用程式是否會傳送異常終止報告。
就是這麼簡單!Crashlytics 現在會監控應用程式的當機情形,您可以在 Crashlytics 資訊主頁中查看及調查當機報告和統計資料。
後續步驟
(建議) 收集 GWP-ASan 報告,藉此瞭解原生記憶體錯誤導致的當機情形。這些記憶體相關錯誤可能與應用程式中的記憶體毀損問題有關,而這類問題是造成應用程式安全漏洞的主要原因。如要充分利用這項偵錯功能,請確認應用程式已明確啟用 GWP-ASan,並使用最新的 Crashlytics SDK for NDK (18.3.6 以上版本或 Firebase BoM 31.3.0 以上版本)。
自訂當機報告設定,新增選擇加入的回報、記錄、鍵和非致命錯誤追蹤。
整合 Google Play,這樣您就能直接在 Crashlytics 資訊主頁中,依據 Google Play 追蹤記錄篩選 Android 應用程式的當機報告。這樣���來,您就能更專注於資訊主頁的特定版本。
疑難排解
如果您在 Firebase 主控台和 Logcat 中看到不同的堆疊追蹤,請參閱疑難排解指南。
上傳符號的其他方法
本頁上方的主要工作流程適用於標準 Gradle 版本。不過,有些應用程式會使用不同的設定或工具 (例如 Gradle 以外的建構程序)。在這種情況下,您可以使用下列選項來順利上傳符號。
選項:上傳程式庫模組和外部依附元件的符號
在下列情況下,這個選項會很實用:
- 如果您在 Gradle 中使用自訂的 NDK 建構程序
- 如果原生資料庫是在程式庫/功能模組中建構,或由第三方提供
- 如果自動符號上傳工作失敗,或您在資訊主頁中看到未符號化的當機情形
選項:上傳非 Gradle 版本或無法存取的未經精簡的原生資料庫的符號
在下列情況下,這個選項會很實用:
如果您使用 Gradle 以外的建構程序
如果您以某種方式取得未經精簡的原生資料庫,但在 Gradle 建構期間無法存取這些資料庫