用例

本指南概述了您可以使用 Google Pay API for Passes 就“公交卡”类别与客户进行互动的具体方式。您可以使用此 API 为客户提供以下选项:

更新公交卡

如果公交卡保存后发生了变化,您可以使用 updatepatch REST API 将这些变化传达给乘客。

要更新卡券的显示方式,您只需要 updatepatch TransitClass。对 TransitClass 的更改将传播给与该类关联的所有对象。这是一种快速简便的方法,可让您通过几次调用更新许多卡券的外观。

要更新单个卡券(例如当预计出发时间发生更改时),您需要 updatepatch 单个 TransitObject。在 TransitObject 级别定义的所有字段就属于这种情况,即使部分 TransitObject 对象共用相应字段的值也是如此。如果您调用 TransitObject list 方法,则可以找到特定类的所有对象。

有时,您可能不知道何时会发生变化,或何时会触发对 update 或 patch REST API 的调用。在这种情况下,您可以安排定期针对每个 TransitObject 调用 updatepatch REST API。

定义多航段旅程

通常,一次旅程会包含多个路段,而不是直接到达某人的目的地。为了完成此旅程,公交运营商可以为旅程的每个路段发放一张卡券,也可以共发放单独一张卡券。Google Pay for Passes 也模仿了这种操作,为每个路段提供一个 TransitObject 或提供一个多路段 TransitObject

针对每个路段使用一个 TransitObject 非常简单。您可以使用 object.ticketLeg 来定义路段。您可以创建和更新每张卡券,就好像它们是独立的一样。但是,您可能需要定义一种将这些卡券归为一组的方法。如需了解详情,请参阅对多个公交卡分组。这是定义多路段旅程的首选方式。

只有在每个路段中都接受这种类型的集合卡券,并且卡券上的信息(例如二维码)对于所有路段都相同时,才应使用多路段 TransitObject 对象。您可以使用 object.ticketLegs[] 列表来定义路段。卡券的卡片部分仅显示第一个路段的出发地和最后一个路段的目的地,而完整行程显示在卡券的详细信息部分中。

创建一个按钮即可保存多个卡券

如果用户购买了多张卡券,并且他们可能会将所有卡券保存到 Google Pay,那么一种很有用的做法是让用户只需点击一下保存到 Google Pay 按钮或链接即可保存许多对象。可以在 JSON 网络令牌 (JWT) 中定义多个对象或类。

JWT 必须采用以下任一格式:

  • 仅使用预先插入的类和对象。
  • 仅使用完全在 JWT 中定义的对象和类资源。

如需详细了解“卡券”的界面表示法,请参阅对多个公交卡分组

对多个公交卡分组

有些功能在用于组(而非单个对象)时会具有不同的工作方式,例如在界面上为多名乘客保存多个公交卡时的状态通知或组织方式。

TransitObject 对象仅在共用一个 object.classId, object.ticketLeg.departureDateTime 以及按优先级列出的以下属性之一时,才能分为一组:

  1. object.tripId
  2. object.purchaseDetails.confirmationCode

这是为了对同一旅程不同乘客的卡券分组。

如果您希望对卡券进行分组,我们建议您统一设置这些字段,即使特定 TransitObject 未与任何其他 TransitObject 分为一组也是如此。

处理过期卡券

Google Pay 应用的“卡券”标签下有一个“过期卡券”部分,其中包含所有已归档或无效的卡券。如果公交卡至少满足下列一个条件,则系统就会将其移至“过期卡券”部分:

  • object.ticketLeg.arrivalDateTime 或最后 object.ticketLegs[].arrivalDateTimeobject.validTimeInterval.end.date 起已过了 24 小时。
  • object.state 被标记为 expiredinactivecompleted

接收即将发布的通知

Google Pay 会在出发前三小时向用户发送通知。该通知的格式不可修改。

要接收与下次出发相关的此类状态通知,用户必须导航到设置 > 通知,并启用卡券的动态

如果用户将多个卡券归为一组,则系统将只显示一个通知。用户打开状态通知后,该状态通知不会自动关闭。自动关闭功能将于预计出发时间的 60 分钟后执行。

用户保存某张卡券后,可以通过引用其 objectId 链接到该卡券。

可以使用以下链接来引用卡券:

https://pay.google.com/gp/v/object/{<issuerId>}.{<ObjectId>}

您可以使用 Google Pay 应用或网络浏览器查看卡券。