Live Activity

Live Activity — это карточка, которая обновляется в реальном времени, чтобы пользователь видел прогресс, не открывая приложение (статус рейса, доставка, поездка и подобное). На iOS это небольшая карточка на экране блокировки и в Dynamic Island. На Android 16 и новее это такая же карточка, которая показывается как постоянное уведомление с индикатором прогресса.

Используйте элемент Live Activity в journey, чтобы запустить, обновить или завершить такую карточку на iOS, Android или на обеих платформах.

Каждый элемент выполняет одно действие:

• Start: создать карточку.
• Update: изменить существующую карточку.
• End: закрыть карточку.

Чтобы позже изменить или закрыть ту же карточку, добавьте ещё один элемент Live Activity и укажите в Card created by тот элемент, который создал карточку.

Примеры использования

Используйте этот элемент всякий раз, когда пользователь должен видеть постоянно меняющийся статус, не открывая приложение.

• Статус рейса: покажите карточку после регистрации. Поддерживайте актуальность выхода на посадку, статуса и времени во время полёта. Удалите карточку после посадки.
• Доставка еды: покажите карточку при оформлении заказа. Поддерживайте актуальность имени курьера, времени прибытия и расстояния в пути. Удалите карточку при доставке.
• Заказ такси: покажите карточку при запросе поездки. Поддерживайте актуальность водителя, времени прибытия и номера машины, пока водитель приближается. Удалите карточку по завершении поездки.
• Заказ или запись: покажите карточку при подтверждении заказа или бронирования. Поддерживайте актуальность статуса по мере продвижения. Удалите карточку, когда заказ выполнен или визит завершён.
• Прямая трансляция события: покажите карточку при начале события. Поддерживайте актуальность счёта, периода или расписания, пока событие идёт. Удалите карточку по завершении события.

Совет

Полные примеры journey см. в Как показать статус рейса на экране блокировки и Как показать прогресс доставки на экране блокировки.

Предварительные требования

Перед настройкой этого элемента проверьте, что нужно каждой платформе.

Для карточки iOS:

• Поддержка iOS Live Activity: ваше приложение должно поддерживать Live Activities. См. руководство iOS SDK по Live Activities.
• Опубликованная схема виджета: попросите команду разработки опубликовать схему, соответствующую типу Live Activity в приложении, в разделе Applications → Configure → Live Activity schemas. Они также могут опубликовать схему через API. О том, что должно входить в схему, см. Написание схемы.
• Виджет в списке: после публикации схемы выберите её в поле Widget в этом элементе. Если список Widget пуст, схема ещё не опубликована.

Для уведомления Android:

• Поддержка Android Live Updates: вашему приложению нужны SDK 6.11+ и модуль pushwoosh-liveupdates. Для Android схема не нужна. Попросите Android-разработчика подтвердить, что модуль включён в сборку.

Настройте элемент

1. Перетащите элемент Live Activity на холст.

   

2. Дважды нажмите на элемент, чтобы открыть его настройки.

3. Введите имя в поле Step name.

4. В поле Action выберите один из вариантов:

   • Start: создать карточку Live Activity.
   • Update: изменить содержимое существующей карточки.
   • End: закрыть карточку.

5. В разделе Platforms включите iOS Live Activity, Android Live Updates или обе платформы. Хотя бы одна платформа должна оставаться включённой, поэтому последнюю выключить нельзя. При Update и End раздел Platforms показывает платформы из связанного элемента Start и доступен только для чтения.

   

6. Только для Start задайте ключ карточки, чтобы последующие шаги Update и End могли найти эту карточку:

   • В поле Card key: event выберите событие, идентифицирующее карточку (например, событие входа в journey).
   • В поле Card key: attribute выберите атрибут, который делает ключ уникальным для каждого путешественника. Это обязательно, если задано Card key: event. Если оставить его пустым, выбор события не будет иметь эффекта — так же, как если оставить оба поля пустыми: одна карточка на путешественника, адресуемая по User ID по умолчанию.

   

Свяжите Update и End с нужной карточкой

Когда Action — это Update или End, используйте Card created by, чтобы указать точный элемент Start, создавший эту карточку. Иначе Update или End её не найдёт.

1. В поле Card created by выберите Step name того элемента Start (например, Order card start).

После выбора Card created by поле Card key (from the start element) показывает значения Card key: event и Card key: attribute из этого Start. Это поле доступно только для чтения и подтверждает, на какую карточку указывает этот элемент.

Примечание

Пример: Start назван Order card start. В Update и End выберите Order card start в Card created by. Оба шага тогда изменяют или закрывают ту же карточку заказа.

Выберите язык карточки

Card language применяется и к карточке iOS, и к уведомлению Android.

Установите Card language на default или конкретный код языка. Содержимое под default — резервный вариант для любого языка, который вы не заполнили отдельно.

Настройте карточку iOS

Пропустите этот раздел, если включена только платформа Android Live Updates.

Выберите виджет и версию схемы

1. В поле Widget выберите опубликованный тип Live Activity для этой карточки. Поля содержимого ниже зависят от этого выбора. При Update или End поле Widget доступно только для чтения и наследуется от элемента Card created by.

