Beginning Passbook in iOS 6: Part 2/2

Dissecting pass styles…

Next you are going to look in more detail at the different styles of passes. Here is a preview of how they all look when imported in Passbook – you can see each type has a small style touch applied to the card:

So, how to create different passes? Go back to the source of the FreeHug coupon you were working on previously and open up pass.json. In the top-level dictionary you’ve added a key called “coupon”– the value of this key is a dictionary with field definitions. All passes work the same way – the only thing you need to do is change the key name from coupon to the style you’d like to have!

Santa’s well deserved vacation trip

To make the examples in this part a bit more fun, Vicki Wenderlich planned Santa’s vacation trip and prepared all the passes he’s going to need throughout his well-deserved vacation. With his iPhone’s Passbook loaded with coupons, VIP cards, and plane tickets bought in advance, Santa can have some time off after the Christmas rush without carrying around extra papers in his sack of toys. The first example is of course Santa’s plane boarding card for his flight to Tahiti.
Here’s the content of pass.json from the BoardingPass.pkpass example included in this chapter’s resources:

{
  "formatVersion" : 1,
  "passTypeIdentifier" : "pass.com.iOS6-By-Tutorials",
  "serialNumber" : "AX6184HJDG",
  "teamIdentifier" : "ABC1230000",
  "barcode" : {
    "message" : "AXB739-StClaus-A280",
    "format" : "PKBarcodeFormatQR",
    "messageEncoding" : "iso-8859-1"
  },
  "organizationName" : "Reindeer Airways LLC",
  "description" : "Train Boarding Pass",
  "logoText" : "Reindeer Airways",
  "foregroundColor" : "rgb(255, 255, 255)",
  "backgroundColor" : "rgb(230, 72, 56)",
  "boardingPass" : {
    "headerFields" : [
      {
        "key" : "header",
        "value" : "1",
        "label" : "Seat"
      }
    ],
    "primaryFields" : [
      {
        "key" : "from",
        "value" : "NorthPole"
      },
      {
        "key" : "to",
        "value" : "Tahiti"
      }
    ],
    "secondaryFields" : [
      {
        "key" : "meal",
        "label" : "Meal",
        "value" : "Milk & Cookies"
      }
    ],
    "auxiliaryFields" : [
      {
        "key" : "departure",
        "label" : "Departure:",
        "dateStyle" : "PKDateStyleMedium",
        "timeStyle" : "PKDateStyleMedium",      
        "value" : "2012-12-27T10:35Z"
      }    
    ],
    "backFields" : [
      {
        "label" : "terms & conditions",
        "key" : "terms",
        "value" : "Ticket is non-refundable.  Please specify which type of cookie you want upon check-in: chocolate chip, peanut butter, or M&M sugar cookie."
      }
    ],
    "transitType" : "PKTransitTypeAir"
  }
}

As you can see, the structure of the file is almost the same as what you had before, with the difference that instead of coupon you have a boardingPass key. There’s one other thing of interest: inside the boardingPass dictionary there’s an extra field called “transitType”. This field is specific for the boarding pass and is what sets the little transit icon shown on the front side of the pass.

For transitType, depending on what kind of boarding pass are you building, you can use one of the predefined type constants: PKTransitTypeAir, PKTransitTypeTrain, PKTransitTypeBus, PKTransitTypeBoat, and PKTransitTypeGeneric.

And that’s the difference between building a coupon and a boarding pass! The source code above results in this nifty boarding pass:

Can you spot Santa’s meal preferences on the boarding card? So can the flight attendant – he’s up for a relaxing flight!

Boarding Pass style considerations

• Note that the primary fields are using quite a large font so that they can’t show more than a few characters of text. Longer destination names like “San Francisco” are going to be cut off, so consider using destination codes instead of names. It would be best is to show the full name of the city as the field label, and the destination code as the value.
• The boarding pass doesn’t show any pictures, so use only the icon and logo image files.
• It’s a great idea to use the header field for things like airport departure gate, departure platform or a seat number.

Make sure you are using the correct transit type for your boarding pass! Here are the different icons shown, depending on type:

And here’s also a preview of the positions of all available fields you can use (of course you don’t need to use all of the fields; this is to give you an overview of the styling and the positions of the available fields):

