開始使用 Firebase Crashlytics

iOS+ Android Android (NDK) Flutter Unity

如果 Android 應用程式包含原生程式庫，只要對應用程式的建構設定進行幾項小更新，即可從 Firebase Crashlytics 啟用原生程式碼的完整堆疊追蹤和詳細當機報告。

本指南說明如何使用 Firebase Crashlytics NDK 適用的 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:34.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:20.0.2")
    implementation("com.google.firebase:firebase-analytics:23.0.0")
}

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

1. 在根層級 (專案層級) Gradle 檔案 (<project>/build.gradle.kts 或 <project>/build.gradle) 中，將 Crashlytics Gradle 外掛程式新增至 plugins 區塊：

   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.3" apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id("com.google.firebase.crashlytics") version "3.0.6" 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.3' apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id 'com.google.firebase.crashlytics' version '3.0.6' apply false
   }

   您的應用程式是否使用較舊的 Gradle 版本？建議升級，否則請使用 Crashlytics Gradle 外掛程式 2.9.9 版。

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
          }
      }
  }
}

注意： Crashlytics NDK 發行版本包含 Android NDK 支援的所有架構原生二進位檔。如果應用程式指定特定子集，可以使用 ABI 分割排除不必要的架構。

步驟 4：設定自動上傳原生符號

如要從 NDK 異常終止產生可讀取的堆疊追蹤記錄，Crashlytics 必須瞭解原生二進位檔中的符號。Crashlytics Gradle 外掛程式 包含 uploadCrashlyticsSymbolFileBUILD_VARIANT 工作，可自動執行這項程序。

注意： 視應用程式的設定和工具 (例如非 Gradle 建構作業) 而定，Crashlytics 支援上傳符號的替代選項。

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

   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，並使用最新版 Crashlytics NDK 適用的 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 屬性。

1. 請確認您已完成本頁稍早主要工作流程中的下列初始工作：

   1. 在 Firebase 控制台中啟用 Crashlytics。

   2. 新增 NDK 的 Crashlytics SDK 和 Crashlytics Gradle 外掛程式。

   3. 已將 Crashlytics 擴充功能新增至建構作業。

   4. 設定自動上傳原生符號。

2. 為了讓自動上傳符號工作可以找到符號資訊，請在模組 (應用程式層級) 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 中的符號。

3. 最後，請強制測試當機，完成 Crashlytics 設定，並在 Firebase 控制台的 Crashlytics 資訊主頁中查看初始資料。

選項：上傳非 Gradle 建構作業的符號，或無法存取的未剝除原生程式庫

這個選項在下列情況下很有幫助：

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

• 如果未經剝除的原生程式庫是以某種方式提供給您，導致 Gradle 建構期間無法存取

查看這個選項的操作說明

如要使用這個選項，您必須在建立發布版本或任何建構版本時執行 Firebase CLI 指令，才能在 Firebase 控制台中查看符號化的堆疊追蹤記錄。

1. 請確認您已完成本頁稍早主要工作流程中的下列初始工作：

   1. 在 Firebase 控制台中啟用 Crashlytics。

   2. 新增 NDK 的 Crashlytics SDK 和 Crashlytics Gradle 外掛程式。

   請注意，使用這個選項時，您不需要新增 firebaseCrashlytics 擴充功能或設定自動上傳符號，因為您會改用 Firebase CLI (請參閱下方的後續步驟) 產生及上傳符號檔案。

2. 設定環境和專案，以便上傳符號：

   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" ... />

3. 建構專案。

4. 上傳符號資訊。

   注意： 請完成這個步驟，然後開始操作。日後，每當您建立版本建構作業或任何建構作業時，都請完成這個步驟，以便在 Firebase 控制台中查看符號化的堆疊追蹤記錄。

   建構完成後，請產生與 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 嗎？

     以下提供兩種方法，可找出 Firebase 應用程式 ID：

     • 在 google-services.json 檔案中，應用程式 ID 是 mobilesdk_app_id 值；或

     • 在 Firebase 控制台中，前往「Project settings」(專案設定)。 向下捲動至「您的應用程式」資訊卡，然後按一下所需的 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	提供其他偵錯資訊

5. 最後，請強制測試當機，完成 Crashlytics 設定，並在 Firebase 控制台的 Crashlytics 資訊主頁中查看初始資料。

   強制應用程式當機後，請務必執行 Firebase CLI crashlytics:symbols:upload 指令，上傳符號檔。

---