一般 API 流程

下圖說明用來插入類別、儲存物件及更新物件的一般通訊流程。您必須負責實作伺服器、網路瀏覽器和 Google Pay API for Passes 之間的所有動作。下圖使用「會員」票證做為範例,但所有其他票證都可使用類似的流程。

JS 按鈕和 JWT 網頁連結適用的一般 API 流程

以下大綱及上圖詳細說明 JavaScript (JS) 按鈕和 JSON Web Token (JWT) 適用的一般 API 流程:

  1. 會員卡發卡機構建立 LoyaltyClass
    1. 您的伺服器定義 LoyaltyClass
    2. 您的伺服器發出 POST 要求,藉此在 Google Pay API for Passes 伺服器中插入 LoyaltyClass
  2. 您的伺服器有項服務,能針對特定 LoyaltyClass 產生 LoyaltyObject 的 JWT。這個物件代表使用者的會員卡。
    1. 您的伺服器使用 JWT 顯示 [儲存至 Google Pay] 按鈕:
      • 如果是網站,請使用我們的 JavaScript 按鈕。
      • 如果是電子郵件、簡訊和原生應用程式,請使用具有 [儲存至 Google Pay] 按鈕的 JWT 連結。
  3. 使用者在會員卡發卡機構的網站、電子郵件、原生應用程式或簡訊中,按一下或輕觸 [儲存至 Google Pay]
    1. 系統將使用者導向到達網頁來儲存 LoyaltyClass 物件。要儲存的物件會根據 JWT 顯示在到達網頁上。如果使用者是在原生應用程式中輕觸按鈕,系統會提示使用者將物件儲存在 Google Pay 應用程式中。
    2. 使用者按一下發卡機構屬性上的 [儲存至 Google Pay] 即可儲存 LoyaltyObject
    3. 系統將 LoyaltyObject 插入 Google 伺服器,然後推送至 Google Pay 應用程式。LoyaltyObject 稱為「會員票證」。
  4. 發卡機構更新卡片資料:
    1. 會員卡發卡機構使用 Object.id 執行 LoyaltyObjectGET 要求。
    2. 會員卡發卡機構更新 LoyaltyObject
    3. 會員卡發卡機構發出 PUTPATCH 要求,藉此在 Google Pay API for Passes 伺服器中插入更新的 LoyaltyObject
    4. 系統將 LoyaltyObject 推送至 Google Pay 應用程式。

「精簡版」JWT 變化版本

因為會遭到瀏覽器截斷,網頁連結中使用的 JWT 長度不得超過 1800 個字元。如果這會造成作業困難,建議您事先插入類別和物件。這樣一來,JWT 就只需要包含「物件 ID」欄位。

下圖顯示將 [儲存至 Google Pay] 按鈕新增至電子郵件或簡訊的 API 流程。

JWT POST 要求 API 流程

要在儲存物件之前執行建立及插入類別所需的後端工作通常很困難,不過若不執行,JWT 很可能會超過 1800 個字元的長度上限。這非常適合用於活動票券和登機證這類會隨時間建立許多類別的票證。

以下提供以航班類別為例的相關流程:

  1. 您的伺服器針對 FlightObjectFlightClass 產生 JWT。這兩個項目都是在 JSON 中定義,而且 FlightObject 會參照 FlightClass
  2. 這個 JWT 會從伺服器傳送至用戶端應用程式,應用程式即會顯示 [儲存至 Google Pay] 按鈕。請務必使用符合「儲存至 Google Pay」品牌規範的按鈕。
  3. 使用者在用戶端應用程式中按一下 [儲存至 Google Pay] 按鈕。
    1. 系統向 JWT 端點發出 POST 要求。這麼做會插入類別 ID 和物件 ID。如果 JWT 中的類別 ID 或物件 ID 已存在於系統中,則不會再次插入這些項目。請參閱我們的 API 參考資料說明文件,瞭解如何更新現有類別和物件。如已插入這些項目,則不會顯示任何錯誤。
    2. 系統開啟傳回的 URI 回應,以便使用者儲存票證。這個 URI 在傳回後具有一週的有效時間。

如要實作 API,請參閱 JWT POST 要求方法