開始使用 Android 版 Crashlytics

本指南說明如何在 Android 應用程式中開始使用 Firebase Crashlytics。

在應用程式中設定 Firebase Crashlytics SDK 後，您可以在 Firebase 控制台中取得完整的當機報告。使用 Android 版 Crashlytics，您可以取得當機、非致命錯誤和「應用程式無回應」(ANR) 錯誤的報告。

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`. Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me set up Firebase Crashlytics for my app.

事前準備

如要設定 Crashlytics，您必須在 Firebase 控制台和 IDE 中執行多項工作，例如新增 Firebase 設定檔和 Crashlytics SDK。如要完成設定，您必須強制測試當機，將第一份當機報告傳送至 Firebase。

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

2. 建議：如要自動取得當機前使用者動作記錄，瞭解導致當機、非致命錯誤或 ANR 事件的使用者動作，請在 Firebase 專案中啟用 Google Analytics。

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

   • 如果您使用的現有 Firebase 專案未啟用 Google Analytics，可以在 Firebase 控制台的「settings 設定」>「整合」頁面啟用。

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

   • Gradle 8.0
   • Android Gradle 外掛程式 8.1.0
   • Google 服務 Gradle 外掛程式 4.4.1

步驟 1：在應用程式中加入 Crashlytics SDK

如要使用當機前使用者動作記錄，請一併將 Google Analytics 專用 Firebase SDK 新增至應用程式。請確認 Firebase 專案已啟用 Google Analytics。

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:35.0.2"))

    // Add the dependencies for the Crashlytics and Analytics libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-crashlytics")
    implementation("com.google.firebase:firebase-analytics")
}

只要使用 Firebase Android BoM，應用程式就會一律使用相容的 Firebase Android 程式庫版本。

dependencies {
    // Add the dependencies for the Crashlytics and Analytics libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-crashlytics:21.0.0")
    implementation("com.google.firebase:firebase-analytics:24.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.5.0" apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id("com.google.firebase.crashlytics") version "3.0.8" 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.5.0' apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id 'com.google.firebase.crashlytics' version '3.0.8' 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，並在 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 控制台中，依序前往「DevOps & Engagement」(開發運作與參與度) >「Crashlytics dashboard」(資訊主頁)，查看測試當機報告。

   如果重新整理控制台後，五分鐘內仍未看到測試當機事件，請啟用偵錯記錄檔，查看應用程式是否傳送當機報告。

大功告成！Crashlytics 現在會監控應用程式，偵測當機、非致命錯誤和 ANR。前往Crashlytics 資訊主頁，查看及調查所有報表和統計資料。

後續步驟

• 自訂當機報告設定：新增選擇加入報告、記錄、金鑰和非致命錯誤追蹤。

• 與 Google Play 整合，即可直接在 Crashlytics 資訊主頁中，依 Google Play 測試群組篩選 Android 應用程式的當機報告。這樣一來，您就能更專注於特定建構作業的資訊主頁。

• 在 Android Studio 中查看及篩選 Crashlytics 資料。

  • 在 Android Studio 中，使用「App Quality Insights」 (AQI) 視窗查看 Crashlytics 資料和程式碼，不必在 Crashlytics 資訊主頁和 IDE 之間來回切換，即可開始偵錯主要問題。
  • 請參閱 Android Studio 說明文件，瞭解如何使用 AQI 視窗。
  • 歡迎您將使用心得與我們分享！如要針對 AQI 視窗提供意見，請提交錯誤報告。

• 將資料匯出至 BigQuery 或 Cloud Logging，即可使用進階分析和功能，例如查詢資料、建立自訂資訊主頁，以及設定自訂快訊。