Reference

Urban Airship Wallet is now Urban Airship Reach. Though the product name has changed, the features and functionality remain the same. All /wallet-api.urbanairship.com/ endpoints will continue to function as before. For more information about Urban Airship Reach, please see our news release.

Pass Types & Layouts

Urban Airship Reach provides a drag-and-drop interface to assist in the design of passes — format and preview the look of the pass as you build it. Building upon the five basic pass styles provided by Apple, we created seven different basic use case templates, as seen below. Of these seven, the Loyalty, Gift Card, and Coupon type passes are supported by Android Pay.

All Reach passes should be opened in Apple Wallet or Android Pay to verify their final appearance.

Pass Types

Location Radius is for Apple Wallet only. The proximity requirement for Android Pay is 150 meters for all pass types.

Type Use Cases Available Triggers Location Radius Date Window Apple Wallet Android Pay
Loyalty programs, tiered status programs Location Small (100m) N/A Yes Yes
Discounts, special offers, ongoing engagement Location Small (100m) N/A Yes Yes
Gift cards, prepaid cards, return credits Location Small (100m) N/A Yes Yes
Membership cards, photo IDs, monthly passes, claim tickets Date and Location* Small (100m) Supported Yes No
Event & admission tracking, season tickets, invitations, movie tickets Date and Location** Large (1,000m) Supported Yes No
Airline boarding passes; ferry, bus, and train tickets Date and Location*** Large (1,000m) Supported Yes No
Everything else Date and Location* Small (100m) Supported Yes No

* Location can be used alone, but Date cannot be used without Location.
** Date can be used alone, but Location cannot be used without Date.
*** You can specify a Date, a Location, or both.

Key

Type: The pass type.
Use Cases: Example use cases.
Available Triggers: Which Triggers will cause pass-related text to appear on the lock screen.
Location Radius: The minimum required proximity to a defined location Trigger for Relevant Location text to appear on the lock screen.
Date Window: The window of time before and after a defined date and time Trigger when Relevant Date text will appear on the lock screen.
Apple Wallet: Supported by Apple Wallet.
Android Pay: Supported by Android Pay.

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.

Pass Layouts

Fields

Pass type determines the number of fields that appear on the front of a pass.

  • Most passes can have up to three header fields, a single primary field, up to four secondary fields and up to four auxiliary fields.
  • Boarding passes use two primary fields to show origination and destination. They also can have up to five auxiliary fields.
  • Coupons and Member Cards combine secondary and auxiliary fields onto a single line, for up to four fields total.
  • Event Tickets with a background image, and Generic passes with a square bar code (QR code or Aztec) will not use auxiliary fields.
  • The number of fields on a pass also depends on the text in each field. If there is too much text in a field, some fields will not be displayed.

Images

Pass type also determines the types of images that will appear on the pass. Event Ticket passes have two different layouts, determined by the type of images and/or barcode types that are selected.

Pass Type Supported Images
Loyalty Icon, Logo, Strip
Coupon Icon, Logo, Strip
Gift Card Icon, Logo, Strip
Member Card Icon, Logo, Thumbnail
Event Ticket (Layout 1) Icon, Logo, Background, Thumbnail
Event Ticket (Layout 2) Icon, Logo, Strip
Boarding Pass Icon, Logo, Footer
Generic Icon, Logo, Thumbnail

Image Sizes

For Apple Wallet, each image type should adhere to the specifications below.

Image Type Width Height Maximum File Size
Thumbnail 180 180 100KB
Background 360 400 250KB
Icon 58 58 50KB
Logo 320 100 150KB
Strip 624 246 450KB
Footer 572 30 50KB

For Android Pay, specifications for each image type may change. The currently supported specs for Android Pay images can be found under the User Interface Guidelines for Android Pay.

Images that are too large are automatically resized, which may reduce quality or change the expected proportions of the image. Always send and install a test pass, and verify the pass’s appearance prior to distribution to end users.

Image file size limits are enforced when uploading via the UI.

Layout Schematics

The images below indicate where each field appears on the pass. In some cases, field placement is determined by the images selected.

Pass Types Apple Wallet Android Pay
Loyalty
Coupon
Gift Card
Member Card N/A
Event Ticket (Layout 1) N/A
Event Ticket (Layout 2) N/A
Boarding Pass N/A
Generic N/A

Pass Colors

You can use Reach to customize your passes’ text, label, and background colors. As you design the pass, the previewer instantly updates to reflect changes. Image blur effects and other appearance behaviors are also reflected in the pass preview.

Apple uses proprietary algorithms to determine the final text colors used when rendering a pass. While Reach will reflect Apple Wallet’s appearance behavior most of the time, it is sometimes not possible to predict minor visual differences. Likewise, Google will automatically determine the background color of an Android Pay pass based on your chosen logo image. For this reason it is highly recommended that you preview the pass in Apple Wallet or Android Pay when customizing colors and logo images.

See: Template Design Tutorial: Appearance and Pass Distribution Methods: Send Test Pass.

Barcode Types

Type Display API Associated Strings Supported Platforms
PDF417 "PKBarcodeFormatPDF417" Apple Wallet, Android Pay
Aztec "PKBarcodeFormatAztec" Apple Wallet, Android Pay
QR "PKBarcodeFormatQR" Apple Wallet, Android Pay
Code 128 "PKBarcodeFormatCode128" Apple Wallet, Android Pay
UPC-A "UPC_A" Android Pay
EAN-13 "EAN_13" Android Pay
Code 39 "CODE_39" Android Pay

Security

Urban Airship Reach does not support RC4 ciphers and some other discretionary ciphers that are considered weak. The full list of supported ciphers is as follows:

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

We strongly advise using TLSv1.2 if possible. SSLv3 and TLSv1.1 are not available at this time.

In an effort to make Reach as secure as possible, we’ve removed support for several legacy platforms:

  • Devices on Android Gingerbread or lower
  • Devices on iOS 5.0.1 or lower
  • Java 6 or lower
  • Java 7 and 8 without Unlimited Strength cipher libraries enabled
  • Windows XP, Server 2003, and Internet Explorer 9 (or lower)

Troubleshooting

Apple Wallet

Pass Doesn’t Load into Apple Wallet

In rare instances, some passes created in Urban Airship Reach will not load in Apple Wallet. Here are some probable causes:

  1. We’ve found inconsistent support of PNG image bit-depths by Apple Wallet and OS X PassViewer. 8-bit .png images are not currently supported by Apple Wallet. We recommend that you re-create your PNG at 24-bits (in Photoshop use Save for Web, and choose PNG-24), then re-upload your image in Urban Airship Reach.

  2. Corrupt graphics will sometimes cause an image to not appear on the pass. Regenerate your graphics using your favorite graphics editor (you can use Apple’s Preview.app if you prefer) as 24-bit PNGs and re-upload them in Urban Airship Reach.