# Mobile Wallet Reference

Design and usage reference for Airship Mobile Wallet passes.

## Supported Platforms

| Pass type | Apple Wallet | Google Wallet |
|  --- | :---: |  :---: |
| Member card<sup>1</sup> | &#10003; |  |
| Gift card<sup>1</sup> | &#10003; | &#10003; |
| Loyalty<sup>1</sup> | &#10003; | &#10003; |
| Coupon<sup>2</sup> |  &#10003; | &#10003;  |
| Event ticket | &#10003; | &#10003; |
| Boarding pass<sup>3</sup> | &#10003; | &#10003; |
| Generic | &#10003; | &#10003; |

<sup>1. Member card, Gift card, and Loyalty passes for Apple Wallet are based on Apple's Store Card pass style.</sup><br>
<sup>2. Coupon passes for Google Wallet are based on Google's Offer pass style.</sup><br>
<sup>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](https://support.apple.com/en-us/HT207957)
* [Countries or regions where you can use Google Wallet](https://support.google.com/wallet/answer/12060037)

## Location and Date Triggers

**For use with:**

* **Dashboard:** [Adding a Relevant Location trigger](https://www.airship.com/docs/guides/wallet/user-guide/notifications/triggers/#add-a-relevant-location-trigger)
* **API:** [Setting locations array for an Adaptive Link](https://www.airship.com/docs/developer/rest-api/wallet/schemas/adaptive-links/#adaptivelinkrequest)

Location radius is the minimum required proximity to a defined location for Relevant Location text to appear. For date triggers, you can set a date window, which is the period before and after a defined date and time when Relevant Date text will appear.

Date triggers are supported for Apple Wallet only. The table below shows location support, location radius, and date support for each pass type:

| Pass type | Location support | Location radius | Date support |
| --- | --- | --- | --- |
| Member card | Apple | Small (100 m) |  |
| Gift card | Apple, Google | Small (100 m for both platforms) |  |
| Loyalty | Apple, Google | Small (100 m for both platforms) |  |
| Coupon | Apple, Google | Small (100 m for both platforms) |  |
| Event ticket<sup>1</sup> | Apple, Google | Large (Google: 250 m, Apple: 1,000 m) | &#10003; |
| Boarding pass<sup>2</sup> | Apple, Google | Large (Google: 250 m, Apple: 1,000 m) | &#10003; |
| Generic<sup>3</sup> | Apple, Google | Small (100 m for both platforms) | &#10003; |

<sup>1. For Apple Wallet Event tickets, Date can be used alone, but Location cannot be used without Date.</sup><br>
<sup>2. For Apple Wallet Boarding passes, you can specify a Date, a Location, or both.</sup><br>
<sup>3. For Apple Wallet Generic passes, Location can be used alone, but Date cannot be used without Location.</sup>

See also [Relevance Information Displays Passes on the Lock Screen](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html#//apple_ref/doc/uid/TP40012195-CH4-SW53), including Table 4-2, in the Apple Wallet Developer Guide, and [Nearby Notifications](https://developers.google.com/wallet/retail/loyalty-cards/use-cases/trigger-push-notifications#nearby-notifications) in the Google Wallet Developer Guide.

## 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](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html#//apple_ref/doc/uid/TP40012195-CH4-SW1)
* [Google Wallet API for Passes: Generic](https://developers.google.com/wallet/generic/resources/template)
* [Google Wallet API for Passes: Gift cards](https://developers.google.com/pay/passes/guides/pass-verticals/pass-template?vertical=gift-cards#pass-vertical)
* [Google Wallet API for Passes: Loyalty](https://developers.google.com/pay/passes/guides/pass-verticals/pass-template?vertical=loyalty#pass-vertical)
* [Google Wallet API for Passes: Offer/Coupon](https://developers.google.com/pay/passes/guides/pass-verticals/pass-template?vertical=offers#pass-vertical)
* [Google Wallet API for Passes: Boarding passes](https://developers.google.com/pay/passes/guides/pass-verticals/pass-template?vertical=boarding-passes#pass-vertical)
* [Google Wallet API for Passes: Event tickets](https://developers.google.com/pay/passes/guides/pass-verticals/pass-template?vertical=event-tickets#pass-vertical)

### 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](https://developers.google.com/pay/passes/guides/pass-verticals/pass-template?vertical=loyalty#default-template) 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](https://www.airship.com/docs/guides/wallet/user-guide/ui/template-editor/#advanced-options) 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.

| Pass Type | Fields |
|  --- |  --- |
| Loyalty | Icon<sup>1</sup>, Logo, Strip, Hero<sup>2</sup> |
| Coupon | Icon<sup>1</sup>, Logo, Strip, Hero<sup>2</sup> |
| Gift Card | Icon<sup>1</sup>, Logo, Strip, Hero<sup>2</sup> |
| Member Card | Icon<sup>1</sup>, Logo, Thumbnail |
| Event Ticket (Layout 1) | Icon<sup>1</sup>, Logo, Background, Thumbnail |
| Event Ticket (Layout 2) | Icon<sup>1</sup>, Logo, Strip |
| Boarding Pass | Icon<sup>1</sup>, Logo, Strip, Hero<sup>2</sup>, Footer |
| Generic | Icon<sup>1</sup>, Logo, Thumbnail, Hero<sup>2</sup> |

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

#### Image Sizes {#reference-image-sizes}

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

| Image type | Width | Height | Maximum file size |
|  --- |  --- |  --- |  --- |
| Hero | 1032 px | 336 px | 200 KB |
| Thumbnail | 180 px | 180 px | 100 KB |
| Background | 360 px | 400 px | 250 KB |
| Icon | 58 px | 58 px | 50 KB |
| Logo | 660 px | 660 px | 150 KB |
| Strip | 624 px | 246 px | 450 KB |
| Footer | 572 px | 30 px | 50 KB |

Always send and install a [test pass](https://www.airship.com/docs/guides/wallet/user-guide/design-template/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](https://www.airship.com/docs/guides/wallet/user-guide/ui/template-editor/#images) 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 | ![apl-loyalty](https://www.airship.com/docs/images/loyalty-layout_hu_c1e7d5aed08a6e41.webp) | ![goog-loyalty](https://www.airship.com/docs/images/ws-android-pay-loyalty_hu_76c12a97895e6a56.webp) |
| Coupon | ![apl-coupon](https://www.airship.com/docs/images/coupon-layout_hu_c082c4d09345d1d0.webp) | ![goog-coupon](https://www.airship.com/docs/images/ws-android-pay-coupon_hu_e786bc13b140037.webp) |
| Gift card | ![apl-gift-card](https://www.airship.com/docs/images/gift-layout_hu_f39a4238a9bf3821.webp) | ![goog-gift-card](https://www.airship.com/docs/images/ws-android-pay-giftcard_hu_757cf1e43e26b276.webp) |
| Member card | ![apl-member](https://www.airship.com/docs/images/member-layout_hu_b6f1c1a521c7efcc.webp) |  |
| Event ticket (Layout 1) | ![apl-event-1](https://www.airship.com/docs/images/event-layout1_hu_d787c7d007c30831.webp) | ![Mobile Wallet Reference](https://www.airship.com/docs/images/ws-android-pay-event-pass_hu_a08c012270b333ee.webp) |
| Event ticket (Layout 2) | ![apl-event-2](https://www.airship.com/docs/images/event-layout2_hu_d5d425bb46960997.webp) |  |
| Boarding pass | ![apl-boarding-pass](https://www.airship.com/docs/images/boarding-layout_hu_e07298e4857eeec4.webp) | ![google-boarding-pass](https://www.airship.com/docs/images/ws-android-pay-boarding-pass_hu_75f51e4cbd451217.webp) |
| Generic | ![apl-generic](https://www.airship.com/docs/images/generic-layout_hu_10704d258fe4bf5b.webp) | ![google-generic](https://www.airship.com/docs/images/generic-layout-google-wallet_hu_27d157d8c3e10981.webp) |

## Barcode Types {#ws-barcode-types}

| Type | Display | API associated strings | Apple Wallet | Google Wallet |
|  --- |  --- |  --- |  :---: | :---: |
| PDF417 | ![pdf417](https://www.airship.com/docs/images/ws-pdf417_hu_5fbf3b845fcbe7bf.webp) | `"PKBarcodeFormatPDF417"` | &#10003; | &#10003; |
| Aztec | ![aztec](https://www.airship.com/docs/images/ws-aztec_hu_50a7c3d2ac3bf75c.webp) | `"PKBarcodeFormatAztec"` | &#10003;| &#10003; |
| QR | ![qr](https://www.airship.com/docs/images/ws-qr_hu_56eb4161457a10de.webp) | `"PKBarcodeFormatQR"` | &#10003; | &#10003; |
| Code 128 | ![code128](https://www.airship.com/docs/images/ws-code128_hu_5d76f960d0799a6e.webp) | `"PKBarcodeFormatCode128"` | &#10003; | &#10003; |
| UPC-A | ![upca](https://www.airship.com/docs/images/ws-upca_hu_4729b918158757cf.webp) | `"UPC_A"` |  | &#10003; |
| EAN-13 | ![ean13](https://www.airship.com/docs/images/ws-ean13_hu_603231e951f7a39f.webp) | `"EAN_13"` |  | &#10003; |
| Code 39 | ![code39](https://www.airship.com/docs/images/ws-code39_hu_5c360666aebe6262.webp) | `"CODE_39"` |  | &#10003; |

## Sharing Policy {#sharing-policy}

<p>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.</p>
<p>Apple Wallet and Google Wallet support slightly different sharing settings.</p>
<table>
  <thead>
      <tr>
          <th>Sharing policy</th>
          <th style="text-align: center">Apple</th>
          <th style="text-align: center">Google</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td>Multiple users and devices <strong>(Default)</strong></td>
          <td style="text-align: center">✓</td>
          <td style="text-align: center">✓</td>
      </tr>
      <tr>
          <td>One user on multiple devices</td>
          <td style="text-align: center"></td>
          <td style="text-align: center">✓</td>
      </tr>
      <tr>
          <td>One user on one device</td>
          <td style="text-align: center">✓</td>
          <td style="text-align: center">✓<sup>1</sup></td>
      </tr>
  </tbody>
</table>
<p><sup>1. Intended for use in limited circumstances.
<a href="https://support.airship.com/" target="_blank">Contact Airship Support<span class="external-link-icon">&thinsp;<i class="ph ph-arrow-square-out"></i></span></a> for additional information.</sup></p>

## Apple vs Google URL Differences

<p>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:</p>
<ul>
<li>
<p><strong>Apple Wallet:</strong> Pass URLs generated from Apple Wallet templates <strong>point to
a stored .pkpass file</strong>. A .pkpass file can be considered similar to a PDF or
any other document that you might link to.</p>
</li>
<li>
<p><strong>Google Wallet:</strong> Pass URLs generated from Google Wallet templates <strong>provide a
deep link</strong> from Google into the Google Wallet app so that the pass can be
downloaded directly without requiring a browser window to facilitate the
request.</p>
</li>
</ul>
<p>For additional detail about the <code>publicUrl</code> object and pass deep linking, see:
<a href="https://www.airship.com/docs/developer/rest-api/wallet/schemas/passes/">API: Passes</a>.</p>

## Single- vs Multi-Use Public URL {#single-vs-multi-use-public-url}

<p>When generating a pass via the
<a href="https://www.airship.com/docs/developer/rest-api/wallet/operations/passes/#createpass">API</a>, you can
create a publicly accessible URL for the pass, hosted at
<code>https://wallet-api.urbanairship.com</code>. The Public URL can be either a <em>single</em>
or <em>multiple</em> (multi-use) pass type, referring to the number of times the pass
can be be downloaded.</p>
<ul>
<li>
<p>Use the <em>Single</em> 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.</p>
</li>
<li>
<p>Use the <em>Multiple</em> option if the pass is non-unique and can be downloaded
by multiple devices and shared many times.</p>
</li>
</ul>
> **Important:** A public URL is required for Android and optional for iOS.

> **Note:** The URLs returned by the [CSV Batch Importer](https://www.airship.com/docs/guides/wallet/user-guide/create-links/csv-batch-import/)
> are multi-use passes — they can be downloaded by multiple devices.

## Adaptive Link Expiration

<p>Adaptive Links automatically expire after a period that begins upon creation and ends after a duration determined by its associated pass type:</p>
<ul>
<li><strong>Boarding pass:</strong> 30 days</li>
<li><strong>Event ticket:</strong> 30 days</li>
<li><strong>Coupon:</strong> 365 days</li>
<li><strong>Generic:</strong> 730 days</li>
<li><strong>Gift card:</strong> 730 days</li>
<li><strong>Loyalty:</strong> 730 days</li>
<li><strong>Member card:</strong> 730 days</li>
</ul>

For additional details, including setting custom expiration dates, see [Expiration](https://www.airship.com/docs/guides/wallet/user-guide/create-links/adaptive-links/#expiration) in *About Adaptive Links*.

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

1. 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](#layouts) for more information. These are iOS examples of a boarding pass, a coupon, and a loyalty card.

![Examples of a boarding pass, coupon, and loyalty card on iOS](https://www.airship.com/docs/images/pass-examples_hu_6ad3d996b2e8b99e.webp)

*Examples of a boarding pass, coupon, and loyalty card on iOS*