Узнайте о сбоях в игре Unity с помощью расширенных функций Crashlytics. Узнайте о сбоях в игре Unity с помощью расширенных функций Crashlytics.

1. Введение

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

Вы добавите новые функции в игру MechaHamster: Level Up with Firebase Edition . Эта игра представляет собой новую версию классической игры MechaHamster для Firebase, в которой удалена большая часть встроенного функционала Firebase, что позволяет вам реализовать новые возможности Firebase.

Вы добавите в игру меню отладки. Оно вызывает созданные вами методы и позволяет использовать различные функции Crashlytics. Эти методы покажут вам, как добавлять в автоматические отчёты о сбоях пользовательские ключи, журналы, нефатальные ошибки и многое другое.

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

Чему вы научитесь

• Типы ошибок, которые автоматически выявляет Crashlytics.
• Дополнительные ошибки, которые можно целенаправленно зафиксировать.
• Как добавить больше информации к этим ошибкам, чтобы сделать их более понятными.

Что вам понадобится

• Unity (минимальная рекомендуемая версия 2019+) с одним или обоими из следующих:
  • Поддержка сборки iOS
  • Поддержка сборки Android
• (Только для Android) Firebase CLI (используется для загрузки символов для отчетов о сбоях)
  • Следуйте инструкциям по установке Firebase CLI .
    Если вы уже установили CLI, обязательно обновите его до последней версии .

2. Настройте среду разработки

В следующих разделах описывается, как загрузить код Level Up with Firebase и открыть его в Unity.

Обратите внимание, что этот пример игры Level Up with Firebase используется в нескольких других практическом занятиях по Firebase + Unity, поэтому вы, возможно, уже выполнили задания из этого раздела. Если да, то можете сразу перейти к последнему шагу на этой странице: «Добавление Firebase SDK для Unity».

Загрузите код

Клонируйте репозиторий GitHub этой кодовой лаборатории из командной строки:

git clone https://github.com/firebase/level-up-with-firebase.git

Кроме того, если у вас не установлен git, вы можете загрузить репозиторий в виде ZIP-файла .

Откройте Level Up с помощью Firebase в редакторе Unity

1. Запустите Unity Hub и на вкладке «Проекты» щелкните стрелку раскрывающегося списка рядом с кнопкой «Открыть» .
2. Нажмите Добавить проект с диска .
3. Перейдите в каталог, содержащий код, и нажмите кнопку OK .
4. При появлении запроса выберите версию редактора Unity и целевую платформу (Android или iOS).
5. Щелкните имя проекта, level-up-with-firebase , и проект откроется в редакторе Unity.
6. Если ваш редактор не открывает его автоматически, откройте MainGameScene в разделе Assets > Hamster на вкладке Project редактора Unity.
   

Дополнительную информацию об установке и использовании Unity см. в разделе Работа в Unity .

3. Добавьте Firebase в свой проект Unity

Создать проект Firebase

1. Войдите в консоль Firebase, используя свою учетную запись Google.
2. Нажмите кнопку, чтобы создать новый проект, а затем введите название проекта (например, Mechahamster Codelab ).
   

   Это имя проекта используется в качестве отображаемого имени в интерфейсах Firebase, и Firebase автоматически создаёт уникальный идентификатор проекта на его основе. Обратите внимание, что вы можете нажать значок «Изменить» сейчас, чтобы указать желаемый идентификатор проекта, но изменить этот идентификатор после создания проекта будет невозможно.

   Запомните идентификатор своего проекта, так как он понадобится вам позже для идентификации вашего проекта Firebase в Firebase CLI. Если вы забудете свой идентификатор, вы всегда сможете найти его позже в настройках проекта .

3. Нажмите «Продолжить» .
4. При появлении соответствующего запроса ознакомьтесь с условиями Firebase и примите их, а затем нажмите кнопку «Продолжить» .
5. (Необязательно) Включите помощь ИИ в консоли Firebase (так называемая «Gemini в Firebase»).
6. Для этой практической работы вам понадобится Google Analytics для оптимального использования продуктов Firebase, поэтому включите опцию Google Analytics. Следуйте инструкциям на экране, чтобы настроить Google Analytics.
7. Нажмите «Создать проект» , дождитесь завершения подготовки проекта, а затем нажмите «Продолжить» .

