背景
借助自动关联的卡券功能,您可以向 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 个)。 |