Pierwsze kroki z Crashlytics dla Androida NDK

Wybierz platformę: iOS+ Android Android NDK Flutter Unity


Jeśli w aplikacji na Androida używasz bibliotek natywnych, 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ć zgłaszanie awarii za pomocą pakietu SDK Firebase Crashlytics dla NDK.

Jeśli chcesz dowiedzieć się, jak zacząć korzystać z Crashlytics w projektach Unity, zapoznaj się z przewodnikiem dla początkujących dotyczącym Unity.

Zanim zaczniesz

  1. Dodaj Firebase do projektu aplikacji na Androida, jeśli nie korzystasz w nim jeszcze z tej usługi. Jeśli nie masz aplikacji na Androida, możesz pobrać przykładową aplikację.

  2. Zalecane: aby automatycznie otrzymywać logi działań użytkownika, które pomogą Ci zrozumieć działania użytkownika prowadzące do awarii, błędu niekrytycznego lub błędu ANR, musisz włączyć Google Analytics w projekcie w Firebase.

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

    • Jeśli używasz dotychczasowego projektu w Firebase bez włączonej usługi Google Analytics, możesz ją włączyć na stronie Ustawienia > Integracje w konsoli Firebase.

  3. Upewnij się, że Twoja aplikacja ma te minimalne wymagane wersje:

    • Gradle 8.0
    • Wtyczka Androida do obsługi Gradle 8.1.0
    • Wtyczka Gradle usług Google w wersji 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ść dla biblioteki Crashlytics NDK na Androida. Zalecamy używanie Firebase Android BoM do kontrolowania obsługi wersji biblioteki.

Aby zapewnić optymalne działanie usługi Crashlytics, zalecamy włączenie Google Analytics w projekcie w 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:35.0.2"))

    // 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")
}

Gdy korzystasz z Firebase Android BoM, aplikacja zawsze używa zgodnych wersji bibliotek Firebase na Androida.

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

Jeśli nie zdecydujesz się na użycie 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, co zapewni 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:21.0.0")
    implementation("com.google.firebase:firebase-analytics:24.0.0")
}

Krok 2. Dodaj do aplikacji wtyczkę Crashlytics do Gradle

  1. W pliku Gradle na poziomie głównym (na poziomie projektu) (<project>/build.gradle.kts lub <project>/build.gradle) dodaj wtyczkę Crashlytics 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.5.0" apply false

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

    // Add the dependency for the Crashlytics Gradle plugin
    id 'com.google.firebase.crashlytics' version '3.0.8' 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 rozszerzenie Crashlytics do kompilacji

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 zrzuty stosu z awarii NDK, Crashlytics musi znać symbole w natywnych plikach binarnych. Wtyczka Gradle Crashlytics zawiera zadanie uploadCrashlyticsSymbolFileBUILD_VARIANT, które automatyzuje ten proces.

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

  2. Aby nazwy metod pojawiały się w zrzutach stosu, po każdej kompilacji biblioteki NDK musisz bezpośrednio 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 do Gradle zależą od obecności identyfikatora kompilacji GNU w natywnych obiektach współdzielonych.

    Możesz sprawdzić obecność tego identyfikatora, 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ś testową awarię, aby zakończyć konfigurację

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

  1. Dodaj do aplikacji kod, którego możesz użyć do wymuszenia testowej awarii.

    Możesz użyć tego kodu w pliku MainActivity aplikacji, aby dodać do niej przycisk, którego naciśnięcie spowoduje awarię. Przycisk ma etykietę „Test Crash”.

    Kotlin 

    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. Skompiluj i uruchom 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ą kodu powyżej.

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

  4. W konsoli Firebase otwórz panel DevOps i zaangażowanie > Crashlytics, aby sprawdzić, czy jest tam raport o awarii testowej.

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


To wszystko. Crashlytics monitoruje teraz Twoją aplikację pod kątem awarii. Możesz wyświetlać i analizować raporty o awariach oraz statystyki w panelu Crashlytics.

Dalsze 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ć powiązane z uszkodzeniem pamięci w aplikacji, co jest główną przyczyną luk w zabezpieczeniach aplikacji. Aby korzystać z tej funkcji debugowania, upewnij się, że Twoja aplikacja ma wyraźnie włączone GWP-ASan i używa najnowszego pakietu SDK Crashlytics dla NDK (w wersji 18.3.6 lub nowszej albo Firebase BoM w wersji 31.3.0 lub nowszej).

  • Dostosuj konfigurację raportów o awariach, dodając raportowanie po wyrażeniu zgody, dzienniki, klucze i śledzenie błędów niekrytycznych.

  • Zintegruj z Google Play, aby móc 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 logcat widzisz różne zrzuty stosu, zapoznaj się z przewodnikiem rozwiązywania problemów.


Alternatywne opcje przesyłania symboli

Główny przepływ pracy na tej stronie dotyczy standardowych kompilacji Gradle. Niektóre aplikacje używają jednak innej konfiguracji lub innych narzędzi (np. procesu kompilacji innego niż Gradle). W takich sytuacjach przydatne mogą być te opcje.

Opcja: przesyłanie symboli modułów biblioteki i zależności zewnętrznych

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

  • Jeśli używasz niestandardowego procesu kompilacji NDK w Gradle
  • Jeśli biblioteki natywne są tworzone w module biblioteki lub module funkcji albo dostarczane przez inną firmę,
  • Jeśli zadanie automatycznego przesyłania symboli nie działa lub w panelu Crashlytics widzisz awarie bez symboli,

Opcja: przesyłanie symboli w przypadku kompilacji innych niż Gradle lub niedostępnych nieodchudzonych bibliotek natywnych

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

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

  • Jeśli nieodchudzone biblioteki natywne są dostarczane w sposób, który uniemożliwia dostęp do nich podczas kompilacji Gradle,