自動連結的票證
透過集合功能整理內容
你可以依據偏好儲存及分類內容。
背景
自動連結票證功能可讓您將其他票證傳送給已在 Google 錢包中擁有您現有票證的使用者。您也可以在使用者儲存主要 (主) 票證時，預先將票證連結至主要票證。自動連結票證會與主要票證分組，主要票證上方會顯示摘要，通知使用者新票證已連結。系統支援以下票證類型做為主要或連結票證：
- 活動票券
- 登機證
- 大眾運輸票證
- 優惠
- 禮物卡
- 會員票證
- 一般票證
|
|
|
主要通行證，指出已新增新通行證 |
與主要票證連結的新票證
|
應用實例
將票證連結至現有票證時，可能會有不同的用途。以下是幾個例子：
- 將優惠連結至現有會員卡。
- 將餐飲優待券連結至登機證或活動票券。
- 將停車票證連結至活動票券。
使用自動連結的票證時的注意事項
- 主要物件和已連結的物件必須使用相同的「issuerId」。
- 每個主要物件最多可連結 50 個物件。
- 系統無法保證會自動推送已連結的票證，這項作業會視為盡力而為。使用者可以選擇停用自動連結票證功能。如果用途是關鍵，而且使用者必須收到已連結的票證，建議您透過其他管道進行通訊，確保使用者新增票證。
- Google 錢包 AUP 的更新包括使用自動連結票證的指引，請遵守這些規定。
整合步驟
如果您已建立主要物件，可以略過步驟 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 個)。 |
除非另有註明，否則本頁面中的內容是採用創用 CC 姓名標示 4.0 授權，程式碼範例則為阿帕契 2.0 授權。詳情請參閱《Google Developers 網站政策》。Java 是 Oracle 和/或其關聯企業的註冊商標。
上次更新時間：2025-08-29 (世界標準時間)。
[null,null,["上次更新時間：2025-08-29 (世界標準時間)。"],[[["\u003cp\u003eAuto Linked Passes enable sending additional passes to users who already have an existing pass in their Google Wallet, linking them to a primary pass for easy access.\u003c/p\u003e\n"],["\u003cp\u003eSupported pass types include event tickets, boarding passes, transit passes, offers, gift cards, loyalty passes, and generic passes.\u003c/p\u003e\n"],["\u003cp\u003eLinking passes allows for various use cases such as attaching offers to loyalty cards, meal vouchers to boarding passes, or parking passes to event tickets.\u003c/p\u003e\n"],["\u003cp\u003eConsiderations include using the same issuer ID for primary and linked passes, a limit of 50 linked objects per primary object, and best-effort automatic pushing of linked passes.\u003c/p\u003e\n"],["\u003cp\u003eIntegration involves creating a primary and linked object, then updating the primary object with the linked object's ID in the \u003ccode\u003elinkedObjectIds\u003c/code\u003e parameter.\u003c/p\u003e\n"]]],["Auto Linked Passes enable grouping a new pass with an existing \"primary\" pass in Google Wallet. To implement, create a primary and a linked pass object, then update the primary object with the linked object's ID in the `linkedObjectIds` parameter. Both passes must share the same issuer ID, with a limit of 50 linked objects per primary pass. The system will group linked passes, but delivery is not guaranteed. Linked passes cannot be primary passes.\n"],null,["# Auto Linked Passes\n\n#### Background\n\nThe Auto Linked Passes feature lets you send additional passes to a\nuser who already has your existing pass in their Google Wallet. You can also\npre-link passes to a primary pass when a user saves the **primary**\n(main) pass. The Auto Linked Pass is grouped with the primary pass with a\ncallout above the primary pass informing the user that a new pass has been\nlinked. The following pass types are supported as primary or linked passes;\n\n- Event ticket\n- Boarding pass\n- Transit pass\n- Offer\n- Gift card\n- Loyalty pass\n- Generic pass\n\n|--------------------------------------------------------------|-------------------------------------|\n| | |\n| Primary pass with the callout that a new pass has been added | New pass linked to the primary pass |\n\n#### Use Cases\n\nYou may have different use cases for linking passes to an existing pass. Some\nexamples include:\n\n- Link an offer to an existing loyalty card.\n- Link a meal voucher to a boarding pass or event ticket.\n- Link a parking pass to an event ticket.\n\n#### Some considerations when using Auto Linked Passes\n\n- The primary object and linked object must use the same issuerId.\n- There is a limit of 50 linked objects per primary object.\n- Pushing linked passes automatically is not guaranteed and considered best-effort. Users can opt out of receiving Auto Linked Passes. If the use case is critical and the user must receive the linked pass, we recommend communicating through another channel to ensure the user adds the pass.\n- Updates to the [Google Wallet AUP](https://payments.developers.google.com/terms/aup) include guidance on the use of Auto Linked Passes which must be adhered to.\n\n#### Integration Steps\n\nIf you have already created a **primary** object you can skip step 1.\n\n1. Create an [object](/wallet/tickets/transit-passes/qr-code/use-cases/create) of any pass type listed with the required parameters. This is the **primary** object.\n2. Create another object of any pass type listed. This is going to be the **linked** object.\n3. Either before or after the primary object is saved, [update](/wallet/tickets/transit-passes/qr-code/use-cases/update) the primary object with the ID of the linked object in the linkedObjectIds parameter.\n\nThere is a minimum payload required to set the linkedObjectIds on a primary\npass. The 3 required parameters include;\n\n1. ISSUERID.PRIMARY_OBJECT_ID\n2. ISSUERID.PRIMARY_CLASS_ID\n3. ISSUERID.LINKED_OBJECT_ID\n\n#### Example JSON Request to add a linked object to a pass object\n\n```carbon\n ...\n {\n \"id\": \"ISSUERID.PASS_OBJECTID\",\n \"classId\": \"ISSUERID.PASS_CLASSID\",\n \"barcode\": {\n \"type\": \"qrCode\",\n \"value\": \"QR code\"\n },\n \"linkedObjectIds\": {\"ISSUERID.LINKED_PASS_OBJECTID\"}\n }\n ...\n```\n\n#### Example JSON Response after linking an object to a pass object\n\n```scdoc\n …\n \"state\": \"active\",\n \"linkedObjectIds\": {\n \"ISSUERID.LINKED_PASS_OBJECTID\"\n }\n …\n```\n\n#### Expected behavior\n\nAfter receiving a successful response, devices with the pass you updated\nshould receive the linked pass. This linked pass will be grouped together with\nthe primary pass. Users can see the linked pass by swiping right.\n\n#### Exception handling\n\nPotential errors may happen with incorrect use of the API which can\ninclude;\n\n| **Message** | **Reason** |\n|------------------------------------------------------------------------------------|----------------------------------------------------------------------|\n| Primary object and linked object don't share the same issuer ID. | You cannot attach a linked object to another issuer's object. |\n| Primary object and linked object refer to the same object. | You cannot attach the same object as the linkedObject. |\n| Linked object does not exist. | The linked object should already be inserted into the Wallet API. |\n| Linked object already has another linked object. Cannot add nested linked objects. | Linked objects cannot have another linked object. |\n| Object is already linked to another object. Cannot add nested linked objects. | Primary object cannot be a linked object by itself. |\n| Cannot add any more linked objects, limit exceeded. | The limit of 50 linked passes has been reached for the primary pass. |"]]
