Инструментирование элементов управления SwiftUI

ЕдиныйАгент для iOS версии 8.249+

После инструментирования вашего мобильного приложения с помощью ЕдиныйАгент для iOS, вам может потребоваться также инструментировать SwiftUI-элементы вашего приложения. Эта страница содержит дополнительную информацию о том, как настроить ваш проект, обновить SwiftUI instrumentor, преодолеть некоторые известные ограничения и многое другое.

Для инструментирования элементов управления SwiftUI, SwiftUI instrumentor добавляет дополнительный код в исходный код вашего проекта (файлы *.swift) в процессе сборки. Этот код отслеживает состояние элементов пользовательского интерфейса и уведомляет ЕдиныйАгент для iOS обо всех обновлениях. После завершения процесса сборки все изменения в исходном коде вашего проекта отменяются.

❗ Важно Для получения подробной информации о действиях, выполняемых SwiftUI instrumentor, и копии измененных файлов кода проверьте каталог АппОптима_instrumented. SwiftUI instrumentor создает резервные копии инструментированных файлов и сгенерированных журналов в формате ZIP-архива.

1. Требования

• SwiftUI version 2.0+
• iOS 14+
• ЕдиныйАгент for iOS

2. Поддерживаемые элементы управления

• Button
• Stepper
• Picker
• Toggle
• Slider

3. Необходимые шаги

1. Создайте приложение в веб-интерфейсе АппОптима.
2. Настройте ЕдиныйАгент для своего проекта
3. Установите SwiftUI instrumentor

4. Управление SwiftUI instrumentor

4.1. Установка SwiftUI instrumentor

Для инструментирования элементов управления SwiftUI в вашем приложении установите

АппОптима SwiftUI instrumentor. Вы можете сделать это через Homebrew или вручную.

Homebrew

Вручную

Запустите команду brew tap АппОптима/tools, чтобы добавить один из АппОптима taps. Запустите команду brew install DTSwiftInstrumentor, чтобы установить SwiftUI instrumentor. Закройте Xcode и выполните команду DTSwiftInstrumentor install <PROJECT.xcodeproj> --scheme <SCHEME> --target <TARGET>.

Скачайте и распакуйте ZIP-файл, содержащий наш SwiftUI instrumentor. Ссылка на файл доступна в мастере мобильной инструментации (mobile instrumentation wizard). Создайте папку .АппОптима в корне вашего проекта - на том же уровне, что и файл *.xcodeproj. ❗ Важно Если вы получаете системное предупреждение о том, что вы не можете создать папку с именем, начинающимся с точки, выполните одно из следующих действий: В терминале запустите команду mkdir .АппОптима в корне проекта, чтобы создать папку .АппОптима. В терминале запустите команду defaults write com.apple.finder AppleShowAllFiles true и killall Finder, чтобы показать скрытые папки и файлы. Затем в Finder создайте папку .АппОптима. Вы также можете выполнить команду defaults write com.apple.finder AppleShowAllFiles false и killall Finder, чтобы снова скрыть скрытые папки и файлы. 3. Скопируйте загруженный DTSwiftInstrumentor в папку .АппОптима и убедитесь, что файл можно выполнить (executable). 4. Выйдите из Xcode и выполните команду .АппОптима/DTSwiftInstrumentor install <PROJECT.xcodeproj> --scheme <SCHEME> --target <TARGET>.

❗ Важно

Если при реализации возникнет ошибка, проверьте журнал сборки Xcode или журнал инструментации для получения подробной информации об ошибке. Дополнительные подсказки см. в разделе Устранение неполадок.

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

4.2. Обновление SwiftUI instrumentor

Когда новая версия SwiftUI будет доступна, вы сможете обновить ее через Homebrew или вручную.

Homebrew	Вручную
Как только новая версия инструмента будет выпущена, она будет загружаться через добавленный tap. Чтобы обновить SwiftUI instrumentor, запустите команды brew update и brew upgrade DTSwiftInstrumentor.	Скачайте и разархивируйте ZIP-файл, содержащий новую версию SwiftUI instrumentor. Ссылка доступна в мастере мобильной инструментации (mobile instrumentation wizard). Скопируйте загруженный DTSwiftInstrumentor в папку .АппОптима и замените существующий файл.

❗ Важно

Если вы видите следующее предупреждение при сборке, вам также нужно обновить скрипты сборки, которые были интегрированы во время установки АппОптима SwiftUI instrumentor.

АппОптима: There is an upgrade for your project instrumentation. Please execute "DTSwiftInstrumentor project-upgrade <PROJECT.xcodeproj>" to upgrade your project

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

