應用實例

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

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

---

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] 按鈕。

應用實例

以下應用實例僅適用於「登機證」類別：

• 更新票證。
• 儲存有多個航段的航程。
• 建立可儲存多張票證的按鈕。
• 將多份登機證分成一組。
• 接收近期航班的通知。
• 接收航班的最新消息通知。
• 處理過期的票證。
• 連結已儲存的票證。
• 從已儲存的票證連出。

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

更新票證

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

如要更新特定航班所有登機證的欄位 (例如預估起飛時間變更時)，你只需對 FlightClass 進行 update 或 patch，或是使用 Google Pay Merchant Center 即可。Google 會將這項資訊套用到與更新後的 FlightClass 相關聯的所有 FlightObject。凡是在 FlightClass 層級定義的所有欄位，均應採取這樣的做法。

如要更新單一票證 (例如一名乘客的座位號碼變更時)，則需對單一 FlightObject 進行 update 或 patch。凡是在 FlightObject 層級定義的所有欄位，均應採取這樣的做法。

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

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

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

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

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

航班最新消息的資料來源

不論 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 結構和四個 FlightObject 物件：

	FlightClass A (SFO 到 LAX：航空公司、航班號碼、起飛時間)	FlightClass B (LAX 到 TPE：航空公司、航班號碼、起飛時間)
乘客 Q	FlightObject: id_01	FlightObject: id_02
乘客 Z	FlightObject: id_03	FlightObject: id_04

這些欄位可反映實體登機證的情況。乘客 Q 和乘客 Z 都會有兩張紙本登機證。

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

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

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

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

注意事項：請務必使用相同的 JWT 格式，藉此確保格式一致。

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

如要進一步瞭解票證的 UI 表示法，請參閱將多份登機證分成一組一節。

將多份登機證分成一組

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

只有所有 FlightObject 物件的下列屬性都相同時，物件才會被視為一個群組：

• 核發者 ID (來自 Google Pay API for Passes Merchant Center)
• class.flightHeader.carrier.carrierIataCode
• class.flightHeader.flightNumber
• class.localScheduledDepartureDateTime
• object.reservationInfo.confirmationCode

如果兩個 FlightObject 物件的上述任一屬性有所不同，就不會被分成一組。

注意：上述屬性中，有些是類別屬性，有些則是物件屬性。透過這樣的設計，你可以將不同類別的 FlightObject 物件分組。

接收近期航班的狀態通知

Google Pay 會在航班起飛時間的三個小時前向使用者傳送通知，航班時間是由 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 不到三小時。

通知的格式如下：「順風航空已將登機門變更為 A1」。通知格式為固定的，無法修改。

登機時間和起飛時間

如果你變更了 class.localBoardingDateTime 或 class.localEstimatedOrActualDepartureDateTime，並且符合下列條件，系統就會傳送欄位已變更的通知。

• 距離 class.localScheduledDepartureDateTime 不到 24 小時。
• 時間分別提前或延後 10 分鐘以上。

通知的格式如下：「順風航空已將登機時間變更為晚上 6:00」。通知格式為固定的，無法修改。

處理過期的票證

開啟 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 票證標題下方，連結至您的應用程式或網站。這項功能適用於所有類型的 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
              }
            }
    }
  }
  …
  …
  …
}