Building Your First Pass

Case Study: A Very Simple Coupon

Suppose you own a candy shop and you want to email your customers a coupon for a free lollipop. You trust most of your customers and you’re only running the promotion until the giant bucket of lollipops runs out, so you don’t take any special effort to prevent customers from using their coupon more than once. You create a pass with the same information that you would include on a printed coupon: a description of the offer and some information about your store.

In this tutorial, you will set up your environment for pass development, sign one of the sample passs, and then make some minor changes to that pass.

Creating and Populating the Pass Package

Passes are created as a package containing a pass.json file that defines the pass, and image assets such as the logo and the icon.

To create the pass package for your pass, do the following:

1. Make a new directory in the Documents folder called Lollipop.pass. The .pass extension is a best practice to indicate that the directory is a pass package.

2. Download this book’s companion file (the link is near the top of the page) and locate the coupon in the Sample Passes directory.

3. Open the raw pass package and copy the files it contains to your Lollipop.pass directory.

Setting the Pass Type Identifier and Team ID

Every pass has a pass type identifier which is associated to a developer account. Pass type identifiers are managed in the iOS Provisioning Portal by a team admin. To build this pass, you need to request and configure a pass type identifier. (You can’t use the pass type identifier that is already in the pass because it isn’t associated with your developer account.)

To request a pass type identifier, do the following:

1. In the iOS Provisioning Portal, go to the Pass Type IDs section.

2. Click the New Pass Type ID button.

3. Enter the description and pass type identifier, and click Submit.

To configure a pass type identifier, do the following:

1. In the Pass Type IDs section of the iOS Provisioning Portal, click the Configure link next to the pass type identifier.

2. Click the Configure button next to “Pass Certificate”.

3. Follow the directions that are shown to generate a certificate signing request in Keychain Access, upload it to the iOS Provisioning Portal, and then download the certificate.

   After you download the certificate, you can delete the certificate signing request.

4. Open the certificate with Keychain Access to add it to your keychain.

To find your team ID, do the following:

1. Open Keychain Access and select your certificate.

2. Select File > Get Info and find the Organizational Unit section under Details. This is your team ID.

   The pass type identifier appears in the certificate under the User ID section.

Edit the pass.json file and change the pass type identifier to the identifier you just set up, and change the team ID to match the values you just found.

Listing 1-1  Setting the pass type ID and team ID

{

    ...

    "passTypeIdentifier" : "your pass type identifier",

    "teamIdentifier" : "your team ID",

    ...

}

Signing and Compressing the Pass

As part of building your production environment, you will need to set up a system for automatically signing and compressing passes as described in “Passes Are Cryptographically Signed and Compressed.” For the purpose of this tutorial, a very simple tool for signing passes is included.

To get the signpass tool, do the following:

1. Download this book’s companion file (the link is near the top of the page) and locate the signpass project.

2. Open the project in Xcode and build it.

3. Right-click on the signpass executable (in the Products folder in Xcode) and select Show in Finder.

4. Move the signpass executable to the Documents folder.

To sign and compress the pass, use the signpass tool to sign the pass package. In Terminal, run the following commands:

cd ~/Documents

./signpass -p Lollipop.pass

This creates a signed and compressed pass named Lollipop.pkpass in the Documents folder. If the signpass command fails, make sure you are using your correct pass type identifier and check that the pass.json file contains valid JSON.

Changing the Offer

The sample pass is already a coupon, but it doesn’t have the right details for a candy store. First, change the description and organization name. Find the following keys in the pass.json file and change their values:

Listing 1-2  Setting the description and organization name

{

    ...

    "description" : "Coupon for a free lollipop at Example Candy Store",

    "logoText" : "Example Candy Store",

    ...

}

Next, the pass needs to describe the actual offer. This requires three levels of keys, as shown in Listing 1-3. At the top level, find the coupon key which indicates that this pass is a coupon. Its value is a dictionary that describes the coupon. At the second level, find the primaryFields key which shows text on the front of the pass for the offer. Its value is a dictionary that describes the contents of the field. At the third level, the key is a string that uniquely identifies the field within the pass, and the value and label contain text that appears on the pass. Change their values to describe the candy store’s offer.

Listing 1-3  Describing the offer

{

    ...

    "description" : "Coupon for a free lollipop at Example Candy Store",

    "logoText" : "Example Candy Store",

    "coupon" : {

        "primaryFields" : [

            {

                "key": "offer",

                "value": "Free lollipop"

                "label": "On July 29"

            }

        ]

    },

    ...

}

At the second level of the pass, find the auxiliaryFields and backFields keys. Delete these keys and their values.

Viewing the Pass

The simplest way to see what a pass looks like during development is in the iOS Simulator app. To view the pass, launch Simulator and drag the Lollipop.pkpass file into the Simulator window. It displays the pass and offers to add it to Passbook, as shown in Figure 1-1.

When testing in the iOS Simulator app, errors are logged to the system log, which you can view with the Console app. If the pass doesn’t display or fails to add to Passbook, check the log for a description of what went wrong.