Зарегистрируйте свое приложение в Firebase

1. Оставаясь в консоли Firebase , в центре страницы обзора проекта щелкните значок Unity, чтобы запустить рабочий процесс настройки, или, если вы уже добавили приложение в свой проект Firebase, щелкните Добавить приложение , чтобы отобразить параметры платформы.
2. Выберите для регистрации цели сборки Apple (iOS) и Android.
3. Введите идентификатор(ы) платформы вашего проекта Unity. Для этой лабораторной работы введите следующее:
   • Для Apple (iOS) : введите com.google.firebase.level-up в поле идентификатора пакета iOS .
   • Для Android : введите com.google.firebase.level_up в поле имени пакета Android .

   Важно : идентификатор пакета iOS и имя пакета Android, указанные выше, различаются . Идентификатор iOS недействителен для Android и наоборот. Убедитесь, что вы используете правильный идентификатор.

4. (Необязательно) Введите псевдонимы, специфичные для платформы вашего проекта Unity.
5. Нажмите «Зарегистрировать приложение» , а затем перейдите к разделу «Загрузка файла конфигурации» .

Добавить файлы конфигурации Firebase

После нажатия кнопки «Зарегистрировать приложение» вам будет предложено загрузить два файла конфигурации (по одному для каждой целевой сборки). Для подключения к Firebase вашему проекту Unity потребуются метаданные Firebase из этих файлов.

1. Загрузите оба доступных файла конфигурации:
   • Для Apple (iOS) : загрузите GoogleService-Info.plist .
   • Для Android : загрузите google-services.json .
2. Откройте окно проекта Unity, затем переместите оба файла конфигурации в папку Assets .

   Важно: даже если вы планируете собирать только iOS или Android, вам следует загрузить оба файла и добавить их в свой проект.

3. Вернитесь в консоль Firebase, в рабочем процессе настройки нажмите кнопку Далее и перейдите к добавлению пакетов SDK Firebase для Unity.

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

Добавьте Firebase SDK для Unity

1. Нажмите «Загрузить Firebase Unity SDK» в консоли Firebase.

   Примечание: загрузка этого SDK может занять некоторое время. Заварите кофе или чай — пейте много воды, друзья.

2. Распакуйте SDK в удобное место.
3. В открытом проекте Unity перейдите в раздел Assets > Import Package > Custom Package .
4. В диалоговом окне Импорт пакета перейдите в каталог, содержащий распакованный SDK, выберите FirebaseAnalytics.unitypackage и нажмите Открыть .
5. В открывшемся диалоговом окне «Импорт пакета Unity» нажмите кнопку «Импорт» .
6. Повторите предыдущие шаги для импорта FirebaseCrashlytics.unitypackage .
7. Вернитесь в консоль Firebase и в рабочем процессе настройки нажмите кнопку Далее .

Дополнительную информацию о добавлении Firebase SDK в проекты Unity см. в разделе Дополнительные параметры установки Unity .

4. Настройте Crashlytics в своем проекте Unity.

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

Инициализируйте Crashlytics SDK

1. В Assets/Hamster/Scripts/MainGame.cs добавьте следующие операторы using :

   using Firebase.Crashlytics;
   using Firebase.Extensions;
   

   Первый модуль позволяет использовать методы из Crashlytics SDK, а второй содержит некоторые расширения для C# Tasks API . Без обоих операторов using следующий код не будет работать.
2. Оставаясь в MainGame.cs , добавьте инициализацию Firebase к существующему методу Start() , вызвав InitializeFirebaseAndStartGame() :

   void Start()
   {
     Screen.SetResolution(Screen.width / 2, Screen.height / 2, true);
     InitializeFirebaseAndStartGame();
   }
   

3. И снова, в MainGame.cs найдите InitializeFirebaseAndStartGame() , объявите переменную приложения, а затем перезапишите реализацию метода следующим образом:

   public Firebase.FirebaseApp app = null;
   
   // Begins the firebase initialization process and afterwards, opens the main menu.
   private void InitializeFirebaseAndStartGame()
   {
     Firebase.FirebaseApp.CheckAndFixDependenciesAsync()
     .ContinueWithOnMainThread(
       previousTask => 
       {
         var dependencyStatus = previousTask.Result;
         if (dependencyStatus == Firebase.DependencyStatus.Available) {
           // Create and hold a reference to your FirebaseApp,
           app = Firebase.FirebaseApp.DefaultInstance;
           // Set the recommended Crashlytics uncaught exception behavior.
           Crashlytics.ReportUncaughtExceptionsAsFatal = true;
           InitializeCommonDataAndStartGame();
         } else {
           UnityEngine.Debug.LogError(
             $"Could not resolve all Firebase dependencies: {dependencyStatus}\n" +
             "Firebase Unity SDK is not safe to use here");
         }
       });
   }
   

Размещение логики инициализации здесь предотвращает взаимодействие с игроком до инициализации зависимостей Firebase.

Преимущества и последствия сообщения необработанных исключений как фатальных обсуждаются в разделе FAQ Crashlytics .

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

Примечание: Выполните шаги из этого раздела для настройки Crashlytics. В дальнейшем выполняйте эти шаги каждый раз при создании релизной сборки или любой сборки, для которой вы хотите видеть символизированные трассировки стека в консоли Firebase (в этой практической работе — после каждого шага).

Действия по созданию и загрузке символов различаются для приложений iOS и Android.

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

1. В диалоговом окне «Параметры сборки» экспортируйте свой проект в рабочее пространство Xcode.
2. Создайте свое приложение.
   Для платформ Apple плагин Firebase Unity Editor автоматически настраивает ваш проект Xcode для генерации и загрузки файла символов, совместимого с Crashlytics, на серверы Firebase для каждой сборки. Эта информация о символах необходима для отображения трассировок стека в символьной форме на панели управления Crashlytics.

Андроид

1. (только во время первоначальной настройки, а не для каждой сборки) Настройте сборку:
   1. Создайте новую папку с названием Builds в корне каталога вашего проекта (т. е. как родственную папку каталога Assets ), а затем создайте подпапку с названием Android .
   2. В Файл > Настройки сборки > Настройки проигрывателя > Конфигурация установите для параметра Scripting Backend значение IL2CPP.
      • IL2CPP обычно приводит к тому, что сборки становятся меньше и имеют лучшую производительность.
      • IL2CPP также является ЕДИНСТВЕННЫМ доступным вариантом на iOS, и его выбор здесь позволяет двум платформам достичь большего паритета и упрощает отладку между ними (если вы решите собрать обе).
2. Создайте приложение. В разделе «Файл» > «Параметры сборки» выполните следующие действия:
   1. Убедитесь, что флажок «Создать символы.zip» установлен (или, если отображается раскрывающийся список, выберите «Отладка» ).
   2. Создайте APK-файл непосредственно из редактора Unity в только что созданной вами подпапке Builds/Android .
3. После завершения сборки необходимо сгенерировать файл символов, совместимый с Crashlytics, и загрузить его на серверы Firebase. Эта информация о символах необходима для просмотра трассировок стека сбоев нативной библиотеки в виде символов на панели управления Crashlytics.
   
   Создайте и загрузите этот файл символов, выполнив следующую команду Firebase CLI :

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

   • FIREBASE_APP_ID : идентификатор вашего приложения Firebase для Android (не имя пакета). Найдите это значение в файле google-services.json , который вы скачали ранее. Это значение mobilesdk_app_id .
     Пример идентификатора приложения Firebase для Android: 1:567383003300:android:17104a2ced0c9b9b
   • PATH/TO/SYMBOLS : путь к сжатому файлу символов, созданному в каталоге Builds/Android после завершения сборки (например: Builds/Android/myapp-1.0-v100.symbols.zip ).

     Примечание: это имя файла изменится, поскольку проект собирается с разными номерами, установленными для Version и Bundle Version Code в Файл > Настройки сборки > Настройки проигрывателя > Идентификация .

Принудительно выполните тестовый сбой для завершения настройки

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

1. В MainGameScene найдите GameObject EmptyObject в иерархии редактора, добавьте к нему следующий скрипт и сохраните сцену. Этот скрипт вызовет сбой теста через несколько секунд после запуска приложения.

   using System;
   using UnityEngine;
   
   public class CrashlyticsTester : MonoBehaviour {
       // Update is called once per frame
       void Update()
       {
           // Tests your Crashlytics implementation by
           // throwing an exception every 60 frames.
           // You should see reports in the Firebase console
           // a few minutes after running your app with this method.
           if(Time.frameCount >0 && (Time.frameCount%60) == 0)
           {
               throw new System.Exception("Test exception; please ignore");
           }
       }
   }
   

