Интеграция статуса рейса

Сообщайте пассажирам об изменениях их рейса в момент, когда они происходят: новый гейт, задержка, посадка, прибытие или отмена. Интеграция статуса рейса подключает Pushwoosh к AeroDataBox, поставщику полетных данных, чтобы Journey мог отслеживать рейс конкретного пассажира и реагировать в момент изменения его статуса.

Требуется помощь разработчика

Вам понадобится помощь вашей команды разработчиков, чтобы отправить событие бронирования с правильными атрибутами и составить тело запроса для шага Webhook. Поделитесь с ними этим руководством.

Обзор интеграции

Тип интеграции

Источник: вы подписываете бронирование на его рейс из Journey. Pushwoosh отправляет изменения статуса обратно в виде события, которое вы используете позже в том же Journey.

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

Перед подключением статуса рейса убедитесь, что у вас есть:

• Активный аккаунт Pushwoosh с приложением в дата-центре NUE Pushwoosh. Интеграция статуса рейса пока недоступна в других дата-центрах.
• Аккаунт AeroDataBox и API-ключ. Счет за использование данных выставляется на ваш собственный аккаунт AeroDataBox.
• Событие бронирования, которое содержит авиакомпанию, номер, дату и аэропорт вылета (см. Создание Journey для статуса рейса).
• Выделенный токен доступа API для аутентификации Journey.

Как работает интеграция?

Подключение интеграции и отслеживание одного рейса — это два отдельных шага, выполняемых в разное время:

1. Подключите свой ключ AeroDataBox в Settings → 3rd-party integrations.
2. Событие бронирования запускает Journey для пассажира.
3. Шаг Webhook в Journey подписывает это бронирование на его рейс через публичный API Pushwoosh.
4. Pushwoosh отслеживает рейс с помощью AeroDataBox и обнаруживает изменения: гейт, задержка, посадка, прибытие, отмена или назначение ленты выдачи багажа.
5. Каждое изменение доставляется в приложение в виде события PW_FlightStatusChanged, которое элементы Journey Wait for Trigger и Condition split направляют на нужное сообщение.

Каждая подписка на рейс завершается автоматически через 36 часов после местной даты вылета. Она может завершиться и раньше: как только рейс приземлится или будет отменен либо как только его больше ничто не отслеживает. После этого Pushwoosh отменяет соответствующую подписку AeroDataBox, чтобы за нее не продолжали списывать оплату в фоновом режиме.

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

Сценарии использования

Интеграция статуса рейса охватывает четыре вида обновлений, каждое из которых можно использовать отдельно или комбинировать в одном Journey:

• Оповещения о смене гейта: уведомляйте пассажиров в момент изменения их гейта вылета.
• Уведомления о задержке: оповещайте пассажиров, как только задержка рейса превысит несколько минут, чтобы они могли скорректировать свои планы.
• Уведомления о посадке и прибытии: сообщайте пассажирам, когда начинается посадка или их рейс приземлился.
• Получение багажа: отправляйте номер ленты выдачи багажа, как только он будет назначен.

Настройка интеграции

Подключение статуса рейса к Pushwoosh

Подключите свой ключ AeroDataBox один раз для каждого приложения:

1. Откройте свое приложение и перейдите в Settings → 3rd-party integrations.

2. В разделе Available services найдите карточку Flight Status и нажмите Configure.

   

3. Вставьте свой ключ AeroDataBox в поле API key и нажмите Connect.

   

После нажатия Connect карточка перемещается в Connected services.

Если ключ отклонен

Pushwoosh проверяет ключ в фоновом режиме. Если что-то не так, на карточке появляется одно из этих сообщений:

Сообщение	Причина
provider rejected the API key	Ключ недействителен или был отозван в AeroDataBox
provider account is out of credits	На вашем тарифном плане AeroDataBox закончились средства
provider rate limit reached	AeroDataBox ограничивает количество запросов, это пройдет само
provider is unavailable	Не удалось связаться с AeroDataBox из-за проблем с сетью или сбоя на любой из сторон
provider refused the request	AeroDataBox вернул ошибку, которую Pushwoosh не может распознать

Замена ключа

Снова откройте карточку Flight Status в разделе Connected services, например после того как ключ был отклонен:

• Заменить ключ: вставьте новый ключ в поле API key.
• Сохранить текущий ключ: оставьте поле API key пустым. В поле отображаются только последние несколько символов сохраненного ключа.

Отключение интеграции

1. Откройте карточку Flight Status в разделе Connected services.
2. Удалите ключ.

После отключения:

