항공편 상태 통합

항공편의 변경 사항을 발생하는 즉시 승객에게 알리세요: 새 게이트, 지연, 탑승, 도착 또는 취소. 항공편 상태 통합은 Pushwoosh를 항공 데이터 제공업체인 AeroDataBox에 연결하여, 고객 여정이 특정 승객의 항공편을 감시하고 상태가 변경되는 즉시 대응할 수 있도록 합니다.

개발자 지원 필요

올바른 속성을 가진 예약 이벤트를 보내고 웹훅 단계의 요청 본문을 빌드하려면 개발팀이 필요합니다. 이 가이드를 개발팀과 공유하세요.

통합 개요

통합 유형

소스: 여정 내에서 예약을 해당 항공편에 구독합니다. Pushwoosh는 상태 변경을 동일한 여정에서 나중에 사용할 이벤트로 다시 보냅니다.

전제 조건

항공편 상태를 연결하기 전에 다음을 확인하세요:

• Pushwoosh의 NUE 데이터 센터에 애플리케이션이 있는 활성 Pushwoosh 계정. 항공편 상태는 아직 다른 데이터 센터에서는 사용할 수 없습니다.
• AeroDataBox 계정 및 API 키. 피드는 사용자 자신의 AeroDataBox 계정으로 청구됩니다.
• 항공편의 항공사, 편명, 날짜 및 출발 공항을 포함하는 예약 이벤트 (항공편 상태 여정 빌드 참조).
• 여정이 인증하는 데 사용할 전용 API 액세스 토큰.

통합은 어떻게 작동하나요?

통합 연결과 한 항공편 감시는 서로 다른 시점에 수행되는 두 가지 별개의 단계입니다:

1. 설정 → 3자 통합에서 AeroDataBox 키를 연결합니다.
2. 예약 이벤트가 승객을 여정에 진입시킵니다.
3. 여정의 웹훅 단계는 Pushwoosh의 공개 API를 통해 해당 예약을 항공편에 구독합니다.
4. Pushwoosh는 AeroDataBox로 항공편을 감시하고 게이트, 지연, 탑승, 도착, 취소 또는 수하물 벨트 배정과 같은 변경 사항을 감지합니다.
5. 각 변경 사항은 PW_FlightStatusChanged 이벤트로 앱에 전달되며, 여정의 트리거 대기 및 조건 분기가 올바른 메시지로 라우팅합니다.

각 항공편 구독은 현지 출발 날짜로부터 36시간 후에 자동으로 종료됩니다. 항공편이 착륙하거나 취소된 경우, 또는 더 이상 항공편을 감시하는 여정이 없는 경우에는 더 일찍 종료될 수 있습니다. 그러면 Pushwoosh가 해당 AeroDataBox 구독을 취소하므로 백그라운드에서 요금이 계속 청구되지 않습니다.

이 기간은 구독 시점에 예약된 출발 날짜를 기준으로 고정되며, 이후 AeroDataBox가 지연을 보고해도 바뀌지 않습니다. 지연으로 항공편이 다음 날로 넘어가면, 지연된 실제 출발 전에 구독이 종료될 수 있습니다.

사용 사례

항공편 상태는 네 가지 종류의 업데이트를 다루며, 각각 단독으로 사용하거나 하나의 여정에서 결합하여 사용할 수 있습니다:

• 게이트 변경 알림: 출발 게이트가 변경되는 즉시 승객에게 알립니다.
• 지연 알림: 항공편 지연이 몇 분을 초과하면 승객에게 알려 계획을 조정할 수 있도록 합니다.
• 탑승 및 도착 업데이트: 탑승이 시작되거나 항공편이 착륙할 때 승객에게 알립니다.
• 수하물 수취: 수하물 벨트 번호가 배정되는 즉시 전송합니다.

통합 설정

Pushwoosh에 항공편 상태 연결

애플리케이션당 한 번 AeroDataBox 키를 연결합니다:

1. 애플리케이션을 열고 설정 → 3자 통합으로 이동합니다.

2. 사용 가능한 서비스 아래에서 항공편 상태 카드를 찾아 구성을 클릭합니다.

   

3. AeroDataBox 키를 API 키에 붙여넣고 연결을 클릭합니다.

   

연결을 클릭하면 카드가 연결된 서비스로 이동합니다.

키가 거부된 경우

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가 인식하지 못하는 오류를 반환했습니다

키 교체

예를 들어 키가 거부된 후에는 연결된 서비스에서 항공편 상태 카드를 다시 엽니다:

• 키 교체: API 키에 새 키를 붙여넣습니다.
• 현재 키 유지: API 키를 비워 둡니다. 필드에는 저장된 키의 마지막 몇 자만 표시됩니다.

통합 연결 해제

1. 연결된 서비스에서 항공편 상태 카드를 엽니다.
2. 키를 제거합니다.

연결을 해제한 후:

• 새 구독이 더 이상 생성되지 않습니다.
• 여정이 이미 감시 중인 항공편은 구독이 자체적으로 종료되거나 여정에서 삭제할 때까지 구독을 유지합니다.
• 카드의 활성 구독 수에는 이러한 구독이 종료될 때까지 포함됩니다.

항공편 상태 여정 빌드

여정을 빌드하기 전에

다음을 확인하세요:

• 항공편의 항공사, 편명, 날짜(YYYY-MM-DD), 출발 공항을 포함하는 예약 이벤트와, 여정 전체에서 세션 매칭에 사용되는 <항공사><편명>/<날짜>/<출발 공항> 형식의 항공편 키를 담은 속성 하나. 예: LH400/2026-09-20/MUC.
• 전용 API 액세스 토큰. 구독 메서드는 계정의 모든 토큰을 허용하며 부여할 권한이 없습니다. 이 여정 전용으로 하나 생성하여 나중에 다른 것에 영향을 주지 않고 해지할 수 있도록 하세요.
• 데이터 센터의 공개 API 호스트. NUE 계정의 경우 rpc-api.svc-nue.pushwoosh.com입니다.
• 여정의 캠페인 진입 제한을 끕니다. 캠페인 진입 제한은 사용자별 진입만 추적합니다. 아래에서 설정한 세션 식별자를 알지 못하므로, 제한 기간이 지날 때까지 승객의 두 번째 항공편을 차단합니다.

예약 이벤트에서 여정 시작

1. 트리거 기반 진입을 추가하고 flight_booked와 같은 예약 이벤트를 선택합니다.
2. 사용자가 동시에 가질 수 있는 세션 수 제어 아래에서 사용자당 여러 활성 세션을 선택합니다.
3. 항공편 키 속성을 세션 식별자로 선택합니다. 이렇게 하면 동일한 승객이 한 번에 둘 이상의 항공편을 각자의 세션에서 추적할 수 있습니다.

웹훅 단계로 예약 구독

진입 직후에 웹훅 단계를 추가합니다. 요청 본문은 진입 이벤트에서 항공편 필드를 가져오므로, 이 단계를 사용하려면 진입 바로 뒤에 위치해야 합니다.

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 토큰> 헤더를 추가합니다. Authorization이라는 이름의 헤더는 자동으로 비밀로 처리되므로, 저장 후 Pushwoosh가 이 값을 마스킹합니다. 편집 및 버전 기록에 이것이 무엇을 의미하는지 보려면 헤더 값을 비밀로 표시를 참조하세요.

5. DATA에 아래 요청 본문을 입력하고, 자신의 애플리케이션 코드를 직접 입력합니다:

   {
     "application": "<애플리케이션 코드>",
     "user_id": "{{device:user_id}}",
     "source": "journey",
     "flight": {
       "carrier": "",
       "flight_number": "",
       "flight_date": "",
       "departure_airport": ""
     }
   }

6. 네 개의 빈 flight 값 각각에 대해 DATA BUILDER를 엽니다.

7. 이벤트 카테고리를 선택합니다.

8. 예약 이벤트에서 일치하는 속성(항공사, 편명, 항공편 날짜, 출발 공항)을 선택합니다.

9. Pushwoosh가 생성한 매크로를 복사하여 해당 필드의 값으로 붙여넣습니다. 나머지 세 값에 대해 반복합니다.

