Как начать работу с Crashlytics для Unity

Выберите платформу:

iOS+ Android Android NDK Flutter Unity

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

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

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

Подготовка

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

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

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

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

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

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

1. Скачайте Firebase Unity SDK и распакуйте архив в удобное место. SDK Firebase Unity не зависит от платформы.

2. В открытом проекте Unity выберите Assets (Объекты) > Import Package (Импортировать пакет) > Custom Package (Пользовательский пакет).

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

   Чтобы использовать историю действий, добавьте в приложение Firebase SDK для Google Analytics (FirebaseAnalytics.unitypackage). Убедитесь, что в проекте Firebase включена Google Аналитика.

   Unity 2017.x и более поздние версии позволяют использовать фреймворк .NET 4.x. Если в проекте Unity используется .NET 4.x, импортируйте dotnet4/FirebaseCrashlytics.unitypackage.

4. В окне Import Unity Package нажмите Import.

Важно! При использовании SDK Firebase Unity для платформ Apple не отключайте подмену метода. Для работы SDK требуется Swizzling; без него ключевые функции Firebase (например, обработка токенов FCM) не будут работать правильно.

Шаг 2. Инициализируйте Crashlytics

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

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

   2. Нажмите Add Component (Добавить компонент) в окне Inspector (Инспектор) для нового объекта.

   3. Выберите скрипт CrashlyticsInit, чтобы добавить его в объект 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 для загрузки символов.

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

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

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

Примечание. Вы также можете выполнять команды CLI Firebase в Cloud Shell. Cloud Shell – это среда командной строки, которая работает в браузере и не требует аутентификации. Она доступна в консоли Firebase и поставляется с предустановленным интерфейсом командной строки Firebase. Это делает его удобным вариантом для быстрого старта, при условии, что вы добавите файлы проекта в среду Cloud Shell.

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

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

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

1. В диалоговом окне Build Settings (Настройки сборки) экспортируйте проект в рабочую область Xcode.

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

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

Android

1. В диалоговом окне Build Settings (Настройки сборки) выполните одно из следующих действий:

   • экспортировать проект в Android Studio;

   • Создайте APK-файл прямо в Unity Editor.
     Перед сборкой убедитесь, что в диалоговом окне Build Settings (Настройки сборки) установлен флажок Create symbols.zip (Создать symbols.zip).

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

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

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

     Как найти идентификатор приложения Firebase

     Найти идентификатор приложения Firebase можно двумя способами:

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

     • В консоли Firebase перейдите в раздел Settings (Настройки) > General (Общие). Прокрутите страницу до карточки Ваши приложения и нажмите на нужное приложение Firebase, чтобы найти его идентификатор.

   • PATH/TO/SYMBOLS – путь к файлу символов, созданному CLI.

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

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

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

   Пожаловаться	Описание
   --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. В консоли Firebase перейдите в раздел DevOps & Engagement (DevOps и взаимодействие) > Crashlytics dashboard (Панель управления) и проверьте, появился ли тестовый отчет о сбое.

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

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

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

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

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

• Экспортируйте данные в BigQuery или Cloud Logging, чтобы выполнять расширенный анализ и использовать дополнительные функции, например запрашивать данные, создавать собственные сводки и настраивать специальные оповещения.