사용 사례

다음 패스 카테고리 중 하나를 선택하여 사용 방법을 자세히 알아보세요.

Google Pay API for Passes를 사용하면 항공 탑승권을 통해 사용자와 소통할 수 있습니다. 이 가이드에는 저장된 항공 탑승권의 기능을 보다 잘 이해할 수 있도록 개념이 설명되어 있습니다.

탑승권을 구현하려면 클래스 및 객체를 미리 삽입하는 메서드인 JWT POST 요청 메서드 또는 '스키니' JWT 링크를 사용하세요.

FlightClass 및 FlightObject

Google Pay API for Passes의 다른 카테고리와 마찬가지로 탑승권 데이터도 두 가지 데이터 구조, 즉FlightObject와 FlightClass로 저장됩니다. 이 가이드에서는 이러한 데이터 구조를 사용하여 항공 탑승권을 지원하는 방법을 설명합니다.

FlightClass

FlightClass에는 특정 날짜 및 시간의 특정 항공편과 관련해서 모든 승객 또는 일부 승객에 공통된 데이터가 포함됩니다. 예를 들어 항공사, 출발지, 목적지, 항공편 번호, 출발 시간 등이 이러한 공통 데이터에 해당합니다. 특정 항공편을 이용하는 모든 승객의 탑승권에는 이러한 동일한 데이터가 포함됩니다.

FlightClass에는 동일한 비행기의 일부 승객에 공통된 데이터도 포함됩니다. 예를 들어 퍼스트 클래스, 비즈니스 클래스, 이코노미 클래스에 해당하는 세 가지 FlightClass 구조를 생성할 수 있습니다. 이렇게 하면 필요에 따라 각 하위 집합에 서로 다른 필드를 사용할 수 있습니다. 이 경우에도 세 클래스는 모두 특정 날짜 및 시간에 동일한 항로로 운행되는 동일한 비행기를 나타냅니다.

FlightObject

FlightObject는 특정 시점에 특정 비행기를 이용하는 각 승객을 나타냅니다. 예를 들어 FlightObject에는 승객 이름, 좌석 번호, 탑승 바코드가 포함됩니다. 이러한 데이터는 각 승객의 탑승권마다 다릅니다.

FlightObject에 포함된 리소스는 사용자의 Google Pay 앱에 저장됩니다.

지원되는 국가

항공 탑승권을 지원하는 국가를 알아보려면 지원되는 국가 목록을 참조하세요. 사용자가 티켓을 구매한 위치에 따라 Google Pay에 저장 버튼을 표시할 위치를 제한하는 것이 좋습니다.

사용 사례

다음 사용 사례는 항공 탑승권 카테고리에만 해당합니다.

패스 업데이트
다구간 항공 여정 저장
여러 패스를 저장하는 버튼 만들기
여러 탑승권 그룹화
예정된 항공편 알림 수신
항공편 업데이트 알림 수신
만료된 패스 처리
저장된 패스에 링크 걸기
저장된 패스에서 연결 해제

패스 업데이트

생성된 패스에 변경사항이 있는 경우 REST API를 사용하여 변경사항을 사용자에게 전달합니다. 이 변경사항이 클래스에만 영향을 줄 경우 Google Pay 판매자 센터를 사용할 수도 있습니다. 패스 업데이트는 사용자와 소통하는 중요한 방법입니다.

예상 출발 시간을 변경하는 등 특정 항공편의 모든 탑승권에 대한 필드를 업데이트하려면 FlightClass를 update 또는patch하거나 Google Pay 판매자 센터를 사용하면 됩니다. Google이 이 정보를 업데이트된 FlightClass와 연결된 모든 FlightObject에 전달합니다. 이는 FlightClass 수준에서 정의된 모든 필드에 적용됩니다.

