本頁面由 Cloud Translation API 翻譯而成。

取得 Android NDK 當機報告

如果您的 Android 應用程式包含原生資料庫，您可以針對原生程式碼啟用完整堆疊追蹤和詳細當機報告透過 Firebase Crashlytics 對應用程式版本進行幾項小幅更新此外還會從 0 自動調整資源配置您完全不必調整資源調度設定

本指南將說明如何使用 Firebase Crashlytics NDK 適用的 SDK。

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

事前準備

如果您尚未在 Android 中新增 Firebase，請先完成這項作業。專案。如果您沒有 Android 應用程式，請下載範例應用程式。
建議：自動取得導覽標記記錄瞭解引發當機、一般錯誤或 ANR 事件的使用者動作您必須在 Firebase 專案中啟用 Google Analytics。
- 如果現有的 Firebase 專案未啟用 Google Analytics，您可以前往 Firebase 控制台的 >「專案設定」整合分頁標籤，啟用 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.3.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:19.1.0")
    implementation("com.google.firebase:firebase-analytics:22.1.0")
}

想找 Kotlin 專屬的程式庫模組嗎？距離開始還有 2023 年 10 月 (Firebase BoM 32.5.0)，Kotlin 和 Java 開發人員皆可依附於主要程式庫模組 (詳情請參閱這項計畫的常見問題)。

步驟 2：將 Crashlytics Gradle 外掛程式新增至應用程式

在您的根層級 (專案層級) Gradle 檔案 (<project>/build.gradle.kts 或 <project>/build.gradle)，請將 plugins 區塊的 Crashlytics Gradle 外掛程式：

Kotlin

您是否仍在使用 buildscript 語法？瞭解詳情加入 Firebase 外掛程式使用這個語法

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

您是否仍在使用 buildscript 語法？瞭解如何使用這個語法新增 Firebase 外掛程式。

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
}

在模組 (應用程式層級) 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 自動執行這項程序

您是否能存取自動上傳符號的工作將模組中的 nativeSymbolUploadEnabled 設為 true (應用程式層級) Gradle 檔案。
您必須明確叫用，方法名稱才會顯示在堆疊追蹤中 uploadCrashlyticsSymbolFileBUILD_VARIANT 執行任務。例如：
```
>./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT
```
NDK 適用的 Crashlytics SDK 和 Crashlytics Gradle 外掛程式取決於原生共用物件中是否有 GNU 版本 ID。

如要驗證這個 ID 的存在，請執行以下指令：每個二進位檔的 readelf -n。如果建構 ID 是缺少，請將 -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));

建構並執行應用程式。
強制執行測試當機，以便傳送應用程式的首份當機報告：
1. 在測試裝置或模擬器中開啟應用程式。
2. 在應用程式中，按下「測試當機」透過程式碼新增的按鈕。
3. 應用程式當機後，請重新啟動應用程式，以便將當機報告傳送至 Firebase。
前往下列網址的 Crashlytics 資訊主頁： Firebase 控制台，查看測試當機情形。

重新整理控制台後，如未發現測試當機五分鐘後啟用偵錯記錄功能查看應用程式是否傳送當機報告。

就是這麼簡單！「Crashlytics」正在監控應用程式的當機情形，而你您可以查看及調查當機報告和統計資料， Crashlytics資訊主頁。

後續步驟

(建議) 收集 GWP-ASan 報告，協助偵錯因原生記憶體錯誤而導致的當機情形。這些記憶體相關錯誤可能與應用程式中的記憶體毀損問題有關，而這類問題是造成應用程式安全漏洞的主要原因。如要利用這項偵錯功能，請確認您的應用程式具有已明確啟用 GWP-ASan 並使用最新的 Crashlytics SDK for NDK (18.3.6 以上版本或 Firebase BoM v31.3.0+)。
自訂當機報告設定，新增選擇使用報告、紀錄、鍵不嚴重的錯誤追蹤
與 Google Play 整合，讓可以直接依下列路徑篩選 Android 應用程式的當機報告：Google Play Crashlytics資訊主頁。這樣一來，您就能更專注於資訊主頁的特定版本。

疑難排解

