Beginning Passbook in iOS 6: Part 1/2

Get me the certificate!

Head to the iOS Developer Portal (https://developer.apple.com/devcenter/ios/index.action), and after you log in, open up the iOS Provisioning Portal from the menu on the right-hand side.

If you’ve already been checking out the new stuff for iOS 6, you might have noticed the new item in the left menu called Pass Type IDs. Click on that link and on the next page, you’ll see a list of all the pass types you’ve already created (probably empty at this point).

Click the New Pass Type ID button and you’ll go to a page where you can create a new type. In the description field enter “Free Hug Pass” and in the Identifier field enter “pass.com.yourdomain.couponfreehug”. For the Pass Type ID, Apple recommends the reversed domain notation with a prefix of “pass.” So that’s the format you’re using.

Note: For the purposes of this chapter you can certainly use “com.yourdomain”, but in production applications remember that you should replace com.yourdomain with the actual reverse notation for your domain. ☺

Also note that if you decide to change the identifier here to something other than “pass.com.yourdomain.couponfreehug”, you’ll also have to update the passTypeIdentifier value in pass.json accordingly.

Next, simply click Submit to create your pass.

By the very way that light indicator is not lit up in green, you might already guess there’s something missing. Yes – you are right. You still need to generate the pass certificates. Click on Configure to do that. The next page that comes up is a good place to spot the full identifier of your pass.

Here you can see your teamIdentifier (it’s the first 10 characters beginning with ABC) and update pass.json with it – make sure to replace only the placeholder and leave the quotes around it!

All right! Your pass.json metadata is now updated. However, there’s still an extra step to get your certificate imported into your development environment.
Back in the iOS Provisioning Portal, click the Configure button:

This will launch the Pass Certificate Assistant (*fancy name!), which will guide you through the process of generating your certificate. Pay attention to the dialog and follow the steps.

After you upload your signing request, your certificate will be generated in a timely manner and you should see the success dialogue:

Click Continue one more time and then click Download to get the certificate file. After the file downloads, find and double click it to import it into the Keychain. Note that it’s most probably in the Downloads folder inside your user folder, unless you’ve set another default download location in your browser.
If Keychain asks you to confirm the import, click the Add button:

And then you should see your certificate in Keychain Access:

w00t – you’re done making your certificate! Now you have real metadata in your JSON file and the proper certificate for when the time comes to sign the pass.

Passes come in style this year!

Let’s continue building the pass.json file – next up is styling its looks.

Open up pass.json and at the end of the line defining the “description” key, add a comma – you need this because you’re going to be adding more keys to that dictionary. Just before the closing curly bracket, add:

    "logoText" : "Free Hugs LLC",
    "foregroundColor" : "rgb(255, 255, 255)",
    "backgroundColor" : "rgb(135, 129, 189)",
    "labelColor" : "rgb(45, 54, 129)"

Here’s what those keys do:

• logoText – this is the text that shows up in the pass header next to your logo image.
• foregroundColor – the color of the text.
• backgroundColor – the background color of the pass. Passbook will take the background color code and create a nice gradient based on it that gives the front of the pass a very nice visual appearance when presented to the user. Apple recommends using vibrant colors.
• labelColor – depending on your background color, the labels (or hints) on the pass will be rendered in a color that is nicely recognizable over the background. If you want, though, you can specify your own color code for those labels.

Now your pass has some style! Heidi Klum would be proud.

You’re going to keep adding elements until you have the bare minimum to proceed to building and testing in Passbook. Next, you’ll add a barcode.
Sounds complicated, right? Luckily, it’s incredibly easy to do this. PassKit supports three different types of barcodes (all of them being 2D barcode formats): QR, PDF417 and Aztec. To illustrate what I mean:

In other words, passes don’t support those old-fashioned barcodes you usually see on the packaging of items in the grocery store and (anticipating your question) support for them is not planned. Instead, PassKit uses fancy 2D formats, which are easier for image-based scanning devices (like the iPhone) to read.
You will use the PDF417 standard for the Free Hug coupon (the middle option in the picture above), so add a comma after the last line of the code (again before the closing bracket) and paste in the barcode JSON:

    "barcode" : {
        "message" : "All you need is love",
        "format" : "PKBarcodeFormatPDF417",
        "messageEncoding" : "iso-8859-1"
    }

Believe it or not, this is all you need to do – Apple will take care of generating the barcode for you! The barcode dictionary has three keys:

• message – this is the data you’d like the barcode to contain. It can be a unique code, the bearer’s client ID, or anything else. In the case of the Free Hug pass, it’s just a text message that authorizes the bearer to a promotional hug.
• format – the barcode format name. To generate a 2D barcode, use one of the constants : PKBarcodeFormatQR, PKBarcodeFormatPDF417 or PKBarcodeFormatAztec.
• messageEncoding – the name of the text encoding used to decode the message. If you use a non-“latin1” language, you will want to use UTF8 or any other text encoding that suits you (if you use standard English letters and numbers, the default to go with is “iso-8859-1”).

So far, the pass source code should look something like this:

{
    "formatVersion" : 1,
    "passTypeIdentifier" : "pass.com.yourdomain.couponfreehug",
    "serialNumber" : "001",
    "teamIdentifier" : "ABC1230000",
    "organizationName" : "Free Hugs LLC",
    "description" : "Coupon for 1 Free Hug",
    "logoText" : "Free Hugs LLC",
    "foregroundColor" : "rgb(255, 255, 255)",
    "backgroundColor" : "rgb(135, 129, 189)",
    "labelColor" : "rgb(45, 54, 129)",
    "barcode" : {
        "message" : "All you need is love",
        "format" : "PKBarcodeFormatPDF417",
        "messageEncoding" : "iso-8859-1"
    }
}

Next you’ll add some valuable information to the front side of the pass.

Once again, after the closing bracket of the barcode dictionary add a comma. (You keep doing this because I’d like for you to stick to having a valid JSON file at all times. Once you’re used to writing valid JSON, you can save yourself lots of time while debugging down the road.)

Go ahead and add the key denoting a coupon type of pass (again, paste this just before the final closing bracket):

    "coupon" : {
    }

Inside this empty dictionary you will be adding all the definitions and data to show information on the coupon pass. In between the enclosing brackets of “coupon” add:

       "primaryFields" : [
           {
           "key" : "offer",
           "label" : "for you",
           "value" : "Free hug"
           }
       ]

This structure looks a bit weird at first glance, but believe me – it all makes sense. First you add a new key called “primaryFields”, the value of which is an array. Why an array? Because all sections can display one or more fields, so you need a list to specify them one after another.

Each dictionary in the list describes one field. You’ve probably already figured it all out, but let me spell it out just in case. For each field you’ve got the following basic keys:

• key – the field name. In this case, the “offer” field is the one that shows up in the main content area of the pass.
• label – the accompanying label to the field. In this case, “for you” will show up in small letters below the text.
• value – the text the field shows on the pass. In this case, “Free hug!” will show up very large in the majority of the content area.

There are more keys you can use for each field, but you’ll have a look at those later on.

The important thing is – you now have a complete pass.json file! Sweet!