Bắt đầu sử dụng Firebase Crashlytics


Nếu ứng dụng Android của bạn có chứa thư viện gốc, bạn có thể bật dấu vết ngăn xếp đầy đủ và báo cáo chi tiết về sự cố cho mã gốc của mình từ Firebase Crashlytics bằng một vài bản cập nhật nhỏ cho cấu hình bản dựng của ứng dụng.

Hướng dẫn này mô tả cách định cấu hình tính năng báo cáo sự cố bằng SDK Firebase Crashlytics cho NDK.

Nếu bạn đang tìm hiểu cách bắt đầu sử dụng Crashlytics trong các dự án Unity, hãy xem Hướng dẫn bắt đầu sử dụng Unity.

Trước khi bắt đầu

  1. Nếu bạn chưa thực hiện, hãy thêm Firebase vào dự án Android của bạn. Nếu không có ứng dụng Android, bạn có thể tải ứng dụng mẫu xuống.

  2. Được đề xuất: Để tự động nhận nhật ký đường dẫn nhằm hiểu rõ các hành động của người dùng dẫn đến sự kiện gặp sự cố, không nghiêm trọng hoặc ANR, bạn cần bật Google Analytics trong dự án Firebase của mình.

    • Nếu dự án Firebase hiện tại của bạn chưa bật Google Analytics, bạn có thể bật Google Analytics trong thẻ Tích hợp của > Cài đặt dự án trong bảng điều khiển Firebase.

    • Nếu bạn đang tạo một dự án Firebase mới, hãy bật Google Analytics trong quy trình tạo dự án.

  3. Đảm bảo ứng dụng của bạn có phiên bản tối thiểu bắt buộc sau đây:

    • Gradle 8.0
    • Trình bổ trợ Android cho Gradle 8.1.0
    • Trình bổ trợ Gradle cho Các dịch vụ của Google 4.4.1

Bước 1: Thêm Crashlytics SDK cho NDK vào ứng dụng của bạn

Trong tệp Gradle (cấp ứng dụng) của mô-đun (thường là <project>/<app-module>/build.gradle.kts hoặc <project>/<app-module>/build.gradle), hãy thêm phần phụ thuộc cho thư viện Crashlytics NDK cho Android. Bạn nên sử dụng Firebase Android BoM để kiểm soát việc tạo phiên bản thư viện.

Để có trải nghiệm tối ưu với Crashlytics, bạn nên bật Google Analytics trong dự án Firebase và thêm Firebase SDK cho Google Analytics vào ứng dụng của mình. 

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

Bằng cách sử dụng Firebase Android BoM, ứng dụng của bạn sẽ luôn sử dụng những phiên bản tương thích của thư viện Android trên Firebase.

(Cách khác)  Thêm phần phụ thuộc của thư viện Firebase mà không dùng BoM

Nếu chọn không sử dụng Firebase BoM, bạn phải chỉ định từng phiên bản thư viện Firebase trong dòng phần phụ thuộc của thư viện đó.

Xin lưu ý rằng nếu sử dụng nhiều thư viện Firebase trong ứng dụng, bạn nên sử dụng BoM để quản lý các phiên bản thư viện, nhằm đảm bảo rằng tất cả các phiên bản đều tương thích. 

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

Bước 2: Thêm trình bổ trợ Crashlytics Gradle vào ứng dụng

  1. Trong tệp Gradle cấp gốc (cấp dự án) (<project>/build.gradle.kts hoặc <project>/build.gradle), hãy thêm trình bổ trợ Gradle Crashlytics vào khối 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. Trong tệp Gradle mô-đun (cấp ứng dụng) (thường là <project>/<app-module>/build.gradle.kts hoặc <project>/<app-module>/build.gradle), hãy thêm trình bổ trợ Gradle Crashlytics:

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

Bước 3: Thêm tiện ích Crashlytics vào bản dựng

Trong tệp Gradle cấp mô-đun (cấp ứng dụng) của bạn (thường là <project>/<app-module>/build.gradle.kts hoặc <project>/<app-module>/build.gradle), hãy định cấu hình tiện ích 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
          }
      }
  }
}

Bước 4: Thiết lập chế độ tự động tải biểu tượng gốc lên

Để tạo ra các dấu vết ngăn xếp có thể đọc được từ các sự cố NDK, Crashlytics cần biết về các biểu tượng trong các tệp nhị phân gốc của bạn. Trình bổ trợ Crashlytics Gradle bao gồm tác vụ uploadCrashlyticsSymbolFileBUILD_VARIANT để tự động hoá quy trình này.

  1. Để có thể truy cập vào tác vụ tải biểu tượng lên tự động, hãy đảm bảo rằng nativeSymbolUploadEnabled được đặt thành true trong tệp Gradle mô-đun (cấp ứng dụng).

  2. Để tên phương thức xuất hiện trong dấu vết ngăn xếp, bạn phải gọi rõ ràng tác vụ uploadCrashlyticsSymbolFileBUILD_VARIANT sau mỗi bản dựng của thư viện NDK. Ví dụ:

    >./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

  3. Cả SDK Crashlytics cho NDK và trình bổ trợ Crashlytics Gradle đều phụ thuộc vào sự hiện diện của mã nhận dạng bản dựng GNU trong các đối tượng dùng chung gốc.

    Bạn có thể xác minh sự hiện diện của mã nhận dạng này bằng cách chạy readelf -n trên mỗi tệp nhị phân. Nếu không có mã bản dựng, hãy thêm -Wl,--build-id vào cờ của hệ thống bản dựng để khắc phục vấn đề.

