Instant Passbook App Development for iOS How-to

With iOS, Apple introduced the Passbook app as a central digital wallet for all the store cards, coupons, boarding passes, and event tickets that have become a popular feature of apps.

A company wishing to take advantage of this digital wallet and the extra functionality it provides, can use Apple's developer platform to create a Pass for their users.

The following diagram describes how Passes are delivered to a Passbook, and how these can be updated:

The process of creating a Pass involves cryptographically signing the Pass using a certificate and key generated from your iOS developer account. For this reason, the generation of the Pass needs to take place on a server, and then be delivered to Passbook either via your own app, as an e-mail attachment, or by embedding it in a website.

It's important to note that Apple does not provide any system for the Pass providers to authenticate, validate, or invalidate Passes. The Pass can contain barcode information, but it is up to the Pass provider to provide the infrastructure for reading and processing these barcodes.

Instead of just sitting in the Passbook app, waiting to be used, a Pass can contain location and time triggers, that proactively present the Pass to the user, serving as both a reminder and providing convenient access. For example, an event Pass could be set to appear 15 minutes before the start time, at the time when a user is likely to want to present their event Pass to an attendant. Alternatively, a coupon Pass could be presented as a user approaches their local store where the coupon can be redeemed.

Passes that have been added to Passbook can also be updated dynamically. For example, if the Pass is for a store card, a change to the card balance may require an update to the Pass. In the case of, for example an airline ticket Pass, a departure gate change should trigger a Pass update.

When a Pass needs to be updated, your server sends a push notification to the Passbook app on the user's device. This push notification is not displayed to the user.

Upon receiving this Push Notification, the Passbook app then makes a request to your server for the updated Pass information. Your server would then respond to the relevant request, and provide the updated information in the expected format.

When the Passbook App on the user's device receives the updated information, it silently updates the Pass. The next time the user looks at the Pass contained in the Passbook app, the updated information is displayed.

Support for Passbook is also built into OSX Mountain Lion (10.8.2). Pass files with the pkpass file extension will open in a preview window:

Clicking on the Add to Passbook button will place the Pass in the Passbook associated with the iCloud account set up in OSX system preferences.

The OSX Mail app and Safari also support embedded Passes.

When building a Pass, you can specify a relevant time and up to 10 relevant locations that will trigger a message to be displayed on the lock screen. The message looks similar to a push notification, however a Pass notification is less intrusive. When it is relevant to display, it doesn't vibrate the iPhone and it doesn't wake up the screen. The notification only becomes visible when the phone wakes up from sleep:

The option to specify relevant times and locations, and how far from the location the notification is triggered, is determined by the Pass type, as we will see later.

To get started with creating your own Pass, you will need a paid iOS developer account. If you intend to present the Passes within an existing iOS app, you will need access to the iOS developer account that publishes this existing app. In addition, many of these steps require apps and utilities only available on OSX, Keychain Access for example, which is used in the certificate creation process. Therefore, these steps should be undertaken using a Mac, running OSX.

The certificate and key pair should now be visible in Keychain Access. These now need to be converted into a format that can be used to correctly sign the Passes you will create. Select the certificate in Keychain Access, and from the menu choose File | Export Items, and choose an export location. You will be asked to provide a password to protect the exported items, you may also be asked for the administrator password as you are performing a task that requires administrator privileges.

You will need to use a command-line tool called OpenSSL to use the exported file to generate the key and certificate files that will be needed. This command line tool can be run from a built-in OSXutility called Terminal. To open Terminal, go to your Applications folder in Finder. Terminal is located in the Utilities folder.

Apple's security model ensures that only registered iOS developers can create Passes and that Passes cannot be altered by a third party while being delivered to a user's device, without being detected, and rejected by Passbook.

The certificate creation process produces a Pass Type certificate that is tied to the Pass Type ID that it was created from, which in turn ties it to your developer account. This provides a method for verifying the contents of a Pass signed using this certificate, and therefore, a way of detecting any manipulation of the Pass by anyone other than the registered Pass creator.

You can get the full JSON code, which we will use, from the following link:

http://passkit.pro/example-generic-json

This will create a Pass that looks like the following two images.

The following screenshot shows the front of the Pass:

The back of the Pass is shown in the following screenshot:

The pass.json file we've just created contains the following top-level key/value pairs:

The following two top-level key/value pairs determine under what circumstances the Pass is presented to the user on their lock screen.

