Начало работы с Crashlytics для Android NDK

Выберите платформу: iOS+ Android Android NDK Flutter Unity


Если в вашем приложении для Android используются нативные библиотеки, вы можете включить полные трассировки стека и подробные отчеты о сбоях для нативного кода в Firebase Crashlytics. Для этого нужно внести несколько небольших изменений в конфигурацию сборки приложения.

В этом руководстве рассказывается, как настроить отчеты о сбоях с помощью Firebase Crashlytics SDK для NDK.

Если вы хотите узнать, как начать работу с Crashlytics в проектах Unity, ознакомьтесь с руководством по началу работы с Unity.

Подготовка

  1. Если вы ещё этого не сделали, добавьте Firebase в проект Android. Если у вас нет приложения для Android, вы можете скачать пример приложения.

  2. Рекомендуется. Чтобы автоматически получать журналы навигации и понимать, какие действия пользователя привели к сбою, некритической ошибке или событию ANR, включите Google Analytics в проекте Firebase.

    • Если вы создаете новый проект Firebase, включите Google Analytics в процессе его создания.

    • Если вы используете имеющийся проект Firebase, в котором не включена Google Analytics, откройте Настройки > Интеграции на консоли Firebase и включите ее.

  3. Убедитесь, что в вашем приложении используются следующие минимальные версии:

    • Gradle 8.0
    • Плагин Android Gradle 8.1.0
    • Плагин Gradle для сервисов Google 4.4.1

Шаг 1. Добавьте в приложение Crashlytics SDK для NDK

В файле Gradle на уровне модуля (обычно <project>/<app-module>/build.gradle.kts или <project>/<app-module>/build.gradle) добавьте зависимость для библиотеки NDK Crashlytics для Android. Мы рекомендуем использовать Firebase Android BoM для управления версиями библиотеки.

Чтобы использовать Crashlytics с максимальной эффективностью, рекомендуем включить Google Analytics в проекте Firebase и добавить в приложение Firebase SDK для Google Аналитики. 

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

Благодаря Firebase Android BoM в вашем приложении всегда будут использоваться совместимые версии библиотек Firebase Android.

(Альтернативный вариант.) Добавьте зависимости библиотеки Firebase без использования BoM.

Если вы не используете Firebase BoM, вам нужно указать версию каждой библиотеки Firebase в строке зависимости.

Если в приложении используется несколько библиотек Firebase, мы настоятельно рекомендуем использовать BoM для управления версиями библиотек, чтобы обеспечить их совместимость. 

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

Шаг 2. Добавьте в приложение плагин Gradle Crashlytics

  1. В корневом (на уровне проекта) файле Gradle (<project>/build.gradle.kts или <project>/build.gradle) добавьте плагин Gradle Crashlytics в блок 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. В модуле (на уровне приложения) Gradle-файла (обычно <project>/<app-module>/build.gradle.kts или <project>/<app-module>/build.gradle) добавьте плагин 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'
}

Шаг 3. Добавьте расширение Crashlytics в сборку

В модульном файле Gradle на уровне приложения (обычно <project>/<app-module>/build.gradle.kts или <project>/<app-module>/build.gradle) настройте расширение 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
          }
      }
  }
}

Шаг 4. Настройте автоматическую загрузку нативных символов

Чтобы Crashlytics мог создавать понятные трассировки стека при сбоях NDK, ему нужны сведения о символах в ваших нативных двоичных файлах. Плагин Gradle Crashlyticsвключает задачу uploadCrashlyticsSymbolFileBUILD_VARIANT, которая автоматизирует этот процесс.

  1. Чтобы вы могли получить доступ к задаче для автоматической загрузки символов, убедитесь, что в файле Gradle на уровне модуля (приложения) для параметра nativeSymbolUploadEnabled задано значение true.

  2. Чтобы имена методов появлялись в трассировках стека, после каждой сборки библиотеки NDK необходимо явно вызывать задачу uploadCrashlyticsSymbolFileBUILD_VARIANT. Пример:

    >./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

  3. Как Crashlytics SDK для NDK, так и плагин Gradle Crashlytics зависят от наличия идентификатора сборки GNU в общих объектах.

    Чтобы проверить наличие этого идентификатора, запустите команду readelf -n для каждого двоичного файла. Если идентификатор сборки отсутствует, добавьте -Wl,--build-id в флаги системы сборки, чтобы устранить проблему.

