如果您的 Android 應用程式包含本機程式庫,您可以透過對應用程式的建置配置進行一些小更新,從 Firebase Crashlytics 啟用本機程式碼的完整堆疊追蹤和詳細崩潰報告。
本指南介紹如何使用適用於 NDK 的 Firebase Crashlytics SDK 配置崩潰報告。
如果您正在尋找如何在 Unity 專案中開始使用 Crashlytics,請查看Unity 入門指南。
在你開始之前
如果您尚未將 Firebase 新增至您的 Android 專案中,請將其新增至您的 Android 專案中。如果您沒有 Android 應用程序,可以下載範例應用程式。
推薦:若要取得無崩潰使用者、麵包屑日誌和速度警報等功能,您需要在 Firebase 專案中啟用 Google Analytics。
如果您現有的 Firebase 專案未啟用 Google Analytics,您可以從您的 Firebase 專案的整合標籤中啟用 Google Analytics。
Firebase 控制台中的 >專案設定。如果您要建立新的 Firebase 項目,請在專案建立工作流程期間啟用 Google Analytics。
步驟 1 :將適用於 NDK 的 Crashlytics SDK 添加到您的應用程式
在模組(應用程式層級)Gradle 檔案(通常<project>/<app-module>/build.gradle.kts
或<project>/<app-module>/build.gradle
)中,新增 Crashlytics NDK 的依賴項Android 的函式庫。我們建議使用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:32.6.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.6.0") implementation("com.google.firebase:firebase-analytics:21.5.0") }
步驟 2 :將 Crashlytics Gradle 外掛程式新增至您的應用程式中
在根級(專案級) Gradle 檔案(
<project>/build.gradle.kts
或<project>/build.gradle
)中,將 Crashlytics Gradle 外掛程式新增至plugins
區塊:Kotlin
plugins { id("com.android.application") version "7.3.0" apply false // ... // Make sure that you have the Google services Gradle plugin dependency id("com.google.gms.google-services") version "4.4.0" apply false // Add the dependency for the Crashlytics Gradle plugin id("com.google.firebase.crashlytics") version "2.9.9" apply false }
Groovy
plugins { id 'com.android.application' version '7.3.0' apply false // ... // Make sure that you have the Google services Gradle plugin dependency id 'com.google.gms.google-services' version '4.4.0' apply false // Add the dependency for the Crashlytics Gradle plugin id 'com.google.firebase.crashlytics' version '2.9.9' 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 外掛程式包含uploadCrashlyticsSymbolFile BUILD_VARIANT
任務來自動執行此程序。
為了能夠存取自動符號上傳任務,請確保在模組(應用程式層級)Gradle 檔案中將
nativeSymbolUploadEnabled
設為true
。為了讓方法名稱出現在堆疊追蹤中,您必須在每次建置 NDK 函式庫後明確呼叫
uploadCrashlyticsSymbolFile BUILD_VARIANT
任務。例如:>./gradlew app:assembleBUILD_VARIANT\ app:uploadCrashlyticsSymbolFileBUILD_VARIANT
Crashlytics SDK for NDK 和 Crashlytics Gradle 外掛程式都依賴本機共享物件中 GNU 建置 ID 的存在。
您可以透過執行來驗證此 ID 是否存在
readelf -n
對每個二進位。如果建置 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並使用適用於 NDK 的最新 Crashlytics SDK(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 建置流程,或者您的本機程式庫是在程式庫/功能模組中建置的或由第三方提供的,則您可能需要明確指定未剝離程式庫的路徑。為此,您可以在 Gradle 建置檔案的 Crashlytics 擴充功能中新增unstrippedNativeLibsDir
屬性。
確保您已完成本頁前面主工作流程中的以下初始任務:
為了讓自動符號上傳任務能夠找到您的符號訊息,請將以下內容新增到您的模組(應用程式層級) Gradle 檔案中(通常
<project>/<app-module>/build.gradle.kts
或<project>/<app-module>/build.gradle
):Kotlin
import com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension // ... android { // ... buildTypes { release { configure
{ nativeSymbolUploadEnabled = true unstrippedNativeLibsDir = file("PATH/TO/UNSTRIPPED/DIRECTORY") } } } } Groovy
// ... 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
檔案中,您的應用程式 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
命令來上傳符號檔案。