2. В поле Schema version выберите, какую опубликованную версию схемы этого виджета использовать. Поля Card content берутся из этой версии. При Update и End поле Schema version остаётся выбираемым: вы можете выбрать другую опубликованную версию того же унаследованного виджета, отличную от той, что использовал связанный Start.

   

Задайте фиксированные атрибуты карточки (только Start)

В Start, в разделе Card attributes, добавьте поля, которые остаются фиксированными на весь срок жизни карточки, задаются один раз и больше не меняются — например, номер рейса или ID заказа. Они отдельны от полей Card content ниже. Те значения могут меняться при Update.

Спросите у вашего iOS-разработчика точный список Field name. Эти имена остаются фиксированными на весь срок жизни карточки (тип ActivityAttributes приложения). Не используйте изменяющиеся имена Card content (тип ContentState приложения).

1. Нажмите Add attribute.
2. Задайте Field name и Value для каждого нужного атрибута.

Update и End не задают атрибуты. То, что задал Start для этой карточки, остаётся неизменным.

Осторожно

Атрибуты карточки отправляются точно так, как ожидает тип ActivityAttributes вашего приложения, поле за полем. Ошибка в имени или пустое значение — и декодер устройства отклонит весь payload. В одном реальном тесте Start с flightNumber открыл карточку, а Start без атрибутов доставил только конверт, без чего-либо для показа на экране блокировки.

Заполните содержимое карточки

В разделе Card content введите буквальное значение или плейсхолдер персонализации в каждое поле. Одно поле отображается на каждое свойство в выбранной версии схемы.

Предзаполнение при Update и End

При Update или End, если Card content для текущего Card language пусто (включая только что добавленный язык), Pushwoosh предзаполняет поля из связанного элемента Start при открытии настроек:

• Тот же язык, что и в Start, если для этого языка есть содержимое.
• Иначе содержимое default из Start.
• Если у Start нет ни того, ни другого, оставьте поля пустыми и заполните их сами.

Предзаполненные значения остаются редактируемыми. Нажмите Apply, только если хотите сохранить изменения. Само по себе открытие элемента не меняет уже запущенный journey.

Поля, которые вы оставите пустыми при Update или End, не отправляются. Что карточка затем покажет в этих полях, зависит от вашего приложения: оно может сохранить предыдущее значение, очистить его или сделать что-то ещё. Спросите у команды разработки, как ваше приложение это обрабатывает.

При End поле Card content необязательно. Заполненное вами поле становится последним значением, показанным перед закрытием карточки.

Настройте приоритет и время доставки

1. В Delivery priority выберите, когда iOS должна доставить это обновление:

   • Immediate: iOS доставляет немедленно и может разбудить телефон (и воспроизвести звук, если он задан).
   • Quiet: iOS может доставить позже вместе с другими обновлениями и не будит телефон сразу.
   • Default (batched): iOS использует собственную стандартную пакетную доставку и не будит телефон сразу.

2. В Sound выберите звук из списка. Ваша команда разработки добавляет звуковые файлы в бандл iOS-приложения. См. Пользовательский звук push-уведомления. Звук воспроизводится только вместе с Alert title или Alert text, как и баннер.

3. В зависимости от заданного для этого элемента Action (Start, Update или End) заполните одно из следующего:

   • Start или Update: задайте Stale after, min — сколько минут данные на карточке должны выглядеть актуальными. По истечении этого времени iOS затемняет цифры как устаревшие. Карточка остаётся на экране блокировки. Чтобы цифры продолжали выглядеть актуальными, отправьте ещё один Update до истечения этого времени.
   • End: задайте Dismiss after, min — сколько времени закрытая карточка остаётся на экране блокировки, прежде чем iOS её удалит. Оставьте 0, и карточка продолжит показывать своё финальное Card content, пока iOS сама не уберёт её, в течение до 4 часов.

4. При желании задайте Relevance score — число от 1 до 100. Если у человека одновременно активно более одной Live Activity из вашего приложения, iOS сначала показывает ту, у которой оценка выше. Оставьте 0, чтобы не задавать предпочтение. Pushwoosh вообще не отправляет оценку 0 в Apple. Полную картину см. в Несколько активностей на устройство.

Заполните уведомление Android

Заполните заголовок, текст, индикатор прогресса и время в заголовке уведомления Android. Этот раздел появляется, только когда включена платформа Android Live Updates. Он использует тот же Card language, что и карточка iOS.

1. Задайте Notification title для каждого языка, который вы заполняете для Android. При Start и Update journey не запустится, пока у каждого из этих языков нет заголовка. Для языка без заголовка в форме показывается напоминание.

2. Задайте Notification text.

   

