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