Pobieranie raportów o awariach NDK na Androidzie

Jeśli Twoja aplikacja na Androida zawiera biblioteki natywne, możesz włączyć pełne zrzuty stosu i szczegółowe raporty o awariach kodu natywnego z Firebase Crashlytics, wprowadzając kilka niewielkich zmian w konfiguracji kompilacji aplikacji.

Z tego przewodnika dowiesz się, jak skonfigurować raportowanie awarii za pomocą pakietu SDK Firebase Crashlytics SDK dla NDK.

Jeśli szukasz informacji o tym, jak zacząć korzystać z Crashlytics w projektach na Unity, zajrzyj do podręcznika Unity dla początkujących.

Zanim zaczniesz

1. Dodaj Firebase do swojego projektu na Androida, jeśli jeszcze go nie masz. Jeśli nie masz aplikacji na Androida, możesz pobrać przykładową aplikację.

2. Zalecane: aby automatycznie pobierać dzienniki menu nawigacyjnego, które pozwalają analizować działania użytkowników, które prowadzą do awarii, błędów niekrytycznych lub błędów ANR, musisz włączyć Google Analytics w swoim projekcie Firebase.

   • Jeśli w istniejącym projekcie Firebase nie masz włączonej usługi Google Analytics, możesz włączyć Google Analytics na karcie Integracje w konsoli Firebase na stronie settings > Ustawienia projektu.

   • Jeśli tworzysz nowy projekt Firebase, włącz Google Analytics w trakcie procesu tworzenia projektu.

3. Upewnij się, że aplikacja ma minimalną wymaganą wersję:

   • Gradle 8.0
   • Wtyczka Androida do obsługi Gradle 8.1.0
   • Wtyczka usług Google do Gradle 4.4.1

Krok 1. Dodaj do aplikacji pakiet SDK Crashlytics dla NDK

Aby zapewnić optymalne działanie Crashlytics, włącz Google Analytics w projekcie Firebase i dodaj do aplikacji pakiet SDK Firebase dla Google Analytics.

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.0.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")
}

Dzięki wykorzystaniu BM od Firebase Android Twoja aplikacja zawsze będzie używała zgodnych wersji bibliotek Firebase na Androida.

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

Krok 2. Dodaj do aplikacji wtyczkę Crashlytics Gradle

1. W pliku Gradle na poziomie głównym (na poziomie projektu) (<project>/build.gradle.kts lub <project>/build.gradle) dodaj wtyczkę Gradle Crashlytics do bloku 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.1" apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id("com.google.firebase.crashlytics") version "3.0.0" 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.1' apply false
   
       // Add the dependency for the Crashlytics Gradle plugin
       id 'com.google.firebase.crashlytics' version '3.0.0' apply false
   }
   

2. W pliku Gradle modułu (na poziomie aplikacji) (zwykle <project>/<app-module>/build.gradle.kts lub <project>/<app-module>/build.gradle) dodaj wtyczkę 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'
   }

Krok 3. Dodaj do kompilacji rozszerzenie Crashlytics

W pliku Gradle modułu (na poziomie aplikacji) (zwykle <project>/<app-module>/build.gradle.kts lub <project>/<app-module>/build.gradle) skonfiguruj rozszerzenie 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
          }
      }
  }
}

Krok 4. Skonfiguruj automatyczne przesyłanie symboli natywnych

Aby generować czytelne zrzuty stosu z awarii NDK, Crashlytics musi znać symbole w natywnych plikach binarnych. Wtyczka Crashlytics Gradle zawiera zadanie uploadCrashlyticsSymbolFileBUILD_VARIANT automatyzujące ten proces.

1. Aby móc uzyskać dostęp do zadania automatycznego przesyłania symboli, upewnij się, że właściwość nativeSymbolUploadEnabled jest ustawiona na true w pliku Gradle modułu (na poziomie aplikacji).

2. Aby nazwy metod pojawiały się w zrzutach stosu, musisz jawnie wywołać zadanie uploadCrashlyticsSymbolFileBUILD_VARIANT po każdej kompilacji biblioteki NDK. Przykład:

   >./gradlew app:assembleBUILD_VARIANT\
              app:uploadCrashlyticsSymbolFileBUILD_VARIANT
   

