Отображение интерактивных уведомлений с помощью Live Activities

Краткий обзор

Live Activities отображают наиболее актуальные данные вашего приложения на заблокированном экране iPhone или iPad и на Dynamic Island, позволяя пользователям получать информацию мгновенно и выполнять быстрые действия, связанные с интерактивными уведомлениями.

Чтобы воспользоваться Live Activities, нужно добавить код в существующее расширение виджета или создать новое расширение виджета, если приложение еще не включает его. Live Activities используют функциональность WidgetKit и SwiftUI в качестве пользовательского интерфейса. Роль фреймворка ActivityKit заключается в управлении жизненным циклом каждого Live Activity: вы используете его API для запроса, обновления и завершения Live Activity, а также для получения push-уведомлений ActivityKit.

Рекомендации по дизайну см. в разделе Human Interface Guidelines > Live Activities.

Ограничения

Live Activity может быть активной до восьми часов, если приложение или пользователь не завершит его до этого срока. По истечении восьми часов система автоматически завершает Live Activity и удаляет ее из Dynamic Island. Однако Live Activity остается на экране блокировки до тех пор, пока пользователь не удалит её, или в течение ещё четырех часов, прежде чем система удалит её — в зависимости от того, что произойдет раньше. В результате Live Activity остается на экране блокировки максимум 12 часов.

Дополнительную информацию о завершении Live Activity см. в разделе «Завершение Live Activity» ниже.

Если вы используется изображение, размер которого превышает размер представления Live Activity, система может не запустить Live Activity. Например, изображение, которое вы используете для минимального представления Live Activity, не должно превышать 45x36,67 точек. Рекомендации по размеру представлений Live Activity см. в разделе Human Interface Guidelines > Live Activities.

Каждое Live Activity, в отличие от виджета, не может получать доступ к сети или обновлению местоположения. Чтобы обновлять динамические параметры активного Live Activity, используется ActivityKit в приложении или разрешение Live Activities получать push-уведомления, как описано в разделе Запуск и обновление Live Activities с помощью ActivityKit push-уведомлений.

Важно!
Статические и динамические параметры ,включая данные обновлений ActivityKit и ActivityKit push-уведомлений, должны быть меньше 4KB.

Добавление поддержки Live Activity в приложение

Live Activities являются частью Widget Extension. Если в приложении уже используются виджеты, то нужно просто добавить код Live Activity в существующее Widget Extension и повторно использовать его между виджетами и Live Activities.Хотя Live Activity и используют функциональность WidgetKit, они не являются виджетами. В отличие от механизма временной шкалы, который используется для обновления пользовательского интерфейса виджетов, Live Activity запускается и обновляется из приложения с помощью ActivityKit или с помощью push-уведомлений ActivityKit.

Примечание:
Можно создать расширение виджета, чтобы использовать Live Activities, без самого виджета. Тем не менее, возможность применения как виджетов, так и Live Activities помогает персонализировать приложение и передавать информацию в более наглядном виде.

Для поддержки приложением Live Activity необходимо:

1. Создать Widget Extension, если в приложении ещё нет виджетов, и убедиться, что выбрана опция «Include Live Activity». Дополнительные сведения о создании расширения Widget Extension см. в разделах WidgetKit и Создание Widget Extension.
2. Если проект включает файл Info.plist, добавить в него поле NSSupportsLiveActivities и выставить ему значение YES. Если Info.plist не включен в проект, то тогда необходимо добавить логический флаг для атрибута Supports Live Activities и установите для него значение YES.
3. Добавить код, определяющий структуру протокола ActivityAttributes для описания статических и динамических параметров Live Activity.
4. Использовать определенные ActivityAttributes для создания ActivityConfiguration, для того чтобы передавать информацию об отображении представлений в Dynamic Island и .
5. Добавить код для настройки, запуска, обновления и завершения Live Activities.
6. Добавить интерактивность Live Activity с помощью Button или Toggle, как описано в разделе Добавить интерактивность виджетам и Live Activities.
7. Добавить анимацию для привлечения внимания к обновлениям данных, как описано в разделе Анимация обновлений данных в виджетах и Live Activities.

Определение статических и динамических данных

После добавления виджета с Live Activities в проект Xcode, необходимо с помощью протокола ActivityAttributes описать данные, которые будет отображать Live Activity. ActivityAttributes сообщают системе о статических данных, которые появляются в Live Activity. ActivityAttributes также используется для объявления структуры Activity.ContentState, которая описывает все те данные, которые будут обновляться динамически. В приведенном ниже примере кода из Apple Developer Documentation AdventureAttributes описывает информацию о герое статическими данными с помощью let Hero: EmojiRanger. Обратите внимание, как код определяет Activity.ContentState для инкапсуляции динамических данных: текущего уровня здоровья героя и строки, описывающей, что происходит с героем.

Подсказка:
Чтобы сделать код более наглядным и простым для чтения, можно определить псевдоним типа для ContentState; например: публичный псевдоним типа HeroStatus = ContentState.

Создание представления на экране блокировки

Для создания UI Live Activity используется SwiftUI в Widget Extension. Как и в случае с виджетами, размер UI для Live Activity не указывается, система сама определяет соответствующие размеры.

Код ниже отображает данные на заблокированном экране, которую описывает структура AdventureAttributes с использованием AdventureLiveActivityView:

Подсказка:
Максимальная высота Live Activity на Lock Screen — 160 точек.

На устройстве, которое не поддерживает Dynamic Island, система отображает только баннер на экране блокировки, если:

• Устройство разблокировано и приложение не используется.
• Вы передаете AlertConfiguration в функцию update(_:alertConfiguration:).

На iPhone в режиме Standby представление на экране блокировки масштабируется до размера экрана устройства. Убедитесь, что ресурсы устройства обеспечивают достаточно высокое разрешение для режима ожидания, а также рассмотрите возможность обновления представления экрана блокировки, чтобы использовать дополнительное пространство. Для определения Standby режима используется isActivityFullscreen.

Компактное и минимальное представления

Live Activity отображается на Dynamic Island только тех устройств, которые его поддерживают. Когда запускается одно или несколько Live Activities и другие приложения не используют Live Activity, то элементы представлений leading side и trailing side отображаются вместе, формируя единый блок информации на Dynamic Island для одного Live Activity.

Расширенное представление Live Activity визуально разделяется на несколько областей. Обратите внимание, как в пример выше возвращается DynamicIsland, который определяет несколько объектов DynamicIslandExpandedRegion. Для размещения контента в указанную позицию расширенного представления передаются следующие значения DynamicIslandExpandedRegionPosition:

• center (размещает контент под камерой TrueDepth)
• leading (размещает контент слева от камеры TrueDepth с захватом области под center)
• trailing (размещает контент справа от камеры TrueDepth с захватом области под center)
• bottom (размещает контент под center, leading и trailing областями).

Чтобы отобразить контент в расширенном представлении Live Activity, система сначала определяет ширину области center, принимая во внимание минимальную ширину leading и trailing областей. Затем система размещает и масштабирует leading и trailing области в зависимости от их вертикального положения. По умолчанию leading и trailing области имеют одинаковое количество горизонтального пространства.

Можно указать системе установить приоритет одного из представлений DynamicIslandExpandedRegion, задав priority в инициализаторе init(_:priority:content:), в результате чего область с наивысшим приоритетом будет растянута на всю ширину Dynamic Island. На следующем рисунке показаны leading и trailing области в расширенном представлении, имеющие более высокий приоритет отображения под камерой.

Примечание:
Если контент слишком широкий и не может отображаться в области leading рядом с камерой TrueDepth, можно использовать модификатор belowIfTooWide для отображения контента под камерой.

Добавление кнопок и toggle-переключателей

Подобно виджетам, начиная с iOS 17 и iPadOS 17, Live Activities могут содержать кнопки и toggle-переключатели SwiftUI для быстрых действий. Например, приложение для заказа еды может отображать в Live Activity кнопку, которую нажимает пользователь для получения заказ на вынос в ресторане.

Для добавления toggle-переключателя или кнопки в Live Activity , используются фреймворк App Intents и инициализаторы для Button и Toggle. Дополнительные сведения об использовании toggle-переключатеей и кнопок в widget extensions, и в том числе в Live Activities, см. в WidgetKit.

Доступная среда в Live Activity

Одним из основных принципов при создании приложений является разработка с учетом доступной среды. И Live Activities не исключение. Чтобы позволить пользователям настраивать способ взаимодействия с Live Activity и убедиться, что VoiceOver для Live Activity работает правильно, необходимо добавить метки доступности (accessibility labels) в SwiftUI, которые создаются для Live Activity. Дополнительные сведения см. в разделе Добавление описания к виджетам и Live Activities.

Доступность Live Activities

Live Activities доступны на iPhone и iPad. Если приложение доступно на других устройствах и предлагает возможность использования виджета, необходимо убедится, что Live Activities обрабатываются корректно на момент выполнения работы приложения. При необходимости функция Live Activity может быть отключена в настройках устройства.

Чтобы узнать, доступны ли Live Activities и разрешил ли пользователь использовать Live Activities в приложении можно:

• Использовать areActivitiesEnabled, чтобы синхронно определить, отображать ли в приложении пользовательский интерфейс для запуска Live Activity.
• Получать асинхронные обновления об изменениях статуса авторизации пользователя с помощью потока activityEnablementUpdates и реагировать на них соответствующим образом.

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

