Wallet Push Notifications

Use push notifications to deliver important information to your pass holders regarding their flight, event, or wallet pass program. For example, you might want to notify pass holders about weather conditions for an event, even when no changes were made to the time or location of the event. Or you might want to alert coupon pass holders that their coupon is set to expire.

Notification Appearance and Behavior

The push notification is generated by the native wallet app (Apple Wallet on iOS, Google Wallet on Android) and appears in banner format on the device’s lock screen.

The full notification message content appears in the “Last Notification” field on the back of the pass. The field always displays the most recent notification message. You can customize the field label when sending notifications via the API.

iOS notifications contain the message content:

Android notifications alert the pass holder that a new message has been added to the pass:

Including URLs

Your message text can include URLs that direct the pass holder to visit a webpage. To comply with Google Wallet and Apple Wallet Terms of Service, it is important that any URLs included in your message remain relevant to the pass or pass holder experience.

The URL appears as plain text in the notification. On the back of Apple Wallet passes, Apple automatically converts URLs to links. Google Wallet does not automatically convert URLs to links, but you can use an HTML anchor tag to make them links.

POST /v1/pass/123/notify HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>

{
   "value": "Redeem your discount: <a href=\"https://my.store.example.com\">https://my.store.example.com</a>"
}

Send Notifications from the Dashboard

You can send, schedule, and manage Wallet Push Notifications from the Airship dashboard. You cannot edit a message after sending, but you can cancel a scheduled message and create a new one.

From a wallet project:

1. Go to Templates and select a template.
2. Select Send message and configure:
   • Message — Enter your message text.
   • External ID — (Optional) Enter an ID for testing purposes.
   • Send time — Select Now or Schedule for later. If scheduling, specify the date, time, and time zone.
3. Select Send message.

To view a log of all notifications for the project, go to Dashboard or Templates and select Notification history. Only notifications sent from the dashboard are included in the history. Each message row includes the following information:

• Whether the message was sent or scheduled
• Scheduled send date and time in UTC
• Message text
• Username of the sender
• Message creation date and time in UTC
• Template ID and external ID, if any
• Status — Completed or Cancelled
• Actions — You can select Cancel for scheduled notifications.

Use the API method to delete notifications.

Send Notifications using the API

You can send notifications using any one of the Push Notifications endpoints across all pass identifiers.

Identifiers for individual passes:

• Pass ID
• Pass with external ID

Identifiers for groups of passes:

• Template ID
• Template with external ID
• Tag
• Segment

POST /v1/pass/123/notify HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>

{
   "value": "20% off any one regular priced item"
}

POST /v1/pass/123/notify HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>

{
   "label": "Current Promotion",
   "value": "20% off any one regular priced item"
}

Delete Notifications

Deleting a notification removes the “Last Notification” field from the back of the pass. It does not remove a push notification that has already been delivered.

DELETE /v1/pass/123/notify HTTP/1.1
Content-Type: application/json
Authorization: Basic <Base64 key>

Schedule Notifications

Use the Schedule an Update or Push Notification endpoint to set a future delivery date and time for a push notification.

POST /v1/schedules/12345 HTTP/1.1
Authorization: Basic <Base64 key>
Content-Type: application/json
Api-Revision: 1.2

{
   "name": "New Offer Update",
   "schedule": {
      "scheduled_time": "2017-04-10T18:45:00"
   },
   "notify": {
      "audience": {
         "tag": "TZ_ET"
      },
      "pass": {
         "notification": {
            "value": "20% off any one regular priced item"
         }
      }
   }
}

Automatic Notifications

For Google Boarding Passes, Google automatically notifies holders when departureGate, departureTerminal, departureTime, or boardingTime are updated. These are independent of any notifications you send through Airship.

Best Practices for Wallet Push Notifications

• Daily Notification Limits: Google Wallet currently limits to maximum three notifications per day per pass, and Apple Wallet limits to maximum twenty notifications per day per pass.

  Limit the daily notifications across both platforms to three notifications per day. Sending too many notifications can create an unpleasant user experience and increase the likelihood that your pass holder will disable wallet notifications or remove the pass.

• Identical Message Content: Airship blocks attempts to send identical notification messages back to back, regardless of how much time has passed in between.

  If your use case requires sending the same message content in back to back notifications, be sure to change the message slightly so that it is not exactly the same as the previous message. Otherwise, pass holders may assume subsequent messages were sent in error.