了解 2023 年 Google I/O 大会上介绍的 Firebase 亮点。了解详情

Получайте отчеты о сбоях Android NDK

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

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

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

Прежде чем вы начнете

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

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

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

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

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

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

Для оптимальной работы с Crashlytics мы рекомендуем включить Google Analytics в вашем проекте Firebase и добавить Firebase SDK для Google Analytics в ваше приложение.

Kotlin+KTX

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

Используя 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:18.3.7'
    implementation 'com.google.firebase:firebase-analytics-ktx:21.3.0'
}

Java

dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:32.1.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:18.3.7'
    implementation 'com.google.firebase:firebase-analytics:21.3.0'
}

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

  1. В файле Gradle корневого уровня (уровня проекта) ( <project>/build.gradle ) добавьте подключаемый модуль Crashlytics Gradle в качестве зависимости buildscript:

    buildscript {
    repositories {
      // Make sure that you have the following two repositories
      google()  // Google's Maven repository
      mavenCentral()  // Maven Central repository
    }

    dependencies {
        ...
        classpath 'com.android.tools.build:gradle:7.2.0'

        // Make sure that you have the Google services Gradle plugin dependency
        classpath 'com.google.gms:google-services:4.3.15'

        // Add the dependency for the Crashlytics Gradle plugin
        classpath 'com.google.firebase:firebase-crashlytics-gradle:2.9.5'
    }
}

  2. В файле Gradle вашего модуля (уровня приложения) (обычно <project>/<app-module>/build.gradle ) добавьте подключаемый модуль Crashlytics Gradle:

    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. Добавьте расширение firebaseCrashlytics в свою сборку.

В файл Gradle модуля (уровня приложения) (обычно app/build.gradle ) добавьте расширение firebaseCrashlytics .

Kotlin+KTX

// ...

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

Java

// ...

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 необходимо знать о символах в ваших собственных двоичных файлах. Плагин Crashlytics Gradle включает задачу uploadCrashlyticsSymbolFile BUILD_VARIANT для автоматизации этого процесса.

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

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

    >./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

  3. И Crashlytics SDK для NDK, и подключаемый модуль Crashlytics Gradle зависят от наличия идентификатора сборки GNU в собственных общих объектах.

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

Шаг 5. Принудительно завершите настройку с помощью тестового сбоя.

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

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

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

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

  3. Принудительно выполните тестовый сбой, чтобы отправить первый отчет о сбое вашего приложения:

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

    2. В своем приложении нажмите кнопку «Проверить сбой», которую вы добавили с помощью приведенного выше кода.

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

  4. Перейдите на панель инструментов Crashlytics консоли Firebase, чтобы увидеть сбой вашего теста.

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


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

Следующие шаги

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

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

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

Поиск неисправностей

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


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

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

Опция : загрузить символы для библиотечных модулей и внешних зависимостей.

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

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

Опция : загрузка символов для сборок, отличных от Gradle, или недоступных необработанных нативных библиотек.

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

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

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