4.3. Удаление SwiftUI instrumentor

Если вам больше не нужен АппОптима SwiftUI instrumentor, вы можете удалить его из системы с помощью Homebrew или вручную удалить его из своего проекта.

Homebrew

Вручную

Выполните команду brew remove DTSwiftInstrumentor и brew untap АппОптима/tools, чтобы удалить SwiftUI instrumentor из вашей системы.

Запустите DTSwiftInstrumentor uninstall <PROJECT.xcodeproj>, чтобы удалить SwiftUI instrumentor из вашего проекта. (Опционально) Удалите папки .АппОптима и АппОптима_instrumented из вашего проекта. Эти папки содержат кэш, данные журналов и, при наличии, вручную установленный бинарный файл инструментария. Они содержат кэш инструментария, данные журналов и, при наличии, бинарные файлы инструментария.

5. Проверьте различия инструментирования SwiftUI

ЕдиныйАгент для iOS версии 8.257+

Для проверки различий между вашим исходным кодом и кодом, измененным SwiftUI instrumentor, выполните одну из следующих команд:

• Из корневой директории проекта выполните одну из следующих команд, чтобы проверить разницу между вашим и измененным инструментом SwiftUI:
  • DTSwiftInstrumentor diff, если вы установили инструмент с помощью Homebrew
  • .АппОптима/DTSwiftInstrumentor diff, если вы установили инструмент вручную
• Из любой директории:
  • DTSwiftInstrumentor diff <путь-к-корневой-директории-проекта>

6. Известные ограничения

6.1. Инструментирование пользовательских элементов управления SwiftUI не поддерживается

В настоящее время АппОптима не поддерживает инструментирование пользовательских элементов управления SwiftUI. Список элементов управления SwiftUI, которые можно инструментировать, можно найти в разделе Поддерживаемые элементы управления.

6.2. Проблемы с предпросмотром в Xcode.

Когда сборка симулятора включала инструменты SwiftUI, предварительные просмотры не загружались в Xcode. В качестве обходного пути мы отключили инструментарий SwiftUI для сборок симулятора. Если вы хотите добавить инструментарий SwiftUI в сборки симулятора, см. Сборки симулятора инструментов.

6.3. Только SwiftUI 2.0+

АппОптима поддерживает инструментирование SwiftUI 2.0+ потому, что listener onChange недоступен в более ранних версиях SwiftUI. Поэтому требуется версия iOS 14+ для целевой платформы.

6.4. Более длительное время сборки

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

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

• Собирайте приложение только для устройств (Device). Если вы решили инструментировать сборки для симулятора, отключите эту функцию.
• Не запускайте инструментирование SwiftUI на каждой возможной сборке. Мы рекомендуем запускать инструментирование SwiftUI на ветках, таких как main или release.

6.5. Несовместимость с watchOS

Невозможно скомпилировать проект, содержащий файлы, добавляемые в цель watchOS, поскольку ЕдиныйАгент для watchOS отсутствует. В этом случае вручную исключите все файлы, которые используются совместно или являются частью цели watchOS.

6.6. tvOS не поддерживается

В настоящее время официальной поддержки сборок tvOS SwiftUI нет.

7. Настройка инструментирования SwiftUI

7.1. Включить повтор сеанса (Session Replay) при сбоях

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

7.2. Исключить файлы из SwiftUI instrumentor

По умолчанию, инструментатор АппОптима SwiftUI обрабатывает все файлы с расширением .swift, но инструментирует только файлы, содержащие поддерживаемые элементы управления. Если необходимо, вы можете исключить определенные файлы и директории из процесса инструментирования SwiftUI.

Чтобы исключить файлы и директории из процесса инструментирования SwiftUI:

1. Добавьте ключ конфигурации DTXExcludedSwiftUIFiles в файл Info.plist вашего проекта.
2. Перечислите относительные пути ко всем файлам и каталогам, которые вы не хотите инструментировать. Пути должны указываться относительно корня проекта, то есть каталога, в котором находится файл .xcodeproj.

<key>DTXExcludedSwiftUIFiles</key>

<array>

<string>relative/file/path/</string>

<string>relative/file.swift</string>

</array>

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

7.3. Сборки симулятора инструментов

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

Чтобы включить инструменты SwiftUI для сборок симулятора, добавьте ключ конфигурации DTXSwiftUIInstrumentSimulatorBuilds в файл Info.plist вашего проекта и установите для этого ключа значение true.

<key>DTXSwiftUIInstrumentSimulatorBuilds</key>

