開始使用 Firebase Crashlytics


如果 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

    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

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

    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 建構程序
  • 如果原生程式庫是在程式庫/功能模組中建構,或是由第三方提供
  • 如果自動上傳符號工作失敗,或資訊主頁顯示未符號化的當機情形

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

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

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

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