Bước 5: Xác định sự cố thử nghiệm để hoàn tất việc thiết lập

Để hoàn tất việc thiết lập Crashlytics và xem dữ liệu ban đầu trên trang tổng quan Crashlytics của bảng điều khiển Firebase, bạn cần xác định sự cố thử nghiệm.

  1. Thêm mã vào ứng dụng mà bạn có thể dùng để buộc xảy ra sự cố kiểm thử.

    Bạn có thể dùng mã sau trong MainActivity của ứng dụng để thêm một nút vào ứng dụng. Khi nhấn nút này, ứng dụng sẽ gặp sự cố. Nút này có nhãn "Test Crash" (Kiểm thử sự cố).

    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. Tạo bản dựng và chạy ứng dụng của bạn.

  3. Buộc sự cố kiểm thử xảy ra để gửi báo cáo sự cố đầu tiên của ứng dụng:

    1. Mở ứng dụng trên thiết bị kiểm thử hoặc trình mô phỏng.

    2. Trong ứng dụng của bạn, hãy nhấn vào nút "Test Crash" (Kiểm thử sự cố) mà bạn đã thêm bằng mã ở trên.

    3. Sau khi ứng dụng gặp sự cố, hãy khởi động lại ứng dụng để ứng dụng có thể gửi báo cáo sự cố đến Firebase.

  4. Chuyển đến Crashlytics trang tổng quan của bảng điều khiển Firebase để xem sự cố trong quá trình kiểm thử.

    Nếu bạn đã làm mới bảng điều khiển nhưng vẫn không thấy sự cố kiểm thử sau 5 phút, hãy bật tính năng ghi nhật ký gỡ lỗi để xem ứng dụng của bạn có gửi báo cáo sự cố hay không.


Vậy là xong! Crashlytics hiện đang giám sát ứng dụng của bạn để phát hiện sự cố và bạn có thể xem cũng như điều tra báo cáo và số liệu thống kê về sự cố trong trang tổng quan Crashlytics.

Các bước tiếp theo

  • (Đề xuất) Nhận trợ giúp gỡ lỗi các sự cố do lỗi bộ nhớ gốc gây ra bằng cách thu thập báo cáo GWP-ASan. Những lỗi liên quan đến bộ nhớ này có thể liên quan đến tình trạng hỏng bộ nhớ trong ứng dụng của bạn. Đây là nguyên nhân hàng đầu gây ra các lỗ hổng bảo mật của ứng dụng. Để tận dụng tính năng gỡ lỗi này, hãy đảm bảo rằng ứng dụng của bạn đã bật GWP-ASan một cách rõ ràng và sử dụng SDK Crashlytics mới nhất cho NDK (v18.3.6 trở lên hoặc Firebase BoM v31.3.0 trở lên).

  • Tuỳ chỉnh chế độ thiết lập báo cáo sự cố bằng cách thêm báo cáo chọn tham gia, nhật ký, khoá và tính năng theo dõi lỗi không nghiêm trọng.

  • Tích hợp với Google Play để bạn có thể lọc báo cáo sự cố của ứng dụng Android theo Google Play ngay trong trang tổng quan Crashlytics. Nhờ đó, bạn có thể tập trung bảng điều khiển vào các bản dựng cụ thể.

Khắc phục sự cố

Nếu bạn thấy các dấu vết ngăn xếp khác nhau trong bảng điều khiển Firebase và trong logcat, hãy tham khảo Hướng dẫn khắc phục sự cố.


Các lựa chọn thay thế để tải biểu tượng lên

Quy trình làm việc chính trên trang này ở trên áp dụng cho các bản dựng Gradle tiêu chuẩn. Tuy nhiên, một số ứng dụng sử dụng cấu hình hoặc công cụ khác (ví dụ: quy trình tạo khác với Gradle). Trong những trường hợp này, các lựa chọn sau đây có thể hữu ích để tải biểu tượng lên thành công.

Lựa chọn: Tải biểu tượng lên cho các mô-đun thư viện và phần phụ thuộc bên ngoài

Lựa chọn này có thể hữu ích trong các trường hợp sau:

  • Nếu bạn sử dụng quy trình tạo NDK tuỳ chỉnh trong Gradle
  • Nếu các thư viện gốc của bạn được tạo trong một mô-đun thư viện/tính năng hoặc do bên thứ ba cung cấp
  • Nếu tác vụ tải biểu tượng tự động lên không thành công hoặc bạn thấy các sự cố không có biểu tượng trong trang tổng quan

Lựa chọn: Tải biểu tượng lên cho các bản dựng không phải Gradle hoặc các thư viện gốc chưa gỡ bỏ không truy cập được

Lựa chọn này có thể hữu ích trong các trường hợp sau:

  • Nếu bạn sử dụng một quy trình tạo khác ngoài Gradle

  • Nếu các thư viện gốc chưa được gỡ bỏ biểu tượng được cung cấp cho bạn theo cách nào đó mà bạn không thể truy cập trong quá trình tạo bản dựng Gradle