通过 Google Pay 吸引用户

在更新重要信息时添加消息

所有类别都有一个消息部分。使用此部分突出显示重要信息，例如会员卡、礼品卡、优惠、活动门票、登机牌和公交卡的变化。如需了解详情，请参阅您的卡券类型对应的卡券模板页面：

您可以通过填充 messages[] 数组属性，使用 insert、update 或 patch 方法将消息添加到类或对象中。此外，您还可以通过 addMessage 方法在现有消息的基础上添加最多 10 条消息。如需了解详情，请参阅参考文档。

以下代码可获取优惠的当前失效日期 ( validTimeInterval.end)，然后更新失效日期并将其添加到 messages[] 数组。如此一来，当用户在 Google Pay 应用上查看已保存的 Object 时，就能知道信息发生了变化：

Java

// Get the specific Offer Object
OfferObject obj = client.offerobject().get("2945482443380251551.ExampleObject1").execute();

// Update the version, validTimeInterval.end, and add a message
obj.setVersion(obj.getVersion() + 1L);
obj.setValidTimeInterval(new TimeInterval().setEnd(new DateTime().setDate(new com.google.api.client.util.DateTime(new Date().getTime() + 263000000000L))));

// Get the current messages
List messages = obj.getMessages();

// Define new message
WalletObjectMessage message = new WalletObjectMessage()
  .setHeader("Important Notice")
  .setBody("Your offer has been extended!");

// Add the new message about updates to the Offer Object
messages.add(message);
obj.setMessages(messages);

// Update the Offer Object
OfferObject returnObj = client.offerobject().patch(obj.getId(), obj).execute();

PHP

// Get the specific Offer Object
Google_OfferObject $offerObj = $service->offerobject->get('2945482443380251551.ExampleObject1');

// Update the version, validTimeInterval.end, and add a message
$offerObj->setVersion($offerObj->getVersion() + 1);
$validTimeInterval = new Google_TimeInterval();
$startDateTime = new Google_DateTime();
$startDateTime->setDate('2013-06-12T23:20:50.52Z');
$validTimeInterval->setStart($startDateTime);
$endDateTime = new Google_DateTime();
$endDateTime->setDate('2013-12-12T23:20:50.52Z');
$validTimeInterval->setEnd($endDateTime);
$offerObj->setValidTimeInterval($validTimeInterval)

// Get the current messages
$messages = $offerObj->getMessages();

// Define new message
$newMessage = array(
  'header' => 'Important Notice',
  'body' => 'Your offer has been extended!',
  'kind' => 'walletobjects#walletObjectMessage'
);

// Add the new message about updates to the Offer Object
array_push($messages, $newMessage);
$offerObj->setMessages($messages);

// Update the Offer Object
Google_OfferObject offerObj = $service->offerobject->update('2945482443380251551.ExampleObject1',offerObj);

Python

# Get the specific Offer Object
offer_object = service.offerobject().get(resourceId='2945482443380251551.ExampleObject1')
# Update the version, validTimeInterval.end, and add a message
offer_object['version'] = str(int(offer_object['version']) + 1)
offer_object['validTimeInterval'] = {
     'start' : {'date':'2018-01-20T23:20:50.520Z'}
     ,'end' : {'date':'2018-01-24T23:20:50.520Z'}
    }

// Get the current messages
messages = offer_object['messages']

// Define new message
message = {
   'header': 'Important Notice',
   'body': 'Your offer has been extended!',
   'kind': 'walletobjects#walletObjectMessage'
 }

// Add the new message about updates to the Offer Object
messages.append(message)
offer_object['messages'] = messages

# Update the Offer Object
api_request = service.offerobject().update(resourceId='2945482443380251551.ExampleObject1',body=offer_object)
api_response = api_request.execute()

注意：除非设置了 startTime，否则在插入 Object 后，系统会立即显示一条消息。如果未提供 endTime，消息将一直显示在消息列表中。如需了解详情，请参阅 messages[] 属性。

更新状态

无论属于什么类别，所有对象都具有 state 属性。更新对象的状态是让您的客户知道其卡券已被兑换或已过期的重要方式。

任何更新都应先通过 GET 请求检索 Object。这可确保使用最新版本的对象。在余额发生变化时，应递增对象的版本号。要保存更新后的 Object，请发出 PUT 请求。