The behavior of the two relevancy keys described above varies depending on the Pass type. The Pass type determines that for locations and relevantDate, which are required and which are options, it also determines the triggering criteria used in presenting a Pass on the user's lock screen.

An explanation of the differing behavior can be found in Apple's Passbook Programming Guide (Apple Developer account signin required) at:

https://developer.apple.com/library/ios/#documentation/UserExperience/Conceptual/PassKit_PG/Chapters/Creating.html#//apple_ref/doc/uid/TP40012195-CH4-SW53

Your choice of Pass type effects many things about the Pass, including overall style, text layout, available graphical asset options, and lock screen behavior. Apple has optimized the Pass types for their individual use cases, so try to pick a Pass type that most closely represents your Pass's use case. If none of the specific Pass types are appropriate, then the generic Pass type can be used.

The Passbook Programming Guide describes the different layout configurations for each Pass type:

https://developer.apple.com/library/ios/#documentation/UserExperience/Conceptual/PassKit_PG/Chapters/Creating.html#//apple_ref/doc/uid/TP40012195-CH4-SW1

Within the Pass type top-level key is a dictionary, containing arrays of various display groups, including headerFields, primaryFields, secondaryFields, and backFields, which are displayed according to Pass type. Each group contains an array of dictionaries, specifying key, label, and value. The label and value fields are displayed on the Pass, while the key field should be unique within your Pass format, and will be used when updating a Pass.

Graphical assets can be provided to further visually customize your Pass. The icon.png asset is required, but the following assets can optionally be included in the Pass package:

All assets should include a retina version that is twice as wide and twice as high, with @2x at the end of the filename. Therefore, for the icon, you provide the following files:

The following table provides the available size of each asset, and the space available for each Pass type. The sizes are provided as pixels width x pixels height:

* 90px x 90px is the space available, but the graphic must be either 60px x 90px, or 90px x 60px

** Allowed size for the strip asset is 312 x 84 for Event tickets, 312 x 110 when a square barcode is used and 312 x 123 otherwise.

The graphical assets for your Pass and the pass.json file should be in their own folder, with the .pem files created earlier, in a higher level folder.

Here is an example of the folder structure:

Congratulations! You now have a customized and signed Pass.

The goal of the signing process is to prevent the Pass from being modified by a third party between leaving your servers and being received by the user. When the manifest.json file is created, each file in the Pass package has its hash value calculated and stored. If the contents of any of the files were to change, its hash value would also change, therefore this manifest.json file represents an easy way of checking that the Pass package files have not been modified.

However, this on it's own is not enough, as a third party could modify the manifest.json file when they modify other files in the package. To guard against this, public/private key encryption is used to produce a signature file from the manifest.json. Your private key, to which only you have access, was used to generate the file, but anyone with access to the public key can use it to verify that the manifest file hasn't been tampered with.

Using this process, the user's device can be sure that the source of the Pass it receives is genuine and hasn't been altered in transit.

Because of this verification, it is important that only files specified in the manifest.json file are included in the zipped file. Individually selecting the files in Finder, and then choosing compress from the menu, is a good way to ensure this. Be careful if you choose to zip the entire contents of a folder, possibly through a Terminal command, as this can include additional hidden files like .DS_Store.

Changing the file extension tells the system that it should be treated as a Pass instead of a regular ZIP file.

It's important to understand the process and steps involved in signing a Pass, however it is unlikely that it will be feasible to manually perform these steps for every Pass that you create. Instead they should form part of an automated system for producing your user's Passes.

Pre-built Pass creation implementations are starting to emerge, including this PHPserver code:

https://github.com/tschoffelen/PHP-Passkit

The Pass e-mail creation script, used below, can be downloaded from the following location:

http://passkit.pro/ruby-email-script

The script used above is written in Ruby, as the Ruby interpreter is installed by default on OSX.

Sending a Pass as an attachment that will be understood by iOS and OSX, and presented to the user, requires it to have a specific MIME Type specified in the attachment. This MIME type is the following:

application/vnd.apple.pkpass

This script, or something similar could be used to automate the delivery of Passes to a large number of users, through email.

You will need access to your own web server, or shared hosting space with FTP access. The following instructions are for an Apache web server. Mac OSX does come with an Apache web server built in, which can be used. This used to be available under the Sharing menu in System Preferences, however since OSX 10.8 it can only be activated by the command line. You can run the following command from the Terminal, to start the web server:

sudoapachectl start

The root for this server can be found at /Library/WebServer/Documents/.

The files we will create can be downloaded from the following location:

