應用實例

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

Google Pay API for Passes 可讓你透過活動票券與使用者互動。本指南討論的概念應可協助你進一步瞭解已儲存活動票券的功用。

如要實作活動票券，請使用 JWT POST 要求方法或「精簡版」JWT 連結，這兩種方法均會預先插入類別與物件。

下列應用實例僅適用於「活動票券」類別：

更新票證

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

如要針對特定活動更新所有活動票券的欄位，例如活動場地的地址變更時，您只須使用 update 或 patch 來更新 EventTicketClass，或是使用 Google Pay Merchant Center 即可。Google 會將這項資訊套用到與更新後的 EventTicketClass 相關聯的所有 EventTicketObject。凡是在 EventTicketClass 層級定義的所有欄位，均應採取這樣的做法。

如要調整單一票證 (例如一名票券持有人的座位號碼變更時)，您必須使用 update 或 patch 更新單一 EventTicketObject。凡是在 EventTicketObject 層級定義的所有欄位，均應採取這樣的做法。

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

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

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

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

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

有關如何建立多張票證的按鈕範例，請參閱儲存多位參與者按鈕一節。

如要進一步瞭解票證的 UI 表示方式，請參閱將多張活動票券分組一節。

將多張活動票券分組

某些功能若用於群組 (而非個別物件)，運作方式就會改變，例如狀態通知，或是多張已儲存票證在使用者介面中的排列方式。

EventTicketObject 是否會被視為群組，就看 class.eventID 屬性是否已經定義。

使用 class.eventId 分組

class.eventId 屬性可以用來將票券分組，不論其他屬性如何定義。 舉例來說，假設兩個 EventTicketObject 物件有 class.eventId = "foo"，即使 class.eventName 和 class.dateTime.start 不同，也會被視為同一群組的物件。

使用 class.eventID 時，物件的以下屬性只要一致，就會被視為同一群組的物件。

  • 核發者 ID (來自 Google Pay API for Passes Merchant Center)
  • class.eventId

不使用 class.eventId 分組

如果 EventTicketObject 物件的 class.eventId 並未設定，則物件的下列所有屬性均須相同才會被視為屬於同一群組：

  • 核發者 ID (來自 Google Pay API for Passes Merchant Center)
  • class.eventName
  • class.dateTime.start

接收近期活動的通知

Google Pay 會在活動開始時間的三個小時前向使用者傳送通知，活動時間是由 class.dateTime.start 定義。

如要收到這種通知，使用者必須先啟用通知功能。如要確認是否已啟用通知功能，使用者可依序前往 [設定] > [通知]，查看是否已啟用 [票證最新消息]。

如果使用者已啟用螢幕鎖定的通知功能，則該通知會顯示在通知區域和螢幕鎖定畫面中。

通知的格式如下 (此格式無法修改)：

class.eventName
Expand for more options

使用者只要輕觸通知並解鎖裝置，相關票證就會顯示在 Google Pay 應用程式中。

如果使用者同時擁有多張票證，系統只會顯示時間最接近當下的可用票證。如果使用者儲存了已分組的票證 (如將多張活動票券分組一節中所述)，則系統只會顯示該群組中的一張票證。不過使用者輕觸通知時，可以向左或向右滑動來查看群組中的其他票證。

使用者開啟通知後，該通知會固定顯示且不會自動關閉，在 class.dateTime.end 過後 60 分鐘，該通知才會自動關閉。如果沒有提供 class.dateTime.end 時間，系統會改為使用 class.dateTime.start。

附帶優惠

附帶優惠能讓現有優惠出現在活動票券檢視畫面中，方便使用者找到相關內容。EventTicketObject 中的可寫入清單欄位 linkedOfferIds 會指出哪些優惠與活動票券相關聯。

在連結前建立優惠

如要連結附帶優惠，你必須先建立要連結至活動票券的優惠類別與物件。要進一步瞭解如何建立優惠，請參閱優惠一節。與獨立優惠不同，使用者不須特別儲存附帶優惠。OfferObject 中的 id 欄位會用來指向 EventTicketObject。

使用 REST API 呼叫 insert 或 update 或 patch 或 modifyLinkedOfferObjects 即可將現有優惠連結到活動票券。

建立活動票券時使用 insert 呼叫將優惠連結至活動票券，或是使用 update 呼叫將優惠同時與現有活動票券相連結和取消連結時，可以使用既定的格式將 EventTicketObject 的其餘部分寫入 linkedOfferIds 欄位：

{
  "id": "2945482443380251551.ExampleObject1",
  "classId": "2945482443380251551.ExampleClass1",
  ...
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

使用 patch 呼叫將優惠與現有的活動票券建立連結和取消連結時，linkedOfferIds 欄位可以是要求中的唯一欄位： 

{
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

然而，為了避免在處理陣列時出錯，請指定需新增和移除的附帶優惠，並透過可行方法省略不應更動的附帶優惠。建議你使用以下範例中的 modifyLinkedOfferObjects 方法：

{
  "linkedOfferObjectIds" {
    "addLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject1",
      "2945482443380251551.OfferObject2"
    ],
    "removeLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject3",
      "2945482443380251551.OfferObject4"
    ]
  }
}

設計含有附帶優惠的活動票券

附帶優惠會顯示在資訊卡區段和詳細資料區段之間的活動票券檢視畫面中，如下所示。輪轉介面最多只能顯示 5 個附帶優惠。如果活動票券還連結了其他優惠，使用者可按一下輪轉介面底端的 [更多] 按鈕來顯示所有優惠。

附帶優惠

按一下滑鼠時，附帶優惠將使用簡化的優惠設計，如下所示。

已點選的附帶優惠

處理過期的票證

開啟 Google Pay 應用程式後，使用者可在「票證」分頁下方的「過期的票證」專區查看所有封存票證和無效票證。如果票證符合下列一或多項條件，系統就會將其移至「過期的票證」專區：

  • 自 class.dateTime.end 到期已過至少 72 小時。如未指定 class.dateTime.end，則會改以 class.dateTime.start 當做依據。在 class.dateTime.end 或 class.dateTime.start 到期後的 72 到 96 小時之間，票證會移至「過期的票證」。
  • 當 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
              }
            }
    }
  }
  …
  …
  …
}