Delivering Apple Wallet Passes via Push

This guide explains how to deliver Apple Wallet passes via push notifications. You can send a single unique pass to a specific customer, or create a shareable pass and push it out to as many customers as you like.

The Pass URL

If you don’t have one already, create a template in Urban Airship Reach, and use the Reach API to create a pass. The API also provides an option for creating a Public URL hosted at https://wallet-api.urbanairship.com. Use the Single Public URL option if you are creating a unique single-use pass, or the Multiple option if the pass is non-unique and can be shared many times.

A Single Public URL can only be downloaded once.

If you have downloaded a pass file that you wish to push, you will need to host it publicly or otherwise make it available via a URL. You will want to make sure the server hosting the pass has the mime type correctly set for .pkpass files.

Push the Pass

After creating the pass, find the app that will receive the push notifications.

If your app is capable of handling a Wallet custom key, follow these steps:

  1. Create a new Message.

  2. Enter your message.

  3. Turn Actions and Android to Off.

  4. Under iOS options add a custom key of wallet or ^w. The value should be the Public URL you created above, which may look like this:

    https://wallet-api.urbanairship.com/v1/download/pass/9cde359c-c6b6-c6b6-c6b6-1159b754c89c
    

  5. Choose your audience. If you are sending out a unique and non-shareable pass, then you probably want to target a single device. Otherwise, choose the option that best represents the target audience.

  6. Choose Delivery.

  7. Confirm and Send Now.

API Example:

{
    "audience":{
        "device_token" : "A7A8325D2D2B690C8C580183EB9FFFFF4DA97CA947A68D8CEBD6B89ADAD9413A"
    },
    "device_types":[ "ios" ],
    "notification":{
        "ios":{
            "alert":"20% off Kung Fu classes!",
            "extra":{
               "^w" : "https://wallet-api.urbanairship.com/v1/download/pass/9cde359c-c6b6-c6b6-c6b6-1159b754c89c"
            }
        }
    }
 }

If your app is not ready for Wallet custom keys, all is not lost. Replace steps 3 and 4 above with:

3 Under Actions choose URL and enter the Public URL for the pass you created above.

4 Turn Android off.

API Example:

{
   "audience":{
      "device_token":"A7A8325D2D2B690C8C580183EB9FFFFF4DA97CA947A68D8CEBD6B89ADAD9413A"
   },
   "device_types":[ "ios" ],
   "notification":{
      "ios":{
         "alert":"20% off Kung Fu classes!"
      },
      "actions":{
         "open":{
            "type":"url",
            "content":"https://wallet-api.urbanairship.com/v1/download/pass/9cde359c-c6b6-c6b6-c6b6-1159b754c89c"
         }
      }
   }
}

Viewing the Results

With an app that supports Wallet custom keys in push notifications, the user experience may look something like the following.

  1. The push notification promises a discount on Kung Fu classes.
  2. Tapping on the notification above takes you to the app where you’re presented with a choice on accepting an Apple Wallet pass.
  3. Choosing Add will install the pass in Apple Wallet. Choosing Review will display the pass and give you the options to Add or Cancel.

It is not necessary to change your app to handle the Wallet custom key in a push notification. If you send the pass as a URL Action, your app will pass the URL to Safari. Users will then be presented with the pass and the option to Add or Cancel, as above. Once the choice is made, users will remain in Safari.