응답에서 아무것도 매핑할 필요가 없습니다. 응답은 flight_key를 반환하며, 이 값은 이미 예약 이벤트에 있습니다.

주의

구독 호출이 실패하면 다른 웹훅 단계와 마찬가지로 승객이 이 단계에서 여정을 떠납니다. 해당 승객의 항공편은 감시되지 않으며, 여정의 후반부에 있는 어떤 알림도 받지 못합니다. 요청이 실패하면 어떻게 되나요를 참조하세요.

상태 업데이트 대기

웹훅 단계 뒤에 트리거 대기 단계를 추가합니다.

1. 브랜치 하나를 추가하고 이벤트를 PW_FlightStatusChanged로 설정합니다.
2. 다중 세션 속성 매칭 아래에서, 진입에 사용한 것과 동일한 항공편 키 속성을 선택합니다. 이렇게 하면 상태 업데이트가 실제로 해당 항공편에 대한 승객만 깨우도록 보장합니다.
3. 대기 기간을 항공편을 충분히 포함하도록 설정합니다. 대부분의 여정에는 48시간이면 충분합니다.
4. 트리거되지 않음 브랜치는 다음 단계 없이 두거나 대체 메시지를 추가합니다. 대기가 끝나기 전에 항공편 업데이트가 없는 승객은 여기서 여정을 떠나며, 이는 예상된 동작입니다.

이벤트 유형별 분기

트리거 대기 단계 뒤에 조건 분기를 추가합니다.

1. 조건 유형으로 이벤트를 선택합니다.
2. 여정의 이벤트에서 PW_FlightStatusChanged를 선택합니다.
3. 속성 아래에서 event_type을 선택합니다.
4. 조건을 is로 설정합니다.
5. gate_change 값을 가진 브랜치를 추가합니다.
6. 저장을 클릭합니다. 이렇게 하면 게이트 변경에 대해 명명한 브랜치와 다른 모든 이벤트 유형에 대한 다른 모든 사용자라는 두 개의 브랜치가 생성됩니다.

이 요소를 반복하거나 더 많은 브랜치를 추가하여 delay, boarding, departed, arrived, cancelled, baggage_ready와 같이 조치하려는 다른 event_type 값에 대해 동일하게 작업합니다.

승객에게 알림

게이트 변경 브랜치에 푸시 요소를 추가합니다.

1. 푸시 프리셋을 선택하거나 생성합니다.
2. 메시지 유형을 거래 메시지로 설정합니다. 항공편 상태 알림은 프로모션이 아닌 서비스 알림이기 때문입니다. 빈도 제한은 적용되지 않으며, 제어 그룹에 있는 승객에게도 도달합니다.
3. 이벤트 속성으로 개인화를 활성화합니다.
4. 소스 이벤트로 PW_FlightStatusChanged를 선택합니다.
5. flight_number와 gate_new에서 프리셋의 플레이스홀더를 채웁니다.

대신 Live Activity 카드 표시

Push 대신, 또는 Push와 함께 Live Activity 요소 세 개를 추가하세요:

• Start: 진입 바로 뒤가 아니라 웹훅 단계 바로 뒤에 둡니다. 진입은 다음 단계 하나에만 연결되므로 웹훅과 Start가 둘 다 진입 바로 뒤에 올 수 없습니다.
• Update: 게이트 변경 브랜치에 둡니다.
• End: 여정이 더 이상 항공편을 추적할 필요가 없을 때(예: 도착 또는 취소 후) 둡니다.

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. Pushwoosh가 인식하지 못하는 AeroDataBox 상태는 unknown으로 보고됩니다.
• delay_minutes: delay 이벤트뿐 아니라 모든 이벤트에 포함됩니다. 0은 항공편이 정시임을, 음수 값은 일찍 운항 중임을 의미합니다. delay 이벤트는 지연이 5분에 도달하면 전송됩니다.
• 시간 속성: arrival_* 및 _local 속성을 포함한 모든 시간 속성은 Date가 아닌 String입니다. 이렇게 하면 빈 시간이 이벤트에서 제외되지 않고, 현지 시간이 공항의 UTC 오프셋을 유지합니다. 날짜로 필터링하려면 flight_date와 event_time을 사용하세요.