Pass Distribution Methods

Passes are distributed via URL:

  1. The URL points to the pass.
  2. When an end user opens the URL, they can view and install the pass.

After you design a pass template, you then generate the template's pass URLs, using these methods:

API

Dashboard

After you generate the URLs, you can then distribute the passes via the method of your choosing. The user experience and setup steps for various methods are described below.

The Pass URL

Hosting

Pass URLs are hosted by Urban Airship.

Note

URLs that are not activated will expire after 6 months.

Apple vs Google URL Differences

From the user’s perspective, the install experience is the same on either iOS or Android — the pass is downloaded directly to either the Apple Wallet or Google Pay app. However, there are differences between the pass URLs:

  • Apple Wallet: Pass URLs generated from Apple Wallet templates point to a stored .pkpass file. A .pkpass file can be considered similar to a PDF or any other document that you might link to.

  • Google Pay: Pass URLs generated from Google Pay templates provide a deep link from Google into the Google Pay app so that the pass can be downloaded directly without requiring a browser window to facilitate the request.

For additional detail about the publicUrl object and pass deep linking, see: API: Passes.

Single- vs Multi-Use Public URL

When generating a pass via the API, you have the option to create a publicly accessible URL for the pass, hosted at https://wallet-api.urbanairship.com. The Public URL can be either a single or multiple (multi-use) pass type, referring to the number of times the pass can be be downloaded.

  • Use the Single option if you are creating a unique pass. A Single Public URL can only be downloaded once, but the user can share the pass from the Apple Wallet directly.

  • Use the Multiple option if the pass is non-unique and can be downloaded by multiple devices and shared many times.
Note

A Public URL is required for Android and optional for iOS.

Note

The URLs returned by the CSV Batch Importer are multi-use passes — they can be downloaded by multiple devices.

Distribution Methods

Send Test Pass

After you have saved your Template, send yourself a test pass.

  1. Open your project from the dashboard, then click Templates in the navigational header
  2. Click anywhere in a template's row to see its expanded view, then click the Edit Design button. If you have only one template in the project, the initial view is expanded.
  3. Follow the steps below for either Apple or Google.

Apple

Receive the pass via email, then save it to your device. iOS devices must be running at iOS 6 or later to view passes.

  1. Click the Send Test Pass button at the bottom of the screen.

  2. Enter an email address in the browser dialog that opens, then click the OK button.

  3. View the pass on your mobile device: Open the Mail app on your iOS device, open the "New Pass Generated..." email, tap the Wallet attachment to view the pass, then tap the Wallet attachment to save and view the pass.

Google

Save the pass to Google Pay on the web, then view the pass on your Android device. Make sure you are first logged in to your Google account before attempting to save the pass.

  1. Click the Test Pass button at the top of the screen, then click the Save the pass... link in the confirmation box that appears.The pass will open in Google Pay in a new tab. If not yet logged in, Google will prompt you to do so.

  2. Click the Save button to save the pass to your Google Pay app.
  3. View the pass on your mobile device: Check the Google Pay application on your device, and open your saved pass to view it.

Setup

See the Triggers Tutorial for setup steps.

Send an Apple Wallet pass URL to a user via email, SMS, etc.

When the user clicks the link, the device’s default browser will open the pass URL, and the user may then save the pass to the device's Wallet app.

Setup

No set up is required. Once you generate an Apple Wallet pass URL, it is ready to be distributed to users, however, it must be a publicly accessible URL. See: Single- vs Multi-Use Public URL.

Urban Airship hosts the pass for your convenience, but if the use case requires you to download and host the file yourself, you can.

  • Make sure the server hosting the pass has the MIME-type correctly set for .pkpass files.

  • For Mobile Safari to recognize the file, your server has to be properly configured to support the MIME-type application/vnd.apple.pkpass. The process for adding MIME-type support varies by web server vendor. Many hosting companies provide a control panel interface which allows you to easily add a new type.

Send an Google Pay pass URL to a user via email, SMS, etc.

When the user clicks the link, the device’s Google Pay app will open the pass URL, and the user may then save the pass.

Setup

No set up is required. Once you generate an Google Pay pass URL, it is ready to be distributed to users.

Note

Because of the potential length of Google pass URLs, we advise using dynamic links instead of create pass calls. Dynamic links are ~120 characters maximum.

Save to Google Pay

Note

Pass creation via the API is the preferred method due to ease of use and implementation, but in some cases you may want to use the Save to Google Pay method.

Save to Google Pay lets your users save an object to Google Pay from the web at the click of a button. Urban Airship simplifies this process by providing an API function that returns the JavaScript that will render the Save to Google Pay button with the necessary information to create a wallet object. All you need is the user information and any pass-specific details.

User Experience

Once the Save to Google Pay button is rendered on the page, a user can hover over it to display the currently logged in account, with an option to change to a different account. If not logged in, a log in window appears.


