用例

选择以下一种卡券类别可详细了解其使用方式。

Google Pay API for Passes 让您可以通过活动门票与用户互动。本指南中讨论的概念将帮助您更好地理解所保存的活动门票的功能。

要实现活动门票，请使用 JWT POST 请求方法或“瘦”JWT 链接，它们是预先插入类和对象的方法。

以下用例仅适用于活动门票类别：

更新卡券

如果卡券在创建后发生了变化，请使用 REST API 将这些变化传达给用户。如果这些变化仅影响类型，您还可以使用 Google Pay Merchant Center。卡券更新是与用户互动的重要途径。

要更新特定活动的所有门票的字段（例如当场馆地址发生变化时），您只需要 update 或 patch EventTicketClass，或者使用 Google Pay Merchant Center。Google 会将此信息传播到与已更新的 EventTicketClass 关联的所有 EventTicketObject。在 EventTicketClass 级别定义的所有字段就属于这种情况。

要更新单个卡券（例如当一位持票人的座位号发生变化时），您需要 update 或 patch 单个 EventTicketObject。在 EventTicketObject 级别定义的所有字段就属于这种情况。

有时，您可能不知道何时会发生变化，或何时会触发 update 或 patch 请求。在这种情况下，您可以安排定期针对每个类和对象发出 update 或 patch 请求。如果您调用 EventTicketClass list 方法，则可以找到特定发卡机构帐号的所有类。如果您调用 EventTicketObject list 方法，则可以找到特定类的所有对象。

创建可保存多个卡券的按钮

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

您必须使用以下任一格式创建 JWT：

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

如需通过示例了解如何为多个卡券创建按钮，请参阅保存多位参与者按钮。

如需详细了解卡券的界面表示法，请参阅给活动门票分组。

给活动门票分组

有些功能在用于一组对象（而非单个对象）时会具有不同的工作方式，例如在界面上保存多个卡券时的状态通知或组织方式。

EventTicketObject 是否被视为同组，取决于是否定义了同样的 class.eventID 属性。

使用 class.eventId 分组

class.eventId 属性可用于对门票进行分组，而不受其他属性的限制。例如，如果两个 EventTicketObject 对象都具有 class.eventId = "foo"，那么即使它们的 class.eventName 和 class.dateTime.start 不同，也会被视为同组。

使用 class.eventID 时，只要下列属性保持一致，对象即可被视为同组。

  • 发卡机构 ID（来自 Google Pay API for Passes Merchant Center）
  • class.eventId

不使用 class.eventId 分组

如果没有为 EventTicketObject 对象设置 class.eventId，则仅在下列所有属性一致的情况下，这些对象才会被视为同组：

  • 发卡机构 ID（来自 Google Pay API for Passes Merchant Center）
  • class.eventName
  • class.dateTime.start

接收即将进行的活动的通知

Google Pay 会在活动开始前三小时向用户发送通知。事件时间由 class.dateTime.start 定义。

若要接收此通知，用户必须启用通知功能。如需检查此功能是否已启用，用户可以转至设置 > 通知，并查看卡券的动态是否已开启。

如果用户启用了在锁定屏幕上显示通知的设置，那么通知会显示在通知区域和锁定屏幕中。

通知采用以下不可修改的格式： 

class.eventName
Expand for more options

如果用户点击通知并解锁设备，Google Pay 应用中会显示他们的卡券。

如果用户有多张卡券，系统只会显示即将可用的卡券。如果他们根据给活动门票分组保存了已分组的门票，通知仅会显示组中的一张门票。但是，用户点击这张门票后，可以左右滑动来查看该组中的其他卡券。

通知会被固定，而不是在用户打开后自动关闭。自动关闭的时间是 class.dateTime.end 之后 60 分钟。如果没有提供 class.dateTime.end 时间，则系统会使用 class.dateTime.start。

关联的优惠

