用例

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

借助 Google Pay API for Passes，您可以通过会员卡与用户互动。通过本指南中讨论的概念，您可以更好地了解已保存的会员卡的功能。

以下用例仅适用于会员卡类别：

更新卡券。
在 Google Pay 应用中扫描。
关联的优惠。
地理围栏通知。
处理过期卡券。
链接到已保存的卡券。
从已保存的卡券进行链接。
注册和登录。

更新卡券

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

要更新卡券的显示方式，例如徽标发生更改时，您只需要 update 或 patch LoyaltyClass，或者使用 Google Pay Merchant Center。Google 会将此信息传播到与已更新的 LoyaltyClass 关联的所有 LoyaltyObject。在 LoyaltyClass 级别定义的所有字段就属于这种情况。

要更新单个卡券（例如会员卡积分余额发生变化时），您需要 update 或 patch 单个 LoyaltyObject。在 LoyaltyObject 级别定义的所有字段就属于这种情况。

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

在 Google Pay 应用中扫描

用户可以通过扫描或手动添加会员卡详细信息，将一些会员卡添加到其 Google Pay 应用中。Google Pay API for Passes 会创建一个 LoyaltyObject，它不会引用您之前定义的 LoyaltyClass。您无需执行任何操作即可创建新的对象或类。不过，Google Pay API for Passes 所创建的 LoyaltyObject 无法更新，其行为类似于静态卡券。

关联的优惠

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

在关联之前创建优惠

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

将优惠关联至会员卡

通过 REST API 调用 insert、update、patch 或 modifyLinkedOfferObjects，可以将现有优惠与会员卡相关联。

如果您通过调用 insert 在创建会员卡时将优惠与会员卡关联，或者通过调用 update 将优惠与现有会员卡关联或解除关联，则可以使用已确定的格式同时编写字段 linkedOfferIds 以及 LoyaltyObject 的其余部分：

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

注意：如果您 update 现有 LoyaltyObject 时未提供可写字段 linkedOfferIds，则所有优惠都将解除关联。

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

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

注意：要通过调用 patch 解除与所有已关联的优惠之间的关联，您必须明确将 linkedOfferIds 字段设置为 null 或 []。

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

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

设计包含关联优惠的会员卡

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

注意：如果关联的 OfferClass 中缺少主打图片，则关联的优惠将使用此视图中 LoyaltyClass 的背景颜色。

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

注意：此图片中包含完成简化的优惠设计所必需的所有字段。但是，创建有效的 OfferClass 或 OfferObject 并不意味着必须使用所有这些字段。如需查看必需字段的列表，请参阅 OfferClass insert 和 OfferObject insert 方法。

地理围栏通知

Google 可根据消费者与您定义的位置的距离来触发与消费者所保存 Object 相关的通知。

添加地理定位信息的方法有两种：

在创建 Google Pay API for Passes Merchant Center 帐号时，将使用 Google 地图中的地理定位信息。
通过 REST API 将坐标添加到对象或类中。

如需了解将坐标添加到对象或类的说明，请参阅使用 REST API 添加地理定位信息。

地理围栏概念

借助 Google 地图中的地理定位信息，Google 可通过算法确定用户是否身处该店铺或该区域内。此检测适用于根据 Google Pay API for Passes Merchant Center 帐号开发的所有类和对象。

该算法会考虑 GPS、Wi-Fi、蓝牙、移动、停留时间和其他因素。当确定用户身处指定地点时，地理围栏通知就会被触发。

如果在 Object 中手动指定坐标，则当用户距离坐标 150 米时，会触发地理围栏通知。

地理围栏通知的频率、限制以及用户停用机制

一个用户每天最多可接收四条通知。

如果在地理围栏中有多个保存的对象，则会显示一条不可修改的通知（每个 Google Pay API for Passes Merchant Center 帐号对应一条通知），其中以轮播界面显示不同的对象。对象可在轮播界面中循环显示：

要确保地理围栏通知生效，用户必须在 Google Pay 应用的通知设置中启用“关于您的内容的动态更新”，并且必须在其设备上开启定位服务。

使用 REST API 添加地理定位信息

您可以在类或对象中指定一组位置（即纬度和经度）。 Google 会对照与某个类或对象关联的位置列表查看用户当前的地理定位，并在用户距离其中某个位置 150 米以内时通知用户。以下代码示例展示了如何在您的类或对象中指定位置：

资源

{
  ... //Class or Object content

  "locations": [{
    "kind": "walletobjects#latLongPoint",
    "latitude": 37.422087,
    "longitude": -161446
  }, {
    "kind": "walletobjects#latLongPoint",
    "latitude": 37.429379,
    "longitude": -121.12272999999999
  }, {
    "kind": "walletobjects#latLongPoint",
    "latitude": 37.333646,
    "longitude": -122.884853
  }]
}

Java

List<LatLongPoint> locations = new ArrayList<LatLongPoint>();
locations.add(new LatLongPoint().setLatitude(37.422087).setLongitude(
    -122.161446));
locations.add(new LatLongPoint().setLatitude(37.429379).setLongitude(
    -121.12272999999999));
locations.add(new LatLongPoint().setLatitude(37.333646).setLongitude(
    -122.884853));

yourClassOrObject.setLocations(locations);

PHP

$locations = array(
  array(
    'kind' => 'walletobjects#latLongPoint',
    'latitude' => 37.442087,
    'longitude' => -122.161446
  ),
  array(
    'kind' => 'walletobjects#latLongPoint',
    'latitude' => 37.429379,
    'longitude' => -122.12272999999999
  ),
  array(
    'kind' => 'walletobjects#latLongPoint',
    'latitude' => 37.333646,
    'longitude' => -121.884853
  )
);

Python

offer_class_object = {
  # class or object content
  'locations': [{
    'kind': 'walletobjects#latLongPoint',
    'latitude': 37.442087,
    'longitude': -122.161446
    },{
    'kind': 'walletobjects#latLongPoint',
    'latitude': 37.429379,
    'longitude': -122.12272999999999
    },{
    'kind': 'walletobjects#latLongPoint',
    'latitude': 37.333646,
    'longitude': -121.884853
  }]
}

处理过期卡券

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

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 卡券标题下方的应用或网站。此功能适用于所有类型的 Google Pay 卡券。

请求权限

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

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

在您的 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
              }
            }
    }
  }
  …
  …
  …
}

借助会员注册和登录功能，用户可以搜索您的会员卡，并通过 Google Pay 加入或登录他们的帐号。如需了解详情，请参阅注册和登录。