背景
自動連結票證功能可讓您將其他票證傳送給已在 Google 錢包中擁有您現有票證的使用者。您也可以在使用者儲存主要 (主) 票證時，預先將票證連結至主要票證。自動連結的票證會與主要票證分組，並在主要票證上方顯示說明文字，告知使用者已連結新票證。系統支援以下票證類型做為主要或連結票證：
- 活動票券
- 登機證
- 大眾運輸票證
- 優惠
- 禮物卡
- 會員憑證
- 一般票證
|
|
| 主要通行證，指出已新增新通行證 | 與主要票證連結的新票證 |
應用實例
您可能會將票證連結至現有票證，以便執行不同的用途。以下是幾個例子：
- 將優惠連結至現有會員卡。
- 將餐飲優待券連結至登機證或活動票券。
- 將停車票連結至活動票券。
使用自動連結票證時的注意事項
- 主要物件和已連結的物件必須使用相同的「issuerId」。
- 每個主要物件最多可連結 50 個物件。
- 系統無法保證會自動推送已連結的票證，這項作業會視為盡力而為。使用者可以選擇停用自動連結票證功能。如果用途至關重要，且使用者必須收到已連結的票證，建議您透過其他管道進行溝通，確保使用者會新增票證。
- Google 錢包應用程式使用者政策的更新內容包括自動連結票證的使用指南，您必須遵守這些指南。
整合步驟
如果您已建立主要物件，可以略過步驟 1。
- 使用所列必要參數，建立任何票證類型的物件。這是主要物件。
- 建立其他任何列出通行證類型的物件。這將是連結的物件。
- 在儲存主要物件之前或之後，使用 linkedObjectIds 參數中連結物件的 ID 更新主要物件。
您必須提供最低酬載，才能在主要通道上設定 linkedObjectId。3 個必要參數包括：
- ISSUERID.PRIMARY_OBJECT_ID
- ISSUERID.PRIMARY_CLASS_ID
- 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 個)。 |