獲取 Android NDK 崩潰報告

如果您的 Android 應用程式包含本機程式庫,您可以透過對應用程式的建置配置進行一些小更新,從 Firebase Crashlytics 啟用本機程式碼的完整堆疊追蹤和詳細崩潰報告。

本指南介紹如何使用適用於 NDK 的 Firebase Crashlytics SDK 配置崩潰報告。

如果您正在尋找如何在 Unity 專案中開始使用 Crashlytics,請查看Unity 入門指南

在你開始之前

  1. 如果您尚未將 Firebase 新增至您的 Android 專案中,請將其新增至您的 Android 專案中。如果您沒有 Android 應用程序,可以下載範例應用程式

  2. 建議:要自動取得麵包屑日誌以了解導致崩潰、非致命或 ANR 事件的使用者操作,您需要在 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.8.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.3")
    implementation("com.google.firebase:firebase-analytics:21.6.1")
}
正在尋找 Kotlin 特定的庫模組?2023 年 10 月(Firebase BoM 32.5.0)開始,Kotlin 和 Java 開發人員都可以依賴主庫模組(有關詳細信息,請參閱有關此計劃的常見問題解答)。

步驟 2 :將 Crashlytics Gradle 外掛程式新增至您的應用程式中

  1. 根級(專案級) 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.1" 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.1' apply false
    
        // Add the dependency for the Crashlytics Gradle plugin
        id 'com.google.firebase.crashlytics' version '2.9.9' apply false
    }
    
  2. 模組(應用程式層級) 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任務來自動執行此程序。

  1. 為了能夠存取自動符號上傳任務,請確保在模組(應用程式層級)Gradle 檔案中將nativeSymbolUploadEnabled設為true

  2. 為了讓方法名稱出現在堆疊追蹤中,您必須在每次建置 NDK 函式庫後明確呼叫uploadCrashlyticsSymbolFile BUILD_VARIANT任務。例如:

    >./gradlew app:assembleBUILD_VARIANT\
               app:uploadCrashlyticsSymbolFileBUILD_VARIANT
    
  3. Crashlytics SDK for NDK 和 Crashlytics Gradle 外掛程式都依賴本機共享物件中 GNU 建置 ID 的存在。

    您可以透過執行來驗證此 ID 是否存在readelf -n對每個二進位。如果建置 ID 不存在,請新增-Wl,--build-id到您的建造系統的標誌來解決問題。

第 5 步:強制測試崩潰以完成設置

要完成 Crashlytics 的設定並在 Firebase 控制台的 Crashlytics 儀表板中查看初始數據,您需要強制測試崩潰。

  1. 將程式碼新增到您的應用程式中,您可以使用它來強制測試崩潰。

    您可以在應用程式的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));
    
  2. 建置並運行您的應用程式。

  3. 強制測試崩潰以發送應用程式的第一個崩潰報告:

    1. 從測試設備或模擬器開啟您的應用程式。

    2. 在您的應用程式中,按您使用上面的程式碼新增的「測試崩潰」按鈕。

    3. 您的應用程式崩潰後,重新啟動它,以便您的應用程式可以將崩潰報告傳送到 Firebase。

  4. 前往 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 建置期間無法存取它們