本頁面由 Cloud Translation API 翻譯而成。

Google 錢包中的 Motics 票券技術詳細資料

本頁面提供大眾運輸業者 (PTO) 和的系統整合商必須與 Google 整合，才能提供 Motics 票券。解決方案會利用 Google Wallet API 實作啟用端點。

系統架構

這個部分顯示系統架構和 Motics 儲存流程。

圖 1. Motics 票券省錢流程

圖 1 顯示了以下位置建立、啟用和固定 Motics 票券的流程：在多個實體中使用 Google 錢包：

Google 伺服器
PTO (系統整合商) 伺服器
Motics SCE 伺服器
網路商店

以下將詳細說明流程：

在初始設定階段，PTO 伺服器會建立 transitClass。使用 transitClass:Insert 傳遞 ownerId 和 activationUrl Google Wallet API 端點。這是一次性的活動。
接著，當使用者從網路商店購票時，PTO 伺服器會呼叫 transitObject:Insert 包含基本票務資訊和部分票務資訊欄位，指出這張 Motics 票券。
接著，PTO 伺服器和網路商店會共同合作，將「新增至 Google 錢包」按鈕，最後將票券的 JWT 傳回至即可。
現在，當 Google 伺服器呼叫啟用端點 (位於 activationUrl 後方)。
在回應步驟 4 中，PTO 伺服器會產生簽章 (sigSTB) 包含與 SAM 簽署的 SCE_ID。
回應 activationUrl 呼叫之前，PTO 伺服器必須先呼叫 transitObject:Patch 包含所有必要的 Motics 資訊。包括 Motics applicationData。
只有在 transitObject:Patch 呼叫成功之後，PTO 伺服器應會傳回成功 (HTTP-200) 回應給 activationUrl 呼叫。

實作「移動與」取消連結 Flow

為了提供良好的使用者體驗，使用者應能移動 Motics 裝置之間票證，但須符合發卡機構定義的特定限制。在這種情況下，核發機構必須實作移動及取消連結流程。

啟用端點

核發機構/PTO (或其系統整合商) 必須導入票證儲存票券後，Google 將叫用的啟用端點。網址應在叫用 transitClass:Insert 時提供至這個端點。啟用端點會產生簽章 (sigSTB) 並呼叫使用 transitObject:Patch 方法運作，其中的參數定義如下專區。

要求

傳送至啟用端點的要求格式如下：

Content-Type: application/json
Body: {
  "classId": "123.classId",
  "expTimeMillis": 1669671940735,
  "eventType": "activate",
  "objectId": string - base64 encoded ID of the TransitObject,
  "deviceContext": string - base64 encoded SCE_ID,
}

回應

主體為空白的 HTTP-200 成功回應在下列情況中應傳回：

已產生含有 SCE_ID 的 sigSTB 並使用 SAM 簽署
成功呼叫 transitObject:Patch 方法

Status: 200 - OK
Body: {}

延遲時間目標

啟用端點應遵循下列延遲目標：

所有要求中至少有 50% 必須在 200ms內回應
所有要求中至少有 95% 必須在 2s內回應
10s 設有固定上限

Google Wallet API 異動

下方概述 Google Wallet API 端點的變更，支援系統架構中所述的 Motics。

方法：transitClass:insert

這是用來建立 transitClass Google 的 Google Wallet API 端點後端。系統整合商需透過下列方法叫用這個 API 要求參數及任何其他適用欄位。詳情請參閱請使用 transitClass 和transitClass.Insert API 說明文件，完整的清單 (非 Motics) 參數等詳細資料。

POST: https://walletobjects.googleapis.com/walletobjects/v1/transitClass

JSON 表示法

Motics 整合至少需要有下列版本的 JSON 表示法： transitClass:insert 要求主體中的 transitClass。其他必要性必須一併設定 transitClass 個中繼資料欄位。

{
  "id": string,
  "multipleDevicesAndHoldersAllowedStatus": ONE_USER_ONE_DEVICE (MultipleDevicesAndHoldersAllowedStatus),
  "deviceCertificationSupport": {
     "vdvCertDetails": {
        "ownerId" string,
        "certEnvironment": PRODUCTION/STAGING,
      },
  },
  "activationOptions": {
    "activationUrl": string
  },
  ...
}

如果 certEnvironment =「正式版」，Google 伺服器將擷取憑證實際工作環境的 Motics 伺服器。當 certEnvironment = 準備 Google 伺服器就會從沙箱 Motics 伺服器擷取憑證。

方法：transitObject:insert

這是用來插入新 transitObject 的 Google Wallet API 端點使用者想要購買票券並新增至 Google 錢包的票券。系統整合商應傳遞 transitObject，主要是含有下列資訊的票券資訊：這個點。請參閱 transitObject 和transitObject.Insert API 查看完整版 (非 Motics) 參數清單以及其他詳細資料。

POST：https://walletobjects.googleapis.com/walletobjects/v1/transitObject

JSON 表示法

Motics 整合至少需要有下列版本的 JSON 表示法： transitObject:insert 要求主體中的 transitObject。其他物件中繼資料欄位，也可以設定包含。

{
  "id": string,
  "classId": string,
  "validTimeInterval": {
    object (TimeInterval)
  },
  "activationStatus": {
    "state": NOT_ACTIVATED (State)
  },
  "rotatingBarcode": {
    "type": AZTEC (BarcodeType),
    "valuePattern": "{vdv_barcode}",
    "deviceEntitlementSupport": {
      "vdvEntitlementDetails": {
        "applicationData": "",
      },
    },
  },
  ...
}

注意：

API 需要納入 applicationData 欄位。此時在 Motics 啟用流程中，applicationData 值尚不知道。因此必須設為空字串
- applicationData 稍後會在 transitObject:Patch 中設定呼叫。
validTimeInterval DateTime 物件必須具有時區偏移例如：2024-04-12T19:20:50.52-04:00

方法：transitObject:patch

這是用來修補 transitObject 的 Google Wallet API 端點 Google 用來產生及擷取 VDV 電子售票服務時使用的 Motics 條碼憑證請參閱 transitObject 和transitObject.Patch API 查看完整版 (非 Motics) 參數清單以及其他詳細資料。

PATCH:
https://walletobjects.googleapis.com/walletobjects/v1/transitObject/{resourceId}

JSON 表示法

Motics 整合需要下列表示法的 transitObject:patch 要求主體中的 transitObject。請注意，此代表已填入 applicationData 欄位的點。

{
  "activationStatus": {
    "state": ACTIVATED (State)
  },
  "rotatingBarcode": {
    "type": AZTEC (BarcodeType),
    "valuePattern": "{vdv_barcode}",
    "deviceEntitlementSupport": {
      "vdvEntitlementDetails": {
        "applicationData": string - Hex encoded,
      },
    },
  }
}

應用程式資料規格

以下是 The Motics 規格的內容 applicationData (代碼：0x5F07)。applicationData 應由採用「Tag-length-value (TLV)」格式的系統整合商。系統稍後提供這項資料封裝較大的資料結構，最終成為 QR code 的一部分再也不是件繁重乏味的工作

標記	長度	值
`0x9E`	81 80	簽名 `OctetString`，已簽署授權資料的前 128 個位元組 Google 字詞：`sigSTB`
`0x9A`	不一	殘差資料 `OctetString`，剩餘授權資料 Google 字詞：`sigSTB cont.`
`0x7F21`	81 C8	核發憑證 `OctetString`，憑證資料 Google 字詞：`Cert(puk_SAM)`
`0x42`	08 歲	憑證授權單位參考資料 (CAR) `OctetString`，CAR 值 Google 字詞：`CAR`