Как начать работу с Crashlytics на платформах Apple

В этом руководстве рассказывается, как начать работу с Firebase Crashlytics в приложении для платформ Apple (например, в приложении для iOS).

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

Help me use Firebase in my app.
1. Make sure that **Firebase agent skills** are installed and updated. For Claude Code, Codex, or Cursor agents, help me install the Firebase plugin. For other agents, run `npx skills add firebase/agent-skills`.  Always try to use **Firebase agent skills** for Firebase-related tasks.
2. Help me set up Firebase Crashlytics for my app.

Подготовка

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

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

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

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

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

   Обратите внимание, что история действий пользователя доступна для всех платформ Apple, поддерживаемых Crashlytics, кроме watchOS.

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

Для установки зависимостей Firebase и управления ими используйте Swift Package Manager.

1. Откройте проект приложения в Xcode и перейдите в меню File (Файл) > Add Packages (Добавить пакеты).
2. Когда появится запрос, добавьте хранилище Firebase SDK для платформ Apple:

  https://github.com/firebase/firebase-ios-sdk.git

3. Выберите библиотеку Crashlytics.
4. Чтобы использовать историю действий, добавьте в приложение Firebase SDK для Google Analytics. Убедитесь, что в проекте Firebase включена Google Аналитика.
5. Добавьте флаг -ObjC в раздел Other Linker Flags (Другие флаги компоновщика) в настройках сборки целевого объекта.
6. Только для macOS. В файле Info.plist добавьте ключ NSApplicationCrashOnExceptions и задайте для него значение YES.
7. После этого Xcode автоматически начнет распознавать и скачивать зависимости в фоновом режиме.

Затем настройте модуль Firebase:

1. Импортируйте модуль Firebase в структуру App или подкласс UIApplicationDelegate:

   Swift

   import Firebase

   Objective-C

   @import Firebase;

2. Настройте общий экземпляр FirebaseApp (обычно в методе application(_:didFinishLaunchingWithOptions:) делегата приложения):

   Swift

   // Use the Firebase library to configure APIs.
   FirebaseApp.configure()

   Objective-C

   // Use the Firebase library to configure APIs.
   [FIRApp configure];

Шаг 2. Настройте Xcode для автоматической загрузки файлов dSYM

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

1. Откройте рабочую область Xcode проекта и выберите файл проекта в навигаторе слева.

2. В списке TARGETS (ЦЕЛИ) выберите основную цель сборки.

3. Перейдите на вкладку Build Settings (Настройки сборки) и выполните следующие действия, чтобы Xcode создавал dSYM для ваших сборок.

   1. Нажмите Все и найдите debug information format.

   2. Для всех типов сборки задайте для параметра Debug Information Format (Формат отладочной информации) значение DWARF with dSYM File.

4. Перейдите на вкладку Build Phases (Этапы сборки) и выполните следующие действия, чтобы Xcode мог обработать dSYM и загрузить файлы:

   1. Нажмите add > New Run Script Phase (Новый этап выполнения скрипта).

      Убедитесь, что новый этап Run Script является последним этапом сборки проекта. В противном случае Crashlytics не сможет правильно обработать dSYM.

   2. Разверните новый раздел Запустить скрипт.

   3. В поле скрипта (под надписью Shell) добавьте следующий скрипт:

      Этот скрипт обрабатывает файлы dSYM вашего проекта и загружает их в Crashlytics.

      "${BUILD_DIR%/Build/*}/SourcePackages/checkouts/firebase-ios-sdk/Crashlytics/run"

   4. В разделе Input Files (Входные файлы) добавьте пути к следующим файлам:

      ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}

      ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${PRODUCT_NAME}

      ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Info.plist

      $(TARGET_BUILD_DIR)/$(UNLOCALIZED_RESOURCES_FOLDER_PATH)/GoogleService-Info.plist

      $(TARGET_BUILD_DIR)/$(EXECUTABLE_PATH)

      Если в настройках сборки проекта есть ENABLE_USER_SCRIPT_SANDBOXING=YES и ENABLE_DEBUG_DYLIB=YES, добавьте следующее:

      ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${PRODUCT_NAME}.debug.dylib

      Зачем нужны пути к этим файлам

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

      • Чтобы Crashlytics мог обрабатывать файлы dSYM, укажите их местоположение.
      • Указав местоположение файла GoogleService-Info.plist, вы позволите Crashlytics связать dSYM с вашим приложением Firebase.
      • Если вы укажете местоположение исполняемого файла приложения, скрипт запуска не будет повторно загружать один и тот же файл dSYM. Обратите внимание, что двоичные файлы приложения не загружаются.

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

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

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

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

   Вы можете использовать приведенный ниже код, чтобы добавить в приложение кнопку, нажатие на которую вызывает сбой. с надписью "Тестовый сбой".

   SwiftUI

   Button("Crash") {
     fatalError("Crash was triggered")
   }

   UIKit

   Swift

   import UIKit
   
   class ViewController: UIViewController {
     override func viewDidLoad() {
         super.viewDidLoad()
   
         // Do any additional setup after loading the view, typically from a nib.
   
         let button = UIButton(type: .roundedRect)
         button.frame = CGRect(x: 20, y: 50, width: 100, height: 30)
         button.setTitle("Test Crash", for: [])
         button.addTarget(self, action: #selector(self.crashButtonTapped(_:)), for: .touchUpInside)
         view.addSubview(button)
     }
   
     @IBAction func crashButtonTapped(_ sender: AnyObject) {
         let numbers = [0]
         let _ = numbers[1]
     }
   }

   Objective-C

   #import "ViewController.h"
   
   @implementation ViewController
   ‐ (void)viewDidLoad {
       [super viewDidLoad];
   
       // Do any additional setup after loading the view, typically from a nib.
   
       UIButton* button = [UIButton buttonWithType:UIButtonTypeRoundedRect];
       button.frame = CGRectMake(20, 50, 100, 30);
       [button setTitle:@"Test Crash" forState:UIControlStateNormal];
       [button addTarget:self action:@selector(crashButtonTapped:)
           forControlEvents:UIControlEventTouchUpInside];
       [self.view addSubview:button];
   }
   
   ‐ (IBAction)crashButtonTapped:(id)sender {
       @[][1];
   }
   
   @end

2. Соберите и запустите приложение в Xcode, отключив отладчик Xcode.

   1. Нажмите play_arrowBuild and then run the current scheme (Собрать и запустить текущую схему), чтобы собрать приложение на тестовом устройстве или в симуляторе.

   2. Дождитесь запуска приложения и нажмите stopStop running the scheme or action (Остановить схему или действие), чтобы закрыть первый экземпляр приложения. В нем содержится отладчик, который мешает работе Crashlytics.

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

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

   2. В приложении нажмите кнопку Test Crash, которую вы добавили с помощью кода выше.

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

4. В консоли Firebase перейдите в раздел DevOps & Engagement (DevOps и взаимодействие) > Crashlytics dashboard (Панель управления) и проверьте, появился ли тестовый отчет о сбое.

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

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

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

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

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