Otrzymuj raporty o awariach Androida NDK

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

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

Jeśli chcesz dowiedzieć się, jak zacząć używać Crashlytics w swoich projektach 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ć próbną aplikację.

  2. Zalecane: aby automatycznie otrzymywać logi ścieżki, które pomogą Ci zrozumieć działania użytkowników prowadzące do awarii, niekrytycznych błędów lub zdarzeń ANR, musisz włączyć Google Analytics w projekcie Firebase.

    • Jeśli w istniejącym projekcie Firebase nie włączono Google Analytics, możesz włączyć Google Analytics 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 te minimalne wymagane wersje:

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

Krok 1. Dodaj do aplikacji pakiet SDK Crashlytics dla NDK

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

Aby zapewnić optymalne działanie usługi 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.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")
}

Dzięki użyciu Firebase Android BoMaplikacja zawsze będzie używać zgodnych wersji bibliotek Firebase na Androida.

(Alternatywnie)  Dodaj zależności biblioteki Firebase bez używania pakietu BoM

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

Jeśli w aplikacji używasz kilku bibliotek Firebase, zdecydowanie zalecamy korzystanie z BoM do zarządzania wersjami bibliotek. Dzięki temu wszystkie wersje będą ze sobą 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.2.1")
    implementation("com.google.firebase:firebase-analytics:22.1.2")
}
 Szukasz modułu biblioteki dla Kotlina? Od października 2023 r. (Firebase BoM 32.5.0) deweloperzy Kotlina i Java mogą korzystać z głównego modułu biblioteki (szczegółowe informacje znajdziesz w często zadawanych pytaniach dotyczących tej inicjatywy).

Krok 2. Dodaj do aplikacji wtyczkę Crashlytics Gradle

  1. W pliku Gradle na poziomie katalogu głównego (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.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. W pliku Gradle modułu (na poziomie aplikacji) (zwykle <project>/<app-module>/build.gradle.kts lub <project>/<app-module>/build.gradle) dodaj wtyczkę Gradle Crashlytics:

    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 generować czytelne ścieżki stosu z awarii NDK, Crashlytics musi znać symbole w natywnatnych plikach binarnych. Wtyczka do obsługi Gradle Crashlytics zawiera zadanie uploadCrashlyticsSymbolFileBUILD_VARIANT, które automatyzuje ten proces.

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

  2. Aby nazwy metod były widoczne w śladach stosu, musisz wyraźnie wywołać zadanie uploadCrashlyticsSymbolFileBUILD_VARIANT po każdym wygenerowaniu biblioteki NDK. Przykład:

    >./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

  3. Zarówno pakiet SDK Crashlytics dla NDK, jak i wtyczka Gradle Crashlytics zależą od obecności identyfikatora kompilacji GNU w natywnym obiekcie współdzielonym.

    Obecność tego identyfikatora możesz zweryfikować, uruchamiając readelf -n w przypadku każdego binarnego pliku. Jeśli identyfikator kompilacji jest nieobecny, dodaj flagi -Wl,--build-id do systemu kompilacji, aby rozwiązać problem.

Krok 5. Wymuś awarię testową, aby zakończyć konfigurowanie

Aby dokończyć konfigurowanie Crashlytics i zobaczyć pierwsze dane na panelu Crashlytics w konsoli Firebase, musisz wymusić testowy błąd krytyczny.

  1. Dodaj do aplikacji kod, który pozwoli Ci wymusić testowy błąd.

    Aby dodać do aplikacji przycisk, który po naciśnięciu powoduje awarię aplikacji, możesz użyć tego kodu w sekcji MainActivity. Przycisk ma etykietę „Testowy błąd”.

    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. Kompilowanie i uruchamianie aplikacji.

  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. Gdy aplikacja ulegnie awarii, uruchom ją ponownie, aby mogła wysłać raport o awarii do Firebase.

  4. Aby zobaczyć testowy błąd krytyczny, otwórz panel Crashlytics konsoli Firebase.

    Jeśli po 5 minutach od odświeżenia konsoli nadal nie widzisz testowego błędu, włącz debugowanie, aby sprawdzić, czy aplikacja wysyła raporty o błędach.


To wszystko. Crashlytics będzie teraz monitorować Twoją aplikację pod kątem awarii. Możesz wyświetlać raporty i statystyki dotyczące awarii oraz je 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 Crashlytics SDK dla NDK (wersja 18.3.6 lub nowsza albo Firebase BoM w wersji 31.3.0 lub nowszej).

  • Dostosuj konfigurację raportowania awarii, dodając opcję raportowania, dzienniki, klucze i śledzenie błędów niekrytycznych.

  • Integracja z Google Play, dzięki której możesz 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 w konsoli Firebase i w pliku logcat widzisz różne ścieżki wywołań, zapoznaj się z przewodnikiem po rozwiązywaniu problemów.


Alternatywne opcje przesyłania symboli

Główny proces na tej stronie powyżej dotyczy standardowych kompilacji Gradle. Niektóre aplikacje korzystają jednak z innej konfiguracji lub narzędzi (np. z procesu kompilacji innego niż Gradle). W takiej sytuacji poniższe rozwiązania mogą pomóc w poprawnym przesyłaniu symboli.

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

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

  • Jeśli w Gradle używasz niestandardowego procesu kompilacji NDK
  • Jeśli Twoje biblioteki natywne są utworzone w module biblioteki/funkcji lub dostarczone przez inną firmę
  • Jeśli automatyczne przesyłanie symboli nie działa lub na panelu widać niesymbolizowane awarie

Opcja: prześlij symbole dla wersji nieobejmujących Gradle lub niedostępnych nieobciętej biblioteki natywnej.

Ta opcja może być przydatna, gdy:

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

  • Jeśli nieobcięte biblioteki natywne są udostępniane w taki sposób, że nie są dostępne podczas kompilacji Gradle