Начните работу с Crashlytics для Unity

В этом руководстве описано, как начать работу с Firebase Crashlytics в вашем проекте Unity.

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

Для настройки Crashlytics необходимо выполнить действия как в консоли Firebase , так и в вашей IDE (например, добавить файл конфигурации Firebase и SDK Crashlytics ). Для завершения настройки вам потребуется принудительно вызвать сбой теста, чтобы отправить первый отчет о сбое в Firebase.

Прежде чем начать

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

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

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

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

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

Обратите внимание, что при регистрации вашего проекта Unity в проекте Firebase вы, возможно, уже загрузили SDK Firebase Unity и добавили пакеты, описанные в следующих шагах.

1. Загрузите Firebase Unity SDK , затем распакуйте архив в удобное для вас место. Firebase Unity SDK не привязан к конкретной платформе.

2. В открытом проекте Unity перейдите в Assets > Import Package > Custom Package .

3. В распакованном SDK выберите импорт Crashlytics SDK ( FirebaseCrashlytics.unitypackage ).

   Чтобы использовать функцию "хлебные крошки" в логах, добавьте в приложение также Firebase SDK для Google Analytics ( FirebaseAnalytics.unitypackage ). Убедитесь, что Google Analytics включен в вашем проекте Firebase.

4. В окне «Импорт пакета Unity» нажмите «Импорт» .

Шаг 2 : Инициализация Crashlytics

1. Создайте новый скрипт на C#, а затем добавьте его к GameObject на сцене.

   1. Откройте первую сцену, затем создайте пустой GameObject с именем CrashlyticsInitializer .

   2. Для нового объекта нажмите кнопку «Добавить компонент» в инспекторе .

   3. Выберите свой скрипт Crashlytics Init , чтобы добавить его в объект CrashlyticsInitializer .

2. Инициализируйте Crashlytics в методе Start скрипта:

   using System.Collections;
   using System.Collections.Generic;
   using UnityEngine;
   
   // Import Firebase and Crashlytics
   using Firebase;
   using Firebase.Crashlytics;
   
   public class CrashlyticsInit : MonoBehaviour {
       // Use this for initialization
       void Start () {
           // Initialize Firebase
           Firebase.FirebaseApp.CheckAndFixDependenciesAsync().ContinueWith(task => {
               var dependencyStatus = task.Result;
               if (dependencyStatus == Firebase.DependencyStatus.Available)
               {
                   // Create and hold a reference to your FirebaseApp,
                   // where app is a Firebase.FirebaseApp property of your application class.
                   // Crashlytics will use the DefaultInstance, as well;
                   // this ensures that Crashlytics is initialized.
                   Firebase.FirebaseApp app = Firebase.FirebaseApp.DefaultInstance;
   
                   // When this property is set to true, Crashlytics will report all
                   // uncaught exceptions as fatal events. This is the recommended behavior.
                   Crashlytics.ReportUncaughtExceptionsAsFatal = true;
   
                   // Set a flag here for indicating that your project is ready to use Firebase.
               }
               else
               {
                   UnityEngine.Debug.LogError(System.String.Format(
                     "Could not resolve all Firebase dependencies: {0}",dependencyStatus));
                   // Firebase Unity SDK is not safe to use here.
               }
           });
       }
   
     // Update is called once per frame
     void Update()
       // ...
   }

Шаг 3 : (Только для Android) Подготовка к загрузке символов

Этот шаг необходим только для приложений Android, использующих IL2CPP.

• Для приложений Android, использующих скриптовый бэкенд Mono от Unity, эти шаги не требуются.

• Для приложений на платформе Apple эти шаги не требуются, поскольку плагин Firebase Unity Editor автоматически настраивает ваш проект Xcode для загрузки символов.

Crashlytics для Unity SDK 8.6.1+ автоматически включается функция отслеживания сбоев NDK, что позволяет Crashlytics автоматически сообщать о сбоях Unity IL2CPP на Android. Однако для просмотра символизированных трассировок стека для сбоев нативных библиотек на панели мониторинга Crashlytics необходимо загрузить информацию о символах во время сборки с помощью Firebase CLI.

Для настройки загрузки символов следуйте инструкциям по установке Firebase CLI .

Если вы уже установили CLI, обязательно обновите его до последней версии .

Шаг 4 : Создайте свой проект и загрузите символы.

iOS+ (платформа Apple)

1. В диалоговом окне «Параметры сборки» экспортируйте свой проект в рабочую область Xcode.

2. Создайте своё приложение.

   Для платформ Apple плагин Firebase Unity Editor автоматически настраивает ваш проект Xcode для генерации и загрузки совместимого с Crashlytics файла символов на серверы Firebase для каждой сборки.

Android

1. В диалоговом окне «Параметры сборки» выполните одно из следующих действий:

   • Экспортируйте проект в Android Studio для его сборки; или

   • Создавайте APK-файлы прямо в редакторе Unity.
     Перед сборкой убедитесь, что в диалоговом окне «Параметры сборки» установлен флажок «Создать symbols.zip» .