如果在 Firebase 控制台和 logcat，請參閱疑難排解指南。

替代符號上傳方式

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

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

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

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

查看這個選項的操作說明

標準 Crashlytics 符號上傳工作假設是建構將原生資料庫當做應用程式模組 Gradle 建構作業的一部分，使用 NDK 建構工具，例如 CMake。

不過，如果您在 Gradle 中使用自訂 NDK 建構程序，或您的原生程式庫內建於程式庫/功能模組中，或是由第三方，您可能需要明確指定未移除的路徑程式庫為此，您可以新增 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<CrashlyticsExtension> {
                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 Gradle 外掛程式 3.0.0 版開始) 累積多個以及建構口味

查看包含多個目錄的範例

  buildTypes {
    release {
      configure<CrashlyticsExtension> {
        nativeSymbolUploadEnabled = true
        unstrippedNativeLibsDir = file("MY/NATIVE/LIBS")
      }
    }
    productFlavors {
      flavorDimensions += "feature"
      create("basic") {
        dimension = "feature"
        // ...
      }
      create("featureX") {
        dimension = "feature"
        configure<CrashlyticsExtension> {
          unstrippedNativeLibsDir = file("MY/FEATURE_X/LIBS")
        }
      }
    }
  }

uploadCrashlyticsSymbolFilesBasicRelease 工作只會上傳 MY/NATIVE/LIBS 中的符號，但 uploadCrashlyticsSymbolFilesFeatureXRelease 會上傳 MY/NATIVE/LIBS 和 MY/FEATURE_X/LIBS 中的符號。

最後強制測試當機以完成設定 Crashlytics，並在以下位置的 Crashlytics 資訊主頁查看初始資料： Firebase 控制台。

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

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

如果您使用 Gradle 以外的建構程序
如果系統以您無法在 Gradle 建構期間存取這些內容

查看這個選項的操作說明

如要使用這個選項，您必須在建立服務帳戶時執行 Firebase CLI 指令發布子版本，或是要查看符號化堆疊追蹤的任何版本，Firebase。

請確認您已完成主要的請參閱本頁前文的工作流程：
1. 已在 Firebase 控制台中啟用 Crashlytics。
2. 新增了 Crashlytics 適用於 NDK 的 SDK 和 Crashlytics Gradle 外掛程式。
請注意，如果採用這個選項，您不需要新增 firebaseCrashlytics 擴充功能，或是設定自動符號上傳功能，因為要改用透過 Firebase CLI (後續步驟) 產生並上傳符號檔案。
設定環境和專案以上傳符號：
1. 按照操作說明安裝 Firebase CLI。
  
  如已安裝 CLI，請務必更新至最新版本。
2. (僅適用於搭載 Android API 級別 30 以上版本的應用程式) 更新應用程式的停用指標標記的 AndroidManifest.xml 範本：
  1. 依序勾選「Android Player Settings」>「Publishing Settings」>「Build」>「Custom Main Manifest」方塊。
  2. 開啟位於 Assets/Plugins/Android/AndroidManifest.xml 的資訊清單範本。
  3. 在應用程式標記中新增下列屬性： <application android:allowNativeHeapPointerTagging="false" ... />敬上
建構專案。

上傳你的符號資訊。

建構完成後，產生與 Crashlytics 相容的符號並執行下列指令，將檔案上傳到 Firebase 伺服器 Firebase CLI 指令：

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 嗎？
您可以透過以下兩種方式查看 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 符號檔案產生器。
`--generator=breakpad`	使用 Breakpad 符號檔案產生器請注意，符號檔案產生的預設值為 Breakpad。只有在您在建構設定中新增 `symbolGenerator { csym() }` 且想要覆寫該值，改用 Breakpad 時，才使用這個標記。
`--dry-run`	產生符號檔案，但不會上傳這個標記很適合用來檢查系統傳送的檔案
`--debug`	提供其他偵錯資訊

最後強制測試當機以完成設定 Crashlytics，並在以下位置的 Crashlytics 資訊主頁查看初始資料： Firebase 控制台。

建構應用程式時，務必在強制執行當機時執行 Firebase CLI crashlytics:symbols:upload 指令來上傳符號檔案。