승객 한 명의 좌석 번호를 변경하는 등 패스 하나를 업데이트하는 경우에는 FlightObject 하나를 update 또는 patch해야 합니다. 이는 FlightObject 수준에서 정의된 모든 필드에 적용됩니다.

참고: 이 데이터 구조에 대한 자세한 내용은 FlightClass 및 FlightObject를 참조하세요.

때로는 변경사항이 언제 발생하는지, 아니면 update 또는 patch 요청을 언제 트리거해야 할지 모를 수도 있습니다. 이러한 경우에는 각 클래스 및 객체에 대한 update 또는 patch 요청을 주기적으로 예약합니다. FlightClasslist 메서드를 호출하면 특정 발급기관 계정의 모든 클래스를 찾을 수 있습니다. FlightObjectlist 메서드를 호출하면 특정 클래스의 모든 객체를 찾을 수 있습니다.

항공편 업데이트 데이터 소스

class.localScheduledDepartureDateTime에 지정된 시간이 지난 24시간 또는 다음 48시간에 속하는 경우 항공편 상태 카드가 사용자에게 표시됩니다. 이 경우 Google Pay에서 Google 항공편의 데이터 또는 Google Pay 탑승권에 제공된 정보를 표시할 수 있습니다. 사용되는 소스는 다음에 따라 달라집니다.

class.localEstimatedOrActualDepartureDateTime이 제공되지 않으면 Google 항공편이 사용됩니다. 이 경우 설정된 class.flightStatus가 무시됩니다.

예를 들어 항공편이 지연되면 Google Pay 앱의 '홈' 탭에 새로운 출발 시간이 나와 있는 카드가 표시됩니다. 이와 유사한 지연 카드는 '패스' 탭에 표시됩니다.
class.localEstimatedOrActualDepartureDateTime은 제공했지만 class.flightStatus를 제공하지 않은 경우 제공된 시간을 사용하여 항공편 지연 여부를 확인합니다. 다음 논리에 따라 카드의 항공편 상태가 사용자에게 표시됩니다.
- class.localEstimatedOrActualDepartureDateTime이 class.localScheduledDepartureDateTime보다 클 경우 항공편이 지연된다고 나온 카드가 사용자에게 표시됩니다.
- class.localEstimatedOrActualDepartureDateTime이 class.localScheduledDepartureDateTime보다 크지 않을 경우에는 상태 메시지 없이 항공편 정보만 담긴 카드가 사용자에게 표시됩니다.

항공편 정보 출처로 Google 항공편을 사용하지 않으려면 FlightClass의 flightStatus, localScheduledDepartureDateTime, localEstimatedOrActualDepartureDateTime을 제공해야 합니다. 내 데이터만 카드에 사용됩니다. FlightClass에 IATA 코드 대신 ICAO 항공사 코드를 사용하는 경우 Google 항공편이 항공편 정보 출처로 사용되지 않습니다.

특정 필드가 변경되면 사용자에게 변경사항에 대한 푸시 알림이 전송됩니다. 자세한 내용은 항공편 업데이트 알림 수신을 참조하세요.

다구간 항공 여정 저장

하나의 항공 여정이 목적지까지 직항이 아니라 여러 구간을 지나는 경우가 있습니다. 이 경우, 항공사는 각 경유지별로 탑승권을 하나씩 발급합니다. Google Pay API for Passes는 구간별로 하나의 FlightObject를 사용하여 이러한 동작을 모방합니다.

즉, SFO에서 LAX를 거쳐 TPE로 가는 승객이 두 명 있다면 FlightClass 구조가 2개, FlightObject 객체가 4개가 됩니다.

	`FlightClass` A(SFO에서 LAX로 - 항공사, 항공편 번호, 출발 시간)	`FlightClass` B(LAX에서 TPE로 - 항공사, 항공편 번호, 출발 시간)
승객 Q	`FlightObject: id_01`	`FlightObject: id_02`
승객 Z	`FlightObject: id_03`	`FlightObject: id_04`

