Jeśli Twoja aplikacja na Androida zawiera biblioteki natywne , możesz włączyć pełne śledzenie stosu i szczegółowe raporty o awariach dla swojego kodu natywnego z Firebase Crashlytics, wprowadzając kilka drobnych zmian w konfiguracji kompilacji aplikacji.
W tym przewodniku opisano, jak skonfigurować raportowanie awarii za pomocą pakietu SDK Firebase Crashlytics dla NDK.
Jeśli szukasz informacji o tym, jak zacząć korzystać z Crashlytics w projektach Unity, zapoznaj się z przewodnikiem Unity Pierwsze kroki .
Zanim zaczniesz
Jeśli jeszcze tego nie zrobiłeś, dodaj Firebase do swojego projektu na Androida. Jeśli nie masz aplikacji na Androida, możesz pobrać przykładową aplikację .
Zalecane : aby korzystać z takich funkcji, jak użytkownicy bez awarii, dzienniki nawigacyjne i alerty dotyczące prędkości, musisz włączyć Google Analytics w swoim projekcie Firebase.
Jeśli Twój istniejący projekt Firebase nie ma włączonego Google Analytics, możesz włączyć Google Analytics na karcie Integracje w > Ustawienia projektu w konsoli Firebase.
Jeśli tworzysz nowy projekt Firebase, włącz Google Analytics podczas procesu tworzenia projektu.
Krok 1 : Dodaj zestaw Crashlytics SDK dla NDK do swojej aplikacji
W pliku Gradle modułu (na poziomie aplikacji) (zwykle<project>/<app-module>/build.gradle
) dodaj zależność dla biblioteki Crashlytics NDK Android. Zalecamy używanie Firebase Android BoM do kontrolowania wersji bibliotek.Aby optymalnie korzystać z Crashlytics, zalecamy włączenie Google Analytics w projekcie Firebase i dodanie pakietu Firebase SDK dla Google Analytics do swojej aplikacji.
Kotlin+KTX
dependencies { // Import the BoM for the Firebase platform implementation platform('com.google.firebase:firebase-bom:32.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-ktx' }
Korzystając z Firebase Android BoM , Twoja aplikacja będzie zawsze korzystać ze zgodnych wersji bibliotek Firebase Android.
(Alternatywnie) Dodaj zależności biblioteki Firebase bez korzystania z BoM
Jeśli zdecydujesz się nie używać BoM Firebase, musisz określić każdą wersję biblioteki Firebase w jej wierszu zależności.
Pamiętaj, że jeśli używasz w swojej aplikacji wielu bibliotek Firebase, zdecydowanie zalecamy korzystanie z BoM do zarządzania wersjami bibliotek, co zapewnia zgodność wszystkich wersji.
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.3.7' implementation 'com.google.firebase:firebase-analytics-ktx:21.3.0' }
Java
dependencies { // Import the BoM for the Firebase platform implementation platform('com.google.firebase:firebase-bom:32.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' }
Korzystając z Firebase Android BoM , Twoja aplikacja będzie zawsze korzystać ze zgodnych wersji bibliotek Firebase Android.
(Alternatywnie) Dodaj zależności biblioteki Firebase bez korzystania z BoM
Jeśli zdecydujesz się nie używać BoM Firebase, musisz określić każdą wersję biblioteki Firebase w jej wierszu zależności.
Pamiętaj, że jeśli używasz w swojej aplikacji wielu bibliotek Firebase, zdecydowanie zalecamy korzystanie z BoM do zarządzania wersjami bibliotek, co zapewnia zgodność wszystkich wersji.
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.3.7' implementation 'com.google.firebase:firebase-analytics:21.3.0' }
Krok 2 : Dodaj wtyczkę Crashlytics Gradle do swojej aplikacji
W pliku Gradle na poziomie głównym (na poziomie projektu) (
<project>/build.gradle
) dodaj wtyczkę Crashlytics Gradle jako zależność buildscript:buildscript { repositories { // Make sure that you have the following two repositories google() // Google's Maven repository mavenCentral() // Maven Central repository } dependencies { ... classpath 'com.android.tools.build:gradle:7.2.0' // Make sure that you have the Google services Gradle plugin dependency classpath 'com.google.gms:google-services:4.3.15' // Add the dependency for the Crashlytics Gradle plugin classpath 'com.google.firebase:firebase-crashlytics-gradle:2.9.5' } }
W pliku Gradle modułu (na poziomie aplikacji) (zwykle
<project>/<app-module>/build.gradle
) dodaj wtyczkę Crashlytics Gradle: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' ... }
Krok 3 : Dodaj rozszerzenie firebaseCrashlytics
do swojej kompilacji
W pliku Gradle modułu (na poziomie aplikacji) (zazwyczaj app/build.gradle
) dodaj rozszerzenie firebaseCrashlytics
.
Kotlin+KTX
// ... 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 } } } }
Java
// ... 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 } } } }
Krok 4 : Skonfiguruj automatyczne przesyłanie symboli natywnych
Aby wygenerować czytelne ślady stosu z awarii NDK, Crashlytics musi wiedzieć o symbolach w twoich natywnych plikach binarnych. Wtyczka Crashlytics Gradle zawiera zadanie uploadCrashlyticsSymbolFile BUILD_VARIANT
do automatyzacji tego procesu.
Aby uzyskać dostęp do zadania automatycznego przesyłania symboli, upewnij się, że
nativeSymbolUploadEnabled
ma wartośćtrue
w pliku Gradle modułu (na poziomie aplikacji).Aby nazwy metod pojawiały się w śladach stosu, musisz jawnie wywołać zadanie
uploadCrashlyticsSymbolFile BUILD_VARIANT
po każdej kompilacji biblioteki NDK. Na przykład:>./gradlew app:assembleBUILD_VARIANT\ app:uploadCrashlyticsSymbolFileBUILD_VARIANT
Zarówno Crashlytics SDK dla NDK, jak i wtyczka Crashlytics Gradle zależą od obecności identyfikatora kompilacji GNU w natywnych obiektach współdzielonych.
Możesz zweryfikować obecność tego identyfikatora, uruchamiając
readelf -n
na każdym pliku binarnym. Jeśli identyfikator kompilacji jest nieobecny, dodaj-Wl,--build-id
do flag systemu kompilacji, aby rozwiązać problem.
Krok 5 : Wymuś awarię testową, aby zakończyć konfigurację
Aby dokończyć konfigurację Crashlytics i zobaczyć wstępne dane w panelu Crashlytics w konsoli Firebase, musisz wymusić awarię testową.
Dodaj do aplikacji kod, którego możesz użyć do wymuszenia awarii testowej.
Możesz użyć następującego kodu w
MainActivity
swojej aplikacji, aby dodać do aplikacji przycisk, który po naciśnięciu powoduje awarię. Przycisk jest oznaczony jako „Test Crash”.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));
Twórz i uruchamiaj swoją aplikację.
Wymuś awarię testową, aby wysłać pierwszy raport o awarii aplikacji:
Otwórz aplikację z urządzenia testowego lub emulatora.
W aplikacji naciśnij przycisk „Testuj awarię” dodany za pomocą powyższego kodu.
Po awarii aplikacji uruchom ją ponownie, aby aplikacja mogła wysłać raport o awarii do Firebase.
Przejdź do pulpitu nawigacyjnego Crashlytics w konsoli Firebase, aby zobaczyć testową awarię.
Jeśli po odświeżeniu konsoli nadal nie widzisz testowej awarii po pięciu minutach, włącz rejestrowanie debugowania , aby sprawdzić, czy aplikacja wysyła raporty o awariach.
I to wszystko! Crashlytics monitoruje teraz Twoją aplikację pod kątem awarii. Możesz przeglądać i badać raporty o awariach oraz statystyki w panelu Crashlytics.
Następne kroki
(Zalecane) Uzyskaj pomoc w debugowaniu awarii spowodowanych błędami pamięci natywnej, zbierając raporty GWP-ASan . Te błędy związane z pamięcią mogą być związane z uszkodzeniem pamięci w Twojej aplikacji, co jest główną przyczyną luk w zabezpieczeniach aplikacji. Aby skorzystać z tej funkcji, upewnij się, że Twoja aplikacja ma włączoną GWP-ASan i używa najnowszego pakietu Crashlytics SDK dla NDK (wersja 18.3.6+ lub Firebase BoM v31.3.0+).
Dostosuj konfigurację raportów o awariach , dodając raporty zgody, dzienniki, klucze i śledzenie błędów niekrytycznych.
Zintegruj się z Google Play , aby móc filtrować raporty o awariach aplikacji na Androida według ścieżki Google Play bezpośrednio w panelu Crashlytics. Pozwala to lepiej skoncentrować pulpit nawigacyjny na określonych kompilacjach.
Rozwiązywanie problemów
Jeśli widzisz różne ślady stosu w konsoli Firebase i w logcat, zapoznaj się z przewodnikiem rozwiązywania problemów .
Alternatywne opcje przesyłania symboli
Główny przepływ pracy na tej stronie powyżej ma zastosowanie do standardowych kompilacji Gradle. Jednak niektóre aplikacje używają innej konfiguracji lub narzędzi (na przykład procesu kompilacji innego niż Gradle). W takich sytuacjach poniższe opcje mogą być pomocne w pomyślnym przesłaniu symboli.
Opcja : Prześlij symbole modułów bibliotecznych i zewnętrznych zależności
Ta opcja może być pomocna w następujących sytuacjach:
- Jeśli używasz dostosowanego procesu kompilacji NDK w Gradle
- Jeśli Twoje biblioteki natywne są wbudowane w moduł biblioteki/funkcji lub dostarczane przez firmę zewnętrzną
- Jeśli zadanie automatycznego przesyłania symboli kończy się niepowodzeniem lub na pulpicie nawigacyjnym pojawiają się niesymbolizowane awarie
Standardowe zadanie przesyłania symboli Crashlytics zakłada, że budujesz swoje biblioteki natywne w ramach kompilacji Gradle modułu aplikacji, używając standardowych narzędzi do kompilacji NDK, takich jak CMake.
Jeśli jednak korzystasz z dostosowanego procesu kompilacji NDK w Gradle lub Twoje biblioteki natywne są wbudowane w moduł biblioteki/funkcji lub dostarczane przez firmę zewnętrzną, może być konieczne jawne określenie ścieżki do nierozebranych bibliotek. Aby to osiągnąć, możesz dodać właściwość unstrippedNativeLibsDir
do rozszerzenia firebaseCrashlytics
w pliku build.gradle
.
Upewnij się, że wykonałeś następujące zadania początkowe z głównego przepływu pracy wcześniej na tej stronie:
Aby zadanie automatycznego przesyłania symboli mogło znaleźć informacje o symbolu, dodaj następujące elementy do pliku
build.gradle
modułu (na poziomie aplikacji):// ... android { // ... buildTypes { release { firebaseCrashlytics { nativeSymbolUploadEnabled true unstrippedNativeLibsDir file("PATH/TO/UNSTRIPPED/DIRECTORY") } } } }
Wtyczka Crashlytics będzie rekurencyjnie przeszukiwać określony katalog w poszukiwaniu bibliotek natywnych z rozszerzeniem
.so
. Następnie Crashlytics wyodrębnia symbole debugowania ze wszystkich takich bibliotek i przesyła je na serwery Firebase.Oto, co możesz określić we właściwości
unstrippedNativeLibsDir
:Dowolny argument dozwolony dla
org.gradle.api.Project#files(Object...)
, w tym:java.lang.String
,java.io.File
luborg.gradle.api.file.FileCollection
Wiele katalogów dla jednego smaku kompilacji, dostarczając instancję listy lub
FileCollection
Na koniec wymuś awarię testową , aby zakończyć konfigurowanie Crashlytics i zobaczyć początkowe dane w panelu Crashlytics w konsoli Firebase.
Opcja : Prześlij symbole dla kompilacji innych niż Gradle lub niedostępnych, nierozebranych bibliotek natywnych
Ta opcja może być pomocna w następujących sytuacjach:
Jeśli używasz procesu kompilacji innego niż Gradle
Jeśli twoje nierozebrane biblioteki natywne są ci dostarczane w jakiś sposób, nie są dostępne podczas kompilacji Gradle
Ta opcja wymaga uruchomienia polecenia Firebase CLI podczas tworzenia wersji wydania lub dowolnej kompilacji, dla której chcesz zobaczyć symboliczne ślady stosu w konsoli Firebase.
Upewnij się, że wykonałeś następujące zadania początkowe z głównego przepływu pracy wcześniej na tej stronie:
Pamiętaj, że dzięki tej opcji nie musisz dodawać rozszerzenia
firebaseCrashlytics
ani konfigurować automatycznego przesyłania symboli, ponieważ zamiast tego będziesz używać Firebase CLI (kolejne kroki poniżej) do generowania i przesyłania plików symboli.Skonfiguruj swoje środowisko i projekt do przesyłania symboli:
Postępuj zgodnie z instrukcjami, aby zainstalować Firebase CLI .
Jeśli interfejs CLI został już zainstalowany, zaktualizuj go do najnowszej wersji .
(tylko w przypadku aplikacji korzystających z interfejsu API systemu Android na poziomie 30 lub wyższym) Zaktualizuj szablon
AndroidManifest.xml
aplikacji, aby wyłączyć tagowanie wskaźnika:Zaznacz pole Ustawienia odtwarzacza Android > Ustawienia publikowania > Kompilacja > Niestandardowy manifest główny .
Otwórz szablon manifestu znajdujący się w
Assets/Plugins/Android/AndroidManifest.xml
.Dodaj następujący atrybut do tagu aplikacji:
<application android:allowNativeHeapPointerTagging="false" ... />
Zbuduj swój projekt.
Prześlij informacje o swoich symbolach.
Po zakończeniu kompilacji wygeneruj plik symboli zgodny z Crashlytics i prześlij go na serwery Firebase, uruchamiając następujące polecenie Firebase CLI:
firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/SYMBOLS
FIREBASE_APP_ID : Twój identyfikator aplikacji Firebase na Androida (nie nazwa pakietu)
Przykładowy identyfikator aplikacji Firebase na Androida:1:567383003300:android:17104a2ced0c9b9b
Oto dwa sposoby na znalezienie identyfikatora aplikacji Firebase:
W pliku
google-services.json
identyfikator aplikacji to wartośćmobilesdk_app_id
; LubW konsoli Firebase przejdź do ustawień projektu . Przewiń w dół do karty Twoje aplikacje , a następnie kliknij żądaną aplikację Firebase, aby znaleźć jej identyfikator aplikacji.
PATH/TO/SYMBOLS : Ścieżka do pliku symboli wygenerowanego przez CLI
Wyeksportowany do projektu Android Studio — PATH/TO/SYMBOLS może być dowolnym katalogiem. Firebase CLI będzie rekurencyjnie przeszukiwać określony katalog w poszukiwaniu bibliotek natywnych z rozszerzeniem
.so
.Skompiluj plik APK bezpośrednio z Unity — PATH/TO/SYMBOLS to ścieżka spakowanego pliku symboli wygenerowanego w katalogu głównym projektu po zakończeniu kompilacji (na przykład:
myproject/myapp-1.0-v100.symbols.zip
).
Wyświetl zaawansowane opcje używania polecenia Firebase CLI do generowania i przesyłania plików symboli
Flaga Opis --generator=csym
Używa starszego generatora plików symboli cSYM zamiast domyślnego generatora Breakpad
Nie zalecane do użytku. Zalecamy użycie domyślnego generatora plików symboli Breakpad.
--generator=breakpad
Używa generatora plików symboli Breakpad
Należy zauważyć, że domyślnym ustawieniem generowania plików symboli jest Breakpad. Używaj tej flagi tylko wtedy, gdy dodałeś
symbolGenerator { csym() }
w konfiguracji kompilacji i chcesz ją zastąpić, aby zamiast tego używać Breakpad.--dry-run
Generuje pliki symboli, ale ich nie przesyła
Ta flaga jest przydatna, jeśli chcesz sprawdzić zawartość wysyłanych plików.
--debug
Zawiera dodatkowe informacje debugowania Na koniec wymuś awarię testową , aby zakończyć konfigurowanie Crashlytics i zobaczyć początkowe dane w panelu Crashlytics w konsoli Firebase.
Po utworzeniu aplikacji w ramach wymuszania awarii pamiętaj o uruchomieniu polecenia Firebase CLI
crashlytics:symbols:upload
, aby przesłać plik symboli.