3. Pakiet Crashlytics SDK dla NDK i wtyczka Crashlytics Gradle zależą od obecności identyfikatora kompilacji GNU w natywnych obiektach współdzielonych.

   Obecność tego identyfikatora możesz sprawdzić, uruchamiając readelf -n na każdym pliku binarnym. Jeśli nie ma identyfikatora kompilacji, dodaj -Wl,--build-id do flag systemu kompilacji, aby rozwiązać problem.

Krok 5. Wymuś awarię testową, aby dokończyć konfigurację

Aby dokończyć konfigurowanie Crashlytics i wyświetlić dane początkowe w panelu Crashlytics w konsoli Firebase, musisz wymusić awarię testową.

1. Dodaj do aplikacji kod, którego możesz użyć, aby wymusić awarię testową.

   Możesz użyć tego kodu w polu MainActivity aplikacji, aby dodać do niej przycisk, który po naciśnięciu powoduje awarię. Przycisk jest oznaczony etykietą „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));
   

2. Stwórz i uruchom aplikację.

3. Wymuś awarię testową, aby wysłać pierwszy raport o awarii aplikacji:

   1. Otwórz aplikację z urządzenia testowego lub emulatora.

   2. W aplikacji kliknij przycisk „Testuj awarię” dodany za pomocą powyższego kodu.

   3. Gdy aplikacja ulegnie awarii, uruchom ją ponownie, aby wysyłała raport o awariach do Firebase.

4. Otwórz panel Crashlytics w konsoli Firebase, aby zobaczyć awarię testową.

   Jeśli po odświeżeniu konsoli nadal nie widzisz awarii testowej, po 5 minutach włącz rejestrowanie debugowania, aby sprawdzić, czy Twoja aplikacja wysyła raporty o awariach.

To wszystko. Crashlytics monitoruje teraz Twoją aplikację pod kątem awarii. Raporty o awariach i statystyki możesz przeglądać w panelu Crashlytics.

Dalsze kroki

• (Zalecane) Zbieranie raportów GWP-ASan ułatwia debugowanie awarii spowodowanych przez błędy pamięci natywnej. Te błędy związane z pamięcią mogą być związane z uszkodzeniem pamięci w aplikacji, co jest główną przyczyną luk w zabezpieczeniach aplikacji. Aby skorzystać z tej funkcji debugowania, sprawdź, czy aplikacja ma jawnie włączoną funkcję GWP-ASan i korzysta z najnowszego pakietu SDK Crashlytics dla pakietu NDK (wersja 18.3.6 lub nowsza albo Firebase BoM w wersji 31.3.0 lub nowszej).

• Dostosuj konfigurację raportów o awariach, dodając raporty wymagające zgody, logi, klucze i śledzenie błędów niekrytycznych.

• Integracja z Google Play pozwala filtrować raporty o awariach aplikacji na Androida według ścieżki Google Play bezpośrednio w panelu Crashlytics. Dzięki temu możesz skoncentrować się w panelu na konkretnych kompilacjach.

Rozwiązywanie problemów

Jeśli widzisz różne zrzuty 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 dotyczy standardowych kompilacji Gradle. Niektóre aplikacje używają jednak innej konfiguracji lub narzędzi (np. procesu kompilacji innego niż Gradle). W takich sytuacjach pomocne mogą się okazać poniższe opcje.

Opcja: prześlij symbole dla modułów biblioteki i zależności zewnętrznych

Ta opcja może być pomocna w tych sytuacjach:

• Jeśli używasz niestandardowego procesu kompilacji NDK w Gradle
• Jeśli Twoje biblioteki natywne są wbudowane w moduł/bibliotekę/funkcje lub udostępniane przez inną firmę
• Jeśli nie udaje się wykonać zadania automatycznego przesyłania symboli lub w panelu pojawiają się niesymbolizowane awarie

Opcja: prześlij symbole w przypadku kompilacji innych niż Gradle lub niedostępnych nieprzetworzonych bibliotek natywnych.

Ta opcja może być pomocna w tych sytuacjach:

• Jeśli używasz procesu kompilacji innego niż Gradle

• Jeśli Twoje niestrudzone biblioteki natywne zostały Ci udostępnione w taki sposób, nie będą dostępne podczas kompilacji Gradle