이 필드는 실제 탑승권을 반영합니다. 승객 Q와 승객 Z는 종이 탑승권 2개를 갖게 됩니다.

여러 패스를 저장하는 버튼 만들기

패스를 여러 장 구매한 사용자가 모든 패스를 Google Pay에 저장할 가능성이 높다면 사용자가 Google Pay에 저장 버튼 또는 링크 클릭 한 번으로 여러 객체를 저장할 수 있도록 하는 것이 좋습니다. JSON 웹 토큰(JWT)에 서명할 때 여러 객체 또는 클래스를 정의할 수 있습니다.

JWT를 만들 때는 다음 형식 중 하나를 사용해야 합니다.

미리 삽입된 클래스 및 객체만 사용합니다.
JWT에 완전하게 정의된 객체 및 클래스 리소스만 사용합니다.

여러 패스의 버튼을 만드는 방법에 대한 예시는 여러 승객 저장 버튼을 참조하세요.

패스의 UI 표현에 대한 자세한 내용은 여러 탑승권 그룹화를 참조하세요.

여러 탑승권 그룹화

개별 객체가 아니라 그룹에서 사용될 경우 작동 방식이 달라지는 기능이 있습니다. 예를 들어 사용자 인터페이스에서 저장된 여러 패스의 상태 알림 또는 구성이 그러한 기능에 해당합니다.

FlightObject 객체는 각 객체의 다음 속성이 모두 동일한 경우에만 한 그룹으로 간주됩니다.

발급기관 ID(Google Pay API for Passes 판매자 센터에서 제공)
class.flightHeader.carrier.carrierIataCode
class.flightHeader.flightNumber
class.localScheduledDepartureDateTime
object.reservationInfo.confirmationCode

두 개의 FlightObject 객체가 위의 속성 중 어느 하나라도 다르면 해당 객체는 그룹에 속하지 않는 것으로 간주됩니다.

참고: 이 중 일부는 클래스 속성이고 일부는 객체 속성입니다. 따라서 서로 다른 클래스의 FlightObject 객체를 그룹화할 수 있습니다.

예정된 항공편 알림 수신

Google Pay는 항공편 3시간 전에 사용자에게 알림을 보냅니다. 항공편 시간은 class.localScheduledDepartureDateTime로 정의됩니다.

이 알림을 수신하려면 사용자가 알림을 사용 설정해야 합니다. 알림 수신을 원하는 사용자는 설정 > 알림으로 이동하여 패스 관련 업데이트를 사용 설정하면 됩니다.

사용자가 잠금 화면에 알림이 표시되도록 설정한 경우 알림 영역과 잠금 화면에 알림이 표시됩니다.

알림은 다음과 같이 수정 불가능한 형식으로 표시됩니다.

Boarding pass for your flight to class.destination.airportIataCode
Expand for more options

사용자가 알림을 탭하고 기기의 잠금을 해제하면 Google Pay 앱에 패스가 표시됩니다.

사용자에게 패스가 여러 개 있으면 가장 빨리 사용할 수 있는 패스만 표시됩니다. 여러 탑승권 그룹화에 따라 그룹화된 패스를 저장한 경우 그룹에 속한 패스 중 하나만 알림에 표시됩니다. 하지만 알림을 탭하고 왼쪽과 오른쪽으로 스와이프하면 그룹의 다른 패스도 볼 수 있습니다.

알림은 고정되며 사용자가 알림을 열어본 후에도 자동으로 종료되지 않습니다. class.localScheduledDepartureDateTime 후 60분이 지나면 자동으로 종료됩니다.

항공편 업데이트 알림 수신

항공편의 특정 필드가 변경되면 탑승권이 하나 이상 저장된 사용자의 기기에 푸시 알림이 전송됩니다. 알림은 특정 조건이 충족되는 경우에만 전송됩니다.

출발지 터미널 및 게이트

class.origin.terminal 또는 class.origin.gate를 변경한 경우 다음 조건이 충족되면 필드가 변경되었다는 알림이 전송됩니다.

class.localScheduledDepartureDateTime까지 3시간이 채 안 남았습니다.

알림은 '샘플 항공사가 게이트를 A1으로 업데이트했습니다.'와 같은 형식으로 전송되며 형식은 변경할 수 없습니다.

탑승 시간 및 출발 시간

class.localBoardingDateTime 또는 class.localEstimatedOrActualDepartureDateTime을 변경한 경우 다음 조건이 충족되면 필드가 변경되었다는 알림이 전송됩니다.

class.localScheduledDepartureDateTime까지 24시간이 채 안 남았습니다.
각 시간이 10분 이상 변경됩니다.

알림은 '샘플 항공사에서 탑승 시간을 오후 6시로 업데이트했습니다.'와 같은 형식으로 전송되며 형식은 변경할 수 없습니다.

만료된 패스 처리

Google Pay 앱의 '패스' 탭에는 보관처리된 패스 또는 비활성 패스가 모두 포함된 '만료된 패스' 섹션이 있습니다. 다음 조건 중 하나 이상에 해당하는 패스는 '만료된 패스' 섹션으로 이동됩니다.

class.localScheduledDepartureDateTime 또는 class.localEstimatedOrActualDepartureDateTime이 만료된 후 24시간 이상 지났습니다. 이 패스는 class.localScheduledDepartureDateTime 또는 class.localEstimatedOrActualDepartureDateTime이 만료된 후 24~48시간 사이에 '만료된 패스'로 이동합니다.
object.validTimeInterval.end.date가 만료됩니다. 이 패스는 object.validTimeInterval.end.date가 만료된 후 최대 24시간 이내에 '만료된 패스'로 이동합니다.
object.state 필드가 Expired, Inactive 또는 Completed로 표시되어 있습니다.

저장된 패스에 링크 걸기

사용자가 저장한 패스가 있으면 패스에 링크를 걸기 위해 objectId를 참조합니다.

다음 링크를 사용하여 패스를 참조하세요.

https://pay.google.com/gp/v/object/{<issuerId>}.{<ObjectId>}

패스는 Google Pay 앱 또는 웹브라우저에서 확인할 수 있습니다.

저장된 Google Pay 패스에서 연결

저장된 Google Pay 패스의 헤더 아래에서 앱 또는 웹사이트에 연결할 수 있습니다. 이 기능은 모든 유형의 Google Pay 패스에서 사용할 수 있습니다.

액세스 요청

오프라인 판매자용 지원 양식을 사용하여 액세스를 요청하세요. 다음 사항에 유의하세요.

양식에서 발급기관 ID를 공유해야 합니다.
Issue type(발급 유형)에서 'Technical/API Integration(기술/API 통합)'을 선택합니다.
Link your app or website below the Google Pay pass(Google Pay 패스 아래에 앱 또는 웹사이트 연결)를 선택합니다.

Google Pay 패스에 앱 링크 설정

지정된 Google Pay 패스에 대해 appLinkData를 정의하여 앱 또는 웹사이트의 URI를 설정합니다. URI의 형식은 자유롭지만 동적 링크를 사용하는 것이 좋습니다.

appLinkData 필드의 형식 및 컨텍스트는 다음 소스 코드에서 볼 수 있습니다.

{
  "id": string,
  "classId": string,
  …
  …
  …
  "appLinkData": {
    "androidAppLinkInfo": {
      "appLogoImage": {
        "sourceUri": {
          "uri": string
        }
      },
        "title": {
          "defaultValue": {
            "language": string,
              "value": string
          }
        },
          "description": {
            "defaultValue": {
              "language": string,
                "value": string
            }
          },
            "appTarget": {
              "targetUri": {
                "uri": string,
                  "description": string
              }
            }
    }
  }
  …
  …
  …
}