自动关联的卡券

背景

借助“自动关联的卡券”功能,您可以向 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 相同的对象。
关联的对象不存在。 关联的对象应已插入到钱包 API。
关联的对象已与其他关联的对象相关联。无法添加嵌套的链接对象。 所关联对象不能包含其他关联对象。
对象已与其他对象相关联。无法添加嵌套的链接对象。 主要对象本身不能是关联对象。
无法再添加任何关联的对象,已超出限制。 主要卡券已达到 50 张关联卡券的上限。