After clicking the button while logged in with a valid Google account, the Google Object will be created and saved to the user's wallet. Depending on how you configure the onSuccess JSON value, you can redirect to a different page or simply do nothing, and the Google JavaScript library will let the user know the card was successfully saved.

Setup

  1. Define the Origin URL in the project's Settings API menu.

  2. Generate the JavaScript for rendering the Save to Google Pay button.

    In order to generate the necessary JavaScript, a server-side post to our API with the necessary information must occur. The post is as follows, with the template ID matching the template ID in Reach:
    POST /v1/pass/{templateID}/saveToWallet

  3. Include the JavaScript in Google's steps for Integrating the Save to Google Pay Button.

Save to Google Pay via Email

Save your users a click by adding a deep link to a pass from a Save to Google Pay button in an email and from the subject line in Gmail.

User Experience

The user experience is the same as for Save to Google Pay.

Setup

Since the pass URL for Google is already a deep link, just use that URL in a Save to Google Pay button in an email or email subject line. See Google's documentation: Save to Google Pay via Email.

Send via Message

Pass URLs can be included when you send a message via Engage.

Note

Because of the potential length of Google pass URLs, we advise using adaptive links or dynamic links instead of create pass calls. Dynamic links are ~120 characters maximum.

User Experience

When the user taps the notification or link, the device’s default browser will open the pass URL, then the user may save the pass. If sending a web notification, the pass URL opens in the browser as any other link would.

This an example of receiving a push notification on a mobile device:

  1. The push notification promises a discount on party supplies.
  2. The user taps the notification.

    • URL: If the pass was sent via the Web Page (URL) or Adaptive Link action, tapping the notification opens the pass URL in the device’s default browser. Go to step 3.

    • Custom Key: If the pass was sent via custom key , tapping the notification opens your app, where the user is presented with the options to Add, Review, or Cancel.
      • Add installs the pass in the device's Wallet.
      • Review displays the pass. See step 3.
  3. After the pass is opened/displayed, the user may add the pass to the device's wallet.

Setup

Follow the steps in the workflow tutorials. Pass URL entry options vary by message and workflow type.

Workflow Tutorials

Select the Web Page or Adaptive Link action in the Content step of each workflow:

Select the Web Page or Adaptive Link action in the Actions step of the workflow:

Note

These message types do not require user interaction, so you must instead provide the pass URL in the message body:

Alternative Method: Custom Key

Note

The Custom Key Method is for Apple Wallet passes only.

User experience: When the user taps the push notification, your app will open, followed by a prompt to save the Apple Wallet pass.

First add the Urban Airship In App Wallet Action to your app so it can handle a Wallet custom key. This allows users to save passes directly in the app without being redirected to Safari. Then register the action in the app registry.

Once your app is capable of handling a Wallet custom key, substitute the following Content and Delivery steps in each workflow:

  1. Choose Push Notification, then click the Continue button to confirm your choice.
  2. Enter the text that will display in your message.
  3. Select Home from the Message Action dropdown menu.

  4. Click Delivery in the header to move on.

  5. Select Send Now, Schedule, or Optimize.

  6. Toggle Custom Keys, select iOS from the platform dropdown menu, then enter the key and value:

    key = wallet_action or ^w
    value = the public pass URL, or the Adaptive Link URL

    Note

    For push templates, Custom Keys is in the Content step, not Delivery.

  7. Click Review in the header to move on.

API Examples

The examples below use this sample pass URL:

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

URL

See Actions in the API reference.

{
   "audience":{
      "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
   },
   "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"
         }
      }
   }
}

Custom Key

Use the extra key in the iOS Override Object to specify the pass URL.

{
    "audience":{
        "ios_channel": "b8f9b663-0a3b-cf45-587a-be880946e881"
    },
    "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"
            }
        }
    }
 }

Location

Display Passes on Lock Screen

There are two ways to make your pass show up on a user’s lock screen: Relevant Location and Relevant Date. The user must have already installed the pass to their digital wallet.

User Experience

Relevant Location displays a shortcut to your pass on the user’s screen when the device is in the vicinity of certain location.

The radius around the location where the shortcut appears is determined by Apple Wallet or Google Pay and varies by pass type. For instance, Boarding Passes will appear on the lock screen at around 1,000m, while Coupons will appear at around 100m.

Relevant Date displays a shortcut to your pass on a user’s lock screen at a certain date and time.

This is handy for certain types of passes, like Events and Boarding Passes. As with Relevant Location, the timing when the shortcut appears is determined by Apple Wallet or Google Pay and varies by pass type. Relevant Date is not supported on Coupons or Store Cards.

Note

See Pass Reference: Location Triggers for available triggers per pass type, requirements, and location radius and date window information, and Relevance Information Displays Passes on the Lock Screen, including Table 4-2, in Apple Wallet Developer Guide: Pass Design and Creation.