API для iOS Live Activities

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

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

startLiveActivity

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

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

Тело запроса

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

Notifications

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

Параметр	Тип	Обязательный/Необязательный	Описание
content	String	Обязательный	Резервный контент для устройств с версиями iOS ниже 16.1, которые не поддерживают Live Activity. На iOS 16.1+ (с поддержкой Live Activity) контент берется из поля live_activity.
title	String	Необязательный	Заголовок уведомления.
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 и приоритет доставки ниже.

Осторожно

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

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

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

С фильтром

{
  "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.
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 должна завершиться.
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 и приоритет доставки ниже.

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

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

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "SECRET_API_TOKEN",
    "notifications": [
      {
        "apns_priority": 10,
        "live_activity": {
          "event": "update",
          "title": "Live Activity 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 устанавливает 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. Если место на экране ограничено или активности сгруппированы, активность с более высоким значением будет показана с более высоким приоритетом.