Making your own Passbook Business Card

My Passbook and iBeacon enabled business card was something of a hit at WWDC last week. Some people wanted more detail on how it worked or how to create their own version. This post describes the process, from the perspective of a software developer. If you’re not a developer, there are numerous web sites that will help compose Passbook passes, but I can’t personally vouch for any.

The very basics: A Passbook pass is defined by a JSON file. Put the JSON file and any images the pass uses in a folder, and then use Apple’s signpass tool to zip it up and sign it. Now you have a pass. Upload that to a properly-configured server and you can easily share it with others.

To set up any kind of pass, you’ll need:

1. A “Pass Type ID” Certificate, which you can create in the iOS “Certificates, Identifiers, & Profiles” page for your developer account. Create this just like any other certificate. Download it and add it to your Mac’s Keychain.

2. Your team ID, available in the “Member Center” under “Your Account”. This goes in the pass’s JSON file.

3. Apple’s Passbook Programming Guide and Passbook Package Format Reference.

4. Apple’s “companion file” for the Passbook Programming Guide, which is where you get their signpass command-line tool.

I won’t be going through every JSON field, because there are a lot and because the docs are pretty good. If you want an example, get my card and unzip it. Although it’s signed, it’s still a zip archive, and the JSON is not modified during signing. A few key details in mine are:

• I used the generic card type. There are several types, with different rules about behavior and appearance. The eventType card offers the most flexibility of design but has the drawback (to me) that it only responds to iBeacons within ±4 hours of the event start time. Apple’s docs give wireframes of each type. None of them offer arbitrary page layout. Each is like filling out a form, though the exact field list varies depending on card type.

• My card includes a beacons section that identifies my iBeacon. Since the Passbook app supports iBeacons, all you need to do to support them is add the iBeacon’s UUID, major, and minor numbers, plus a short message that appears on people lock screens when the beacon is near.

    "beacons" : [
      {
          "major" : 50166,
          "minor" : 17115,
          "proximityUUID" : "8AEFB031-6C32-486F-825B-E26FA193487D"
          "relevantText" : "Tom is nearby, say hi",
          }
      ],
  

  Make this match your iBeacon. Then when someone who has your card is nearby, something like this appears on their iPhone’s lock screen:

This is not a notification. There's no alert sound or vibration. It's like the way a boarding pass shows up when it's nearly time to depart. Except, it's based on iBeacon proximity instead of time and date.

• Passbook supports three kinds of bar codes and can scan all three. If you include a bar code that encodes your pass’s URL, you can pass it to people by having them scan the code in Passbook.app. I used a PDF417-style code mainly because of its shape. QR codes also work, but their square shape means there’s less room for text. To include a bar code, the JSON only needs to include a message to be encoded (the URL in this case), the message’s text encoding, and the type of code. You don’t need to provide the bar code image, Passbook generates that for you.

    "barcode" : {
      "message" : "https://atomicbird.s3.amazonaws.com/TomHarrington.pkpass",
      "format" : "PKBarcodeFormatPDF417",
      "messageEncoding" : "iso-8859-1"
      },
  

  You can also include an altText message that appears below the bar code (thanks to Allan Evans for pointing that out to me).

The process is:

1. Put the JSON and all of the images in a folder whose name ends with the extension .pass.

2. Sign the pass using signpass, meaning something like:

    signpass -p Foo.pass
   

   By default this saves the pass to Foo.pkpass, but you can change that if you like.

3. Preview the pass, because there will be some trial and error before you get it right. A quick and easy way to do this is to double-click the pkpass. You’ll see a preview, and if it looks good you can add it to your phone right from your Mac. You get the same effect at the command line via open Foo.pkpass. During development I signed and opened in one step to speed up the edit/preview cycle:

    signpass -p TomHarrington.pass && open TomHarrington.pkpass
   

   Viewing the pass this way is quick and easy but the actual appearance is only approximate (even colors may be off). You’ll get a better preview if you drag the pkpass into the iOS simulator, though this is slower.

4. When it looks good, upload it somewhere. Not just anywhere, though. If you want pass downloading to work on iOS, you must:

   • Use a server that serves HTTPS
   • …using a certificate from a known certificate authority (self-signed certificates won’t be accepted).
   • Make sure the server uses MIME type application/vnd.apple.pkpass when serving the pass file.

   If you miss any of these, Passbook will report vague errors that don’t really describe the problem. It’s possible to host a pass at Amazon S3, but you’ll have to do the last step by hand. You can set MIME types per file at Amazon’s S3 console.

   This won’t let you push updates to the card. That’s possible but is beyond what I’m trying to accomplish at the moment.

With all this, you now have possibly the geekiest business card currently possible. If you set one up, let me know, I’d love to see what else people do with the idea.