Начало работы с 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, вы можете включить его на странице Settings (Настройки) > Integrations (Интеграции) в консоли Firebase.

  3. Убедитесь, что у вас установлены минимально необходимые версии приложений:

    • Gradle 8.0
    • Плагин Android Gradle 8.1.0
    • Плагин Google Services Gradle 4.4.1

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

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

Благодаря 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:21.0.0")
    implementation("com.google.firebase:firebase-analytics:24.0.0")
}

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

  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. Настройте автоматическую загрузку нативных символов

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

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

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

    >./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

  3. Для работы SDK Crashlytics для NDK и плагина Crashlytics для Gradle требуется, чтобы в нативных общих объектах присутствовал идентификатор сборки 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 (DevOps и взаимодействие) > Crashlytics dashboard (Панель управления) и проверьте, появился ли тестовый отчет о сбое.

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


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

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

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

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

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

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

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


Альтернативные варианты загрузки символов

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

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

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

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

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

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

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

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