用例

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

使用 Google Pay API for Passes，您可以通过航班登机牌与用户互动。本指南中讨论的概念应有助于您更好地了解所保存的航班登机牌的功能。

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

FlightClass 和 FlightObject

与 Google Pay API for Passes 中的其他类别一样，登机牌的数据存储在两个数据结构中：FlightObject 和 FlightClass。本指南介绍了如何使用这些数据结构来支持使用您的航班登机牌。

FlightClass

FlightClass 用于保存特定日期和时间的特定航班的所有乘客或部分乘客通用的数据。例如，通用数据可以是运输公司、出发地、目的地、航班号或起飞时间。同一航班的所有乘客的登机牌上都会具有相同的数据。

FlightClass 还可以为同一架飞机上的部分乘客保存通用数据。例如，您可以为头等舱、商务舱和经济舱创建三种不同的 FlightClass 结构。这样您就可以为每个子集使用不同的字段（如果需要）。在这种情况下，这三个类代表的仍是在特定日期和时间飞行相同路线的同一架飞机。

FlightObject

FlightObject 代表在特定时间点搭乘特定飞机的每位乘客。例如，FlightObject 包含乘客姓名、座位号和登机牌条形码。每位乘客的登机牌上的这些信息都有所不同。

FlightObject 中包含的资源将保存到用户的 Google Pay 应用中。

支持的国家/地区

要了解哪些国家/地区支持航班登机牌，请参阅支持的国家/地区列表。 我们建议您根据用户购买机票所在的位置来限制保存到 Google Pay 按钮的显示位置。

用例

以下用例仅适用于航班登机牌类别：

更新卡券

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

要更新特定航班的所有登机牌的字段（例如预计出发时间发生变化时），您只需要 update 或 patch FlightClass，或者使用 Google Pay Merchant Center。Google 会将此信息传播到与已更新的 FlightClass 关联的所有 FlightObject。在 FlightClass 级别定义的所有字段就属于这种情况。

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

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

航班动态更新的数据来源

如果 class.localScheduledDepartureDateTime 给出的时间是过去 24 小时内的时间或接下来 48 小时内的时间，则系统会向用户显示航班动态卡片。在这种情况下，Google Pay 要么显示 Google 机票提供的数据，要么显示 Google Pay 卡券中给出的信息。使用哪个来源取决于以下情况：

  • 如果您未提供 class.localEstimatedOrActualDepartureDateTime，则系统会将 Google 机票作为数据来源。在这种情况下，系统将忽略您设置的任何 class.flightStatus。

    例如，如果航班延误，用户会在 Google Pay 应用的“首页”标签页下看到一张显示新的出发时间的卡片。“卡券”标签页下也会显示类似的说明发生延误的卡片。

  • 如果您提供了 class.localEstimatedOrActualDepartureDateTime，但未提供 class.flightStatus，则所提供的时间将用于确定航班是否发生了延误。然后，系统会根据以下逻辑通过卡片向用户显示航班动态：
    • 如果 class.localEstimatedOrActualDepartureDateTime 晚于 class.localScheduledDepartureDateTime，则向用户显示说明航班延误的卡片。
    • 如果 class.localEstimatedOrActualDepartureDateTime 不晚于 class.localScheduledDepartureDateTime，则向用户显示包含航班信息但没有任何动态消息的卡片。

如果您不想使用 Google 机票作为航班信息来源，请务必提供 flightStatus、localScheduledDepartureDateTime 和 FlightClass 的 localEstimatedOrActualDepartureDateTime。这样，卡片上就会仅使用您的数据。另外，如果您在 FlightClass 中使用 ICAO 机场代码，而不是 IATA 代码，则系统不会将 Google 机票用作航班信息来源。

当某些字段发生变化时，用户会收到有关这些变化的推送通知。如需了解详情，请参阅接收航班动态更新通知。

保存有多个航段的航程

一个航程往往会包含多个航段，而不是直飞到乘客的目的地。在此航程中，航空公司会为每个航段发放一张登机牌。Google Pay API for Passes 也参照了这种方式，为每个航段提供一个 FlightObject。

这意味着如果您有两名乘客从 SFO 飞往 LAX，然后飞往 TPE，就会有两个 FlightClass 结构和四个 FlightObject 对象：

  FlightClass A（SFO 到 LAX：航空公司、航班号、出发时间） FlightClass B（LAX 到 TPE：航空公司、航班号、出发时间）
乘客 Q FlightObject: id_01 FlightObject: id_02
乘客 Z FlightObject: id_03 FlightObject: id_04

这些字段反映了实际登机牌的信息。乘客 Q 和乘客 Z 均有两张纸质登机牌。

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

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

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

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

如需查看如何为多张卡券创建按钮的示例，请参阅保存多位乘客按钮。

如需详细了解“卡券”的界面表示，请参阅将多个登机牌归为一组。

将多个登机牌归为一组

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

FlightObject 对象仅在下列属性全部相同的情况下才能分为一组：

  • 发卡机构 ID（来自 Google Pay API for Passes Merchant Center）
  • class.flightHeader.carrier.carrierIataCode
  • class.flightHeader.flightNumber
  • class.localScheduledDepartureDateTime
  • object.reservationInfo.confirmationCode

如果两个 FlightObject 对象的上述任一属性不相同，则它们不会分为一组。

接收即将出发的航班的通知

Google Pay 会在航班出发前三小时向用户发送通知。航班出发时间由 class.localScheduledDepartureDateTime 定义。

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

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

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

Boarding pass for your flight to class.destination.airportIataCode
Expand for more options

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

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

通知会被固定，而不是在用户打开后自动关闭。自动关闭的时间是 class.localScheduledDepartureDateTime 之后 60 分钟。

接收航班动态更新通知

当航班的某些字段发生变化时，保存了一张或多张登机牌的用户会通过其设备收到推送通知。仅当满足特定条件时，才会出现这种情况。

出发地航站楼和登机口

如果您更改 class.origin.terminal 或 class.origin.gate，并且满足以下条件，用户将收到有关字段已更改的通知。

  • 距离 class.localScheduledDepartureDateTime 不到三个小时。

通知的格式如下：“某某航空公司已将登机口更新为 A1”。格式无法更改。

登机时间和起飞时间

如果您更改 class.localBoardingDateTime 或 class.localEstimatedOrActualDepartureDateTime，并且满足以下条件，用户将收到有关字段已更改的通知。

  • 距离 class.localScheduledDepartureDateTime 不到 24 小时。
  • 对应时间变化幅度达到至少 10 分钟或更长时间。

通知的格式如下：“某某航空公司已将登机时间更新为下午 6 点”。格式无法更改。

处理过期卡券

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

  • class.localScheduledDepartureDateTime 或 class.localEstimatedOrActualDepartureDateTime 已过期至少 24 小时。在 class.localScheduledDepartureDateTime 或 class.localEstimatedOrActualDepartureDateTime 过期后的 24-48 小时之间，卡券会随时移至“过期卡券”。
  • 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
              }
            }
    }
  }
  …
  …
  …
}