<true/>

7.4. Создание сборок для неподдерживаемых целей развертывания

SwiftUI instrumentor генерирует код, совместимый со SwiftUI 2.0+, который работает только на устройствах с iOS 14+. Попытка создать сборки для целей развертывания iOS 13 и более ранних версий завершится ошибкой.

Чтобы переопределить эту проверку, добавьте ключ конфигурации DTXSwiftUIIgnoreDeploymentTarget в файл Info.plist вашего проекта и установите для этого ключа значение true.

<key>DTXSwiftUIIgnoreDeploymentTarget</key>

<true/>

7.5. Включить сопоставление номеров строк для проектов Objective-C

Отчеты о сбоях, доступные в АппОптима, не основаны на исходном коде вашего проекта. Эти отчеты основаны на измененном коде, который АппОптима генерирует во время инструментирования. Вот почему сопоставление номеров строк добавляется в ваш проект во время инструментирования, а затем передается в АппОптима при запуске приложения. В противном случае номера строк в отчетах о сбоях будут неверными.

По умолчанию АппОптима SwiftUI instrumentor создает сопоставление номеров строк и вставляет его в основной класс вашего проекта. Это происходит автоматически для проектов с основным классом Swift, но не для устаревших проектов Objective-C. Для таких проектов вы получите сообщение об ошибке, и наш инструментарий SwiftUI не будет инструментировать ваше мобильное приложение.

Чтобы включить сопоставление номеров строк для проектов Objective-C

1. Добавьте ключ конфигурации DTXSwiftUIManualPlaceholder в файл Info.plist вашего проекта и установите для этого ключа значение true.

<key>DTXSwiftUIManualPlaceholder</key>

<true/>

1. Добавьте в основной класс специальный placeholder AppDelegate.m.
2. Добавьте [АппОптима setSwiftUiMapping:@"_АппОптима_SWIFTUI_MAPPING_PLACEHOLDER_"]; к основному классу либо в методе init, либо в методе didFinishLaunchingWithOptions.

Во время сборки, SwiftUI instrumentor заменяет часть этой строки сгенерированным сопоставлением номеров строк.

7.6. Включить автоматическую очистку журнала

ЕдиныйАгент для iOS версии 8.257+

После каждой сборки SwiftUI instrumentor создает резервные копии инструментированных файлов и сгенерированных журналов, которые хранятся в каталоге АппОптима_instrumented. По умолчанию эти файлы не удаляются, и общий размер каталога со временем будет расти. По этой причине мы рекомендуем вам включить автоматическую очистку журнала.

• Чтобы удалить журналы SwiftUI instrumentor после определенного количества сборок, добавьте ключ конфигурации DTXCleanSwiftUILogsByCount в файл Info.plist вашего проекта.

<key>DTXCleanSwiftUILogsByCount</key>

<number>10</number>

• Чтобы удалить журналы через определенное количество дней, добавьте ключ конфигурации DTXCleanSwiftUILogsByAgeDays в файл Info.plist.

<key>DTXCleanSwiftUILogsByAgeDays</key>

<number>5</number>

Если вы добавите оба ключа в файл Info.plist, ключ DTXCleanSwiftUILogsByAgeDays будет иметь приоритет.

8. Устранение неполадок

Мы все еще работаем над улучшением процесса инструментирования SwiftUI. Если у вас возникнут какие-либо проблемы при инструментировании элементов управления SwiftUI, обратитесь в службу поддержки АппОптима и предоставьте файл журнала затронутой сборки. Вы можете найти файл журнала самой последней сборки по пути АппОптима_instrumented/current/instrumentation.log. Файлы журналов предыдущих сборок находятся в архивах с отметками времени в разделе АппОптима_instrumented.

8.1. Инструментация уже работает

Если у вас возникла проблема с АппОптима SwiftUI instrumentor, и он не был восстановлен автоматически, выполните шаги, описанные ниже.

1. Остановите процесс DTSwiftInstrumentor, если он все еще существует.
2. Если вы видите изменения, сделанные SwiftUI instrumentor в исходном коде вашего проекта, выполните следующую команду в корне проекта:

• DTSwiftInstrumentor restore . если вы установили инструмент через Homebrew
• .АппОптима/DTSwiftInstrumentor restore . если вы установили инструмент вручную

8.2. DTSwiftInstrumentor завершил работу с ошибкой при обработке <filename>

Бинарный файл SwiftUI instrumentor дал сбой. Обратитесь в службу поддержки АппОптима и предоставьте файл журнала затронутой сборки.