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 drobnych aktualizacji w konfiguracji kompilacji aplikacji.

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

Jeśli zastanawiasz się, jak zacząć korzystać z Crashlytics w swoich projektach w Unity, zapoznaj się z przewodnikiem dla początkujących na temat Unity.

Zanim zaczniesz

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

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

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

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

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

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

Krok 1. Dodaj do aplikacji pakiet SDK Crashlytics dla NDK

W pliku Gradle (na poziomie aplikacji) modułu (na poziomie aplikacji) (zwykle <project>/<app-module>/build.gradle.kts lub <project>/<app-module>/build.gradle) dodaj zależność z biblioteką Crashlytics NDK na Androida. Do kontrolowania obsługi wersji biblioteki zalecamy używanie funkcji Firebase Android BoM.

Aby zapewnić optymalne działanie Crashlytics, zalecamy włączenie Google Analytics w projekcie Firebase i dodanie do aplikacji pakietu SDK Firebase dla Google Analytics. 

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.1.1"))

    // 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 użyciu BoM Firebase Android BoM Twoja aplikacja zawsze używa zgodnych wersji bibliotek Firebase na Androida.

(Alternatywnie) Dodawanie zależności bibliotek Firebase bez korzystania z BM

Jeśli nie chcesz używać Firebase BoM, musisz określić każdą wersję biblioteki Firebase w wierszu zależności.

Pamiętaj, że jeśli w swojej aplikacji używasz wielu bibliotek Firebase, zdecydowanie zalecamy korzystanie z BoM do zarządzania wersjami bibliotek. Dzięki temu będziesz mieć pewność, że wszystkie wersje są zgodne. 

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.2")
    implementation("com.google.firebase:firebase-analytics:22.0.2")
}
Szukasz modułu biblioteki korzystającego z usługi Kotlin? Od października 2023 r. (Firebase BoM 32.5.0) zarówno deweloperzy aplikacji Kotlin, jak i języki Java mogą korzystać z modułu biblioteki głównej (więcej informacji znajdziesz w odpowiedziach na najczęstsze pytania o tę inicjatywę).

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ę Crashytics Gradle 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.2" apply false

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

  2. Do 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.

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

Krok 4. Skonfiguruj automatyczne przesyłanie symboli natywnych

Aby wygenerować czytelne zrzuty stosu z awarii NDK, Crashlytics musi znać symbole w Twoich natywnych plikach binarnych. Wtyczka Crashlytics do Gradle zawiera zadanie uploadCrashlyticsSymbolFileBUILD_VARIANT, które automatyzuje ten proces.

  1. Aby mieć dostęp do zadania automatycznego przesyłania symboli, upewnij się, że nativeSymbolUploadEnabled ma wartość true w pliku Gradle modułu (na poziomie aplikacji).

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

    >./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

  3. Zarówno pakiet SDK Crashlytics dla NDK, jak i wtyczka Crashlytics Gradle, zależą od obecności identyfikatora kompilacji GNU w natywnych udostępnionych obiektach.

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

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

Aby zakończyć konfigurowanie Crashlytics i zobaczyć początkowe dane w panelu Crashlytics w konsoli Firebase, musisz wymusić awarię testową.

  1. Dodaj do aplikacji kod, który pozwala wymusić awarię testową.

    Aby dodać do aplikacji przycisk, który po naciśnięciu powoduje awarię, możesz użyć podanego niżej kodu w MainActivity aplikacji. Jest on oznaczony etykietą „Testuj awarię”.

    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. Utworzyć i uruchomić aplikację.

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

    1. Otwórz aplikację na urządzeniu testowym lub w emulatorze.

    2. W aplikacji naciśnij przycisk „Test Crash” dodany za pomocą powyższego kodu.

    3. Po awarii aplikacji uruchom ją ponownie, aby mogła przesłać raport o awarii do Firebase.

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

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


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

Dalsze kroki

  • (Zalecane) Zbierając raporty GWP-ASan, możesz uzyskać pomoc w debugowaniu 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, upewnij się, że Twoja aplikacja ma wyraźnie włączone GWP-ASan i korzysta z najnowszego pakietu SDK Crashlytics dla NDK (wersji 18.3.6 lub nowszej albo Firebase BoM w wersji 31.3.0 lub nowszej).

  • Dostosuj konfigurację raportów o awariach, dodając raporty o awariach, 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 lepiej skupić się na konkretnych kompilacjach w panelu.

Rozwiązywanie problemów

Jeśli widzisz różne zrzuty stosu w konsoli Firebase i w narzędziu LogCat, zapoznaj się z przewodnikiem dotyczącym 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. innego procesu kompilacji niż Gradle). W takiej sytuacji poniższe rozwiązania mogą pomóc w poprawnym przesyłaniu symboli.

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

Ta opcja może być przydatna, gdy:

  • Jeśli używasz niestandardowego procesu kompilacji NDK w Gradle
  • Jeśli Twoje biblioteki natywne są utworzone w module biblioteki/funkcji lub dostarczone przez inną firmę
  • Jeśli zadanie automatycznego przesyłania symboli kończy się niepowodzeniem lub widzisz niesymboliczne awarie w panelu

Opcja: prześlij symbole dla kompilacji innych niż Gradle lub niedostępnych nieuproszczonych bibliotek natywnych

Ta opcja może być przydatna, gdy:

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

  • Jeśli Twoje niepozorne biblioteki natywne zostały udostępnione w taki sposób, że nie są one dostępne podczas kompilacji Gradle