Pass Reference

Design and usage reference for Urban Airship digital wallet passes.

Supported Platforms

Pass TypeApple WalletGoogle Pay
Loyalty1
Coupon2
Gift card1
Member card1
Event ticket
Boarding pass
Generic

1Loyalty, gift card, and member card passes for Apple Wallet are based on Apple's Store Card pass style.
2Coupon passes for Google Pay are based on Google's Offer pass style.

Location Triggers

Pass TypeAvailable TriggersLocation RadiusDate WindowApple WalletGoogle Pay
LoyaltyLocationSmall (100m)
CouponLocationSmall (100m)
Gift cardLocationSmall (100m)
Member cardDate and Location1Small (100m)
Event ticketDate and Location2Large (1,000m)
Boarding passDate and Location3Large (1,000m)
GenericDate and Location1Small (100m)

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

Available Triggers
The triggers that 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.

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

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.

For Apple Wallet passes, also see Relevance Information Displays Passes on the Lock Screen, including Table 4-2, in Apple Wallet Developer Guide: Pass Design and Creation.

Layouts

In addition to the layout information provided here, please also refer to Apple and Google developer documentation for the position of fields, images, and other design elements for each pass type.

Fields

  • 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 TypeFields
LoyaltyIcon1, Logo, Strip, Hero2
CouponIcon1, Logo, Strip, Hero2
Gift CardIcon1, Logo, Strip, Hero2
Member CardIcon1, Logo, Thumbnail
Event Ticket (Layout 1)Icon1, Logo, Background, Thumbnail
Event Ticket (Layout 2)Icon1, Logo, Strip
Boarding PassIcon1, Logo, Strip, Hero2, Footer
GenericIcon1, Logo, Thumbnail

1 Icon images are available on iOS only.
2 Hero images are available on Android only.

Image Sizes

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

Image TypeWidthHeightMaximum File Size
Thumbnail180180100KB
Background360400250KB
Icon585850KB
Logo320100150KB
Strip624246450KB
Footer5723050KB

For Google Pay, specifications for each image type may change. The currently supported specs for Google Pay images can be found in the Google API Brand guidelines.

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 dashboard or the API.

Schematics

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

Pass TypeApple WalletGoogle Pay
Loyalty
Coupon
Gift card
Member card
Event ticket (Layout 1)
Event ticket (Layout 2)
Boarding pass
Generic

Barcode Types

TypeDisplayAPI Associated StringsApple WalletGoogle Pay
PDF417"PKBarcodeFormatPDF417"
Aztec"PKBarcodeFormatAztec"
QR"PKBarcodeFormatQR"
Code 128"PKBarcodeFormatCode128"
UPC-A"UPC_A"
EAN-13"EAN_13"
Code 39"CODE_39"

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.