Настройка Live Activity

Прежде чем запускать Live Activity в приложении, необходимо настроить его с помощью структуры ActivityContent. ActivityContent инкапсулирует ActivityAttributes и дополнительную информацию о конфигурации:

• staleDate сообщает системе, когда данные Live Activity устаревают.
• relevanceScore определяет, какие из Live Activities отображаются на Dynamic Island, а также порядок Live Activities на экране блокировки.

Хотя установка staleDate не является обязательной, она весьма полезна для отображения в Live Activity актуальной информации. В определённый момент activityState изменяется на ActivityState.stale, а значение isStale - на true. Доступ к isStale позволяет отслеживать состояние Live Activity и своевременно обновлять информацию. Например, пока пользователь имеет подключение к сети, спортивное приложение может отслеживать состояние Live Activity и обновлять устаревшую дату. Если же пользователь входит в зону без доступа к сети, приложение больше не сможет обновить неактуальную дату и в Live Activity будет представлен текст, указывающий, что отображаемая информация устарела. При следующем запуске приложения или при выполнении фоновых задач приложение сможет реагировать на состояние ActivityState.stale.

Если приложение запускает более одного Live Activity, можно указать оценку релевантности (relevance score), чтобы определить порядок Live Activities на экране блокировки и то, какое из Live Activities будет отображаться на Dynamic Island:

• Если оценка релевантности не указана или если Live Activities имеют одинаковую оценку релевантности, система покажет первое Live Activity, запущенное на Dynamic Island.
• Если были указаны различные оценки релевантности, то на Dynamic Island будет отображено Live Activity с наивысшим показателем.

Система принимает относительные значения оценки релевантности: для приоритетного Live Activity, например, можно указать значение 100, а для менее важных обновлений контента Live Activity — например, 50.

Запуск Live Activity

Запуск Live Activity в коде осуществляется с помощью функции request(attributes:content:pushType:), которой передаются созданные объекты ActivityAttributes и ActivityContent и, при реализации push-уведомления ActivityKit, параметр pushType.

В следующем примере в приложении Emoji Rangers: Supporting Live Activities, interactivity, and animations создаются исходные значения атрибутов и ContentState для Emoji Rangers в Live Activity .

Приложение может запускать Live Activities только тогда, когда оно находится в foreground mode. Для обновления или завершения Live Activity, когда приложение в фоновом режиме, используется Background Tasks.

Также можно активировать возможность обновлений Live Activity с помощью push-уведомлений ActivityKit, для чего нужно передать .token в качестве значения параметра pushType, как показано в примере выше. Для получения уведомлений, нужно отправить pushToken из Live Activity на сервер. Начиная с iOS 17.2 и iPadOS 17.2, Live Activities можно запускать с помощью push-уведомлений ActivityKit. Дополнительные сведения об использовании push-уведомлений ActivityKit см. в разделе Запуск и обновление Live Activities с помощью push-уведомлений ActivityKit.

Анимация контента

Система игнорирует любые модификаторы анимации при определении пользовательского интерфейса Live Activity (например, withAnimation(_:_:) и animation(_:value:)). Однако возможно добавить некоторую анимацию для динамического контента Live Activity, например, анимацию текста, изображений и SF-символов с помощью размытых переходов. Внося изменения в содержимое или состояние контента из пользовательского интерфейса с помощью встроенных переходов вида opacity, move(edge:), slide, push(from:) и их комбинаций, также можно добиться эффекта анимации. Также можно добавить анимацию текст-таймера используя numericText(countsDown:).

Начиная с iOS 17 и iPadOS 17, можно добавлять изменения в данные Live Activity с помощью функций, связанных с контролем времени анимации. Например, можно использовать timingCurve(_:duration:) для создания анимации с собственной кривой времени. Дополнительную информацию об анимации SwiftUI см. в разделе Анимация.

Примечание:
На устройствах с режимом дисплея Always-On анимация не отображается, чтобы продлить срок службы батареи. Рекомендуется использовать значение isLuminanceReduced, чтобы обнаружить пониженную яркость до внесения изменений в анимацию контента.

Обновление и завершение Live Activity с помощью push-уведомлений

Помимо обновления и завершения Live Activity из приложения с помощью ActivityKit, можно обновить или завершить Live Activity с помощью push-уведомлений ActivityKit, которые отправляются со своего сервера в службу push-уведомлений Apple (APNs). Начиная с iOS 17.2 и iPadOS 17.2, push-уведомления ActivityKit также могут запускать Live Activities. Дополнительные сведения об использовании push-уведомлений ActivityKit см. в разделе Запуск и обновление Live Activity с помощью push-уведомлений ActivityKit.