• Новые подписки больше не создаются.
• Рейсы, которые Journey уже отслеживают, сохраняют свои подписки, пока они не завершатся сами по себе или вы не удалите их из Journey.
• Счетчик активных подписок на карточке учитывает эти подписки, пока они не завершатся.

Создание Journey для статуса рейса

Перед созданием Journey

Убедитесь, что у вас есть:

• Событие бронирования, содержащее авиакомпанию, номер, дату (ГГГГ-ММ-ДД) и аэропорт вылета, а также один атрибут, содержащий ключ рейса в формате <авиакомпания><номер>/<дата>/<аэропорт вылета>, например LH400/2026-09-20/MUC. Это то, что используется для сопоставления сессий на протяжении всего Journey.
• Выделенный токен доступа API. Метод подписки принимает любой токен из вашего аккаунта, без необходимости предоставления разрешений. Создайте один специально для этого Journey, чтобы вы могли отозвать его позже, не затрагивая ничего другого.
• Хост публичного API вашего дата-центра. Для аккаунтов NUE это rpc-api.svc-nue.pushwoosh.com.
• Лимит входа в кампанию для Journey должен быть отключен. Лимит входа в кампанию отслеживает входы только для каждого пользователя. Он не знает об идентификаторе сессии, который вы настроите ниже, поэтому он будет блокировать второй рейс пассажира до истечения периода лимита.

Запуск Journey по событию бронирования

1. Добавьте Trigger-based entry и выберите ваше событие бронирования, например flight_booked.
2. В разделе Control how many sessions a user can have at the same time выберите Multiple active sessions per user.
3. Выберите атрибут ключа рейса в качестве идентификатора сессии. Это позволит одному и тому же пассажиру отслеживать несколько рейсов одновременно, каждый в своей сессии.

Подписка на бронирование с помощью шага Webhook

Добавьте шаг Webhook сразу после входа. Тело его запроса извлекает поля рейса из события входа, поэтому шаг должен находиться сразу после входа, чтобы использовать их.

1. Установите REQUEST TYPE в POST.

2. Установите URL в https://rpc-api.svc-nue.pushwoosh.com/api/integrations/flight-status/subscriptions.

3. В HEADERS оставьте Content-Type: application/json.

4. Добавьте заголовок Authorization: Token <ваш API-токен>. Pushwoosh маскирует это значение после сохранения, потому что любой заголовок с именем Authorization автоматически считается секретным. См. Пометка значения заголовка как секрета, чтобы узнать, что это означает для редактирования и истории версий.

5. В DATA введите тело запроса ниже, указав код вашего приложения напрямую:

   {
     "application": "<код вашего приложения>",
     "user_id": "{{device:user_id}}",
     "source": "journey",
     "flight": {
       "carrier": "",
       "flight_number": "",
       "flight_date": "",
       "departure_airport": ""
     }
   }

6. Для каждого из четырех пустых значений flight откройте DATA BUILDER.

7. Выберите категорию Event.

8. Выберите соответствующий атрибут из вашего события бронирования (авиакомпания, номер рейса, дата рейса, аэропорт вылета).

9. Скопируйте сгенерированный Pushwoosh макрос и вставьте его в качестве значения этого поля. Повторите для оставшихся трех значений.

Сопоставлять что-либо из ответа не нужно. Он возвращает flight_key, который уже есть в вашем событии бронирования.

Осторожно

Если вызов подписки завершается ошибкой, пассажир покидает Journey на этом шаге, как и при любом другом шаге Webhook. Его рейс не отслеживается, и он не получит никаких оповещений далее по Journey. См. Что происходит при сбое запроса.

Ожидание обновления статуса

Добавьте шаг Wait for Trigger после шага Webhook.

1. Добавьте одну ветку и установите для нее событие PW_FlightStatusChanged.
2. В разделе сопоставления атрибутов для нескольких сессий выберите тот же атрибут ключа рейса, который вы использовали на входе. Это гарантирует, что обновление статуса разбудит только того пассажира, к рейсу которого оно относится.
3. Установите период ожидания, чтобы он с запасом покрывал время рейса. 48 часов достаточно для большинства маршрутов.
4. Оставьте ветку Not triggered без следующего шага или добавьте запасное сообщение. Пассажиры, по рейсу которых до окончания ожидания не пришло обновление, покидают Journey здесь, и это ожидаемо.

Ветвление по типу события

Добавьте Condition split после шага Wait for Trigger.

1. Выберите Event в качестве типа условия.
2. В Event from Journey выберите PW_FlightStatusChanged.
3. В Attribute выберите event_type.
4. Установите условие is.
5. Добавьте ветку со значением gate_change.
6. Нажмите Save. Это создаст две ветки: ту, которую вы назвали для смены гейта, и All other users для всех остальных типов событий.