When designing a new pass there’s one major point you have to always pay attention to: the different styles of barcodes take up different amount of space on the front side of the pass. The PDF417 barcode has a horizontal layout, so it kind of fits nicely at the bottom of the card – leaving more space for the pass fields (like in the example above). On the other hand the QR barcode has a square shape and takes up more space vertically. Observe the same pass from above when it features a QR barcode:

You can clearly see there’s less vertical space between the fields so that the barcode can also fit on the card; therefore: always start designing a pass with the correct type of barcode, so that you can have the correct field layout from the start!

Note: If you reuse any of the code from the example passes in this part of the chapter, don’t forget to change the team and pass type identifiers to your own – otherwise, your passes won’t import to Passbook.

Are you a premium member?

Next, let’s look into store cards. These are very popular and already widely-used, so I bet many merchants will want to use the iPhone pass format to digitalize their store cards.
There is a store card example included with this chapter. Santa is up for some active recreation so he bought a premium package from the Tahiti Surf & Snorkel school. His pass also conveniently shows him how many pre-paid lessons he has left on his account with the school.

As you can see, the layout of the store card is somewhat similar to the coupon, but the header styling is different. Have a quick look at the source code for the pass above:

{
  "formatVersion" : 1,
  "passTypeIdentifier" : "pass.com.iOS6-By-Tutorials",
  "serialNumber" : "00012",
  "teamIdentifier" : "ABC1230000",
  "barcode" : {
    "message" : "q2eq3aaa",
    "format" : "PKBarcodeFormatPDF417",
    "messageEncoding" : "iso-8859-1"
  },
  "organizationName" : "Tahiti Surf & Snorkel",
  "description" : "Diving Lessons",
  "logoText" : "Tahiti Surf & Snorkel",
  "foregroundColor" : "rgb(255, 255, 255)",
  "backgroundColor" : "rgb(68, 200, 190)",
  "storeCard" : {
    "headerFields" : [
      {
      "key" : "lessons",
      "label" : "Lessons",
      "value" : "4"
      }
    ],
    "primaryFields" : [
      {
        "key" : "balance",
        "label" : "Class",
        "value" : "Premium"
      }
    ],
    "secondaryFields" : [
      {
        "key" : "memberName",
        "label" : "Name",
        "value" : "Mr. Claus"
      }
    ],
    "backFields" : [
      {
        "key" : "date",
        "label" : "Valid from:",
        "dateStyle" : "PKDateStyleMedium",      
        "timeStyle" : "PKDateStyleNone",      
        "value" : "2013-01-01T00:00Z"
      },
      {
        "key" : "date",
        "label" : "Valid until:",
        "dateStyle" : "PKDateStyleMedium",      
        "timeStyle" : "PKDateStyleNone",      
        "value" : "2013-01-03T00:00Z"
      },
      {
        "key" : "terms",
        "label" : "TERMS AND CONDITIONS",
        "value" : "Lessons must be used between 1/1/2013 and 3/1/2013.  Appointments for lessons must be made no less than 48 hours in advance.  Customer must be able to swim."
      }
    ]
  }
}

The basics, which you already well know and love, are all there, so I’m not going to cover them again. However, there are a few things to discuss inside the backFields dictionary. You have two date fields and a text field for the terms and conditions, and all three fields contain dates. This is a great opportunity to connect the pass with the Calendar on the iPhone! Tap the “i” button at the bottom-right corner and have a look:

Passbook auto-detects the dates and turns them into links. When they are tapped, the user is presented with an action sheet, which can take them to the specific day in the Calendar, or help them create an event in the Calendar for the specific day or period. Outstanding!

Store card style considerations

Usually a store card holds the customer’s credit with the store. It’s a good idea to put that information in the primary area of the pass. Passbook can render different currency styles as well, so if you are showing money amounts, consider showing them in the user’s currency, like so:

Passbook even automatically removed the digits after the floating point for the amount in Japanese Yen, because the Yen doesn’t use a decimal point! (1 is the lowest possible value.)

To style a field as a currency amount, you need a numeric value (so, no quotes around the number) and there has to be an extra key to define which currency to use. For an amount in Japanese Yen, that would result in the following code:

{
  "key" : "amount",
  "label" : "Current credit store",
  "value" : 45.20,
  "currencyCode" : "JPY"
}

And finally, here are the kinds of fields a store card can show on its front: