總覽

合作夥伴可透過 Google Wallet Passes API 指定 啟用大眾運輸票券。如果需要啟用，畫面中會顯示「啟用」按鈕 使用者輕觸後，就會呼叫指定端點，並提供下述參數。 端點應確保票證具備有效的兌換資訊 (條碼或 目視檢測)，此時使用者錢包中的票證就會更新。 顯示兌換資訊。請注意，啟用帳戶前，目前所有的兌換情形 這些資訊不會顯示

啟用 API

在 API 中使用 activationOptions 來指定啟用端點： 大眾運輸類別。 合作夥伴必須負責利用 可提供合理的延遲時間

  activationOptions: {
    activationUrl: string
  }
欄位 說明
activationUrl

string

會在啟用要求時呼叫的合作夥伴端點網址。網址應該 都是由 HTTPS 代管，而 robots.txt 應允許 UserAgent:Google-Valuables。

啟用狀態會使用 activationStatus 欄位儲存在物件中。 有效狀態包含 NOT_ACTIVATED 和 ACTIVATED。啟用 端點應將物件更新為 ACTIVATED 狀態，並確保 物件是否包含有效的兌換資訊，例如條碼或目視檢測參數。 deviceContext 欄位可用於裝置固定。

  activationStatus: enum (ActivationStatus),
  deviceContext: {
    deviceToken: string
  },
  hasLinkedDevice: boolean
欄位 說明
activationStatus

enum (ActivationStatus)

這個大眾運輸物件的啟用狀態。這個狀態會改變 讓使用者採取行動例如：「啟用」按鈕會顯示在 票券詳細資料 (如果設為 NOT_ACTIVATED)。

可接受的值為：

  • NOT_ACTIVATED
  • ACTIVATED
deviceContext

object (DeviceContext)

與物件建立關聯的裝置環境。如果設定，兌換資訊將 只會退回指定裝置
hasLinkedDevice

boolean

這個物件目前是否已連結至單一裝置。
DeviceContext
欄位 說明
deviceToken

string

如果設定這個選項，兌換資訊只會在啟用後退還至指定裝置 物件的另一個部分這個 ID 無法做為追蹤使用者裝置的穩定 ID。這項服務 可以變更同一裝置的不同票證 在同一部裝置上啟動。這項設定時，來電者也必須設定 所啟用物件的 hasLinkedDevice。

請注意，deviceToken 的來源為 啟用參數 deviceContext 欄位

裝置固定

使用者可以透過裝置固定功能，在一部裝置上啟用票券， 票券兌換資訊只會顯示在該裝置上。與 第 multipleDevicesAndHoldersAllowedStatus 個 (共 ONE_USER_ONE_DEVICE 個)，已推出 票券只能顯示在單一裝置上。建議您使用狀態 ONE_USER_ALL_DEVICES裝置固定。

啟用前，使用者能在任何裝置上看到票券和啟用按鈕 啟用並固定至裝置後，固定的裝置就會顯示兌換資訊 和其他裝置會顯示啟用按鈕，讓使用者可將票券移至另一個 裝置。如果不想移動票券，但在任何裝置上啟用，請 你可在啟用期間將支援單更新為 ONE_USER_ONE_DEVICE 而不是使用裝置固定功能

如要實作裝置固定功能，請使用 deviceToken 欄位更新物件 與啟用參數一併接收的 將 hasLinkedDevice 設為 true。如有需要，票券可自行處理 。hasLinkedDevice

裝置固定的序列圖

啟用參數

傳送至啟用端點的要求將包含下列參數。

JSON 示例： 

  {
    classId: “123.classId”,
    objectIds: [ “123.objectId” ],
    expTimeMillis: 1669671940735,
    eventType: “activate”,
    nonce: “1c6fccce-6f66-11ed-a1eb-0242ac120002”,
    deviceContext: “6fba937a-6f6e-11ed-a1eb-0242ac120002”
  }

ID 說明
classId

完整的類別 ID，格式如下：

<issuer_id.class_id>
objectIds

使用以下格式的完整物件 ID 陣列：

<issuer_id.object_id>
expTimeMillis 自 EPOCH 起的到期時間 (以毫秒為單位)。到期後 進而視為無效。
eventType 一律為 "activate"。
nonce Nonce，可追蹤任何重複的傳送事件。
deviceContext

Google 產生的不重複 ID，代表使用者執行操作的裝置。 進行更新時，應使用這個 ID，將物件連結至裝置。

指定裝置日後發出的要求時，這個 ID 可能不會保持不變。