如果您的 Android 應用程式包含原生資料庫,您只要對 Firebase Crashlytics 進行幾項小幅更新,只要對應用程式的建構設定進行小幅更新,就能啟用 Firebase Crashlytics 的完整堆疊追蹤和詳細的當機報告。
本指南說明如何使用適用於 NDK 的 Firebase Crashlytics SDK 設定當機回報功能。
如要瞭解如何在 Unity 專案中開始使用 Crashlytics,請參閱 Unity 入門指南。
事前準備
如果您尚未新增 Firebase 至 Android 專案,請先完成這項操作。如果沒有 Android 應用程式,可以下載範例應用程式。
建議做法:如要自動取得導覽標記記錄,瞭解引發當機、不嚴重或 ANR 事件的使用者動作,您必須在 Firebase 專案中啟用 Google Analytics (分析)。
如果現有的 Firebase 專案尚未啟用 Google Analytics (分析),可以前往 Firebase 控制台,在
中,透過 >「專案設定」「Integrations」分頁啟用 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.0.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 程式庫版本。
(替代方法) 新增 Firebase 程式庫依附元件,「不必」使用 BoM
如果選擇不使用 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.0.0") implementation("com.google.firebase:firebase-analytics:22.0.0") }
步驟 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.1" apply false // Add the dependency for the Crashlytics Gradle plugin id("com.google.firebase.crashlytics") version "3.0.0" 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.1' apply false // Add the dependency for the Crashlytics Gradle plugin id 'com.google.firebase.crashlytics' version '3.0.0' 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,並使用最新的 NDK 適用的 Crashlytics SDK (v18.3.6 以上版本或 Firebase BoM v31.3.0 以上版本)。
新增選擇啟用報告、記錄、金鑰和非重大錯誤追蹤,藉此自訂當機報告設定。
整合 Google Play,直接在 Crashlytics 資訊主頁中,按照 Google Play 測試群組篩選 Android 應用程式的當機報告。如此一來,資訊主頁就能更專注於特定建構。
疑難排解
如果您在 Firebase 控制台和 logcat 中看到不同的堆疊追蹤,請參閱疑難排解指南。
上傳符號的替代選項
上述頁面的主要工作流程適用於標準 Gradle 版本。不過,部分應用程式使用不同的設定或工具 (例如 Gradle 以外的建構程序)。在這些情況下,下列選項或許有助於成功上傳符號。
選項:上傳程式庫模組和外部依附元件的符號
這個選項在下列情況相當實用:
- 在 Gradle 中使用自訂 NDK 建構程序
- 如果原生資料庫是透過程式庫/功能模組建構,或是由第三方提供
- 如果自動符號上傳工作失敗,或資訊主頁中出現未符號的當機事件
選項:上傳非 Gradle 建構作業的符號,或是無法存取的原生程式庫無法存取的符號
這個選項在下列情況相當實用:
如果您使用 Gradle 以外的建構程序
向您提供未去除的原生程式庫時,如果這些程式庫在 Gradle 建構期間無法存取