Повторите этот элемент или добавьте в него больше веток для других значений event_type, на которые вы хотите реагировать: delay, boarding, departed, arrived, cancelled и baggage_ready работают одинаково.

Уведомление пассажира

Добавьте элемент Push на ветку смены гейта.

1. Выберите или создайте пресет пуш-уведомления.
2. Установите Message type в Transactional message, так как оповещение о статусе рейса является сервисным уведомлением, а не рекламным. Ограничение частоты не применяется, и оно все равно дойдет до пассажиров в контрольной группе.
3. Включите персонализацию с атрибутами события.
4. Выберите PW_FlightStatusChanged в качестве исходного события.
5. Заполните плейсхолдеры вашего пресета из flight_number и gate_new.

Показать карточку Live Activity вместо этого

Добавьте три элемента Live Activity вместо Push или в дополнение к нему:

• Start: сразу после шага Webhook, а не непосредственно после входа. Вход соединяется только с одним следующим шагом, поэтому Webhook и Start не могут оба стоять сразу после него.
• Update: на ветке смены гейта.
• End: когда Journey больше не нужно отслеживать рейс, например после прибытия или отмены.

В элементе Start, в разделе Card attributes, добавьте все шесть полей, которые нужны типу ActivityAttributes карточки. Card attributes — это свободный список имен и значений, и интерфейс не проверяет имена, поэтому вводите каждое точно так, как указано. Пять из них уже есть в вашем событии бронирования:

• carrier
• flight_number
• flight_date
• departure_airport
• flight_key
• arrival_airport: вызов подписки его не требует, поэтому добавляйте его в событие бронирования, только если вы используете Live Activity.

Осторожно

Если какой-либо из шести Card attributes отсутствует, интерфейс не показывает ошибку, но карточка так и не появляется на устройстве. Каждый последующий Update или End для этого пассажира затем завершается ошибкой с кодом доставки 1031 («push token not found for the specified Live Activity ID»).

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

Справочник по событию PW_FlightStatusChanged

Каждое изменение, обнаруженное интеграцией, доставляется в виде одного события PW_FlightStatusChanged, причем все атрибуты всегда присутствуют: пустые атрибуты отправляются как пустые значения, а не опускаются.

Атрибут	Тип	Описание
event_type	String	Что изменилось (см. значения ниже)
flight_key	String	Тот же ключ рейса, который вы установили в событии бронирования
flight_number	String	Номер рейса
departure_airport	String	Код аэропорта вылета
arrival_airport	String	Код аэропорта прибытия
status	String	Текущий статус рейса (см. значения ниже)
gate_old / gate_new	String	Гейт вылета до и после изменения
terminal_old / terminal_new	String	Терминал вылета до и после изменения
baggage_claim	String	Номер ленты выдачи багажа, после назначения
provider	String	Поставщик данных, сообщивший об изменении (aerodatabox)
delay_minutes	Integer	Отставание от расписания в минутах, присутствует в каждом событии
scheduled_at / estimated_at / actual_at	String	Запланированное, текущее предполагаемое и фактическое время вылета в собственном формате провайдера
arrival_terminal	String	Терминал прибытия, после назначения
arrival_scheduled_at / arrival_estimated_at / arrival_actual_at	String	Запланированное, текущее предполагаемое и фактическое время прибытия в собственном формате провайдера
scheduled_at_local / estimated_at_local / actual_at_local	String	Три времени вылета выше по местному времени аэропорта вылета
arrival_scheduled_at_local / arrival_estimated_at_local / arrival_actual_at_local	String	Три времени прибытия выше по местному времени аэропорта прибытия
flight_date / event_time	Date	Дата рейса и время, когда произошло изменение

Значения и форматы атрибутов

• Значения event_type: gate_change, delay, boarding, departed, arrived, cancelled, baggage_ready.
• Значения status: scheduled, check_in, boarding, departed, delayed, arrived, cancelled, diverted, unknown. Статус AeroDataBox, который Pushwoosh не распознает, сообщается как unknown.
• delay_minutes: присутствует в каждом событии, а не только в событиях delay. 0 означает, что рейс выполняется по расписанию, а отрицательное значение — что он опережает расписание. Событие delay отправляется, как только задержка достигает 5 минут.
• Атрибуты времени: все они, включая arrival_* и _local, имеют тип String, а не Date. Так пустое время не удаляется из события, а местное время сохраняет смещение UTC аэропорта. Для фильтрации по дате используйте flight_date и event_time.