Шаг 5. Завершите настройку, вызвав сбой приложения

Чтобы завершить настройку Crashlytics и посмотреть первые данные на панели управления Crashlytics в консоли Firebase, необходимо принудительно вызвать тестовый сбой.

  1. Добавьте в приложение код, который можно использовать для принудительного создания тестового сбоя.

    Вы можете использовать следующий код в файле MainActivity вашего приложения, чтобы добавить кнопку, при нажатии на которую происходит сбой. Кнопка называется "Тестовый сбой".

    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. Создайте сборку и запустите приложение.

  3. Чтобы принудительно вызвать сбой и отправить первый отчет о нем, выполните следующие действия:

    1. Откройте приложение на тестовом устройстве или эмуляторе.

    2. В приложении нажмите кнопку "Test Crash" (Тестовый сбой), которую вы добавили с помощью кода выше.

    3. После сбоя перезапустите приложение, чтобы оно могло отправить отчет о сбое в Firebase.

  4. В консоли Firebase перейдите на панель DevOps & Engagement > Crashlytics, чтобы проверить отчет о сбое при тестировании.

    Если вы обновили консоль, но тестовое падение не появилось в течение пяти минут, включите ведение журнала отладки, чтобы проверить, отправляет ли ваше приложение отчеты о падениях.


Вот и все! Crashlytics теперь отслеживает сбои в вашем приложении. Вы можете просматривать отчеты о сбоях и статистику на панели управления Crashlytics.

Дальнейшие действия

  • Рекомендуется. Получайте помощь в отладке сбоев, вызванных ошибками нативной памяти, с помощью отчетов GWP-ASan. Эти ошибки памяти могут быть связаны с повреждением памяти в приложении, которое является основной причиной уязвимостей в системе безопасности. Чтобы использовать эту функцию отладки, убедитесь, что в вашем приложении явно включен GWP-ASan и используется последняя версия Crashlytics SDK для NDK (18.3.6 или более поздняя или Firebase BoM 31.3.0 или более поздняя).

  • Настройте отчеты о сбоях, добавив отчеты с запросом согласия, журналы, ключи и отслеживание некритических ошибок.

  • Интегрируйте Google Play, чтобы фильтровать отчеты о сбоях приложения для Android по Google Play и отслеживать их прямо на панели управления Crashlytics. Это позволяет лучше сосредоточиться на определенных сборках.

Устранение неполадок

Если в консоли Firebase и в logcat отображаются разные трассировки стека, ознакомьтесь с руководством по устранению неполадок.


Другие способы загрузки символов

Основной рабочий процесс, описанный выше на этой странице, применим к стандартным сборкам Gradle. Однако некоторые приложения используют другую конфигурацию или инструменты (например, процесс сборки, отличный от Gradle). В таких случаях вам могут помочь следующие варианты:

Вариант. Загрузите символы для модулей библиотеки и внешних зависимостей.

Этот вариант может быть полезен в следующих ситуациях:

  • Если вы используете в Gradle настраиваемый процесс сборки NDK
  • Если ваши библиотеки созданы в модуле библиотеки или функции или предоставлены сторонним поставщиком
  • Если автоматическая загрузка символов не работает или на панели управления Crashlytics отображаются необработанные сбои

Вариант. Загрузите файлы символов для сборок, не использующих Gradle, или недоступных нативных библиотек без удаления символов.

Этот вариант может быть полезен в следующих ситуациях:

  • Если вы используете другой процесс сборки, а не Gradle

  • Если вы получаете нативные библиотеки без удаления символов таким образом, что они недоступны во время сборки Gradle,