iOS Components and Frameworks: Understanding the Advanced Features of the iOS SDK (2014)

Chapter 24. Passbook and PassKit

With iOS 6 Apple introduced a new standard app called Passbook, which is a place to keep and have easy access to a user’s event tickets, traveling tickets, coupons, and store cards (like gift cards, prepaid cards, or rewards cards). Passbook is currently available only on iPhone and iPod touch devices, not on iPad devices.

Passbook has special access to the lock screen. If a user is within a geofence, defined by a location or set of locations listed in the pass, on a relevant date specified in a pass, the pass will be displayed on the lock screen so that the user can slide and open it directly in the Passbook app.

The Passbook app displays passes like a stack so that the user can see the top part of each pass. The top section contains a logo and colored background, and can contain some custom information. When a user taps on the top part of a pass, the pass will expand to display the entire pass, which can contain several areas of custom fields, a background graphic, and a barcode. The user can delete a pass when it is no longer needed, and Passbook will delete it with a shredder animation. The Passbook app has support built in to leverage a Web service and push notifications to handle seamless updates to a pass already in Passbook.

Using Passbook requires building a “pass” in a prescribed format and delivering the pass to a user. The pass needs to be built somewhere other than the user’s device, typically on a server, since it is a signed archive of files including icons and logos for display, a file with information about the pass, a signature file, and a manifest.

There are a few options available to deliver the pass to the user. Mail.app and Safari.app can recognize a pass and import it into Passbook, or a custom app can utilize PassKit to add a new pass or update an existing pass. For testing passes, the iOS Simulator can display a pass when it is dropped onto it.

PassKit is part of the iOS SDK that can be used by custom apps to import or update a pass in Passbook, check whether a pass is new or updated, and display some information about existing passes.

This chapter describes the design considerations relevant to different pass types, and how to build and test passes for Passbook. It demonstrates how to use PassKit to interact with passes from an app. Lastly, it describes how Passbook can handle updates from a Web service.

The Sample App

The sample app is called Pass Test. It includes pre-signed sample passes for each pass type (see Figure 24.1). The user can add a new pass to Passbook in the app using PassKit, can simulate updating an existing pass with new information, can view the pass directly in Passbook, and can remove the pass from Passbook all from the app. The sample app is covered in more detail in the section “Interacting with Passes in an App.”

Figure 24.1 Pass Test sample app.

Designing the Pass

Before a pass can be sent to any users, the pass needs to be designed and configured. The pass provider needs to determine what type of pass should be used and how the pass should look. This includes figuring out what fields of information should be presented on the pass, where the fields should be placed, whether a barcode should be used, and what information will be provided to determine whether the pass should be displayed on the lock screen. An individual pass is actually a signed bundle of files, including some images, a JSON file called pass.json with information about the pass and display information, and a signature and manifest.

Pass Types

Apple has provided several standard pass types, each of which can be customized:

Boarding Pass: A boarding pass is intended to cover travel situations, such as an airline boarding pass, train ticket, bus pass, shuttle voucher, or any other ticket required to board a conveyance with a defined departure location and destination.

Coupon: A coupon is a pass that handles a discount for a vendor. The coupon is designed to be flexible enough to handle a wide variety of permutations, such as percentage or dollar-off discounts, or discounts specific to a product or group of products, or no product at all, at a specific location, group of locations, or any location for a vendor.

Event: An event pass is a ticket for entry to any event, such as a theater production, movie, sporting event, or special museum event—anything with limited access granted by a ticket.

Store Card: A store card pass is similar to a gift card, in that the user can buy a preset amount of money on the pass, display the pass to the vendor for payment, and have the payment amount decremented from the pass. The vendor might allow refilling the pass or might require the purchase of a new pass when the amount has been fully depleted. Store cards can also be used as reward or loyalty cards, in which points are collected with each purchase until a threshold is reached and a reward is given.

Generic: A generic pass can be used for anything that does not fit into the prebuilt pass types, or where the prebuilt pass types are not sufficient. Generic passes include a thumbnail image so that they can be used for an organization-specific ID card like a gym membership card.

Each pass type has a specialized layout to be considered when designing the pass. Passes are divided into sections where fields of data can be presented: header, primary, secondary, auxiliary, and back. Passes can also use custom images in some instances. The following sections describe the layouts for each pass type.

Pass Layout—Boarding Pass

A boarding pass has the layout shown in Figure 24.2.

Figure 24.2 Boarding pass layout.