2. Создайте свое приложение и загрузите информацию о символах после завершения сборки.
   • iOS : плагин Firebase Unity Editor автоматически настраивает ваш проект Xcode для загрузки файла символов.
   • Android : выполните команду Firebase CLI crashlytics:symbols:upload , чтобы загрузить файл символов.

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

3. Запустите приложение. После запуска приложения просмотрите журнал устройства и дождитесь срабатывания исключения от CrashlyticsTester .
   • iOS : просматривайте журналы на нижней панели Xcode.
   • Android : просмотрите журналы, выполнив следующую команду в терминале: adb logcat .
4. Посетите панель управления Crashlytics , чтобы увидеть исключение! Вы увидите его в таблице «Проблемы» в нижней части панели управления. Далее в ходе практического занятия вы узнаете больше о том, как изучать эти отчёты.
5. Убедившись, что событие загружено в Crashlytics, выберите GameObject EmptyObject , к которому вы его прикрепили, удалите только компонент CrashlyticsTester , а затем сохраните сцену, чтобы восстановить ее в исходное состояние.

5. Включите и изучите меню отладки.

На данный момент вы добавили Crashlytics в свой проект Unity, завершили настройку и убедились, что Crashlytics SDK загружает события в Firebase. Теперь вам нужно создать в проекте Unity меню, которое продемонстрирует, как использовать расширенные функции Crashlytics в вашей игре. В проекте Unity «Level Up with Firebase» уже есть скрытое меню отладки, которое вы сделаете видимым и напишете для него функционал.

Включить меню отладки

Кнопка доступа к меню отладки есть в вашем проекте Unity, но в данный момент неактивна. Чтобы получить к ней доступ, необходимо включить кнопку в префабе MainMenu :

1. В редакторе Unity откройте префаб с именем MainMenu .
2. В иерархии префаба найдите отключенный подобъект с именем DebugMenuButton , а затем выберите его.
3. Включите DebugMenuButton , установив флажок в верхнем левом углу слева от текстового поля, содержащего DebugMenuButton .
4. Сохраните сборный дом.
5. Запустите игру в редакторе или на своём устройстве. Меню теперь должно быть доступно.

Важно : поскольку методы аварийного завершения в настоящее время не реализованы, нажатие соответствующих кнопок вызовет исключение System.NotImplementedException и в противном случае не приведет ни к чему.

Предварительный просмотр и понимание тел методов для меню отладки

Далее в этой лабораторной работе вы напишете тела методов для некоторых преднастроенных отладочных методов Crashlytics. Однако в проекте Level Up with Firebase Unity эти методы определены в DebugMenu.cs и вызываются из него.

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

Откройте DebugMenu.cs и найдите следующие методы:

Методы создания и аннотирования проблем Crashlytics:

• CrashNow
• LogNonfatalError
• LogStringsAndCrashNow
• SetAndOverwriteCustomKeyThenCrash
• SetLogsAndKeysBeforeANR

Методы регистрации событий Analytics для облегчения отладки:

• LogProgressEventWithStringLiterals
• LogIntScoreWithBuiltInEventAndParams

На последующих этапах этой лабораторной работы вы реализуете эти методы и узнаете, как они помогают решать конкретные ситуации, которые могут возникнуть при разработке игр.

6. Обеспечить отправку отчетов о сбоях в процессе разработки.

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

