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

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

После того как вы настроите Firebase Crashlytics SDK в приложении, вы сможете получать подробные отчеты о сбоях в консоли 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, так и в IDE (например, добавления файла конфигурации Firebase и SDK Crashlytics). Чтобы завершить настройку, вам нужно вызвать тестовый сбой, чтобы отправить первый отчет о сбое в Firebase.

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

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

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

   • Если вы используете имеющийся проект Firebase, в котором не включена Google Analytics, откройте settings Настройки > Интеграции на консоли 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 (Новый этап выполнения скрипта).

      Убедитесь, что новый этап Выполнить скрипт является последним этапом сборки проекта. В противном случае 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 разрешает скрипту run доступ только к файлам, указанным в разделе Входные файлы.

      • Указав местоположение файлов dSYM проекта, вы позволите Crashlytics обрабатывать их.
      • Указав местоположение файла GoogleService-Info.plist сборки приложения, вы позволите Crashlytics связать файлы dSYM с приложением Firebase.
      • Указав местоположение исполняемого файла приложения, вы позволите скрипту run предотвращать повторную загрузку одного и того же файла 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_arrowСборка и запуск текущей схемы, чтобы собрать приложение на тестовом устройстве или в симуляторе.

   2. Дождитесь запуска приложения и нажмите stopОстановить выполнение схемы или действия, чтобы закрыть исходный экземпляр приложения. В этом экземпляре был отладчик, который мешает работе Crashlytics.

3. Чтобы принудительно вызвать сбой и отправить первый отчет о нем, выполните следующие действия:

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

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

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

4. В консоли Firebase перейдите на панель DevOps & Engagement > Crashlytics, чтобы проверить отчет о сбое при тестировании.

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

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

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

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

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