## 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](https://developers.google.com/wallet/tickets/boarding-passes/rest/v1/flightclass/addmessage)
request with a `message_type` equal to
**`TEXT_AND_NOTIFY`** the following occurs:
1. A "[Message](https://developers.google.com/wallet/reference/rest/v1/Message.md.txt)" item is added to the "back of pass" (aka [Details
Template](https://developers.google.com/wallet/tickets/boarding-passes/resources/template#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](https://payments.developers.google.com/terms/aup) 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](https://developers.google.com/wallet/tickets/boarding-passes/rest/v1/flightclass/update) or [PATCH](https://developers.google.com/wallet/tickets/boarding-passes/rest/v1/flightclass/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](https://developers.google.com/wallet/reference/rest/v1/AddMessageRequest.md.txt)
so that the [Message](https://developers.google.com/wallet/reference/rest/v1/Message.md.txt)
which contains your new text has the [MessageType](https://developers.google.com/wallet/reference/rest/v1/Message.md.txt#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 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 Hyperlink<\a>",
"id": "message_id",
"message_type": "TEXT_AND_NOTIFY"
},
...
```
#### Example [Response](https://developers.google.com/wallet/tickets/boarding-passes/rest/v1/flightclass/addmessage#response-body) 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 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](https://developers.google.com/wallet/tickets/boarding-passes/use-cases/trigger-push-notifications#add-message-and-notify-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](https://developers.google.com/wallet/tickets/boarding-passes/use-cases/trigger-push-notifications.md.txt#update-field-and-notify-supported-fields) 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.
- A notification is only triggered if the start time of the event or flight is in 3 hours or less to avoid spamming users.
- 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](https://developers.google.com/wallet/tickets/boarding-passes/use-cases/updates#use_the_google_wallet_api) 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
##### [FlightObject](https://developers.google.com/wallet/tickets/boarding-passes/rest/v1/flightobject)
- boardingAndSeatingInfo.seatNumber
- boardingAndSeatingInfo.seatAssignment
### 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.
## Automatic Notifications Triggered by Google Wallet
### Upcoming Notification
Google Wallet sends a notification to the user three hours prior to the
flight. The flight time is defined by
`class.localScheduledDepartureDateTime`.
To receive this notification, the user must have notifications enabled. To check this, they can
navigate to **Settings \> Notifications** and see if **Updates about your passes** is
turned on.
The notification shows up in the notifications area, and in the lock screen, if the user has
[notifications enabled for the lock screen](https://support.google.com/android/answer/9079661).
The notification has the following unmodifiable format:
```
Boarding pass for your flight to `class.destination.airportIataCode`
```
If they tap the notification and unlock their device, their pass appears in the Google Wallet app.
If the user has multiple passes, only the soonest useable pass is shown. If they've added grouped
passes as per [Group multiple boarding passes](https://developers.google.com/wallet/tickets/boarding-passes/use-cases/group-multiple.md.txt), the notification only shows one of the passes in
the group. However, when they tap it, the user can swipe left and right to see the other passes in
that group.
The notification is pinned and won't auto-dismiss after a user opens it. Auto-dismiss occurs 60
minutes after `class.localScheduledDepartureDateTime`.
### Flight Update Notification
When certain fields of a flight are changed, users with one or more boarding passes added
receive a push notification on their devices. This happens only if certain conditions are met.
#### Origin terminal and gate
If you change `class.origin.terminal` or `class.origin.gate`,
and the following condition is met, a notification is sent that the field has changed.
- There are less than three hours to go before `class.localScheduledDepartureDateTime`.
The notification is in the following format: "Sample Airlines has updated your gate to A1." The
format cannot be changed.
#### Boarding time and departure time
If you change `class.localBoardingDateTime`
or `class.localEstimatedOrActualDepartureDateTime`, and conditions below are met, a
notification is sent that the field has changed.
- There are less than 3 hours to go before `class.localScheduledDepartureDateTime`.
- The respective time changes by at least 10 minutes or more.
The notification is in the following format: "_Sample Airlines has updated your boarding time to
6:00PM._" The format or language cannot be customized.