API для iOS Live Activities

Документация Apple:

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

Чтобы элемент Journey “Live Activity” мог создавать форму состояния контента из названий полей, а не из редактора необработанного JSON, опубликуйте схему для вашего attributes-type — см. API схем Live Activity.

startLiveActivity

POST https://api.pushwoosh.com/json/1.3/startLiveActivity

Позволяет создавать iOS Live Activities.

Тело запроса

Параметр	Тип	Обязательный/Необязательный	Описание
application	String	Обязательный	Код приложения Pushwoosh
auth	String	Обязательный	Токен доступа API из Pushwoosh Control Panel.
notifications	Array	Обязательный	Массив JSON с параметрами сообщения. Подробности см. в таблице Notifications ниже.

Notifications

Параметры, используемые в массиве notifications:

Параметр	Тип	Обязательный/Необязательный	Описание
content	String	Обязательный*	Тело оповещения для push-уведомления, которое запускает Live Activity, и резервный текст, отображаемый на устройствах с версиями iOS ниже 16.1.
title	String	Обязательный*	Заголовок оповещения для push-уведомления, которое запускает Live Activity.
live_activity	Object	Обязательный	Данные Live Activity для создания Live Activity в iOS.
live_activity.content-state	Object	Обязательный	Контент для уведомления Live Activity.
live_activity.attributes-type	String	Обязательный	Тип атрибутов, используемых в Live Activity.
live_activity.attributes	Object	Обязательный	Атрибуты для Live Activity.
live_activity_id	String	Обязательный	Уникальный идентификатор для Live Activity. Используется для таргетинга этой активности при вызове updateLiveActivity. Должен быть уникальным для каждой сессии активности.
filter	String	Необязательный	Название фильтра (сегмента) Pushwoosh. См. Название сегмента / фильтра. Live Activity будет запущена на всех устройствах, соответствующих этому фильтру.
devices	Array of Strings	Необязательный	Список токенов устройств. Live Activity будет запущена только на указанных устройствах.
send_date	String	Необязательный	Планирует push-уведомление, которое запускает Live Activity, на определенную дату и время — работает с таргетингом как по filter, так и по devices. Используйте формат YYYY-MM-DD HH:mm или now для немедленного запуска (это также значение по умолчанию, если параметр опущен). Дата должна быть не более чем на 1 день в прошлом или на 30 дней в будущем, иначе запрос будет отклонен с ошибкой валидации.
timezone	String	Необязательный	Часовой пояс, используемый для интерпретации send_date. Если опущен, send_date интерпретируется в UTC.
apns_priority	Integer	Необязательный	Управляет приоритетом доставки APNs для этого push-уведомления Live Activity. Принимает 10 (высокий приоритет, доставляется с заголовком apns-priority: 10 для мгновенного отображения на заблокированном экране) или 5 (низкий приоритет, доставляется с apns-priority: 5 для экономии заряда батареи устройства). Любое другое значение рассматривается как 5, без ошибки валидации. Каждое push-уведомление Live Activity по умолчанию имеет приоритет 5, независимо от того, содержит ли оно контент оповещения (content/title) — установите apns_priority: 10 явно, чтобы запросить доставку с высоким приоритетом. См. Time Sensitive Push и приоритет доставки ниже.

Примечание: * Хотя бы одно из полей content или title должно быть непустым. Pushwoosh отклоняет запрос на запуск, если оба поля пусты.

Осторожно

Удаленный запуск Live Activity через startLiveActivity требует iOS 17.2+ на устройстве — более ранние версии не поддерживают API pushToStartTokenUpdates, на который опирается эта конечная точка. См. Запуск Live Activity с помощью удаленного push-уведомления.

При таргетинге на filter (сегмент) запланированное время отправки — это время, когда Pushwoosh начинает рассылку push-уведомлений, а не гарантированный момент доставки. Для больших аудиторий доставка на отдельные устройства может отставать от send_date на несколько минут, так как скорость отправки для push-уведомлений Live Activity не может быть настроена с помощью send_rate.

Повторные вызовы для запуска через push-уведомления исчерпывают лимит без уведомлений. Примерно после десяти быстрых запусков подряд Apple прекращает доставку соответствующего push-уведомления для запуска без какой-либо ошибки, и startLiveActivity по-прежнему возвращает 200. Во время тестирования кампании это выглядит так: “API работает, но на устройстве ничего не происходит”. Делайте паузы между последовательными тестовыми запусками.

Пример запроса

С фильтром

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "apns_priority": 10,
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "FIRST_LIVE_ACTIVITY",
        "filter": "FILTER_NAME_1"
      }
    ]
  }
}

С устройствами

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "apns_priority": 10,
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "SECOND_LIVE_ACTIVITY",
        "devices": ["first_third", "second_device"]
      }
    ]
  }
}

Запланированный запуск

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "content": "Your order is being prepared",
        "title": "Food Delivery",
        "live_activity": {
          "event": "start",
          "title": "Order status",
          "content-state": {
            "status": "Third",
            "estimatedTime": "37 min",
            "emoji": "👨‍🍳"
          },
          "attributes-type": "FoodDeliveryAttributes",
          "attributes": {}
        },
        "live_activity_id": "THIRD_LIVE_ACTIVITY",
        "filter": "FILTER_NAME_1",
        "send_date": "2026-06-16 16:00"
      }
    ]
  }
}

Пример ответа

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}

Примечание:

Прочтите эту статью, чтобы узнать больше о работе с Live Activities с помощью Pushwoosh iOS SDK.

updateLiveActivity

POST https://api.pushwoosh.com/json/1.3/updateLiveActivity

Позволяет обновлять и завершать iOS Live Activities

Тело запроса

Параметр	Тип	Обязательный/Необязательный	Описание
auth	String	Обязательный	Токен доступа API из Pushwoosh Control Panel.
application	String	Обязательный	Код приложения Pushwoosh
notifications	Array	Обязательный	Массив JSON с параметрами сообщения. Подробности см. в таблице Notifications ниже.

Notifications

Параметры, используемые в массиве notifications:

Параметр	Тип	Обязательный/Необязательный	Описание
live_activity	Object	Обязательный	Данные Live Activity для обновления Live Activity в iOS.
live_activity.event	String	Обязательный	Указывает тип события. Используйте "update", чтобы обновить Live Activity, или "end", чтобы закрыть ее.
live_activity.content-state	Object	Обязательный	Объект с парами “ключ-значение”, используемый для передачи данных в Live Activity для обновления ее контента.
live_activity.dismissal-date	Integer	Необязательный	Время (в секундах), когда Live Activity должна завершиться. При end не указывайте это поле, чтобы карточка продолжала показывать последний content-state, пока iOS сама не снимет её — см. примечание ниже. Укажите дату в прошлом, чтобы вместо этого карточка была снята сразу же по получении этого обновления.
live_activity_id	String	Обязательный	Уникальный идентификатор Live Activity для обновления. Должен совпадать с live_activity_id, использованным в startLiveActivity. Обновление будет доставлено на все устройства, на которых была запущена эта активность.
live_activity.relevance-score	Integer	Необязательный	Сообщает системе iOS, какая Live Activity имеет более высокий приоритет, чем другие. Принимает значения от 1 до бесконечности (рекомендуются значения до 100).
live_activity.stale-date	Integer	Необязательный	Время (в секундах), представляющее дату, когда Live Activity становится устаревшей или неактуальной.
apns_priority	Integer	Необязательный	Управляет приоритетом доставки APNs для этого push-уведомления Live Activity. Принимает 10 (высокий приоритет, доставляется с заголовком apns-priority: 10 для мгновенного отображения на заблокированном экране) или 5 (низкий приоритет, доставляется с apns-priority: 5 для экономии заряда батареи устройства). Любое другое значение рассматривается как 5, без ошибки валидации. Каждое push-уведомление Live Activity по умолчанию имеет приоритет 5, независимо от того, содержит ли оно контент оповещения (content/title) — установите apns_priority: 10 явно, чтобы запросить доставку с высоким приоритетом. См. Time Sensitive Push и приоритет доставки ниже.
content	String	Необязательный	Тело оповещения для этого обновления. Обычный случай — это обновление только content-state, при котором не устанавливаются ни content, ни title, ни subtitle, и оповещение вообще не отправляется.
title	String	Необязательный	Заголовок оповещения для этого обновления. Установка content, title или subtitle вызывает оповещение и позволяет воспроизвести ios_sound. Если ни одно из этих трех полей не установлено, обновление остается беззвучным, что является поведением по умолчанию для обновлений только content-state.
subtitle	String	Необязательный	Подзаголовок оповещения для этого обновления. Играет ту же роль в вызове оповещения, что и content/title выше.
ios_sound	String	Необязательный	Имя звукового файла в основном бандле приложения. Он передается внутри aps.alert вместе с content/title/subtitle, а не в aps.sound верхнего уровня, который ActivityKit игнорирует для Live Activities, поэтому он воспроизводится только тогда, когда это обновление также устанавливает хотя бы одно из этих трех полей. iOS также самостоятельно ограничивает частоту оповещений Live Activity. Наблюдалось, что одна и та же полезная нагрузка доставляется со звуком при одной доставке и без него при следующей, как на устройстве, так и в симуляторе.

