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

1. Введение

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

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

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

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

Что вы узнаете

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

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

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

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

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

Обратите внимание, что этот пример игры Level Up с 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. Перейдите в каталог, содержащий код, и нажмите «ОК» .
4. При появлении запроса выберите версию редактора Unity, которую вы хотите использовать, и целевую платформу (Android или iOS).
5. Нажмите на имя проекта level-up-with-firebase , и проект откроется в редакторе Unity.
6. Если ваш редактор не открывает его автоматически, откройте MainGameScene в разделе «Ресурсы» > «Hamster» на вкладке «Проект» редактора Unity.
   

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

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

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

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

Зарегистрируйте свое приложение в 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

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

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

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

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

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

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

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

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

2. Разархивируйте SDK в удобное место.
3. В открытом проекте Unity перейдите в «Активы» > «Импортировать пакет» > «Пользовательский пакет» .
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, а второй содержит некоторые расширения API задач C# . Без обоих операторов 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. В меню «Файл » > «Настройки сборки» > «Настройки проигрывателя» > « Конфигурация » установите для параметра «Скриптовый сервер» значение 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 найдите EmptyObject GameObject в редакторе Hierarchy , добавьте к нему следующий скрипт и затем сохраните сцену. Этот скрипт вызовет сбой теста через несколько секунд после запуска приложения.

   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 в вашей игре. В проекте Level Up с Firebase Unity уже есть скрытое меню отладки, которое вы сделаете видимым и для которого напишете функции.

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

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

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

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

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

Позже в этой лабораторной работе вы напишете тела методов для некоторых предварительно настроенных методов отладки Crashlytics. Однако в проекте Level Up с 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 и несмертельных событиях сообщается при следующем запуске.

Редактор Юнити:

• Информация 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:

   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 Store. Из-за их сложности и того, что они часто вызваны многопоточным кодом с совершенно разным поведением на разных моделях телефонов, воспроизведение ошибок 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. Перемежающиеся события аналитики для дальнейшего обогащения отчетов.

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

В отличие от других методов, написанных вами в этой лаборатории, вам следует использовать эти методы в сочетании с другими. Вызовите эти методы (нажав соответствующую кнопку в меню отладки) в любом произвольном порядке, прежде чем запускать один из остальных. Затем, когда вы изучите информацию в конкретной проблеме Crashlytics, вы увидите упорядоченный журнал событий 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:

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

4. Нажмите хотя бы одну из следующих кнопок один или несколько раз, чтобы вызвать вышеуказанные функции:
   • Строковое событие журнала
   • Вход в систему Int Event
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 .

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

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