В проектах Unity события сбоев и исключений в вашей игре немедленно записываются на диск. Неперехваченные исключения, которые не приводят к сбою игры (например, неперехваченные исключения C# в игровой логике), можно настроить Crashlytics SDK для регистрации как фатальных событий, установив свойство Crashlytics.ReportUncaughtExceptionsAsFatal в значение true при инициализации Crashlytics в вашем проекте Unity . Эти события передаются в Crashlytics в режиме реального времени, без необходимости перезапуска игры конечным пользователем. Обратите внимание, что нативные сбои всегда регистрируются как фатальные события и отправляются при перезапуске игры конечным пользователем.

Примечание: Чтобы сообщать о неперехваченных исключениях как о фатальных событиях, ваш проект Unity должен использовать Firebase Crashlytics Unity SDK версии 10.4.0 и выше.

Кроме того, имейте в виду следующие небольшие, но существенные различия между тем, как различные среды выполнения отправляют информацию Crashlytics в Firebase:

Симулятор iOS:

• Информация Crashlytics предоставляется только в том случае, если Xcode отсоединен от симулятора. Если Xcode подключен, он перехватывает ошибки на более высоком уровне, предотвращая отправку информации.

Мобильные физические устройства (Android и iOS):

• Специфика Android: ошибки ANR регистрируются только на устройствах Android 11+. Ошибки ANR и нефатальные события регистрируются при следующем запуске.

Редактор Unity:

• Информация Crashlytics из редактора в режиме воспроизведения или в автономном режиме НЕ записывается и не загружается в Firebase. Более того, рабочий процесс разработки Firebase Desktop не поддерживает Crashlytics .

Проверьте, как можно вызвать сбой игры одним нажатием кнопки в CrashNow()

После настройки Crashlytics в вашей игре, Crashlytics SDK автоматически регистрирует сбои и неперехваченные исключения и загружает их в Firebase для анализа. Отчёты отображаются на панели управления Crashlytics в консоли Firebase.

1. Чтобы продемонстрировать, что это действительно происходит автоматически: откройте DebugMenu.cs , а затем перезапишите метод CrashNow() следующим образом:

   void CrashNow()
   {
       TestCrash();
   }
   

2. Создайте свое приложение.
3. (Только для Android) Загрузите символы, выполнив следующую команду Firebase CLI:

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

4. Нажмите кнопку «Сбой сейчас» и перейдите к следующему шагу этой лабораторной работы, чтобы узнать, как просматривать и интерпретировать отчет о сбое.

7. Изучите отчеты о проблемах в консоли Firebase

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

1. Нажмите кнопку «Сбой сейчас» , а затем перезапустите приложение.
2. Перейдите на панель управления Crashlytics . Прокрутите вниз до таблицы «Проблемы» в нижней части панели, где Crashlytics группирует события с одинаковой корневой причиной в категории «Проблемы».
3. Нажмите на новую задачу в таблице « Проблемы» . Отобразится сводка событий по каждому отдельному событию, отправленному в Firebase.
   
   Вы должны увидеть что-то похожее на следующий скриншот. Обратите внимание, как в сводке событий отображается трассировка стека вызова, приведшего к сбою.

Дополнительные метаданные

Ещё одна полезная вкладка — « Метаданные Unity ». В этом разделе представлена ​​информация об атрибутах устройства, на котором произошло событие, включая физические характеристики, модель/характеристики процессора и всевозможные метрики графического процессора.

Вот пример, когда информация на этой вкладке может быть полезна:
Представьте, что ваша игра активно использует шейдеры для достижения определённого эффекта, но не все телефоны оснащены графическими процессорами, способными отрисовывать эту функцию. Информация на вкладке «Метаданные Unity» поможет вам лучше понять, какое оборудование должно тестироваться вашим приложением при принятии решения о том, какие функции автоматически предоставлять или полностью отключать.

Хотя на вашем устройстве ошибка или сбой могут никогда не произойти, из-за огромного разнообразия устройств Android в мире полезно лучше понять особые «горячие точки» устройств вашей аудитории.

8. Вызов, перехват и регистрация исключения

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

1. В Assets/Hamster/Scripts/States/DebugMenu.cs добавьте к операторам using следующее:

   // Import Firebase
   using Firebase.Crashlytics;
   

2. Оставаясь в DebugMenu.cs , перезапишите LogNonfatalError() следующим образом:

   void LogNonfatalError()
   {
       try
       {
           throw new System.Exception($"Test exception thrown in {nameof(LogNonfatalError)}");
       }
       catch(System.Exception exception)
       {
           Crashlytics.LogException(exception);
       }
   }
   

3. Создайте свое приложение.
4. (Только для Android) Загрузите символы, выполнив следующую команду Firebase CLI:

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

5. Нажмите кнопку «Записать нефатальную ошибку» , а затем перезапустите приложение.
6. Перейдите на панель инструментов Crashlytics , и вы увидите нечто похожее на то, что вы видели на последнем этапе этой лабораторной работы.
7. Однако на этот раз ограничьте фильтр по типу событий значением «Нефатальные» , чтобы просматривать только нефатальные ошибки, например ту, которую вы только что зарегистрировали.
   

9. Регистрируйте строки в Crashlytics, чтобы лучше понимать ход выполнения программы.

Вы когда-нибудь пытались понять, почему строка кода, вызываемая из разных источников сотни, если не тысячи раз за сеанс, может внезапно сгенерировать исключение или привести к сбою? Конечно, было бы неплохо пройтись по коду в IDE и более внимательно посмотреть на значения, но что, если это происходит лишь у ничтожно малого процента пользователей? Хуже того, что вы будете делать, если не сможете воспроизвести этот сбой, несмотря ни на что?

В подобных ситуациях наличие контекста может иметь решающее значение. С Crashlytics.Log вы можете записать необходимый контекст. Воспринимайте эти сообщения как подсказки себе в будущем о том, что может происходить.

Хотя журналы можно использовать множеством способов, обычно они наиболее полезны для регистрации ситуаций, когда порядок и/или отсутствие вызовов представляют собой жизненно важную информацию.

1. В Assets/Hamster/Scripts/States/DebugMenu.cs перезапишите LogStringsAndCrashNow() следующим образом:

   void LogStringsAndCrashNow()
   {
       Crashlytics.Log($"This is the first of two descriptive strings in {nameof(LogStringsAndCrashNow)}");
       const bool RUN_OPTIONAL_PATH = false;
       if(RUN_OPTIONAL_PATH)
       {
           Crashlytics.Log(" As it stands, this log should not appear in your records because it will never be called.");
       }
       else
       {
           Crashlytics.Log(" A log that will simply inform you which path of logic was taken. Akin to print debugging.");
       }
       Crashlytics.Log($"This is the second of two descriptive strings in {nameof(LogStringsAndCrashNow)}");
       TestCrash();
   }
   

2. Создайте свое приложение.
3. (Только для Android) Загрузите символы, выполнив следующую команду Firebase CLI:

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

4. Нажмите кнопку «Записать строки журнала и сбой сейчас» , а затем перезапустите приложение.
5. Вернитесь на панель управления Crashlytics и нажмите на самую новую проблему в таблице «Проблемы» . Вы снова увидите что-то похожее на предыдущие проблемы.
   
6. Однако если щелкнуть вкладку «Журналы» в сводке событий , вы увидите следующее представление:
   

Примечание: эти журналы полезны не только своими сообщениями, но и временными метками, которые помогают понять порядок их создания.

Важно: чтобы избежать замедления работы приложения, Crashlytics ограничивает размер журналов 64 КБ и удаляет старые записи журнала, когда журнал сеанса превышает этот лимит.

10. Напишите и перезапишите пользовательский ключ

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

Помимо регистрации произвольных строк, Crashlytics предлагает еще одну форму отладки, когда полезно знать точное состояние программы в момент ее сбоя: пользовательские ключи.

Это пары «ключ-значение», которые можно задать для сеанса. В отличие от журналов, которые накапливаются и являются исключительно аддитивными, ключи можно перезаписывать, чтобы отражать только самое последнее состояние переменной или условия.

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

1. В Assets/Hamster/Scripts/States/DebugMenu.cs перезапишите SetAndOverwriteCustomKeyThenCrash() следующим образом:

   void SetAndOverwriteCustomKeyThenCrash()
   {
       const string CURRENT_TIME_KEY = "Current Time";
       System.TimeSpan currentTime = System.DateTime.Now.TimeOfDay;
       Crashlytics.SetCustomKey(
           CURRENT_TIME_KEY,
           DayDivision.GetPartOfDay(currentTime).ToString() // Values must be strings
           );
   
       // Time Passes
       currentTime += DayDivision.DURATION_THAT_ENSURES_PHASE_CHANGE;
   
       Crashlytics.SetCustomKey(
           CURRENT_TIME_KEY,
           DayDivision.GetPartOfDay(currentTime).ToString()
           );
       TestCrash();
   }
   

2. Создайте свое приложение.
3. (Только для Android) Загрузите символы, выполнив следующую команду Firebase CLI:

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

4. Нажмите кнопку «Установить пользовательский ключ и сбой» , а затем перезапустите приложение.
5. Вернитесь на панель управления Crashlytics и нажмите на самую новую проблему в таблице «Проблемы» . Вы снова увидите что-то похожее на предыдущие проблемы.
6. Однако на этот раз щелкните вкладку «Ключи» в сводке событий , чтобы просмотреть значения ключей, включая Current Time :
   

   Важно : ключ crash_info_entry_0 автоматически заполняется Crashlytics только тогда, когда ваше приложение запускается симулятором iOS.

Зачем вам использовать пользовательские ключи вместо пользовательских журналов?

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

Однако, как и у журналов, у пользовательских ключей есть ограничение. Crashlytics поддерживает максимум 64 пары «ключ-значение». После достижения этого порога дополнительные значения не сохраняются. Каждая пара «ключ-значение» может иметь размер до 1 КБ.

11. (Только для Android) Используйте пользовательские ключи и журналы для понимания и диагностики ANR.

Важно : следующий класс проблем в первую очередь касается Android 11 и более поздних версий. Если это не соответствует вашему сценарию разработки, пропустите этот раздел.

Одна из самых сложных для отладки категорий проблем для разработчиков Android — это ошибка «Приложение не отвечает » (ANR). ANR возникают, когда приложение не реагирует на ввод данных более 5 секунд. Если это происходит, это означает, что приложение либо зависло, либо работает очень медленно. Пользователям отображается диалоговое окно, в котором они могут выбрать «Подождать» или «Закрыть приложение».

Ошибки ANR создают неприятный пользовательский опыт и (как упоминалось в ссылке на ANR выше) могут повлиять на обнаружение вашего приложения в Google Play. Из-за их сложности и того, что они часто вызваны многопоточным кодом, поведение которого на разных моделях телефонов существенно различается, воспроизвести ошибки ANR во время отладки зачастую очень сложно, если не невозможно. Поэтому аналитический и дедуктивный подход к их решению обычно является наилучшим.

В этом методе мы будем использовать комбинацию Crashlytics.LogException , Crashlytics.Log и Crashlytics.SetCustomKey для дополнения автоматического ведения журнала проблем и предоставления нам дополнительной информации.

Важно: обратите внимание, что блокирующий код выполняется в потоке пользовательского интерфейса UnityPlayerActivity . Это несколько неестественно для Unity, поскольку этот поток отличается от основного потока Unity, в котором по умолчанию выполняется игровой код. Отладка ANR может быть особенно сложной, поскольку они могут быть вызваны плагинами или другим кодом, который нестандартно выполняется в потоке пользовательского интерфейса.

1. В Assets/Hamster/Scripts/States/DebugMenu.cs перезапишите SetLogsAndKeysBeforeANR() следующим образом:

   void SetLogsAndKeysBeforeANR()
   {
       System.Action<string,long> WaitAndRecord =
       (string methodName, long targetCallLength)=>
       {
           System.Diagnostics.Stopwatch stopWatch = new System.Diagnostics.Stopwatch();
           const string CURRENT_FUNCTION = "Current Async Function";
   
           // Initialize key and start timing
           Crashlytics.SetCustomKey(CURRENT_FUNCTION, methodName);
           stopWatch.Start();
   
           // The actual (simulated) work being timed.
           BusyWaitSimulator.WaitOnSimulatedBlockingWork(targetCallLength);
   
           // Stop timing
           stopWatch.Stop();
   
           if(stopWatch.ElapsedMilliseconds>=BusyWaitSimulator.EXTREME_DURATION_MILLIS)
           {
             Crashlytics.Log($"'{methodName}' is long enough to cause an ANR.");
           }
           else if(stopWatch.ElapsedMilliseconds>=BusyWaitSimulator.SEVERE_DURATION_MILLIS)
           {
             Crashlytics.Log($"'{methodName}' is long enough it may cause an ANR");
           }
       };
   
       WaitAndRecord("DoSafeWork",1000L);
       WaitAndRecord("DoSevereWork",BusyWaitSimulator.SEVERE_DURATION_MILLIS);
       WaitAndRecord("DoExtremeWork",2*BusyWaitSimulator.EXTREME_DURATION_MILLIS);
   }
   

2. Создайте свое приложение.
3. Загрузите символы, выполнив следующую команду Firebase CLI:

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

4. Нажмите кнопку « Установить журналы и ключи» → ANR , а затем перезапустите приложение.
5. Вернитесь на панель управления Crashlytics и нажмите на новую задачу в таблице « Проблемы» , чтобы просмотреть сводку событий . Если вызов прошёл успешно, вы должны увидеть что-то вроде этого:
   
   
   Как видите, Firebase определил, что активное ожидание в потоке является основной причиной, по которой ваше приложение вызвало ошибку ANR.
   
6. Если вы посмотрите журналы на вкладке Журналы сводки событий , вы увидите, что последний метод, зарегистрированный как завершенный, — это DoSevereWork .
   
   
   Напротив, последний метод, указанный как запускаемый, — это DoExtremeWork , что указывает на то, что во время выполнения этого метода произошла ошибка ANR, и игра закрылась до того, как она смогла зарегистрировать DoExtremeWork .
   
   

Важно : если вы не видите ANR на Android, а вместо этого видите ошибку с упоминанием InvalidOperationException , прочтите логи. Эта ошибка включена в эту практическую работу. Следуйте инструкциям, которые регистрируются в журнале исключения, чтобы исправить её. Пересоберите, разверните и повторите итерации, и в конечном итоге вы получите нужную ошибку.

Зачем это делать?

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

12. Добавление событий Analytics для дальнейшего обогащения отчетов

Следующие методы также можно вызывать из меню «Отладка», но вместо того, чтобы самостоятельно создавать проблемы, они используют Google Analytics как дополнительный источник информации для лучшего понимания работы вашей игры.

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

Примечание : Ниже приведены довольно простые примеры использования Google Analytics. Подробное описание Analytics выходит за рамки данной практической работы. Если вы хотите узнать больше, лучше понять, что именно регистрируется этими данными, или научиться отлаживать процесс создания отчётов, см. статью Начало работы с Google Analytics для Unity .

1. В Assets/Hamster/Scripts/States/DebugMenu.cs перезапишите существующие реализации следующих методов:

   public void LogProgressEventWithStringLiterals()
   {
         Firebase.Analytics.FirebaseAnalytics.LogEvent("progress", "percent", 0.4f);
   }
   

   public void LogIntScoreWithBuiltInEventAndParams()
   {
         Firebase.Analytics.FirebaseAnalytics
           .LogEvent(
             Firebase.Analytics.FirebaseAnalytics.EventPostScore,
             Firebase.Analytics.FirebaseAnalytics.ParameterScore,
             42
           );
   }
   

2. Создайте и разверните свою игру, а затем войдите в меню отладки .
3. (Только для Android) Загрузите символы, выполнив следующую команду Firebase CLI:

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

4. Нажмите хотя бы одну из следующих кнопок один или несколько раз, чтобы вызвать указанные выше функции:
   • Событие строки журнала
   • Событие входа в систему
5. Нажмите кнопку «Сбой сейчас» .
6. Перезапустите игру, чтобы событие сбоя было загружено в Firebase.
7. Когда вы регистрируете различные произвольные последовательности событий Analytics, а затем ваша игра генерирует событие, по которому Crashlytics создает отчет (как вы только что сделали), они добавляются на вкладку «Журналы» сводки событий Crashlytics следующим образом:
   

Важно: Отображение пользовательских событий на панели Analytics в консоли Firebase может занять больше времени, чем их появление в журнале сбоев на панели Crashlytics. Кроме того, события Analytics могут не отображаться сразу в обоих местах после их регистрации.

13. Двигаясь вперед

Благодаря этому у вас появится более совершенная теоретическая база для дополнения автоматически генерируемых отчётов о сбоях. Эта новая информация позволит вам использовать текущее состояние, записи прошлых событий и существующие события Google Analytics для более точного анализа последовательности событий и логики, приведших к результату.

Если ваше приложение предназначено для Android 11 (уровень API 30) или выше, рассмотрите возможность включения GWP-ASan — встроенной функции распределения памяти, полезной для отладки сбоев, вызванных встроенными ошибками памяти, такими как use-after-free и heap-buffer-overflow . Чтобы воспользоваться этой функцией отладки, явно включите GWP-ASan .

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

Перейдите к практическому занятию «Используйте Remote Config для своей игры в Unity» , где вы узнаете об использовании Remote Config и A/B-тестирования в Unity.