應用實例

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

登機證 活動票券 儲值卡 會員卡 優惠 大眾運輸票證

---

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

附註：本說明文件只涵蓋條碼/QR 圖碼大眾運輸票證的整合支援，如需其他類型的大眾運輸整合資訊，請參閱大眾運輸票證支援頁面。

如為航班的登機證，請參閱登機證類別說明。

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

TransitClass 和 TransitObject

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

TransitClass

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

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

TransitObject

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

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

支援的國家/地區

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

應用實例

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

• 更新票證。
• 定義包含多段車程的旅程。
• 建立可儲存多張票證的按鈕。
• 將多張大眾運輸票證組成一組。
• 接收近期旅程的通知。
• 處理過期的票證。
• 連結已儲存的票證。
• 從已儲存的票證連出。

注意：所有票證類別都具備相同的核心功能。詳情請參閱將票證儲存至 Google Pay、透過 Google Pay 兌換票證及透過 Google Pay 與使用者互動等說明文件。

更新票證

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

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

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

注意：如要進一步瞭解上述資料結構，請參閱 TransitClass 和 TransitObject 的說明。

注意：如要進一步瞭解 update 和 patch 之間的差異，請參閱修補 (部分更新) 一節。

任何 update 邏輯都應該以 GET 要求做為開頭來擷取類別或物件，確保系統使用的是最新版類別或物件。系統會清除您省略未填的欄位。

一般來說，如果只想為您要變更的欄位提供資料，使用 patch 是比較保險的做法。這樣一來，您省略未填的欄位就不會遭到清除。但是，修改陣列時應格外小心。含有陣列的修補要求也會以您提供的陣列取代現有的陣列。您無法個別修改、新增或刪除陣列中的項目。

有時候，您可能不曉得資料是在何時變更，或是不確定要在什麼時候觸發 update 或 patch 要求。在這種情況下，請針對每個類別和物件安排定期的 update 或 patch 要求。如果您呼叫 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 中完整定義的物件和類別資源。

注意：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 欄位標記為 Expired、Inactive 或 Completed 時。

連結已儲存的票證

使用者儲存票證後，請參照其 objectId 以連結票證。

請使用以下連結來參照票證：

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

您可以透過 Google Pay 應用程式或網路瀏覽器查看票證。

注意：如果使用者未儲存票證，就會收到「找不到項目」的錯誤。如果使用者安裝了 Google Pay 應用程式，這個連結就可離線運作。

從已儲存的 Google Pay 票證連出

您可以在已儲存的 Google Pay 票證標題下方，連結至您的應用程式或網站。這項功能適用於所有類型的 Google Pay 票證。

注意：只有在您完成至少兩項與 Google Pay for Passes API 的整合之後，才能使用這項功能。整合內容必須是應用程式、網站或電子郵件。

要求存取權

請使用商家的支援表格要求存取權。請注意以下幾點：

• 您必須在表格中分享您的核發者 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
              }
            }
    }
  }
  …
  …
  …
}