2. После завершения сборки сгенерируйте файл символов, совместимый с Crashlytics , и загрузите его на серверы Firebase, выполнив следующую команду Firebase CLI:

   firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/SYMBOLS

   • FIREBASE_APP_ID : Ваш идентификатор приложения Firebase для Android (а не имя пакета).
     Пример идентификатора Android-приложения Firebase: 1:567383003300:android:17104a2ced0c9b9b

     Нужно найти идентификатор вашего приложения Firebase?

     Вот два способа найти идентификатор вашего приложения Firebase:

     • В файле google-services.json идентификатор вашего приложения — это значение mobilesdk_app_id ; или

     • В консоли Firebase перейдите в настройки проекта . Прокрутите вниз до карточки «Ваши приложения» , затем щелкните нужное приложение Firebase, чтобы найти его идентификатор приложения (App ID).

   • PATH/TO/SYMBOLS : Путь к файлу символов, сгенерированному интерфейсом командной строки.

     • Экспорт в проект Android Studio — PATH/TO/SYMBOLS — это каталог unityLibrary/symbols , который создается в корневом каталоге экспортированного проекта после сборки приложения через Gradle или Android Studio.

     • APK-файл был создан непосредственно в Unity — PATH/TO/SYMBOLS — это путь к заархивированному файлу символов, сгенерированному в корневом каталоге проекта после завершения сборки (например: myproject/myapp-1.0-v100.symbols.zip ).

   Ознакомьтесь с расширенными параметрами использования команды Firebase CLI для генерации и загрузки файлов символов.

   Флаг	Описание
   --generator=csym	Использует устаревший генератор файлов символов cSYM вместо генератора Breakpad по умолчанию. Использовать не рекомендуется. Рекомендуем использовать генератор символов Breakpad по умолчанию.
   --generator=breakpad	Использует генератор символов Breakpad. Обратите внимание, что по умолчанию для генерации файла символов используется Breakpad. Используйте этот флаг только в том случае, если вы добавили У вас в конфигурации сборки symbolGenerator { csym() } , и вы хотите переопределить его, чтобы использовать Breakpad вместо него.
   --dry-run	Генерирует файлы символов, но не загружает их. Этот флаг полезен, если вы хотите просмотреть содержимое отправляемых файлов.
   --debug	Предоставляет дополнительную отладочную информацию.

Шаг 5 : Принудительно вызовите сбой теста, чтобы завершить настройку.

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

1. Найдите существующий GameObject и добавьте к нему следующий скрипт. Этот скрипт вызовет сбой теста через несколько секунд после запуска вашего приложения.

   using System;
   using UnityEngine;
   
   public class CrashlyticsTester : MonoBehaviour {
   
       int updatesBeforeException;
   
       // Use this for initialization
       void Start () {
         updatesBeforeException = 0;
       }
   
       // Update is called once per frame
       void Update()
       {
           // Call the exception-throwing method here so that it's run
           // every frame update
           throwExceptionEvery60Updates();
       }
   
       // A method that tests your Crashlytics implementation by throwing an
       // exception every 60 frame updates. You should see reports in the
       // Firebase console a few minutes after running your app with this method.
       void throwExceptionEvery60Updates()
       {
           if (updatesBeforeException > 0)
           {
               updatesBeforeException--;
           }
           else
           {
               // Set the counter to 60 updates
               updatesBeforeException = 60;
   
               // Throw an exception to test your Crashlytics implementation
               throw new System.Exception("test exception please ignore");
           }
       }
   }

2. Соберите приложение и загрузите информацию о символах после завершения сборки.

   • iOS+ : Плагин Firebase Unity Editor автоматически настраивает ваш проект Xcode для загрузки файла символов.

   • Android : Для приложений Android, использующих IL2CPP, выполните команду Firebase CLI crashlytics:symbols:upload , чтобы загрузить файл символов.

3. Запустите приложение. После запуска приложения следите за логами устройства и дождитесь появления исключения от CrashlyticsTester .

   • iOS+ : Просмотр журналов в нижней панели Xcode.

   • Android : Чтобы просмотреть логи, выполните следующую команду в терминале: adb logcat .

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

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

Вот и всё! Crashlytics теперь отслеживает сбои в вашем приложении. Перейдите на панель управления Crashlytics , чтобы просмотреть и проанализировать все ваши отчеты и статистику.

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

• (Рекомендуется) Для приложений Android, использующих IL2CPP, получите помощь в отладке сбоев, вызванных ошибками нативной памяти, путем сбора отчетов GWP-ASan . Эти ошибки, связанные с памятью, могут быть связаны с повреждением памяти в вашем приложении, что является основной причиной уязвимостей безопасности приложений. Чтобы воспользоваться этой функцией отладки, убедитесь, что ваше приложение использует последнюю версию Crashlytics SDK для Unity (v10.7.0+) и явно включает GWP-ASan (требуется изменить файл Android App Manifest ).

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