用例

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

更新积分余额或货币余额

更新会员卡积分余额是与客户互动的重要方式。

会员卡积分余额有以下几种数据类型:

  • String
  • Int
  • Double
  • Money

loyaltyPoints.balancesecondaryLoyaltyPoints.balance 属性应只填充上述的一种数据类型。

任何更新都应先通过 GET 请求检索 LoyaltyObject。这可确保使用最新版本的对象。要保存更新后的对象,请发出 PUT 请求。

以下 REST URI 可分别用于 GET 一个对象和 UPDATE 一个对象:

GET https://www.googleapis.com/walletobjects/v1/loyaltyObject/resourceId
PUT https://www.googleapis.com/walletobjects/v1/loyaltyObject/resourceId

以下是使用不同语言更新对象的代码示例:

Java

// Get the specific Loyalty Object
LoyaltyObject obj = client.loyaltyobject().get("2945482443380251551.ExampleObject1").execute();
// Update points
obj.setPoints(points);
// Update the Loyalty Object
LoyaltyObject returnObj = client.loyaltyobject().update(obj.getId(), obj).execute();

PHP

// Get the specific Loyalty Object
Google_LoyaltyObject loyaltyObj = $service->loyaltyobject->get('2945482443380251551.ExampleObject1');
// Update the points
loyaltyObj.setLoyaltyPoints(points);
// Update the Loyalty Object
Google_LoyaltyObject loyaltyObj = $service->loyaltyobject->update('2945482443380251551.ExampleObject1',loyaltyObj);

Python

# Get the specific Loyalty Object
loyalty_object = service.loyaltyobject().get(resourceId='2945482443380251551.ExampleObject1')
# Update the points
loyalty_object['points'] = points
# Update the Loyalty Object
api_request = service.loyaltyobject().update(resourceId='2945482443380251551.ExampleObject1',body=loyalty_object)
api_response = api_request.execute()

保存至 Google Pay 应用

通过扫描或手动添加会员卡详细信息,用户可以将会员卡添加至 Google Pay 应用中。Google Pay API for Passes 会创建一个不引用您之前定义的 LoyaltyClassLoyaltyObject。您无需执行任何操作即可创建该新对象或新类。

与会员卡相关联的优惠

“与会员卡相关联的优惠”允许在会员卡视图中展示现有优惠,使相关内容更易于被用户发现。LoyaltyObject 中的可写列表字段 linkedOfferIds 表明哪些优惠与会员卡关联。通过 REST 调用 insert、update 或 modifyLinkedOfferObjects 方法,可以将现有优惠关联至会员卡。

在关联之前创建优惠

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

将优惠关联至会员卡

在创建或更新会员卡时,可使用 insert 调用将优惠关联至会员卡。您还可以使用一个新的 REST 调用,专门更改与会员卡关联的优惠。

在创建会员卡时关联优惠

您可以在创建会员卡时将优惠关联至会员卡。 通过向以下 REST URI 发出 POST 请求插入 LoyaltyObjects

https://www.googleapis.com/walletobjects/v1/loyaltyClass

您可以使用已建立的格式一同编写字段 linkedOfferIds 与 LoyaltyObject 的其余部分:

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

将优惠关联至现有会员卡

您也可以在会员卡创建后修改会员卡关联的优惠。这可以通过 update 调用或新端点 modifyLinkedOfferObjects 来实现,该端点专门用于关联和移除会员卡优惠。

您可以通过向以下地址发出 PUT 请求来更新现有的 LoyaltyObject

https://www.googleapis.com/walletobjects/v1/loyaltyObject/resourceId

modifyLinkedOfferObjects 方法对于会员卡类而言是唯一的,并会向以下地址发送 POST 请求:

https://www.googleapis.com/walletobjects/v1/loyaltyObject/resourceId/modifyLinkedOfferObjects

如需详细了解如何使用 modifylinkedofferobjects 调用,请点击此处

其请求正文采用以下格式:

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

移除会员卡关联的优惠

如果在 LoyaltyObject 的 update 调用期间向 linkedOfferIds 字段写入数据,该调用中包含的新优惠将覆盖现有优惠。此外,您可以使用 modifylinkedofferobjects 调用中的 removeLinkedOfferObjectIds 字段移除优惠。

此外,通过将关联优惠对象的 object.state 属性更新为 completed,可以将关联优惠从会员卡视图中移除。最后,一旦关联优惠设置的 object.validTimeInterval.end.date 到期,关联优惠将自动从视图中移除。请参阅参考 API

设计关联优惠的会员卡

关联优惠的会员卡具有与典型会员卡不同的模板,如下图所示。

Google Pay API for Passes 关联会员卡模板
  1. class.programLogo
  2. class.issuerName
  3. class.programName
  4. class.heroImage
  5. object.loyaltyPoints.pointsLabel
  6. object.loyaltyPoints.balance
  7. object.barcode.type

    object.barcode.value

  8. object.accountId
  9. class.hexBackgroundColor
  10. offerClass.heroImage
  11. offerClass.title
  12. offerObject.validTimeInterval.end
  13. class.accountNameLabel
  14. object.accountName
  15. class.accountIdLabel
  16. object.accountId
  17. *.imageModulesData.mainImage
  18. *.messages[0].header
  19. *.messages[0].body
  20. *.textModulesData.header
  21. *.textModulesData.body
  22. *.infoModuleData.labelValueRows[0].columns[0].label
  23. *.infoModuleData.labelValueRows[0].columns[0].value
  24. *.linksModuleData.uris[2]
  25. *.linksModuleData.uris[0]
  26. *.linksModuleData.uris[1]

关联至会员卡的优惠也使用不同的模板,如下图所示。

Google Pay API for Passes 关联会员卡模板
  1. class.heroImage
  2. object.barcode.type
    object.barcode.value
  3. object.barcode.alternateText
  4. class.title
  5. class.details
  6. object.validTimeInterval.end
  7. class.finePrint

地理围栏通知

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 小时内,卡券可随时移至“过期卡券”。
  • LoyaltyObjectstate 字段标记为 ExpiredInactiveCompleted

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

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

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

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