Mobile Wallet

Mobile wallet is a channel for Apple Wallet and Google Pay passes — coupons, boarding passes, event tickets, etc. — that a user installs on their iOS or Android device.

You can 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 Airship SDK.

Benefits of Mobile Wallet Passes

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.

Pass Types

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 Mobile Wallet Reference: Location Triggers and the Triggers Tutorial.

Pass TypeUse CasesApple WalletGoogle Pay
LoyaltyLoyalty programs, tiered status programs
CouponDiscounts, special offers, ongoing engagement
Gift cardGift cards, prepaid cards, return credits
Member cardMembership cards, photo IDs, monthly passes, claim tickets
Event ticketEvent & admission tracking, season tickets, invitations, movie tickets
Boarding passAirline boarding passes1
GenericEverything else

1. Also supports ferry, bus, and train tickets.

Specialized Pass Types

In the same way that you use physical loyalty cards and boarding passes differently, different pass types have different characteristics: A loyalty card has a value of points that a user accumulates and spends; a boarding pass is associated with flight information.

Boarding Passes and event tickets function differently from other pass types. Where most passes are a template populated with some amount of information, boarding passes and event tickets are also associated with flight and event objects respectively. An Adaptive Link A pass link that supports templates for both Google Pay and Apple Wallet. When a user taps the link, Airship determines the user's platform and generates the right pass for the user. for these pass types cannot contain URL-encoded parameters to personalize the pass; the payload for the adaptive link must contain all the information for the pass.

Boarding Passes are associated with flights. You cannot create flight information through the dashboard; you must create flights and associate flights with adaptive links (generated from boarding pass templates) through the API.

Event Tickets are associated with events. You cannot create event information through the dashboard; you must create events and associate events with adaptive links (generated from event ticket templates) through the API.

Anatomy of a Pass

A pass is the product of a link generated from a template contained within a mobile wallet project:

  • A mobile wallet project determines the type of pass you can generate and the barcode the pass will use. Your project also contains your Apple Wallet and Google Pay certificates.
  • Templates within the project determine the design of the pass and the fields exposed on the pass.
  • A pass link or an Adaptive Link A pass link that supports templates for both Google Pay and Apple Wallet. When a user taps the link, Airship determines the user's platform and generates the right pass for the user. is the URL the user clicks on to view and install the pass.
  • The pass itself is installed on a user's mobile device. You can update the individual pass even after it has been installed.

In general, the process of getting a pass to your audience is as follows.

You:

  1. Create your project
  2. Design the pass. This is the template.
  3. Generate a URL that points to the pass. This is the pass link.
  4. Distribute the pass link to recipients.

The recipients:

  1. Open the pass link and view the pass.
  2. Install the pass to their Apple Wallet or Google Pay digital wallets.

Project Type and Certificates

When you set up your mobile wallet project, you determine the type of passes you want to create. You cannot change the pass type you want to create later. If you want to generate different kinds of passes — for example, if you have both a Loyalty program and want to send Offers or Coupons, you would need two projects: one for the loyalty card and one for offers/coupons.

Your project also contains your Apple Wallet and Google Pay certificates. Before you can send passes to users, you must upload certificates. You can generate your own Apple Wallet certificate as a developer, and Airship will help you with your Google Pay certificate.

Your project contains your templates and any pass links or adaptive links you generate.

Pass Templates

A template contains the design and fields that you want to populate when you create a pass; you create your passes from templates. A template belongs to a project and is specific to a vendor — Apple or Google.

Your template also contains the barcode type. You can populate different values for the barcode when you generate passes, but the barcode type is determined at the template level.

Fields on your template can have static information, or you can populate them with values when you create the pass. If you want to populate pass fields with personalized information, you must create your passes through the API. You can either generate personalized passes using fields in the pass payload, or by creating a pass with URL-encoded parameters.

When you generate a pass, adaptive link, or dynamic link, the result is a URL. A user can tap or click the URL on their Apple or Android device to view and install the pass.

The pass payload represents what users see on their passes. You can modify passes through the Wallet API; any users who have installed those passes will see the update reflected on their installed passes.

An adaptive link is a vendor-agnostic pass link associated with both Apple and Google templates. When a user taps the link, Airship determines the user's platform (Apple Wallet or Google Pay), generates the appropriate pass for that platform, and installs the pass.

It is recommended that you use adaptive links rather than generating individual pass links whenever possible. Adaptive links provide the following benefits over standard passes:

  • Single, Shortened URL: provide a short URL supporting both Apple Wallet and Google Pay from the same link.
  • URL-encoded pass personalization: leverage CRM data to populate a pass with personalized data without an API call. Just add query parameters to the adaptive link.
  • Boarding Pass and Event Ticket Support: Generate boarding passes and event tickets for your customers.
  • Location detection: Upload locations to your project. Passes your users install from adaptive links will detect the 10 nearest locations and associate them with iOS passes. (Apple Wallet limits passes to 10 locations each.)
 Tip

You can generate an Adaptive Link for a single platform through the API by setting the ID for the opposing template to null. If a user on the unsupported platform attempts to install your pass, you can set the link to drive the user to a landing page of your choosing.

Pass Personalization

When creating a pass from an adaptive link, you can provide a payload with customized values for the pass.

Unlike a standard pass link, adaptive links don't create a pass until a user taps or clicks an adaptive link. For most pass types, you can provide personalized values as URL-encoded query parameters in the adaptive link. These values are incorporated into the pass when a user taps an adaptive link.

For boarding passes and event tickets, you cannot personalize a pass with with URL-encoded parameters. You must provide all values that will appear on the pass in the adaptive link payload object.

Example:

If you wanted to add an offer code, barcode, member ID, and time/location, you could append query parameters to an adaptive link as follows:

https://wallet-api.urbanairship.com/v1/pass/adaptive/QXynXTbMhS?offercode=AUGUST&barcode=A1234567&tags=PST~OR&exid=A1234567

 Note

You cannot personalize Google Pay class fields with unique values. Any field preceded by class constitutes a class field. See Google Pay Pass Verticals documentation for a full list of class fields for each pass type.

Pass Updates

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 help 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.

Pass Distribution Methods

You can distribute pass URLs over any channel you use to communicate with your audience. See the various pass distribution methods.

It's important to remember that you are sending a link to install a pass, not an attachment to a message body. You should send a pass URL 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.

If you are also an Airship messaging customer, you can include the pass URL on any engagement channel. Depending on the message type you choose, you can link to the pass:

  • When the user taps or clicks the notification.
  • When the user taps a button.
  • From the body of the message.