For a boarding pass, the departure location and destination are typically specified as the primary fields (a boarding pass can have up to two primary fields). Secondary and auxiliary fields are laid out beneath the primary fields. The footer image is optional.

Pass Layout—Coupon

A coupon pass has the layout shown in Figure 24.3.

Figure 24.3 Coupon pass layout.

A coupon can have only one primary field, and can optionally display a strip image behind the primary field. A coupon can have up to four total secondary and auxiliary fields.

Pass Layout—Event

An event pass has the layout shown in Figure 24.4.

Figure 24.4 Event pass layout.

An event pass can have only one primary field, and can optionally display a background image behind all the fields and the barcode. If provided, the background image is automatically cropped and blurred. An event can also optionally display a thumbnail image to the right of the primary and secondary fields.

Pass Layout—Generic

A generic pass has the layout shown in Figure 24.5.

Figure 24.5 Generic pass layout.

A generic pass can have only one primary field, and can optionally display a thumbnail image to the right of the primary field. Secondary and auxiliary fields are presented below the primary field.

Pass Layout—Store Card

A store card pass has the layout shown in Figure 24.6.

Figure 24.6 Store card pass layout.

A store card can have only one primary field, and can optionally display a strip image behind the primary field. A store card can have up to four total secondary and auxiliary fields, presented below the primary field.

Pass Presentation

Passes are presented to users in several situations outside Passbook, and it is important to understand which parts of the pass can be customized to handle that presentation. When a pass is distributed to a user via email, it looks like the screenshot displayed in Figure 24.7.

Figure 24.7 Passes distributed in email.

The image presented is icon.png from the pass bundle. The top line of text in blue is derived automatically from the type of pass as specified in the pass.json file, and the bottom line of text is the organization name specified in the pass.json file.

When the device is near a relevant location specified in the pass, or the date is a relevant date specified in the pass, the pass is visible on the device’s lock screen much like a push notification, as shown in Figure 24.8. More information about this is available in the section “Building the Pass,” in the “Pass Relevance Information” subsection.

Figure 24.8 Pass displayed on the lock screen.

The image presented is icon.png in the pass bundle. The top line of text is the organization name specified in the pass.json file, and the bottom line of text is the relevantText specified in the pass.json file, with the relevant locations.

Building the Pass

A pass will typically be built by an automated server. This section and the next section of the chapter describe building a pass manually so that the steps necessary are clear; automating the process would depend on the choice of server environment and is left as an exercise for the reader.

Several steps are required to build a pass. Apple recommends creating a folder to hold all the files required for an individual pass, for example, a folder called Boarding Pass.raw.

Place all the required and desired images in the pass folder. Passes support retina and nonretina versions of images using standard “@2x” naming syntax. The images that need to be provided are these:

icon.png (required): A 29×29-pixel PNG image (and retina version), which will be displayed in any PassKit-capable app (like Mail.app or Safari.app) when the app has detected a pass and is displaying the pass as something that can be used. The image is also displayed for the pass on the lock screen. The icon is automatically given rounded edges and a shine effect like an app icon.

logo.png (required): A logo PNG image, with maximum dimensions of 160×50 pixels (and retina version), that will be placed on the header of the pass in Passbook. Apple recommends using only an image in the logo, and recommends avoiding any stylized text in the logo. When the logo is presented, it will be presented with the standardized header (with customizable text) that will look uniform in Passbook.app.

background.png (optional, available only for event passes): A PNG image with maximum dimensions of 180×220 pixels can be specified for the entire background of the front of the pass. This image is automatically cropped and blurred.

strip.png (optional, available only for coupon, event, and store card passes): A PNG image can be specified to go behind the primary fields on the pass. The strip image has shine applied by default, which can be turned off. Maximum dimensions are 312×84 pixels for Event passes, 312×110 pixels for Coupons and Store Card passes with a square barcode, and 312×123 pixels for Coupons and Store Cards with a rectangular barcode.

thumbnail.png (optional, available only on event and generic passes): A PNG image can be displayed on the front of the pass. Apple recommends this for a person’s image for a membership card, but it could also be used as a membership level indicator or graphical way of presenting pass data.

footer.png (optional, available only for boarding passes): A PNG image can be specified to go just above the barcode on the pass.

The majority of work building an individual pass is in creating the pass.json file. This file defines all the information for the pass, including unique identification of the pass, type of pass, relevance information, and layout and visual customizations for the pass in a JSON hash. Create a plain text file called pass.json in the pass folder, and prepare it with all the desired information for a pass.