Trigger Push Notifications

Partner Triggered Notifications

Add Message and Notify

Background

After a user adds a pass you may want to send them a message related to the pass and ensure they are notified about it. Using the Add Message API request with a message_type equal to TEXT_AND_NOTIFY the following occurs:

  1. A "Message" item is added to the "back of pass" (aka Details Template) and a push notification is sent to users with the pass saved.
  2. Once the user taps the notification it opens Google Wallet to the front of the pass (a.k.a. Card view) and the user will see a callout at the top of the screen with a "View Message" button.
  3. Clicking the callout will take users to the back of the pass, where new unread messages are highlighted.

Some considerations when sending messages with notifications to users

  • Users must have notifications enabled for their passes to receive the push notifications related to messages.
  • Messages may contain URIs to your website or app. Hyperlinks must be a website or app related to the pass. It is a violation of the Acceptable Use Policy to send users to links not related to the pass.
  • You may send a maximum of 3 messages that trigger a push notification in a 24 hour period. Google may throttle your push notification delivery quota if it deems you are spamming your users.
  • The push notification users see on their lock screen is controlled by Google Wallet.
  • You can use the UPDATE or PATCH methods to edit or remove message data using the regular class or object endpoint.

Integration Steps

When you want to notify users about a new issuer message added using the AddMessage API, you will need to update the AddMessageRequest so that the Message which contains your new text has the MessageType TEXT_AND_NOTIFY instead of TEXT.

Example JSON Request to add message and notify in a Passes Class

  …
  "id": ISSUER_ID.CLASS_ID",
  "message":
    {
        "header":"My Class message header",
        "body": "My Class message body with a <a href="https://wallet.google">Hyperlink<\a>",
        "id": "message_id",
        "message_type": "TEXT_AND_NOTIFY"
    },
  …

Example JSON Request to add message and notify in a Passes Object

  …
  "id": OBJECT_ID",
  "classId": "ISSUER_ID.CLASS_ID",
  "message":
    {
        "header":"My Object message header",
        "body": "My Object message body with a <a href="http://play.google.com/store/apps/details?id=com.google.android.apps.maps">Hyperlink<\a>",
        "id": "message_id",
        "message_type": "TEXT_AND_NOTIFY"
    },
  …

Example Response to add message and notify for a Pass Class

  // The updated resource
  …
    {
      "kind": "walletobjects#walletObjectMessage",
      "header": "My Object message header",
      "body": "My Object message body with a <a href="http://play.google.com/store/apps/details?id=com.google.android.apps.maps">Hyperlink<\a>",
      "id": "message_id",
      "messageType": "textAndNotify"
    },
  …

Exception handling

Any attempts to notify more than 3 times will yield a QuotaExceededException response. Any further updates to the pass can be set using "TEXT" instead of "TEXT_AND_NOTIFY" as discussed in the Integration Steps.

Update Field and Notify

Background

After a user adds a pass you may want to trigger a push notification when you update certain fields. The notification will appear on the user's lock screen and inform them that there is an update on their pass. This notification will only trigger for a specific subset of fields defined below using the UPDATE and PATCH API methods. Once an API call to update the pass is made the following occurs:

  1. A push notification is triggered and displayed on the user's lock screen, informing them of a pass update.
  2. Once the user taps the notification it opens Google Wallet to the front of the pass (a.k.a. Card view) and the user will see a callout at the top of the screen with a "Review update" button.
  3. Clicking the button brings the user to a screen where they can see the fields that were changed by the update.

Some considerations when sending field update notifications

  • Users must have notifications enabled for their passes to receive the push notifications related to updates.
  • You may send a maximum of 3 updates that trigger a push notification in a 24 hour period. Google may throttle your push notification delivery quota if it deems you are spamming your users.
  • The push notification that users see on their lock screen is controlled by Google Wallet.
  • The notifyPreference field is a transient field that only lives on this request. For future requests when you wish to trigger a notification, you will have to reset this field on the class or object request.

Integration Steps

In order to trigger these notifications, you will need to use the existing UPDATE or PATCH calls and specify the notifyPreference. When updating a field on a class or object, you can add a new field, notifyPreference, to the class or object request to trigger the notification.

Example JSON Request to update and notify in a Class

    …
    "dateTime":
        {
            "kind": "walletobjects#eventDateTime",
            "doorsOpen": "2024-09-23T19:20:50.00"
        },
    "multipleDevicesAndHoldersAllowedStatus": "multipleHolders",
    "notifyPreference": "notifyOnUpdate",
    …

Setting the notifyPreference to notifyOnUpdate will trigger a notification, provided the updated field is currently supported.

Supported fields

LoyaltyClass
  • rewardsTier
  • secondaryRewardsTier
  • programName
LoyaltyObject
  • loyaltyPoints.balance
  • secondaryLoyaltyPoints.balance

Nearby Notifications

This feature will show users who have enabled notifications and granted precise, always on location access to the Google Wallet app a push notification reminding them that they have saved a pass relevant to their current location.

Integration Steps

How to use

To use this feature, you need to add locations to your classes and objects. You can add up to 10 locations per class and 10 per object. Use MerchantLocations in your class or object definition. You can add these locations when you use the insert, patch, or update methods.

After you add locations to a class or object, Google will send notifications to users when they are nearby. Google decides how close a user needs to be and how long they need to stay in the area before the notification is sent. Google also controls the text of the notification.

An example of a LoyaltyClass with the MerchantLocations set: 
{
  "kind": "walletobjects#loyaltyClass",
  "programLogo": {
  "kind": "walletobjects#image",
  "sourceUri": {
    "uri":
    ...
  }
  },
  "localizedProgramName": {
    "kind": "walletobjects#localizedString",
    "defaultValue": {
      "kind": "walletobjects#translatedString",
      "language": "en",
      "value": "Program Name",
    }
  },
  "id": Id1234,
  "version": "1",
  "allowMultipleUsersPerObject": true,
  "reviewStatus": "underReview",
  "enableSmartTap": false,
  "localizedIssuerName": {
    "kind": "walletobjects#localizedString",
    "defaultValue": {
      "kind": "walletobjects#translatedString",
      "language": "en",
      "value": "Issuer Name"
    }
  },
  "multipleDevicesAndHoldersAllowedStatus": "multipleHolders",
  "merchantLocations": [
    {
      "latitude": 37.79020867928078,
      "longitude": -122.39004
    },
    {
      "latitude": 37.42587,
      "longitude": -122.08620
    },
  ]
}

Expected Behavior

Users should get a sticky notifications about their passes when they are at one of the specified MerchantLocations. If they click the notification, it will open their pass in Google Wallet. Users can dismiss the notification with the swipe gesture. When a user leaves the location, the notification will disappear.