사용 사례

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

Google Pay API for Passes를 사용하면 버스, 페리, 기차 등의 교통카드를 통해 사용자와 소통하며 참여를 유도할 수 있습니다. 이 가이드에는 교통카드 기능을 보다 잘 이해할 수 있도록 개념이 설명되어 있습니다.

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

TransitClasses 및 TransitObjects

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

TransitClass

TransitClass는 이 클래스와 연결된 모든 객체를 표시하기 위해 사용하는 템플릿을 정의합니다. 템플릿은 패스의 여러 다른 섹션에 표시할 필드를 정의하고 객체 간에 공유되는 로고와 발급기관 이름도 정의합니다.

두 가지 패스 유형에서 패스의 섹션 하나 이상에 다른 데이터를 표시해야 하는 경우 TransitClasses를 두 개 만들 수 있습니다. 예를 들어 모든 지점 간 일회용 패스에 사용할 TransitClass 하나와 정기권 패스에 사용할 TransitClass 하나입니다.

TransitObject

TransitObject는 여정, 운송업체, 승객을 나타내는 모든 데이터를 보유합니다. 예를 들어 TransitObject에는 출발지, 목적지, 출발 시간, 운송업체 번호, 승객 이름, 좌석 번호 등이 포함됩니다. 이 값 중 일부는 여러 TransitObjects.에서 공유됩니다.

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

지원되는 국가

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

사용 사례

다음 사용 사례는 대중교통 이용권 카테고리에만 해당합니다.

패스 업데이트

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

로고를 변경하는 등 패스가 표시되는 방식을 업데이트하려면 TransitClass를 update 또는 patch하거나 Google Pay 판매자 센터를 사용하면 됩니다. Google이 이 정보를 업데이트된 TransitClass와 연결된 모든 TransitObject에 전달합니다. 이는 TransitClass 수준에서 정의된 모든 필드에 적용됩니다.

출발 시간이 변경될 때와 같이 패스 하나를 업데이트하는 경우에는 하나의 TransitObject를 update 또는 patch해야 합니다. 이는 TransitObject 수준에서 정의된 모든 필드에 적용됩니다.

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

다구간 여정 정의

하나의 여정이 목적지까지 직행하지 않고 여러 구간을 지나는 경우가 있습니다. 다구간 여정의 경우 운송업체는 여정 구간별로 패스 하나 또는 일회용 패스를 발급할 수 있습니다. Google Pay API for Passes는 구간별로 하나의 TransitObject를 사용하거나 하나의 다구간 TransitObject를 사용하여 이러한 동작을 모방합니다.

구간당 TransitObject 하나를 사용하는 것은 매우 간단합니다. object.ticketLeg를 사용하여 구간을 정의할 수 있습니다. 각 패스가 독립적인 것처럼 만들고 업데이트할 수 있지만 이러한 패스를 그룹화하는 방법을 정의할 수도 있습니다. 자세한 내용은 여러 대중교통 이용권 그룹화를 참조하세요. 이 방법은 다구간 여정을 정의하는 데 주로 사용됩니다.

다구간 TransitObject 객체는 각 구간에서 이 통합 패스 유형을 허용하는 경우와 패스의 정보(예: QR 코드)가 모든 구간에서 동일한 경우에만 사용할 수 있습니다. object.ticketLegs[] 목록을 사용하여 구간을 정의할 수 있습니다. 패스의 카드 부분에는 첫 번째 구간의 출발지와 마지막 구간 목적지만 표시되며 전체 여정은 패스의 세부정보 섹션에 표시됩니다.

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

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

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

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

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

여러 대중교통 이용권 그룹화

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

TransitObject 객체는 같은 object.classId, object.ticketLeg.departureDateTime 및 우선순위에 따라 나열된 다음 속성 중 하나를 공유하는 경우에만 하나의 그룹으로 간주됩니다.

  1. object.tripId
  2. object.purchaseDetails.confirmationCode

이는 여정은 같지만 승객은 다른 패스를 그룹화하기 위한 것입니다.

패스를 그룹화하려면 특정 TransitObject가 다른 항목과 그룹화되지 않더라도 이러한 필드를 일관되게 설정하는 것이 좋습니다.

예정된 여정 알림 수신

Google Pay는 여정 1시간 전에 사용자에게 알림을 보냅니다. 여정 시간은 object.ticketLeg.departureDateTime 또는 첫 번째 object.ticketLegs[].departureDateTime으로 정의됩니다.

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

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

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

Ticket fot your upcoming trip to object.ticketLeg.destinationName
Expand for more options

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

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

알림은 고정되며 사용자가 알림을 열어본 후에도 자동으로 종료되지 않습니다. object.ticketLeg.departureDateTime 또는 첫 번째 object.ticketLegs[].departureDateTime 후 60분이 지나면 자동으로 종료됩니다.

만료된 패스 처리

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

  • object.ticketLeg.arrivalDateTime 또는 마지막 object.ticketLegs[].arrivalDateTime이 만료된 후 24시간 이상 지났습니다. 이 패스는 object.ticketLeg.arrivalDateTime 또는 마지막 object.ticketLegs[].arrivalDateTime이 만료된 후 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 패스에서 사용할 수 있습니다.

액세스 요청

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

  • 양식에서 발급기관 ID를 공유해야 합니다.
  • Issue type(발급 유형)에서 'Technical/API Integration(기술/API 통합)'을 선택합니다.
  • Link your app or website below the Google Pay pass(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
              }
            }
    }
  }
  …
  …
  …
}