應用實例

請選取下列其中一個票證類別,進一步瞭解相關使用方式。


Google Pay API for Passes 可讓你透過公車、渡輪和火車等大眾運輸工具的票證與使用者互動。本指南討論的概念將協助你進一步瞭解大眾運輸票證的功用。

如要建立大眾運輸票證,請使用 JWT POST 要求方法「精簡版」JWT 連結,這兩種方法均會預先插入類別與物件。

TransitClass 和 TransitObject

如同其他 Google Pay API for Passes 類別,系統會將大眾運輸票證資料儲存為以下兩種資料結構:TransitClassTransitObject。本指南將說明這些資料結構的運用方式,方便您提供大眾運輸票證的支援服務。

TransitClass

TransitClass 會定義用來與類別相關聯之任何物件的範本。範本會定義要在票證的不同區段中顯示哪些欄位,也會定義物件之間共用的標誌和發卡機構名稱。

如果兩種票證類型需要在票證的一或多個區段顯示不同資料,您可能會想要建立兩個不同的 TransitClasses。例如,一個 TransitClass 用於任何點對點單次使用票證,另一個 TransitClass 則用於季節票證。

TransitObject

TransitObject 會保存代表旅程、大眾運輸業者及乘客的所有資料。舉例來說,TransitObject 包含旅程出發地、旅程目的地、出發時間、大眾運輸業者編號、乘客姓名、座位號碼等資料。其中某些值可在多個 TransitObjects. 之間共用

TransitObject 包含的資源會儲存至使用者的 Google Pay 應用程式中。

支援國家/地區

如要瞭解哪些國家/地區支援 Google Pay 應用程式,請參閱支援的國家/地區清單。建議你根據使用者購買票券的地點,限制要在哪些地方顯示 [儲存至 Google Pay] 按鈕。

應用實例

以下應用實例僅適用於「大眾運輸票證」類別:

更新票證

如果票證在建立後有所異動,請使用 REST API 向使用者告知相關變更。如果相關變更只會影響類別,您也可以使用 Google Pay Merchant Center。 票證更新是與使用者互動的重要方式。

如要更新票證的顯示方式 (例如標誌變更時),您只需要對 TransitClass 進行 updatepatch,或使用 Google Pay Merchant Center 即可。Google 會將這項資訊套用到與更新後的 TransitClass 相關聯的所有 TransitObject。凡是在 TransitClass 層級定義的所有欄位,均應採取這樣的做法。

如要更新單一票證 (例如出發時間變更時),您必須對單一 TransitObject 進行 updatepatch。凡是在 TransitObject 層級定義的所有欄位,均應採取這樣的做法。

有時候,您可能不曉得資料是在何時變更,或是不確定要在什麼時候觸發 updatepatch 要求。在這種情況下,請針對每個類別和物件安排定期的 updatepatch 要求。如果您呼叫 TransitClass list 方法,就可以找到特定發卡機構帳戶的所有類別。 如果呼叫 TransitObject list 方法,就可以找到特定類別的所有物件。

定義包含多段車程的旅程

旅程往往包含多段車程,而不是直達使用者的目的地。為完成這趟旅程的服務,大眾運輸業者可能會為旅程各段車程核發票證,或是核發單一票證。而 Google Pay API for Passes 會模仿這類行為,為每段車程分別建立一個 TransitObject,或建立單一的多段車程 TransitObject

要為每段車程使用一個 TransitObject 相當簡單。使用 object.ticketLeg 即可定義車程。您可以將每張票證視為獨立個體,個別建立並進行更新。但您可能也想透過某種定義,將這些票證歸納為群組。詳情請參閱將多張大眾運輸票證分組一節。如要定義包含多段車程的旅程,建議您使用這種方法。

只有在每段車程都能接受這個類型的匯總票證,且所有車程的票證資訊 (例如 QR 圖碼) 都相同時,才能使用具有多段車程的 TransitObject 物件。您可以使用 object.ticketLegs[] 清單來定義車程。票證的卡片部分只會顯示第一段車程的出發地與最後一段車程的目的地,而完整行程則會顯示在票證的詳細資料區段中。

建立可儲存多張票證的按鈕

如果使用者購買多張票證,而且可能會將所有票證儲存到 Google Pay,則建議你讓使用者只要按一下 [儲存至 Google Pay] 按鈕或儲存至 Google Pay 連結,就能儲存許多物件。您可以在簽署 JSON Web Token (JWT) 時定義多個物件或類別。

您必須使用下列其中一種格式建立 JWT:

  • 只使用預先插入的類別和物件。
  • 只使用在 JWT 中完整定義的物件和類別資源。

如要進一步瞭解票證的 UI 表示法,請參閱將多張大眾運輸票證分組一節。

將多張大眾運輸票證分組

某些功能若是用於群組 (而非個別物件),就會有不同的運作方式,例如狀態通知,或是在使用者介面組織多張已存票證的方法。

只有在所有 TransitObject 物件都具有相同的 object.classId, object.ticketLeg.departureDateTime 和下列其中一項屬性時 (以下按優先順序列出屬性),這些物件才會被視為一個群組:

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

這樣的設計是為了將同一趟旅程但不同乘客的票證編成一組。

如果希望將票證編組,建議你以一致的方式設定這些欄位,即使特定的 TransitObject 並未與任何其他項目編組也是如此。

接收近期旅程的通知

Google Pay 會在旅程開始前一小時向使用者傳送通知。旅程時間是由 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 欄位標記為 ExpiredInactiveCompleted 時。

使用者儲存票證後,請參照其 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
              }
            }
    }
  }
  …
  …
  …
}