Engage through Google Pay

Add messages when updating important information

All verticals have a message section. Use this section to highlight any important information, such as changes in the loyalty cards, gift cards, offers, event tickets, boarding passes for flights, and transit passes programs. For more information, see the design pages for your pass type:

Messages can be added to a class or object using insert, update, or patch methods by populating the messages[] array property. Alternatively, you can add to the existing messages (up to a maximum of 10) through the addMessage method. For more information, see the Reference.

The following code gets the current Offer expiration date ( validTimeInterval.end), then updates the expiration date and adds to the messages[] array. This way the user can tell information has changed when they view the saved Object on the Google Pay app:

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()

Note: A message is displayed immediately after an Object is inserted unless a startTime is set. The message appears in a list of messages indefinitely if endTime isn't provided. For more information, see the messages[] property.

Update state

Regardless of vertical, all objects have a state property. Updating the object's state is an important way to let your customer know that their Pass has been redeemed or is expired.

Any update should begin with a GET request to retrieve the Object. This ensures the latest version of the object is used. The version of the object should be incremented when the balance is changed. To save the updated Object, make a PUT request.

The following is an example of REST URIs that are used to GET an object and to PUT (update) an offerObject:

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

To learn more about the different GET and update methods by vertical, see the Reference.

Note: PUT (update) methods replace the entire object with the new definition you PUT. If you want to only update specific fields and retain the existing Object data, use PATCH methods as shown in the Reference. For differences between PUT and PATCH, see patch semantics for differences between PUT and PATCH.

The following code samples provide examples of how to update an offerObject in different languages. The code would be similar for objects in other verticals:

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()

Localization

Google Pay API for Passes allows merchants to provide localized content that will be served to the user based on their locale. Additional fields in the API are included to provide this capability. Every localized field is a LocalizedString nested object of the form:

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

The defaultValue is a required field for all LocalizedStrings. Both language and value are required in all translatedStrings.

The language field must refer to a BCP 47 language tag. (e.g. “en-US”, “en-GB”, “es-419”, etc). Value is the translated value of the string and is the string the user will see if their locale is matched.

Localization strings will be served to the user based on a best match of the user's locale. DefaultValue will be used if no appropriate translatedValue is provided. The non-localized fields will not be used if the corresponding localized field is set.

Determine if a user has removed their Pass

To check if a user has removed their Pass (such as a loyalty card) from Google Pay, retrieve the user's Object with the following get call and check its hasUsers attribute.

For example, to check for a loyaltyObject with GET:

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

If all users have deleted the Pass, or the Loyalty Card was removed, Google doesn't delete the object. The hasUsers attribute on the object is set to false.

Checking the hasUsers attribute can be done in real time when the user signs in to your website or app, or in a batch process for large number of users at once.

You defined the object ID used to retrieve the LoyaltyObject when you created the object. To provide personalized information to your users about their current tier and points balances, you must store the IDs in your own repository.

To learn more about different GET methods, see the Reference. Google doesn't provide real time notifications when an object is deleted. To do so would require you to implement a listener service and to comply with a certain Service Level Agreement.

Vertical-specific ways to engage

Some ways to engage are specific to a Pass vertical. Refer to the following "Use cases" pages for each vertical for implementation details: