自动关联的卡券

背景

借助“自动关联卡券”功能，您可以向 Google 钱包中已有您发放的卡券的用户发送其他卡券。您还可以在用户保存主（主要）卡券时，预先将卡券与主卡券相关联。自动关联的卡券会与主卡券归为一组，主卡券上方会显示一条标注，告知用户已关联新卡券。以下卡券类型可作为主卡券或关联卡券使用；

  • 活动门票
  • 登机牌
  • 公交卡
  • 优惠
  • 礼品卡
  • 会员卡
  • 通用卡券
自动关联卡券的主要示例 自动关联卡券次要示例
主要通行卡，带有“已添加新卡券”的标注 与主卡券关联的新卡券

使用场景

您可能需要将卡券关联到现有卡券，以满足不同的使用情形。以下是一些示例：

  • 将优惠与现有会员卡相关联。
  • 将餐券与登机牌或活动门票相关联。
  • 将停车证与活动门票相关联。

使用自动关联的卡券时的一些注意事项

  • 主对象和关联对象必须使用相同的 issuerId。
  • 每个主要对象最多可关联 50 个对象。
  • 我们无法保证自动推送关联的卡券，这属于尽力而为的范畴。用户可以选择不接收自动关联的卡券。如果使用情形非常重要，用户必须收到关联的卡券，我们建议通过其他渠道进行沟通，以确保用户添加卡券。
  • Google 钱包 AUP 的更新内容包括有关使用自动关联卡券的指南，您必须遵守这些指南。

集成步骤

如果您已创建主要对象，则可以跳过第 1 步。

  1. 使用必需的参数创建任意列出的卡券类型的对象。这是主要对象。
  2. 创建所列任何通行证类型的其他对象。这将是关联的对象。
  3. 在保存主对象之前或之后，使用 linkedObjectIds 参数中的关联对象 ID 更新主对象。

设置主卡上的 linkedObjectIds 需要最低有效负载。3 个必需参数包括：

  1. ISSUERID.PRIMARY_OBJECT_ID
  2. ISSUERID.PRIMARY_CLASS_ID
  3. 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 张）。