自動連結的票證

背景

透過「自動連結的票證」功能，您可以將其他票證傳送給已在 Google 錢包中存有現有票證的使用者。您也可以在使用者儲存主要 (主) 票證時，預先將票證連結至主要票證。自動連結的票證會與主要票證分組，並在主要票證上方顯示註解，通知使用者已連結新票證。下列票證類型都可做為主要或已連結的票證：

  • 活動票券
  • 登機證
  • 大眾運輸票證
  • 優惠
  • 禮物卡
  • 會員卡/證
  • 一般票證
自動連結票證主要範例 自動連結票證的次要範例
主要通行證，指出已新增新通行證 與主要票證連結的新票證

應用實例

您可能會將票證連結至現有票證，以便執行不同的用途。以下是幾個例子：

  • 將優惠連結至現有的會員卡。
  • 將餐飲優待券連結至登機證或活動票券。
  • 將停車票證連結至活動票券。

使用自動連結票證時的注意事項

  • 主要物件和連結的物件必須使用同一個核發單位 ID。
  • 每個主要物件最多可連結 50 個物件。
  • 系統無法保證會自動推送已連結的票證，這項作業會視為盡力而為。使用者可以選擇停用自動連結票證功能。如果用途至關重要，且使用者必須收到已連結的票證，建議您透過其他管道進行溝通，確保使用者會新增票證。
  • Google 錢包 AUP 的更新包括使用自動連結票證的指引，請遵守這些規定。

整合步驟

如果您已建立主要物件，可以略過步驟 1。

  1. 使用所需參數建立任何列出的票證類型物件。這是主要物件。
  2. 建立其他任何列出的票證類型物件。這會是 linked 物件。
  3. 在儲存主要物件之前或之後，使用 linkedObjectIds 參數中連結物件的 ID 更新主要物件。

您必須提供最低酬載，才能在主要通道上設定 linkedObjectId。3 個必要參數包括：

  1. ISSUERID.PRIMARY_OBJECT_ID
  2. ISSUERID.PRIMARY_CLASS_ID
  3. ISSUERID.LINKED_OBJECT_ID

JSON 要求示例：將連結的物件新增至票證物件

  …
  {
    "id": "ISSUERID.PASS_OBJECTID",
    "classId": "ISSUERID.PASS_CLASSID",
    "barcode": {
      "type": "qrCode",
      "value": "QR code"
    },
    "linkedObjectIds": {"ISSUERID.LINKED_PASS_OBJECTID"}
  }
  …

將物件連結至票證物件後的 JSON 回應範例

  …
  "state": "active",
  "linkedObjectIds": {
    "ISSUERID.LINKED_PASS_OBJECTID"
  }
  …

預期的行為

收到成功的回應後，已更新票證的裝置應會收到已連結的票證。這個已連結的票證會與主要票證一併分組。使用者可以向右滑動來查看已連結的票證。

例外狀況處理

不當使用 API 可能會發生以下錯誤：

訊息 原因
主要物件和已連結的物件不共用相同的發出者 ID。 您無法將已連結的物件附加至其他發布者的物件。
主要物件和已連結的物件參照相同的物件。 您無法附加與 linkedObject 相同的物件。
已連結的物件不存在。 已連結的物件應已插入 Wallet API。
已連結的物件已包含另一個已連結的物件。無法新增巢狀連結物件。 已連結的物件無法再連結其他物件。
物件已連結至其他物件。無法新增巢狀連結物件。 主要物件本身無法是已連結的物件。
已達上限，無法再新增任何連結物件。 已達主要票證的連結票證數量上限 (50 個)。