取得 Android NDK 當機報告

如果您的 Android 應用程式包含原生資料庫，您只要稍微更新應用程式的建構設定，就能透過 Firebase Crashlytics 為原生程式碼啟用完整堆疊追蹤和詳細當機報告。

本指南說明如何使用適用於 NDK 的 Firebase Crashlytics SDK 設定當機回報功能。

如要瞭解如何在 Unity 專案中開始使用 Crashlytics，請參閱 Unity 入門指南。

事前準備

  1. 如果您尚未將 Firebase 新增至 Android 專案，請先完成這項操作。如果您沒有 Android 應用程式，可以下載範例應用程式。

  2. 建議做法：如要自動取得導覽標記記錄，瞭解引發當機、一般錯誤或 ANR 事件的使用者動作，您必須在 Firebase 專案中啟用 Google Analytics (分析)。

    • 如果現有的 Firebase 專案尚未啟用 Google Analytics (分析)，您可以在 Firebase 控制台中前往 >「專案設定」，在「整合」分頁中啟用 Google Analytics (分析)。

    • 如要建立新的 Firebase 專案，請在專案建立工作流程中啟用 Google Analytics (分析)。

  3. 確認應用程式符合下列「最低」需求版本：

    • 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.1.1"))

    // 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.2")
    implementation("com.google.firebase:firebase-analytics:22.0.2")
}
在尋找 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 {
    // 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
}

  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 外掛程式包含 uploadCrashlyticsSymbolFileBUILD_VARIANT 工作，可自動執行這項程序。

  1. 為了方便您存取自動上傳符號的任務，請務必在模組 (應用程式層級) Gradle 檔案中將 nativeSymbolUploadEnabled 設為 true。

  2. 如要在堆疊追蹤中顯示方法名稱，您必須在每次 NDK 程式庫版本後明確叫用 uploadCrashlyticsSymbolFileBUILD_VARIANT 工作。例如：

    >./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

  3. NDK 適用的 Crashlytics SDK 和 Crashlytics Gradle 外掛程式，都取決於原生共用物件內是否有 GNU 版本 ID。

    您可以在各個二進位檔上執行 readelf -n，驗證這個 ID 的存在。如果沒有版本 ID，請將 -Wl,--build-id 加入建構系統的標記以修正問題。

步驟 5：強制測試當機以完成設定

您需要強制執行測試當機，才能完成 Crashlytics 設定，並在 Firebase 控制台的 Crashlytics 資訊主頁中查看初始資料。

  1. 在應用程式中新增程式碼，以便強制執行測試當機。

    您可以在應用程式的 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));

  2. 建構並執行應用程式。

  3. 強制測試當機，以便傳送應用程式的第一份當機報告：

    1. 透過測試裝置或模擬器開啟應用程式。

    2. 在應用程式中，按下使用上述程式碼新增的「Test Crash」按鈕。

    3. 在應用程式當機後重新啟動，讓應用程式能夠將當機報告傳送至 Firebase。

  4. 前往 Firebase 控制台的 Crashlytics 資訊主頁，查看測試當機情況。

    如果您已重新整理主控台，但五分鐘後仍未看到測試當機情況，請啟用偵錯記錄功能，確認應用程式是否會傳送當機報告。


大功告成！Crashlytics 現在會監控應用程式的當機情形，而您可以透過 Crashlytics 資訊主頁查看及調查當機報告與統計資料。

後續步驟

  • (建議) 您可藉由收集 GWP-ASan 報告，瞭解如何對原生記憶體錯誤造成的當機問題進行偵錯。 這些記憶體相關錯誤可能與應用程式內的記憶體毀損有關，這是造成應用程式安全漏洞的主要原因。如要利用這項偵錯功能，請確認應用程式已明確啟用 GWP-ASan，並使用 NDK 適用的最新版 Crashlytics SDK (18.3.6 以上版本或 Firebase BoM v31.3.0 以上版本)。

  • 新增選擇啟用報告、記錄、鍵及一般錯誤追蹤，以自訂當機報告設定。

  • 與 Google Play 整合，直接在 Crashlytics 資訊主頁中，依 Google Play 測試群組篩選 Android 應用程式的當機報告。如此一來，您就能將資訊主頁的重點放在特定版本上。

疑難排解

如果您在 Firebase 控制台和 logcat 中看到不同的堆疊追蹤，請參閱疑難排解指南。


替代符號上傳方式

上述頁面中的主要工作流程適用於標準 Gradle 版本。不過，部分應用程式會使用不同的設定或工具 (例如 Gradle 以外的建構程序)。在這種情況下，下列選項可能有助於成功上傳符號。

選項：上傳程式庫模組和外部依附元件的符號

這個選項在下列情況下相當實用：

  • 如果您在 Gradle 中使用自訂 NDK 建構程序
  • 如果您的原生資料庫內建於程式庫/功能模組中，或是由第三方提供
  • 如果自動符號上傳工作失敗，或資訊主頁出現未符號的當機問題

選項：上傳非 Gradle 版本或無法存取且未移除的原生資料庫的符號

這個選項在下列情況下相當實用：

  • 如果使用 Gradle 以外的建構程序

  • 如果提供了未移除的原生程式庫，但其在 Gradle 建構期間無法存取這些程式庫，