以下示例 REST URI 用于 GET 一个对象和 PUT（更新）一个 offerObject：

GET https://walletobjects.googleapis.com/walletobjects/v1/offerObject/resourceId
PUT https://walletobjects.googleapis.com/walletobjects/v1/offerObject/resourceId

要详细了解不同类别的 GET 方法和更新方法，请参阅参考。

注意：PUT（更新）方法会将整个对象替换为您 PUT 的新定义。如果只想更新特定字段并保留现有的 Object 数据，请使用参考中所示的 PATCH 方法。如需了解 PUT 和 PATCH 之间的差别，请参阅补丁语义中对 PUT 和 PATCH 之间差异的描述。

以下是使用不同语言更新 offerObject 的示例代码。其他类别的对象的代码也是类似的：

Java

// Get the specific Offer Object
OfferObject obj = client.offerobject().get("2945482443380251551.ExampleObject1").execute();
// Update the version and state
obj.setVersion(obj.getVersion() + 1L);
obj.setState("expired"); //see the Reference API for valid "state" options
// Update the Offer Object
OfferObject returnObj = client.offerobject().update(obj.getId(), obj).execute();

PHP

// Get the specific Offer Object
Google_OfferObject offerObj = $service->offerobject->get('2945482443380251551.ExampleObject1');
// Update the version and points
offerObj.setVersion(offerObj.getVersion() + 1);
offerObj.setState("state"); // see the Reference API for valid "state" options
// Update the Offer Object
Google_OfferObject offerObj = $service->offerobject->update('2945482443380251551.ExampleObject1',offerObj);

Python

# Get the specific Offer Object
offer_object = service.offerobject().get(resourceId='2945482443380251551.ExampleObject1')
# Update the version and state
offer_object['version'] = str(int(offer_object['version']) + 1)
offer_object['state'] = 'expired' # see the Reference API for valid "state" options
# Update the Offer Object
api_request = service.offerobject().update(resourceId='2945482443380251551.ExampleObject1',body=offer_object)
api_response = api_request.execute()

本地化

Google Pay API for Passes 允许商家根据用户的语言区域设置提供本地化内容。API 中包含了额外的字段来提供此功能。每个本地化字段都是采用以下形式的 LocalizedString 嵌套对象：

{
  "kind": "walletobjects#localizedString",
  "translatedValues": [
    {
      "kind": "walletobjects#translatedString",
      "language": string,
      "value": string
    }
  ],
  "defaultValue": [
    {
      "kind": "walletobjects#translatedString",
      "language": string,
      "value": string
    }
  ]
}

对于所有 LocalizedStrings，defaultValue 是必需字段。所有 translatedStrings 都必须填写语言和值。

语言字段必须引用 BCP 47 语言标记。（例如“en-US”、“en-GB”、“es-419”等）。值必须是翻译后字符串的值，当用户的语言区域匹配时，用户将看到翻译后的字符串。

系统将根据用户语言区域的最佳匹配结果向用户提供本地化字符串。如果未提供适当的 translatedValue，将使用 DefaultValue。如果设置了相应的本地化字段，则不会使用非本地化字段。

确定用户是否已移除其卡券

要检查用户是否已从 Google Pay 移除其卡券（例如一张会员卡），请使用以下 get 调用来检索用户的 Object 并检查其 hasUsers 特性。

例如，使用 GET 方法来检查 loyaltyObject：

GET https://walletobjects.googleapis.com/walletobjects/v1/loyaltyObject/objectId

如果所有用户都已删除卡券，或会员卡已被移除，Google 不会删除相应对象，但会将对象的 hasUsers 特性设置为 false。

您可以在用户登录您的网站或应用时实时检查 hasUsers 特性，也可以通过批处理一次性完成大量用户的检查。

您在创建对象时定义了用于检索 LoyaltyObject 的对象 ID。为了向用户提供关于其当前级别和积分余额的个性化信息，您必须将这些 ID 存储在自己的代码库中。

如需详细了解不同的 GET 方法，请参阅参考。Google 不会在删除对象时提供实时通知。要获得实时通知，您需要实现侦听器服务并遵守特定的服务等级协议。

某些类别特有的互动方式

某些互动方式为某一卡券类别所特有。如需详细的实现方法，请参阅每个类别的“使用情形”页面：

登机牌活动门票礼品卡会员卡优惠公交卡