自动关联的卡券
使用集合让一切井井有条
根据您的偏好保存内容并对其进行分类。
背景
借助自动关联的卡券功能，您可以向 Google 钱包中已有卡券的用户发送其他卡券。您还可以在用户保存主要（主）卡券时，预先将其他卡券关联到该主要卡券。自动关联的卡券会与主要卡券分组，主要卡券上方会显示一个宣传信息，告知用户已关联新卡券。以下卡券类型支持作为主要卡券或关联卡券使用；
- 活动门票
- 登机牌
- 公交卡
- 优惠
- 礼品卡
- 会员卡
- 通用卡券
|
|
|
主卡券，其中显示了添加了新卡券的宣传信息
|
与主卡券关联的新卡券
|
使用场景
将卡券关联到现有卡券可能有不同的用例。以下是一些示例：
- 将优惠与现有会员卡相关联。
- 将餐券与登机牌或活动门票相关联。
- 将停车证与活动门票相关联。
使用自动关联的卡券时的一些注意事项
- 主要对象和关联的对象必须使用相同的 issuerId。
- 每个主要对象的链接对象数量上限为 50 个。
- 我们无法保证自动推送关联的卡券，这种做法被视为尽力而为。用户可以选择不接收自动关联的卡券。如果用例很关键，并且用户必须接收关联的卡券，我们建议通过其他渠道进行通信，以确保用户添加该卡券。
- Google 钱包 AUP 更新包含有关使用自动关联的卡券的准则，必须遵守。
集成步骤
如果您已创建主要对象，则可以跳过第 1 步。
- 创建所列任何卡券类型的对象，并添加所需的参数。这是主要对象。
- 创建另一个所列的任何卡券类型的对象。这是 linked 对象。
- 在保存主对象之前或之后，使用 linkedObjectIds 参数中的关联对象 ID 更新主对象。
在主要通行中设置 linkedObjectIds 时，需要满足最低载荷要求。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 相同的对象。 |
| 关联的对象不存在。 |
关联的对象应已插入到钱包 API。 |
| 关联的对象已有一个关联的对象。无法添加嵌套的链接对象。 |
所关联对象不能包含其他关联对象。 |
| 此对象已与其他对象关联。无法添加嵌套的链接对象。 |
主要对象本身不能是关联对象。 |
| 已超出上限，无法再添加更多关联对象。 |
已达到主卡券的关联卡券数量上限（50 个）。 |
如未另行说明，那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可，并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情，请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC)：2025-08-29。
[null,null,["最后更新时间 (UTC)：2025-08-29。"],[[["\u003cp\u003eAuto Linked Passes enable sending additional passes to users who already possess an existing pass in their Google Wallet, grouping them together 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, allowing for diverse use cases like linking offers to loyalty cards or meal vouchers to boarding passes.\u003c/p\u003e\n"],["\u003cp\u003ePrimary and linked passes must share the same issuer ID, with a limit of 50 linked objects per primary object and best-effort automatic pushing that users can opt out of.\u003c/p\u003e\n"],["\u003cp\u003eIntegration involves creating primary and linked objects and updating the primary object with the linked object's ID, requiring specific parameters and adhering to Google Wallet's Acceptable Use Policy.\u003c/p\u003e\n"],["\u003cp\u003eSuccessful linking results in the linked pass being grouped with the primary pass on the user's device, accessible by swiping, while potential errors like issuer ID mismatch or exceeding the linked object limit can occur.\u003c/p\u003e\n"]]],["Auto Linked Passes enable associating additional passes with a user's existing primary pass in Google Wallet. Supported pass types include event tickets, boarding passes, and more. To link passes, create both primary and linked objects, then update the primary object with the linked object's ID using the `linkedObjectIds` parameter. Both passes must share an `issuerId` and the primary pass has a 50-linked pass limit. The `linkedObjectIds` are grouped above the main pass. Ensure correct API usage to avoid errors, such as exceeding limits or mismatched issuer IDs.\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/retail/offers/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/retail/offers/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. |"]]
