背景
借助自动关联的卡券功能,您可以向 Google 钱包中已存有现有卡券的用户发送更多卡券。您还可以在用户保存主卡券时将卡券预先链接到主卡券。自动关联的卡券与主卡券组合在一起,主卡券上方会显示一个标注,通知用户已关联新卡券。支持以下卡券类型作为主卡券或关联的卡券:
- 活动门票
- 登机牌
- 公交卡
- 邀约
- 礼品卡
- 会员卡
- 通用卡券
带有标注(表示已添加新卡券)的主卡券 | 与主卡券关联的新卡券 |
应用场景
将卡券关联到现有卡券可能有多种用例。以下是一些示例:
- 将优惠与现有会员卡相关联。
- 将餐券关联到登机牌或活动门票。
- 将停车卡与活动门票相关联。
使用自动关联的卡券时的一些注意事项
- 主要对象和关联的对象必须使用相同的颁发者 ID。
- 每个主要对象最多只能关联 50 个对象。
- 我们无法保证自动推送关联的卡券,这属于尽力而为。用户可以选择停止接收自动关联的卡券。如果该用例至关重要,并且用户必须接收关联的卡券,我们建议您通过其他渠道进行通信,以确保用户添加该卡券。
- Google 钱包 AUP 的更新包含有关如何使用自动关联的卡券的指南,必须遵守这些指南。
集成步骤
如果您已经创建了 primary 对象,则可以跳过第 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 相同的对象。 |
关联的对象不存在。 | 关联的对象应已插入到 Wallet API 中。 |
关联的对象已包含另一个关联的对象。无法添加嵌套的关联对象。 | 链接的对象不能有另一个关联的对象。 |
该对象已与其他对象关联。无法添加嵌套的关联对象。 | 主要对象本身不能是关联的对象。 |
无法添加更多关联对象,已超出限制。 | 主卡券的关联卡券数量已达到上限(50 个)。 |