Nếu ứng dụng Android của bạn 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 sự cố chi tiết cho mã gốc của mình từ Firebase Crashlytics bằng một số cập nhật nhỏ cho cấu hình bản dựng ứng dụng của bạn.
Hướng dẫn này mô tả cách định cấu hình báo cáo sự cố với SDK Firebase Crashlytics cho NDK.
Nếu bạn đang tìm cách bắt đầu với Crashlytics trong các dự án Unity của mình, hãy xem hướng dẫn Bắt đầu Unity .
Trước khi bắt đầu
Nếu bạn chưa có, hãy thêm Firebase vào dự án Android của bạn. Nếu chưa có ứng dụng Android, bạn có thể tải xuống ứng dụng mẫu .
Khuyến nghị : Để nhận được các tính năng như người dùng không gặp sự cố, nhật ký đường dẫn và cảnh báo vận tốc, 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ừ tab Tích hợp của
Nếu bạn đang tạo dự án Firebase mới, hãy bật Google Analytics trong quy trình tạo dự án.
Bước 1 : Thêm SDK Crashlytics cho NDK vào ứng dụng của bạn
Trong tệp Gradle 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 thêm phần phụ thuộc cho Crashlytics NDK thư viện dành cho Android. Chúng tôi khuyên bạn nên sử dụng BoM Android của Firebase để 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, chúng tôi khuyên bạn nên bật Google Analytics trong dự án Firebase và thêm SDK Firebase 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:32.6.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 Firebase Android.
(Thay thế) Thêm phụ thuộc thư viện Firebase mà không cần sử dụng BoM
Nếu chọn không sử dụng BoM Firebase, bạn phải chỉ định từng phiên bản thư viện Firebase trong dòng phụ thuộc của nó.
Lưu ý rằng nếu bạn sử dụng nhiều thư viện Firebase trong ứng dụng của mình, chúng tôi thực sự khuyên 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:18.6.0") implementation("com.google.firebase:firebase-analytics:21.5.0") }
Bước 2 : Thêm plugin Crashlytics Gradle vào ứng dụng của bạn
Trong tệp Gradle cấp cơ sở (cấp dự án) (
<project>/build.gradle.kts
hoặc<project>/build.gradle
), hãy thêm plugin Crashlytics Gradle vào khốiplugins
:Kotlin
plugins { id("com.android.application") version "7.3.0" apply false // ... // Make sure that you have the Google services Gradle plugin dependency id("com.google.gms.google-services") version "4.4.0" apply false // Add the dependency for the Crashlytics Gradle plugin id("com.google.firebase.crashlytics") version "2.9.9" apply false }
Groovy
plugins { id 'com.android.application' version '7.3.0' apply false // ... // Make sure that you have the Google services Gradle plugin dependency id 'com.google.gms.google-services' version '4.4.0' apply false // Add the dependency for the Crashlytics Gradle plugin id 'com.google.firebase.crashlytics' version '2.9.9' apply false }
Trong tệp Gradle 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 thêm plugin 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 mở rộng Crashlytics vào bản dựng của bạn
Trong tệp Gradle 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 mở rộng 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 tự động tải lên các ký hiệu gốc
Để 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 ký hiệu trong tệp nhị phân gốc của bạn. Plugin Crashlytics Gradle bao gồm tác vụ uploadCrashlyticsSymbolFile BUILD_VARIANT
để tự động hóa quy trình này.
Để bạn có thể truy cập tác vụ tải biểu tượng tự động lên, hãy đảm bảo rằng
nativeSymbolUploadEnabled
được đặt thànhtrue
trong tệp Gradle mô-đun (cấp ứng dụng) của bạn.Để 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ụ
uploadCrashlyticsSymbolFile BUILD_VARIANT
một cách rõ ràng sau mỗi bản dựng thư viện NDK của mình. Ví dụ:>./gradlew app:assembleBUILD_VARIANT\ app:uploadCrashlyticsSymbolFileBUILD_VARIANT
Cả SDK Crashlytics cho NDK và plugin Crashlytics Gradle đều phụ thuộc vào sự hiện diện của ID bản dựng GNU trong các đối tượng được chia sẻ gốc.
Bạn có thể xác minh sự hiện diện của ID này bằng cách chạy
readelf -n
trên mỗi nhị phân. Nếu không có ID bản dựng, hãy thêm-Wl,--build-id
vào cờ của hệ thống xây dựng của bạn để khắc phục sự cố.
Bước 5 : Buộc chạy 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 trong bảng điều khiển Crashlytics của bảng điều khiển Firebase, bạn cần thực hiện thử nghiệm sự cố.
Thêm mã vào ứng dụng của bạn mà bạn có thể sử dụng để buộc thử nghiệm gặp sự cố.
Bạn có thể sử dụng mã sau đây trong
MainActivity
của ứng dụng để thêm một nút vào ứng dụng mà khi nhấn vào sẽ gây ra sự cố. Nút được gắn nhãn "Kiểm tra sự cố".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));
Xây dựng và chạy ứng dụng của bạn.
Buộc thử nghiệm sự cố để gửi báo cáo sự cố đầu tiên cho ứng dụng của bạn:
Mở ứng dụng của bạn từ thiết bị thử nghiệm hoặc trình mô phỏng.
Trong ứng dụng của bạn, hãy nhấn nút "Kiểm tra sự cố" mà bạn đã thêm bằng mã ở trên.
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ủa bạn có thể gửi báo cáo sự cố tới Firebase.
Đi tới trang tổng quan Crashlytics của bảng điều khiển Firebase để xem sự cố thử nghiệm của bạn.
Nếu bạn đã làm mới bảng điều khiển và vẫn không thấy lỗi kiểm tra 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 lỗi hay không.
Và thế 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 và thống kê sự cố trong bảng điều khiển Crashlytics.
Bước tiếp theo
(Được khuyến nghị) 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 hỏng bộ nhớ trong ứng dụng của bạn, đây là nguyên nhân hàng đầu gây ra 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 ứng dụng của bạn đã bật rõ ràng GWP-ASan và sử dụng SDK Crashlytics mới nhất cho NDK (v18.3.6+ hoặc Firebase BoM v31.3.0+).
Tùy chỉnh thiết lập báo cáo sự cố của bạn bằng cách thêm báo cáo chọn tham gia, nhật ký, khóa và 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 bản nhạc Google Play trực tiếp trong trang tổng quan Crashlytics. Điều này cho phép bạn tập trung tốt hơn vào bảng điều khiển của mình trên các bản dựng cụ thể.
Xử lý 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 tùy chọn thay thế để tải lên biểu tượng
Quy trình làm việc chính trên trang này ở trên có thể á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 này, các tùy chọn sau có thể hữu ích để tải biểu tượng lên thành công.
Tùy chọn : Tải lên các ký hiệu cho mô-đun thư viện và các phụ thuộc bên ngoài
Tùy 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 NDK tùy chỉnh trong Gradle
- Nếu thư viện gốc của bạn được xây dựng trong 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
Tác vụ tải lên biểu tượng Crashlytics tiêu chuẩn giả định rằng bạn đang xây dựng thư viện gốc của mình như một phần của bản dựng Gradle của mô-đun ứng dụng, bằng cách sử dụng các công cụ xây dựng NDK tiêu chuẩn như CMake.
Tuy nhiên, nếu bạn đang sử dụng quy trình xây dựng NDK tùy chỉnh trong Gradle hoặc thư viện gốc của bạn được xây dựng trong mô-đun thư viện/tính năng hoặc do bên thứ ba cung cấp, thì bạn có thể cần chỉ định rõ ràng đường dẫn đến các thư viện chưa được gỡ bỏ của mình. Để thực hiện điều này, bạn có thể thêm thuộc tính unstrippedNativeLibsDir
trong phần mở rộng Crashlytics trong tệp bản dựng Gradle của mình.
Đảm bảo rằng bạn đã hoàn thành các tác vụ ban đầu sau đây từ quy trình làm việc chính trước đó trên trang này:
Để tác vụ tải biểu tượng tự động lên có thể tìm thấy thông tin biểu tượng của bạn, hãy thêm phần sau vào tệp Gradle 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
):Kotlin
import com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension // ... android { // ... buildTypes { release { configure
{ nativeSymbolUploadEnabled = true unstrippedNativeLibsDir = file("PATH/TO/UNSTRIPPED/DIRECTORY") } } } } Groovy
// ... android { // ... buildTypes { release { firebaseCrashlytics { nativeSymbolUploadEnabled true unstrippedNativeLibsDir file("PATH/TO/UNSTRIPPED/DIRECTORY") } } } }
Plugin Crashlytics sẽ tìm kiếm đệ quy thư mục được chỉ định cho các thư viện gốc có phần mở rộng
.so
. Sau đó, Crashlytics trích xuất các biểu tượng gỡ lỗi từ tất cả các thư viện như vậy và tải chúng lên máy chủ Firebase.Đây là những gì bạn có thể chỉ định trong thuộc tính
unstrippedNativeLibsDir
:Bất kỳ đối số nào được phép đối với
org.gradle.api.Project#files(Object...)
, bao gồm:java.lang.String
,java.io.File
hoặcorg.gradle.api.file.FileCollection
Nhiều thư mục cho một phiên bản xây dựng bằng cách cung cấp danh sách hoặc phiên bản
FileCollection
Cuối cùng, buộc chạy thử nghiệm sự cố để hoàn tất quá trình thiết lập Crashlytics và xem dữ liệu ban đầu trong trang tổng quan Crashlytics của bảng điều khiển Firebase.
Tùy chọn : Tải lên các biểu tượng cho các bản dựng không phải Gradle hoặc các thư viện gốc chưa được giải mã không thể truy cập được
Tùy 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ác thư viện gốc chưa được gỡ bỏ của bạn được cung cấp cho bạn theo cách nào đó mà bạn không thể truy cập được trong quá trình xây dựng Gradle
Tùy chọn này yêu cầu bạn chạy lệnh Firebase CLI khi tạo bản phát hành hoặc bất kỳ bản dựng nào mà bạn muốn xem dấu vết ngăn xếp được tượng trưng trong bảng điều khiển Firebase.
Đảm bảo rằng bạn đã hoàn thành các tác vụ ban đầu sau đây từ quy trình làm việc chính trước đó trên trang này:
Đã thêm SDK Crashlytics cho NDK và plugin Crashlytics Gradle .
Lưu ý rằng với tùy chọn này, bạn không cần thêm tiện ích mở rộng
firebaseCrashlytics
hoặc thiết lập tải biểu tượng tự động lên vì thay vào đó, bạn sẽ sử dụng Firebase CLI (các bước tiếp theo bên dưới) để tạo và tải lên các tệp biểu tượng của mình.Thiết lập môi trường và dự án của bạn để tải lên biểu tượng:
Làm theo hướng dẫn để cài đặt Firebase CLI .
Nếu bạn đã cài đặt CLI, hãy nhớ cập nhật lên phiên bản mới nhất của nó .
(chỉ dành cho các ứng dụng sử dụng API Android cấp 30+) Cập nhật mẫu
AndroidManifest.xml
của ứng dụng của bạn để tắt Gắn thẻ con trỏ:Chọn hộp cho Cài đặt trình phát Android > Cài đặt xuất bản > Xây dựng > Bản kê khai chính tùy chỉnh .
Mở mẫu bảng kê khai có tại
Assets/Plugins/Android/AndroidManifest.xml
.Thêm thuộc tính sau vào thẻ ứng dụng:
<application android:allowNativeHeapPointerTagging="false" ... />
Xây dựng dự án của bạn.
Tải lên thông tin biểu tượng của bạn.
Sau khi quá trình xây dựng của bạn hoàn tất, hãy tạo tệp biểu tượng tương thích với Crashlytics và tải tệp đó lên máy chủ Firebase bằng cách chạy lệnh Firebase CLI sau:
firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/SYMBOLS
FIREBASE_APP_ID : ID ứng dụng Android Firebase của bạn (không phải tên gói của bạn)
Ví dụ ID ứng dụng Android Firebase:1:567383003300:android:17104a2ced0c9b9b
Dưới đây là hai cách để tìm ID ứng dụng Firebase của bạn:
Trong tệp
google-services.json
, ID ứng dụng của bạn là giá trịmobilesdk_app_id
; hoặcTrong bảng điều khiển Firebase, hãy đi tới cài đặt Dự án của bạn. Cuộn xuống thẻ Ứng dụng của bạn , sau đó nhấp vào Ứng dụng Firebase mong muốn để tìm ID ứng dụng của nó.
PATH/TO/SYMBOLS : Đường dẫn đến tệp ký hiệu do CLI tạo
Đã xuất sang dự án Android Studio - PATH/TO/SYMBOLS có thể là bất kỳ thư mục nào. Firebase CLI sẽ tìm kiếm đệ quy thư mục được chỉ định cho các thư viện gốc có phần mở rộng
.so
.Xây dựng APK trực tiếp từ bên trong Unity - PATH/TO/SYMBOLS là đường dẫn của tệp biểu tượng nén được tạo trong thư mục gốc của dự án khi quá trình xây dựng của bạn hoàn tất (ví dụ:
myproject/myapp-1.0-v100.symbols.zip
).
Xem các tùy chọn nâng cao để sử dụng lệnh Firebase CLI để tạo và tải lên tệp biểu tượng
Lá cờ Sự miêu tả --generator=csym
Sử dụng trình tạo tệp biểu tượng cSYM cũ thay vì trình tạo Breakpad mặc định
Không nên sử dụng. Chúng tôi khuyên bạn nên sử dụng trình tạo tệp biểu tượng Breakpad mặc định.
--generator=breakpad
Sử dụng trình tạo tệp biểu tượng Breakpad
Lưu ý rằng mặc định cho việc tạo tệp biểu tượng là Breakpad. Chỉ sử dụng cờ này nếu bạn đã thêm
symbolGenerator { csym() }
trong cấu hình bản dựng của mình và bạn muốn ghi đè nó để sử dụng Breakpad thay thế.--dry-run
Tạo các tệp biểu tượng nhưng không tải chúng lên
Cờ này hữu ích nếu bạn muốn kiểm tra nội dung của các tệp được gửi.
--debug
Cung cấp thêm thông tin gỡ lỗi Cuối cùng, buộc chạy thử nghiệm sự cố để hoàn tất quá trình thiết lập Crashlytics và xem dữ liệu ban đầu trong trang tổng quan Crashlytics của bảng điều khiển Firebase.
Sau khi bạn xây dựng ứng dụng của mình như một phần của việc khắc phục sự cố, hãy đảm bảo chạy lệnh Firebase CLI
crashlytics:symbols:upload
để tải lên tệp biểu tượng của bạn.