A pass is a digital card — a coupon, boarding pass, event ticket, etc. — that a user installs on their iOS or Android device.
You might think of passes as another message type that you can send to your audience, with a few key differences:
Passes are not purely for communication/notification. They can contain a barcode to scan and other information a user can refer to and consume.
Passes are installed, not just received. Passes are distributed as a URL. A user opens the URL to install the pass, then uses the pass locally via Apple Wallet or Google Pay.
Passes persist and can be updated, like when a gate on a boarding pass changes or a loyalty program's point value changes.
Passes are designed for Apple Wallet and/or Google Pay; they are not interpreted by the Urban Airship SDK.
A pass replaces a physical thing — a card that a user might have kept in their wallet or a physical piece of paper. It can contain a scannable barcode and can be updated remotely to ensure that the pass information is always up-to-date.
- An event pass tells a user where they sit at an event and can be scanned to grant entry.
- A gift card has some store credit a user can consume via barcode.
- A loyalty pass has a barcode a user can scan to rack up points.
When creating passes, it is important to choose a pass type that will make sense to the user. For instance, a user would not expect the boarding pass to be used as an event ticket.
See the Use Cases column in the Pass Types table below.
There are seven different pass types to choose from, each with default layouts, image types, and fields that support their specific use. You can even trigger some passes to appear based on the user's location. See Pass Reference: Location Triggers and the Triggers Tutorial.
|Pass Type||Use Cases||Apple Wallet||Google Pay|
|Loyalty||Loyalty programs, tiered status programs||✓||✓|
|Coupon||Discounts, special offers, ongoing engagement||✓||✓|
|Gift card||Gift cards, prepaid cards, return credits||✓||✓|
|Member card||Membership cards, photo IDs, monthly passes, claim tickets||✓|
|Event ticket||Event & admission tracking, season tickets, invitations, movie tickets||✓|
|Boarding pass||Airline boarding passes; ferry, bus, and train tickets||✓|
Pass appearance is dependent on the template design, but all passes have the same primary elements:
- Background color
- Data fields
- Barcode (optional)
For Apple Wallet passes, you may also set:
- Text color
- Icon image: This is displayed on the lock screen along with any notifications. It is also displayed when a pass is provided by an app, e.g., a mail attachment.
- Data fields on the back of the pass
See Pass Reference: Layouts for more information.
These are iOS examples of a boarding pass, coupon, and loyalty.
How Passes Work
- Create a container for the pass type you want to create. This is the project.
- Design the pass. This is the template.
- Generate a URL that points to the pass. This is the pass URL.
- Distribute the pass URL to recipients.
- Open the pass URL, then install the pass.
- Install the pass to their Apple Wallet or Google Pay digital wallets.
Create and Design
The first step of creating a pass is creating a project that will store the templates for that pass type. Projects can contain both Apple Wallet and Google Pay templates for a single pass type.
You must then design a template for your pass. The template holds the design, field information, and default field values for your pass. If designing passes to support both Apple Wallet and Google Pay users, you will design two templates, one for each platform.
You will then create a link to the pass that users can tap or click to install the pass. Android pass URLs can also be provided in a Save to Google Pay button. This pass URL can either be platform-specific — for either iOS or Android users — or you can create an Adaptive Link.
Adaptive links are the preferred pass-creation method. An Adaptive Link detects the recipient's platform and installs the appropriate pass. Instead of sending an Apple Wallet pass URL to one recipient group and a Google Pay pass URL to another (or both URLs to all recipients), you can associate the two templates using an Adaptive Link, then distribute that single Adaptive Link to all intended recipients.
While you can use Reach to create passes, you cannot distribute passes via Reach. Since the pass is essentially a URL, you can send the pass however you would send any URL, such email or SMS. See: Pass Distribution Methods.
It's important to remember that you are sending a link to install a pass, not attachment to a message body. You should send a pass over a medium that you expect to reach your audience and persist, in case a user decides to dismiss a notification alert and install the pass at a later time.
- When the user taps or clicks the notification.
- When the user taps a button.
- From the body of the message.
A user receives the pass URL, opens the URL, and then has the option to install the pass. The user only needs to install the pass once. They can then open the pass from Apple Wallet, Google Pay, or an app that relies on the respective Apple and Google APIs.
After a user installs a pass, you can seamlessly update the pass as event information, gift card balance, loyalty points, and other information changes, so that your users are always up to date.
By updating an already-installed pass, you can ensure that your customers never miss their gates, and that they take advantage of the loyalty programs that bring them back to your business.
You can optionally continue to update content and appearance of a pass that has already been installed by a recipient. See: Publish Tutorial.
Configuration and Requirements
To get passes into the hands (devices!) of your users, you need:
- An account on go.urbanairship.com.
- A certificate for Apple Wallet or Google Pay.
- A project to contain your certificate, templates, pass URLs, and other settings and information.
- A template to generate your passes from.
The Reach Getting Started Guide walks you through the whole process, with links to individual tutorials for each step.