如果您的 Android 應用程序包含原生庫,您可以通過對應用程序的構建配置進行一些小的更新,從 Firebase Crashlytics 為您的原生代碼啟用完整的堆棧跟踪和詳細的崩潰報告。
本指南介紹如何使用適用於 NDK 的 Firebase Crashlytics SDK 配置崩潰報告。
如果您正在尋找如何在您的 Unity 項目中開始使用 Crashlytics,請查看Unity 入門指南。
在你開始之前
如果您還沒有,請將 Firebase 添加到您的 Android 項目中。如果您沒有 Android 應用程序,可以下載示例應用程序。
推薦:要獲得無崩潰用戶、麵包屑日誌和速度警報等功能,您需要在 Firebase 項目中啟用 Google Analytics。
如果您現有的 Firebase 項目沒有啟用 Google Analytics,您可以從 Firebase 控制台中集成選項卡啟用 Google Analytics。
>項目設置的如果您要創建新的 Firebase 項目,請在項目創建工作流程中啟用 Google Analytics。
第 1 步:將適用於 NDK 的 Crashlytics SDK 添加到您的應用
在您的模塊(應用程序級別)Gradle 文件(通常為<project>/<app-module>/build.gradle
)中,添加 Crashlytics NDK Android 庫的依賴項。我們建議使用Firebase Android BoM來控制庫版本。為了獲得最佳的 Crashlytics 體驗,我們建議在您的 Firebase 項目中啟用 Google Analytics ,並將適用於 Google Analytics 的 Firebase SDK 添加到您的應用程序中。
Kotlin+KTX
dependencies { // Import the BoM for the Firebase platform implementation platform('com.google.firebase:firebase-bom:32.1.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-ktx' }
通過使用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:18.3.7' implementation 'com.google.firebase:firebase-analytics-ktx:21.3.0' }
Java
dependencies { // Import the BoM for the Firebase platform implementation platform('com.google.firebase:firebase-bom:32.1.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:18.3.7' implementation 'com.google.firebase:firebase-analytics:21.3.0' }
第 2 步:將 Crashlytics Gradle 插件添加到您的應用
在根級(項目級) Gradle 文件 (
<project>/build.gradle
) 中,將 Crashlytics Gradle 插件添加為 buildscript 依賴項:buildscript { repositories { // Make sure that you have the following two repositories google() // Google's Maven repository mavenCentral() // Maven Central repository } dependencies { ... classpath 'com.android.tools.build:gradle:7.2.0' // Make sure that you have the Google services Gradle plugin dependency classpath 'com.google.gms:google-services:4.3.15' // Add the dependency for the Crashlytics Gradle plugin classpath 'com.google.firebase:firebase-crashlytics-gradle:2.9.5' } }
在您的模塊(應用程序級) Gradle 文件(通常是
<project>/<app-module>/build.gradle
)中,添加 Crashlytics Gradle 插件: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 步:將firebaseCrashlytics
擴展添加到您的構建中
在您的模塊(應用級)Gradle 文件(通常是app/build.gradle
)中,添加firebaseCrashlytics
擴展。
Kotlin+KTX
// ... 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 } } } }
Java
// ... 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 } } } }
第四步:設置原生符號自動上傳
為了從 NDK 崩潰中生成可讀的堆棧跟踪,Crashlytics 需要了解您的本機二進製文件中的符號。 Crashlytics Gradle 插件包括uploadCrashlyticsSymbolFile BUILD_VARIANT
任務來自動執行此過程。
為了您可以訪問自動符號上傳任務,請確保在您的模塊(應用程序級)Gradle 文件中將
nativeSymbolUploadEnabled
設置為true
。要在堆棧跟踪中顯示方法名稱,您必須在每次構建 NDK 庫後顯式調用
uploadCrashlyticsSymbolFile BUILD_VARIANT
任務。例如:>./gradlew app:assembleBUILD_VARIANT\ app:uploadCrashlyticsSymbolFileBUILD_VARIANT
用於 NDK 的 Crashlytics SDK 和 Crashlytics Gradle 插件都依賴於本地共享對像中是否存在 GNU 構建 ID。
您可以通過在每個二進製文件上運行
readelf -n
來驗證此 ID 是否存在。如果構建 ID 不存在,請將-Wl,--build-id
添加到構建系統的標誌中以解決問題。
第 5 步:強制測試崩潰以完成設置
要完成 Crashlytics 的設置並在 Firebase 控制台的 Crashlytics 儀表板中查看初始數據,您需要強制測試崩潰。
將可用於強制測試崩潰的代碼添加到您的應用程序。
您可以在應用的
MainActivity
中使用以下代碼向您的應用添加一個按鈕,按下該按鈕會導致崩潰。該按鈕標記為“測試崩潰”。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));
構建並運行您的應用程序。
強制測試崩潰以發送您的應用程序的第一個崩潰報告:
從您的測試設備或模擬器打開您的應用程序。
在您的應用中,按下您使用上述代碼添加的“測試崩潰”按鈕。
在您的應用程序崩潰後,重新啟動它,以便您的應用程序可以將崩潰報告發送到 Firebase。
轉到 Firebase 控制台的Crashlytics 儀表板以查看您的測試崩潰。
如果您刷新了控制台,但五分鐘後仍未看到測試崩潰,請啟用調試日誌記錄以查看您的應用程序是否正在發送崩潰報告。
就是這樣! Crashlytics 現在正在監控您的應用程序是否發生崩潰,您可以在 Crashlytics 儀表板中查看和調查崩潰報告和統計信息。
下一步
(推薦)通過收集 GWP-ASan 報告來幫助調試由本機內存錯誤引起的崩潰。這些與內存相關的錯誤可能與應用程序中的內存損壞有關,這是導致應用程序安全漏洞的主要原因。要利用此功能,請確保您的應用已明確啟用 GWP-ASan並使用最新的 Crashlytics SDK for NDK(v18.3.6+ 或 Firebase BoM v31.3.0+)。
通過添加選擇加入報告、日誌、密鑰和非致命錯誤跟踪來自定義您的崩潰報告設置。
與 Google Play 集成,以便您可以直接在 Crashlytics 儀表板中按 Google Play 跟踪過濾 Android 應用程序的崩潰報告。這使您可以更好地將儀表板集中在特定構建上。
故障排除
如果您在 Firebase 控制台和 logcat 中看到不同的堆棧跟踪,請參閱故障排除指南。
上傳符號的替代選項
上面此頁面上的主要工作流程適用於標準 Gradle 構建。但是,某些應用程序使用不同的配置或工具(例如 Gradle 以外的構建過程)。在這些情況下,以下選項可能有助於成功上傳符號。
選項:上傳庫模塊和外部依賴項的符號
此選項在以下情況下很有用:
- 如果您在 Gradle 中使用自定義的 NDK 構建過程
- 如果您的本機庫是在庫/功能模塊中構建的或由第三方提供
- 如果自動符號上傳任務失敗或者您在儀表板中看到未符號化的崩潰
標準的 Crashlytics 符號上傳任務假設您使用標準的 NDK 構建工具(例如 CMake)構建您的原生庫作為應用模塊的 Gradle 構建的一部分。
但是,如果您在 Gradle 中使用自定義的 NDK 構建過程,或者您的原生庫是在庫/功能模塊中構建的或由第三方提供的,您可能需要明確指定未剝離的庫的路徑。為此,您可以在build.gradle
文件的firebaseCrashlytics
擴展中添加unstrippedNativeLibsDir
屬性。
確保您已完成本頁前面主要工作流中的以下初始任務:
為了使自動符號上傳任務可以找到您的符號信息,請將以下內容添加到您的模塊(應用程序級)
build.gradle
文件中:// ... android { // ... buildTypes { release { firebaseCrashlytics { nativeSymbolUploadEnabled true unstrippedNativeLibsDir file("PATH/TO/UNSTRIPPED/DIRECTORY") } } } }
Crashlytics 插件將遞歸地在指定目錄中搜索擴展名為
.so
的本機庫。然後 Crashlytics 從所有這些庫中提取調試符號並將它們上傳到 Firebase 服務器。以下是您可以在
unstrippedNativeLibsDir
屬性中指定的內容:org.gradle.api.Project#files(Object...)
允許的任何參數,包括:java.lang.String
、java.io.File
或org.gradle.api.file.FileCollection
通過提供列表或
FileCollection
實例來實現單一構建風格的多個目錄
最後,強制測試崩潰以完成 Crashlytics 的設置並在 Firebase 控制台的 Crashlytics 儀表板中查看初始數據。
選項:為非 Gradle 構建或無法訪問的未剝離本機庫上傳符號
此選項在以下情況下很有用:
如果您使用 Gradle 以外的構建過程
如果您以某種方式向您提供未剝離的本機庫,但在 Gradle 構建期間無法訪問它們
此選項要求您在創建發布版本或您希望在 Firebase 控制台中查看符號化堆棧跟踪的任何版本時運行 Firebase CLI 命令。
確保您已完成本頁前面主要工作流中的以下初始任務:
請注意,使用此選項,您無需添加
firebaseCrashlytics
擴展程序或設置自動符號上傳,因為您將使用 Firebase CLI(下面的後續步驟)來生成和上傳您的符號文件。為符號上傳設置環境和項目:
按照說明安裝 Firebase CLI 。
如果您已經安裝了 CLI,請確保更新到最新版本。
(僅適用於使用 Android API 級別 30+ 的應用)更新應用的
AndroidManifest.xml
模板以禁用指針標記:選中Android Player Settings > Publishing Settings > Build > Custom Main Manifest複選框。
打開位於
Assets/Plugins/Android/AndroidManifest.xml
的清單模板。將以下屬性添加到應用程序標記:
<application android:allowNativeHeapPointerTagging="false" ... />
構建您的項目。
上傳您的符號信息。
構建完成後,生成一個與 Crashlytics 兼容的符號文件,並通過運行以下 Firebase CLI 命令將其上傳到 Firebase 服務器:
firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/SYMBOLS
FIREBASE_APP_ID :您的 Firebase Android 應用 ID(不是您的包名稱)
示例 Firebase Android 應用程序 ID:1:567383003300:android:17104a2ced0c9b9b
以下是查找您的 Firebase 應用 ID 的兩種方法:
在你的
google-services.json
文件中,你的App ID就是mobilesdk_app_id
值;或者在 Firebase 控制台中,轉到您的項目設置。向下滾動到您的應用卡片,然後點擊所需的 Firebase 應用以查找其應用 ID。
PATH/TO/SYMBOLS : CLI 生成的符號文件的路徑
導出到 Android Studio 項目 — PATH/TO/SYMBOLS可以是任何目錄。 Firebase CLI 將遞歸地在指定目錄中搜索擴展名為
.so
的本機庫。直接從 Unity 中構建 APK — PATH/TO/SYMBOLS是構建完成後在項目根目錄中生成的壓縮符號文件的路徑(例如:
myproject/myapp-1.0-v100.symbols.zip
)。
查看使用 Firebase CLI 命令生成和上傳符號文件的高級選項
旗幟 描述 --generator=csym
使用舊版 cSYM 符號文件生成器而不是默認的 Breakpad 生成器
不推薦使用。我們建議使用默認的 Breakpad 符號文件生成器。
--generator=breakpad
使用 Breakpad 符號文件生成器
請注意,符號文件生成的默認值是 Breakpad。僅當您在構建配置中添加了
symbolGenerator { csym() }
並且您想要覆蓋它以使用 Breakpad 時才使用此標誌。--dry-run
生成符號文件但不上傳它們
如果您想檢查發送的文件的內容,此標誌很有用。
--debug
提供額外的調試信息 最後,強制測試崩潰以完成 Crashlytics 的設置並在 Firebase 控制台的 Crashlytics 儀表板中查看初始數據。
作為強制崩潰的一部分構建您的應用程序後,請確保運行 Firebase CLI
crashlytics:symbols:upload
命令以上傳您的符號文件。