Mobile Wallet Reference

Supported Platforms

<sup>1. Loyalty, gift card, and member card passes for Apple Wallet are based on Apple’s Store Card pass style.
2. Coupon passes for Google Wallet are based on Google’s Offer pass style.
3. Also supports ferry, bus, and train tickets.</sup>

Supported Countries and Regions

Feature support by country and region is determined by Apple and Google. All Airship supported wallet pass types, while not necessarily tied to payment transactions, are bound to the same regional restrictions that apply to the Apple and Google payment (“Pay”) platforms. See:

• Countries and regions that support Apple Pay 
• Countries or regions where you can use Google Wallet 

Location Triggers

Location triggers for Apple Wallet passes:

<sup>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.</sup>

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.

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.

See also 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.

• Apple Wallet Developer Guide: Pass Design and Creation 
• Google Wallet API for Passes: Generic 
• Google Wallet API for Passes: Gift cards 
• Google Wallet API for Passes: Loyalty 
• Google Wallet API for Passes: Offer/Coupon 
• Google Wallet API for Passes: Boarding passes 
• Google Wallet API for Passes: Event tickets 

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.

• Google Wallet Loyalty passes will display the content of the MemberID/AccountID fields  where the barcode should be if a barcode is missing. To avoid this you can leave the fields blank and check the Hide this field if the label and value are blank option in the template.

• Google Wallet Generic passes have two required fields, header and cardTitle, and an optional subheader field.

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

<sup>1. Icon images are available on iOS only.
2. Hero images are available on Android only.</sup>

Image Sizes

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

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 type	Apple Wallet	Google Wallet
Loyalty
Coupon
Gift card
Member card
Event ticket (Layout 1)
Event ticket (Layout 2)
Boarding pass
Generic

Barcode Types

Type	Display	API associated strings	Apple Wallet	Google Wallet
PDF417		"PKBarcodeFormatPDF417"	✓	✓
Aztec		"PKBarcodeFormatAztec"	✓	✓
QR		"PKBarcodeFormatQR"	✓	✓
Code 128		"PKBarcodeFormatCode128"	✓	✓
UPC-A		"UPC_A"		✓
EAN-13		"EAN_13"		✓
Code 39		"CODE_39"		✓

Sharing Policy

By default, templates allow pass sharing across users and devices. You can change the sharing policy for templates from the Templates menu for a mobile wallet project.

Apple Wallet and Google Wallet support slightly different sharing settings.

^{1. Intended for use in limited circumstances. Contact Airship Support  for additional information.}

Security

The Mobile Wallet API supports a basic authorization. Basic Authorization uses your Airship App Key and App or Master Secret to generate a Base-64 authorization string. The authorization header contains the word Basic followed by a space and a Base64-encoded string generated from your project key and project secret. e.g., Basic YXBwX2tleTptYXN0ZXJfc2VjcmV0

Airship Mobile Wallet does not support ciphers that are considered weak. The full list of supported ciphers is as follows:

TLS_CHACHA20_POLY1305_SHA256
TLS_AES_256_GCM_SHA384
TLS_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

Only TLS 1.2 and TLS 1.3 are supported for Wallet API endpoint access.

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

• Android and iOS devices running unsupported operating systems
• Java 6 or lower
• Java 7 and 8 without Unlimited Strength cipher libraries enabled
• Windows XP, Windows 7, Server 2003, Server 2008, Server 2008 R2, and Internet Explorer 9 (or lower)

Apple vs Google URL Differences

From the user’s perspective, the pass installation experience is similar on either iOS or Android — the pass is ultimately downloaded directly to either the Apple Wallet or Google Wallet 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 Wallet: Pass URLs generated from Google Wallet templates provide a deep link from Google into the Google Wallet 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 can 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.

Adaptive Link Expiration

By default, adaptive links automatically expire after a period that begins upon creation and ends after a duration determined by the associated pass type:

• Boarding pass: 30 days
• Event ticket: 30 days
• Coupon: 365 days
• Generic: 730 days
• Gift card: 730 days
• Loyalty: 730 days
• Member card: 730 days

See also: About Adaptive Links: Adaptive Link Expiration.

Troubleshooting Apple Wallet Passes

In rare instances, some passes created in Airship Wallet projects 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 Airship Wallet.

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 to your Airship Wallet project.

Pass Design Elements

Pass appearance is dependent on the template design, but all passes have the same primary elements:

• Background color
• Images
• Data fields
• Barcode (optional)

For Apple Wallet passes, you can 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 Layouts for more information. These are iOS examples of a boarding pass, a coupon, and a loyalty card.