用例

本指南概要介绍了您可以使用 Google Pay API for Passes 中的“优惠”类别与您的客户进行互动的几种方式,具体如下所示:

优惠失效通知

为提醒用户在有效期内使用优惠,系统会在优惠即将失效的 48 小时前触发默认通知。要触发通知,优惠必须符合以下条件:

  1. 之前从未在用户的设备上触发失效通知。
  2. 必须在 validTimeInterval.end.date 中设置有效的未来失效时间 datetime
  3. 在用户的设备上保存的时间超过 12 小时。
  4. 可写字段 disableExpirationNotification 不能设置为 True。此字段默认设置为 false

以下屏幕截图显示了不可修改的默认通知示例:

  1. 优惠(今天、明天、[x] 天后)失效
  2. class.title
  3. class.titleImage

无法自定义优惠失效通知中的标头。

限制时段

如果将优惠失效通知的显示时段设置为用户当地时间晚上 10 点到早上 6 点之间,此优惠会在此时间段之前或之后显示。

自定义优惠失效通知时间

您可以在 OfferObjectsOfferClasses 中使用 message.displayInterval.start.date 字段自定义显示 Offer 失效通知的时间。如果设置了自定义通知时间,触发失效通知的依据为 message.displayInterval.start.date,而不是 validTimeInterval.end.date 计算的默认逻辑。以下是失效通知的自定义时间示例:

{
  “message”: {
   “messageType”: “expirationNotification”,
   “displayInterval”: {
     “start”: {
      “date”: datetime
     }
   }
  }
}

displayInterval.start.date 设置了显示通知的时间。最早可以设置为失效日期之前的 30 天。如果指定的时间跨度超过此值,系统将在失效前的第 30 天触发通知。此消息无需标头和正文字段,即使您有提供也不会被使用。

地理围栏通知

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

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

  1. 在创建 Google Pay API for Passes Merchant Center 帐号时,将使用 Google 地图中的地理定位信息。
  2. 通过 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 小时内,卡券可随时移至“过期卡券”。
  • OfferObjectstate 字段标记为 ExpiredInactiveCompleted

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

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

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

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