Примечание: relevance-score влияет только на порядок отображения нескольких активных Live Activities на одном устройстве — он не влияет на срочность доставки. Используйте apns_priority для управления срочностью доставки обновления.

Примечание

end без dismissal-date не удаляет карточку. Она остаётся на экране блокировки, показывая тот content-state, который был отправлен этим обновлением, а собственная система Live Activity в Apple снимает её сама в течение до 4 часов.

Пример запроса

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "apns_priority": 10,
        "title": "Live Activity Update",
        "live_activity": {
          "event": "update",
          "content-state": {
            "status": "second 66",
            "estimatedTime": "66 min",
            "emoji": "👨‍"
          },
          "relevance-score": 60
        },
        "live_activity_id": "FIRST_LIVE_ACTIVITY"
      }
    ]
  }
}

Пример ответа

{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "Messages": [
      "XXXXX-XXXXXXXX-XXXXXXXX"
    ]
  }
}

Прочтите эту статью, чтобы узнать больше о работе с Live Activities с помощью Pushwoosh iOS SDK.

Time Sensitive Push и приоритет доставки

По умолчанию Apple доставляет обновления Live Activity с низким приоритетом (apns-priority: 5) для экономии заряда батареи. Когда устройство заблокировано, низкоприоритетное обновление обрабатывается в фоновом режиме и становится видимым на экране блокировки только после того, как пользователь разблокирует устройство. На уже разблокированном устройстве оно все равно отображается мгновенно. Используйте параметр apns_priority, описанный выше, чтобы запросить доставку с высоким приоритетом (apns-priority: 10), чтобы обновление немедленно отображалось на экране блокировки без необходимости разблокировки.

Не связано с переключателем Time Sensitive Push

Переключатель Time Sensitive Push в Pushwoosh Control Panel устанавливает interruption-level только для стандартных push-уведомлений. Он не влияет на приоритет доставки Live Activity, отправляемых через этот API — Live Activities используют отдельный путь доставки, который контролируется исключительно параметром запроса apns_priority.

Даже при наличии apns_priority: 10, Apple ограничивает частоту его использования.

Бюджет высокоприоритетных уведомлений APNs

Apple ограничивает количество высокоприоритетных (apns-priority: 10) push-уведомлений, которые приложение может отправлять в час. Для часто обновляемых активностей (например, текущие результаты матчей) зарезервируйте apns_priority: 10 для критически важных событий и используйте apns_priority: 5 или меньшее количество обновлений для рутинных изменений. Включение NSSupportsLiveActivitiesFrequentUpdates в Info.plist вашего приложения (см. руководство по iOS SDK) увеличивает этот бюджет для случаев использования с высокой частотой.

Несколько активностей на одном устройстве

Вы можете запустить несколько Live Activities на одном устройстве, вызвав startLiveActivity несколько раз с разными значениями live_activity_id.

Например, если вы запускаете две активности: FIRST_LIVE_ACTIVITY с filter: FILTER_NAME_1 и SECOND_LIVE_ACTIVITY с filter: FILTER_NAME_2, на устройстве, которое соответствует обоим фильтрам, обе активности будут работать одновременно.

Чтобы обновить одну из них, передайте ее live_activity_id в updateLiveActivity. Обновление будет доставлено на все устройства, где была создана эта активность. Другая активность не будет затронута.

Параметр relevance-score управляет приоритетом отображения, когда на одном устройстве активно несколько Live Activities. Если место на экране ограничено или активности сгруппированы, активность с более высоким значением будет показана с более высоким приоритетом.