3. Настройте индикатор прогресса:

   • Progress: введите число или плейсхолдер в формате {name} (при необходимости {name|format} или {name|format|default}), определяющий положение индикатора, в тех же единицах, что и длины сегментов.
   • Segments: нажмите Add segment для каждой цветной части индикатора и задайте для каждой hex-цвет Color (#RRGGBB или #AARRGGBB) и длину Length. Сумма длин сегментов составляет весь индикатор.
   • Animate the bar without a known end: включите, чтобы показывать движущийся индикатор вместо значения Progress.
   • Hide the progress bar: включите, чтобы показывать карточку без индикатора.

   

4. Задайте время в заголовке:

   • Header time: введите Unix timestamp в секундах (не в миллисекундах) или плейсхолдер — момент, который должны показывать часы в заголовке карточки. Например, 1735689600 означает 2025-01-01 00:00 UTC. Если заданы и это поле, и Header time after, min, используется Header time.
   • Header time after, min: задайте, через сколько минут после отправки должно показываться время в заголовке.
   • Run the header time as a timer: включите, чтобы показывать Header time как идущие часы, а не фиксированное значение. При этом появляется Count down to the header time.
   • Count down to the header time: включите, чтобы вести обратный отсчёт до Header time, а не прямой отсчёт с момента отправки.
   • Hide the header time: включите, чтобы показывать карточку без времени в заголовке.

   

Любое поле выше может содержать плейсхолдер, который разрешается так же, как поля Card content для iOS: из события journey или с персонализацией через атрибут события.

Некоторые устройства Android не покажут уведомление

• Android 15 или старше либо приложение без модуля pushwoosh-liveupdates: Pushwoosh всё равно отправляет обновление, но на устройстве ничего не появляется, и обычный push вместо него не показывается.
• Устройства Huawei и Baidu: они не получают Android Live Updates. Обновления уходят только на устройства, зарегистрированные через Firebase Cloud Messaging (FCM).

Нажатие на уведомление открывает приложение, так же как обычный push.

Настройте баннер оповещения

Этот раздел применяется, только когда включена платформа iOS Live Activity. Если включена только Android Live Updates, эти поля скрыты и ничего не отправляется.

Для всех трёх действий (Start, Update и End):

1. В Alert title задайте заголовок баннера, показываемого на экране блокировки.
2. В Alert text задайте текст баннера.

Осторожно

Если и Alert title, и Alert text пусты, карточка всё равно запускается, обновляется или завершается, но экран блокировки не показывает баннер и не воспроизводит звук. Заполните хотя бы одно из двух полей, если это действие должно проявиться на заблокированном экране.

Выберите, какое устройство получит карточку

Адресация задаётся один раз, в Start. Оставьте оба переключателя выключенными, чтобы отправить карточку на устройство, с которого путешественник вошёл в journey. Включение одного переключателя выключает другой:

• Send to all devices of this user: отправить на каждое устройство, зарегистрированное под User ID этого путешественника, а не только на то, с которого он вошёл.
• Send to the last active device only: отправить на единственное устройство, которое этот User ID использовал последним, вместо всех устройств или устройства входа.

Совет

Включите Send to the last active device only, если один и тот же человек может смотреть с другого iPhone, отличного от того, с которого он вошёл в journey.

При Update и End проверьте Delivery (from the start element). Оно называет режим адресации из связанного Start. Обновление может достичь только той же карточки, поэтому оно уходит тем же способом.

Примечание

Оба переключателя блокируются, как только journey начинает выполняться, — это касается и Start. Чтобы изменить адресацию после этого, сначала поставьте journey на паузу.

Персонализируйте содержимое

Используйте это, когда плейсхолдеры в Alert title, Alert text, Card content или в полях Android Notification title, Notification text, Progress или Header time должны брать значения из события journey или входа на основе API, а не из тегов устройства.

1. В разделе Overwrite personalization включите Personalise message with event attributes.
2. Отметьте флажок Overwrite placeholder рядом с каждым плейсхолдером, который хотите переназначить.
3. Сопоставьте этот плейсхолдер с атрибутом события.

Сохраните элемент

Нажмите Apply, чтобы сохранить настройки элемента. Apply сохраняет этот элемент в journey. Это не подтверждает, что карточка появилась на устройстве. После запуска journey проверьте Total entries и выбывания на этом шаге, а также проверьте карточку на тестовом iPhone, тестовом устройстве с Android 16 или новее либо на обоих — в зависимости от включённых платформ.

Ограничения

• Статистика элемента: на этом шаге проверьте Total entries, строку Delivery (режим адресации) и выбывания (No recipient for the card, Live Activity send failed). Используйте No recipient for the card, чтобы увидеть, что рассылка не нашла устройство для включённых платформ в этом режиме, а не то, что у устройства не было токена Live Activity. Этот шаг не сообщает, показало ли устройство карточку или открыл ли её пользователь.
• Звук не гарантирован на каждое обновление: iOS сама ограничивает частоту оповещений Live Activity. Одно и то же обновление может один раз воспроизвести звук, а в следующий раз прийти беззвучно.
• Много действий Start подряд во время тестирования: если вы отправляете около десяти действий Start для одного и того же человека за короткое время (например, при тестировании journey), Apple может перестать показывать новые карточки, не возвращая ошибку. В journey человек всё ещё может выглядеть доставленным. Оставляйте паузу между тестовыми прогонами.