總覽

合作夥伴可透過 Google Wallet Pass API，指定用於啟用大眾運輸票券的端點。如果需要啟用，使用者會看到「啟用」按鈕，輕觸該按鈕就會以下方說明的參數呼叫指定端點。端點應確保票證在退貨前具備有效的兌換資訊 (條碼或目視檢查)，屆時使用者錢包中的票證會更新，以顯示兌換資訊。請注意，啟用前，系統不會顯示任何現有的兌換資訊。

啟用 API

透過大眾運輸類別的 activationOptions，在 API 中指定啟用端點。合作夥伴負責以合理延遲的方式維持正常運作的啟用端點。

  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。這項設定可能會變更同一部裝置的不同票證，甚至是在同一部裝置的不同啟動情境中變更。設定這項設定時，呼叫端也必須在啟用的物件上設定 hasLinkedDevice。

請注意，deviceToken 是從啟用參數「deviceContext」欄位接收

裝置固定

裝置固定功能可讓使用者在一部裝置上啟用票券，而票券兌換資訊只會顯示在該裝置上。這與 ONE_USER_ONE_DEVICE 的 multipleDevicesAndHoldersAllowedStatus 不同，後者僅允許在單一裝置上顯示票券。建議使用 ONE_USER_ALL_DEVICES 狀態搭配裝置固定功能。

在啟用前，使用者可以在任何裝置上查看票券和啟用按鈕。啟用並固定至裝置後，已固定的裝置會顯示兌換資訊，其他裝置則會顯示啟用按鈕，讓使用者可將票券移至其他裝置。如果不需要移動票券的功能，但在任何裝置上啟用該功能，則可在啟用期間將票證更新為 ONE_USER_ONE_DEVICE，而非使用裝置固定功能。

如要實作裝置固定功能，請使用啟用參數收到的 deviceToken 欄位更新物件，並將相同 API 呼叫中的 hasLinkedDevice 設為 true。如有需要，只要在日後的 API 呼叫中將 hasLinkedDevice 設為 false，即可視需要取消與裝置的連結。

裝置固定序列圖表

啟用參數

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

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 不一定一致。