概览

合作伙伴可通过 Google Wallet Passs API 指定用于激活公交车票的端点。需要激活时，系统将向用户显示“激活”按钮，点按该按钮会使用下文所述的参数调用指定的端点。 端点应确保卡券在返回之前具有有效的兑换信息（条形码或目视检查），此时系统会更新用户钱包中的卡券，以显示兑换信息。请注意，在激活之前，系统不会显示任何现有的兑换信息。

激活 API

在 API 中使用公交类中的 activationOptions 指定激活端点。合作伙伴负责维持有效的激活端点，具有合理的延迟时间。

  activationOptions: {
    activationUrl: string
  }
字段 说明
activationUrl

string

为激活请求而调用的合作伙伴端点的网址。该网址应托管在 HTTPS 上，而 robots.txt 应允许 UserAgent:Google-Valuables 访问网址路径。

激活状态使用 activationStatus 字段存储在对象上。有效状态包括 NOT_ACTIVATED 和 ACTIVATED。激活端点应将对象更新为 ACTIVATED 状态，并确保对象具有有效的兑换信息，如条形码或视觉检测参数。deviceContext 字段可用于固定设备。

  activationStatus: enum (ActivationStatus),
  deviceContext: {
    deviceToken: string
  },
  hasLinkedDevice: boolean
字段 说明
activationStatus

enum (ActivationStatus)

此公交对象的激活状态。此状态会更改工单的表示形式，并允许用户执行操作；例如，如果设置为 NOT_ACTIVATED，则工单详情中会显示“激活”按钮。

可接受的值包括：

  • NOT_ACTIVATED
  • ACTIVATED
deviceContext

object (DeviceContext)

要与该对象关联的设备上下文。如果设置了此字段，则兑换信息将仅返回给指定设备。
hasLinkedDevice

boolean

此对象当前是否已关联到单个设备。
DeviceContext
字段 说明
deviceToken

string

如果设置了此字段，则兑换信息仅会在对象激活后返回给指定设备。此标识符不能用作跟踪用户设备的稳定标识符。它可以针对同一设备的不同卡券，甚至同一设备的不同激活方式而变化。进行此设置时，调用方还必须对要激活的对象设置 hasLinkedDevice。

请注意，deviceToken 是从激活参数 deviceContext 字段收到的

固定设备

通过固定设备功能，用户可以在一台设备上激活票券，并且仅在该设备上显示票券兑换信息。这与 ONE_USER_ONE_DEVICE 的 multipleDevicesAndHoldersAllowedStatus 是分开的，后者仅允许在一台设备上显示票券。建议将状态 ONE_USER_ALL_DEVICES 与设备固定搭配使用。

在激活之前，用户可以在自己的任何设备上查看票券并激活按钮。激活并固定到某台设备后，固定的设备会显示兑换信息，其他设备则会显示一个激活按钮，以便用户将门票转移到其他设备。如果移动工单的功能不是所需的功能，但在任何设备上激活则是在任何设备上激活，那么可以在激活期间将工单更新到 ONE_USER_ONE_DEVICE，而不是使用设备固定。

如需实现固定设备，应使用包含激活参数的 deviceToken 字段更新该对象，并在同一 API 调用中将 hasLinkedDevice 设置为 true。如果需要，可以在以后的 API 调用中将 hasLinkedDevice 设置为 false，从而解除票据与设备的关联。

设备固定序列图

激活参数

向激活端点发出的请求将包含以下参数。

JSON 示例：

  {
    classId: “123.classId”,
    objectIds: [ “123.objectId” ],
    expTimeMillis: 1669671940735,
    eventType: “activate”,
    nonce: “1c6fccce-6f66-11ed-a1eb-0242ac120002”,
    deviceContext: “6fba937a-6f6e-11ed-a1eb-0242ac120002”
  }

标识符 说明
classId

完全限定的类 ID。使用以下格式：

<issuer_id.class_id>
objectIds

使用以下格式的完全限定对象 ID 数组：

<issuer_id.object_id>
expTimeMillis 到期时间（以自纪元以来的毫秒数表示）。到期时间过后，需要将消息视为无效。
eventType 始终为 "activate"。
nonce 用于跟踪任何重复递送的 Nonce。
deviceContext

由 Google 生成的唯一 ID，代表用户正在对其执行操作的设备。 在进行将某个对象关联到设备的更新时，应使用此 ID。

对于来自给定设备的未来请求，此 ID 可能不固定。