http://passkit.pro/apache-mime-type

For the Safari or Mobile Safari browser to understand a Pass file and display it to the user, your Web server needs to present the files with the MIME type of application/vnd.apple.pkpass.

The .htaccess file tells the web server how to treat files in the folder in which resides. In this case it is instructing the web server to inform any visiting web browser that files with the file extension pkpass are to be treated as Passes. The .htaccess must be placed in each folder that contains a Pass.

Only users of a browser that supports this MIME type will be present with the Pass dialog, the rest will be prompted to download the Pass. While Safari and Mobile Safari support Passes, other third party browsers may not. However, the current versions of Chrome on iOS and the in-app browser from the Facebook app do support Pass display.

If you wish to add server-wide support of the Pass MIME type, you can add an entry to your Apache web server's mimes.type file, this is located in the conf directory. Open up the file in a text editor and add the following line in the correct alphabetical position:

application/vnd.apple.pkpass pkpass

You will need to restart the server for this to take effect.

To follow these steps, it is assumed that you have some experience of Objective-C and creating iOS apps.

The example project, created as follows, can be downloaded from the following location:

http://passkit.pro/example-app

This app does not use Automatic Reference Counting (ARC), if you are using the code in an ARC environment, remove any calls to releasing objects.

The example app uses the PassKit framework to present a framework supplied view controller to the user, listen for a delegate callback when the user finishes interacting with the view controller and changes the button's title if the Pass was successfully added to Passbook.

Using the following code, the PKPass object is created from a NSData object:

NSString *passFilePath = [[NSBundle mainBundle] pathForResource:@"Pass-Example-Generic" ofType:@"pkpass"];
NSData *passData = [[NSDataalloc] initWithContentsOfFile:passFilePath];
NSError *passError;
_genericPass = [[PKPassalloc] initWithData:passData error:&passError];
[passData release];

For the sake of simplicity, in this example, the Pass is loaded from a file bundled with the app. It is much more likely in a real-world app that a Pass will be downloaded from a network resource.

PKPassLibrary provides access to the Passes contained in Passbook. It also provides a class method called isPassLibraryAvailable that will tell you if Passbook exists on that device, for example Passbook is not present on iPads. This method is used in the example app to decide whether to show the Pass view controller.

if (![PKPassLibrary isPassLibraryAvailable]) {
    NSLog(@"Passbook not available on this device");
    return;       
}

Further documentation of the PassKit framework can be found in the following location:

https://developer.apple.com/library/ios/#documentation/UserExperience/Reference/PassKit_Framework/

The first stage in updating a Pass is to send a Push Notification to the user's device to prompt the Pass update process. The process for sending Apple Push Notifications (APNs) is outside the scope for this book, and the assumption will made that the facility to send the appropriate APN is available. Further information on APNs can be found in Apple's documentation:

https://developer.apple.com/library/ios/#documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Introduction/Introduction.html

In implementing the required REST API, we will be making use of the GIT source control management tool. If you don't already have GIT installed and setup, follow the GitHub tutorial:

https://help.github.com/articles/set-up-git

The server we have implemented above is to facilitate the Pass update process, which involves back and forth communication between the user's device and your server.

When a user adds a Pass to Passbook that contains webServiceURL and authenticationToken keys, the device registers with your server, passing a device library ID that is used to authenticate further communication, the authentication token to authenticate this initial communication, and a push token to be used when sending an APN.

When information contained in the Pass changes, in our example this may be Peter Brooke being promoted, your server sends an APN to the device, using the push token it received. (The sending of this push notification is outside the scope of this book.) This prompts the device to ask your server for a list of all the updated Passes since it last asked. From this list, the device asks for updated information for each of the Passes in turn. Finally, the server responds with the updated Pass information and the updated Pass is presented to the user.

Further information on the Pass update process can be found in the Apple documentation:

https://developer.apple.com/library/ios/#documentation/UserExperience/Conceptual/PassKit_PG/Chapters/Updating.html

There is also a full specification for the REST API that the server above implements:

https://developer.apple.com/library/ios/#documentation/PassKit/Reference/PassKit_WebService/WebService.html

When testing the web service endpoints in a browser, it is necessary to include the following request header in addition to any authorization header described in the specification:

Accept: application/json

In a live production setting, the web service must use HTTPS, however you can allow Passbook on your device to use HTTP for development testing. If your device has been enabled for development using Xcode, you will have an additional Developer section under the app settings. In the Developer section, under PassKit Testing, switch on Allow HTTP Services: