Nhận báo cáo sự cố của Android NDK

Nếu ứng dụng Android của bạn có chứa thư viện gốc, bạn có thể bật toàn bộ dấu vết ngăn xếp và báo cáo sự cố chi tiết cho mã gốc của mình trên Firebase Crashlytics bằng một vài điểm cập nhật nhỏ đối với 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 báo cáo sự cố bằng Firebase Crashlytics SDK cho NDK.

Nếu bạn đang tìm 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. Thêm Firebase vào dự án Android của bạn nếu bạn chưa thực hiện. Nếu chưa có ứng dụng Android, bạn có thể tải một ứng dụng mẫu xuống.

2. Đề xuất: Để tự động lấy nhật ký breadcrumb để hiểu những hành động của người dùng dẫn đến sự cố, sự kiện không nghiêm trọng hoặc sự kiện 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 từ thẻ Tích hợp của settings > Cài đặt dự án trong bảng điều khiển của 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ó các phiên bản được yêu cầu tối thiểu 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

Để 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:33.1.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 các phiên bản tương thích của thư viện Android trên Firebase.

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.0.1")
    implementation("com.google.firebase:firebase-analytics:22.0.1")
}

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

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

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

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 định cấu hình tiện ích Crashlytics.

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

// ...

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 tính năng tự động tải biểu tượng gốc lên

Để tạo ra 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 ký hiệu trong 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 nhiệm vụ tự động tải biểu tượng lên, 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 tác vụ uploadCrashlyticsSymbolFileBUILD_VARIANT một cách rõ ràng sau mỗi bản dựng của thư viện NDK. Ví dụ:

   >./gradlew app:assembleBUILD_VARIANT\
              app:uploadCrashlyticsSymbolFileBUILD_VARIANT
   

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

   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 mã bản dựng không có, hãy thêm -Wl,--build-id vào cờ của hệ thống xây dựng để khắc phục sự cố.

Bước 5: Xác định sự cố thử nghiệm để hoàn tất quá trình 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 trong bảng điều khiển của 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ể sử dụng để xác định 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. Nút này sẽ gây ra sự cố khi được nhấn. Nút này có nhãn "Test Crash" (Sự cố kiểm thử).

   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));
   

2. Tạo bản dựng và chạy ứng dụng của bạn.

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

   1. Mở ứng dụng của bạn từ thiết bị thử nghiệm hoặc trình mô phỏng.

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

   3. Sau khi ứng dụng của bạn 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. Truy cập vào trang tổng quan Crashlytics trong bảng điều khiển của Firebase để xem sự cố kiểm thử của bạn.

   Nếu bạn đã làm mới bảng điều khiển mà 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ó đang gửi báo cáo sự cố hay không.

Vậy là xong! Crashlytics hiện đang theo dõi ứ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 các báo cáo sự cố cũng như số liệu thống kê trên trang tổng quan Crashlytics.

Các bước tiếp theo

• (Nên dùng) Nhận trợ giúp để gỡ lỗi sự cố do lỗi bộ nhớ gốc 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 – nguyên nhân chính gây ra các lỗ hổng bảo mật ứ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 Crashlytics SDK Crashlytics mới nhất cho NDK (phiên bản 18.3.6 trở lên hoặc Firebase BoM phiên bản 31.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 các 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 cách của Google Play ngay trên trang tổng quan Crashlytics. Điều này cho phép bạn tập trung tốt hơn vào trang tổng quan của mình vào các bản dựng cụ thể.

Khắc phục sự cố

Nếu bạn thấy nhiều dấu vết ngăn xếp trong bảng điều khiển của 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 khác để tải biểu tượng lên

Quy trình làm việc chính trên trang ở trên này á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 xây dựng không phải Gradle). Trong những trường hợp như vậy, các tuỳ chọn sau có thể hữu ích để tải biểu tượng lên thành công.

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

Tuỳ 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 xây dựng NDK tuỳ chỉnh trong Gradle
• Nếu thư viện gốc được xây dựng trong một thư viện/mô-đun tính năng hoặc do một bên thứ ba cung cấp
• Nếu tác vụ tự động tải biểu tượng lên không thành công hoặc bạn thấy sự cố không có biểu tượng trong trang tổng quan

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

Tuỳ 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 xây dựng không phải Gradle

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