“关联的优惠”允许在活动门票视图中展示现有优惠，让用户更容易发现相关内容。EventTicketObject 中的可写列表字段 linkedOfferIds 表明哪些优惠与活动门票关联。

在关联之前创建优惠

在与关联的优惠建立关联之前，必须已创建与活动门票相关联的优惠类和优惠对象。要详细了解如何创建优惠，请参阅优惠。与独立优惠不同，关联的优惠不需要用户特意去保存优惠。OfferObject 中的 id 字段用于指向 EventTicketObject。

通过 REST API 调用 insert、update、patch 或 modifyLinkedOfferObjects 方法，可以将现有优惠与活动门票相关联。

如果您通过调用 insert 在创建活动门票时将优惠与活动门票关联，或者通过调用 update 将优惠与现有活动门票关联或解除关联，则可以使用已建立的格式一同编写字段 linkedOfferIds 与 EventTicketObject 的其余部分：

{
  "id": "2945482443380251551.ExampleObject1",
  "classId": "2945482443380251551.ExampleClass1",
  ...
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

当您通过调用 patch 将优惠与现有活动门票关联或解除关联时，字段 linkedOfferIds 可能是请求中的唯一字段：

{
  "linkedOfferIds": [
    "2945482443380251551.OfferObject1",
    "2945482443380251551.OfferObject2"
  ]
}

不过，为了避免在处理数组时出现错误、指定需要添加和移除的关联优惠，并能够忽略应保持不变的关联优惠，我们建议您使用 modifyLinkedOfferObjects 方法（如下例所示）： 

{
  "linkedOfferObjectIds" {
    "addLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject1",
      "2945482443380251551.OfferObject2"
    ],
    "removeLinkedOfferObjectIds": [
      "2945482443380251551.OfferObject3",
      "2945482443380251551.OfferObject4"
    ]
  }
}

设计包含关联优惠的活动门票

关联的优惠会显示在卡片部分和详细信息部分之间的活动门票视图中，如下所示。轮播界面最多只显示 5 个已关联的优惠。如果有更多优惠与活动门票相关联，用户可以在轮播结束时点击“更多”按钮来显示所有优惠。

关联的优惠

被点击后，关联的优惠会使用简化的优惠设计，如下所示。

被点击后的关联优惠

处理过期卡券

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

  • class.dateTime.end 已过期至少 72 小时。如果未指定 class.dateTime.end，则系统会使用 class.dateTime.start。在 class.dateTime.end 或 class.dateTime.start 过期后的 72-96 小时之间，卡券会随时移至“过期卡券”。
  • object.validTimeInterval.end.date 过期。在 object.validTimeInterval.end.date 过期后的 24 小时内，卡券会随时移至“过期卡券”。
  • object.state 字段标记为 Expired、Inactive 或 Completed。

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

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

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

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

您可以链接到已保存的 Google Pay 卡券标题下方的应用或网站。此功能适用于所有类型的 Google Pay 卡券。

请求权限

使用面向店内商家的支持表单申请访问权限。请注意以下几点：

  • 您必须在表单中共享您的发卡机构 ID。
  • 在“问题类型”下面，选择“技术/API 集成”。
  • 选择链接 Google Pay 卡券下方的应用或网站。

对于指定的 Google Pay 卡券，定义 appLinkData 来设置您的应用或网站的 URI。URI 可采用任何格式，但我们建议您使用动态链接。

在下面的源代码中可以查看 appLinkData 字段的格式和上下文：

{
  "id": string,
  "classId": string,
  …
  …
  …
  "appLinkData": {
    "androidAppLinkInfo": {
      "appLogoImage": {
        "sourceUri": {
          "uri": string
        }
      },
        "title": {
          "defaultValue": {
            "language": string,
              "value": string
          }
        },
          "description": {
            "defaultValue": {
              "language": string,
                "value": string
            }
          },
            "appTarget": {
              "targetUri": {
                "uri": string,
                  "description": string
              }
            }
    }
  }
  …
  …
  …
}