Passbook FAQ

Answers to frequently asked questions about Passbook!

Answers to frequently asked questions about Passbook!

This is a blog post by iOS Tutorial Team member Marin Todorov, a software developer with 12+ years of experience, an independent iOS developer and the creator of Touch Code Magazine.

Passbook is one of the coolest new technologies in iOS 6. You can use it to create store cards, event tickets, coupons, and more!

To help you learn about Passbook, I wrote two massive chapters about it in iOS 6 by Tutorials. I also published an abbreviated version of the first of these chapters for free here.

Since the book has been released, there have been a lot of questions about Passbook. This is because Passbook is a bit more complicated than other Apple APIs – you have to do a lot of server side, command line, and certificate work, and it’s easy to make a mistake somewhere along the way.

So I thought it would be helpful to gather together the common questions people are asking on the forums and via email and put them together into this handy FAQ. We’ll include this in the next version of the book as a free update too! :]

I hope this helps, and I hope to see you make some amazing things with Passbook!

Q: When link to my pass is tapped on the iPhone, Safari tells me it cannot download this type of file. What gives?

A: That usually means Safari was not told by your web server that the content type of the file is “application/vnd.apple.pkpass”. Even if your web page is very simple and does not need any server programming I still recommend you to use PHP to dump the pass to the browser – that’ll give you the finest control over the process and minimize the errors you’ll need to handle.

Just dump the pass contents to the browser and set the content type of the file to “application/vnd.apple.pkpass” as described in the “Building the pass distribution website” section in “Intermediate Passbook”.

Q: When/Why do I need a server?

A: If you only need to send passes to your customers and not follow up on that you don’t really need a web server. You can send the passes via email to your most loyal customers or send the files over via chat, etc.

You DO need a web server if you want to keep a database of the generated passes, if you need to associate passes to a given customer, or if you are implementing a PassKit web service with push notifications and all the bells and whistles as described in “Intermediate Passbook”.

Q: My passes show up fine, but cannot be imported in Passbook!

A: This means your pass file is generally ok – it includes the required files in the proper format. Therefore Passbook can show a preview of the pass. However it means your pass does not pass validation when imported – this can be due different reasons. Watch carefully what happens when you try to import the pass – if it just disappears (vs sliding down) then definitely there was an error while validating the pass.

You should check the device console for error messages, they are usually very informative and you can find where your problem is. To learn how to check the console, check out the “What is wrong with my passes?” section in “Intermediate Passbook”.

Q: How can I preview my passes?

A: You can preview your passes either on your device (with the simple app you build in “Beginning Passbook”) or by double clicking the .pkpass file in Finder on your mac.

But be careful! The OSX Passbook preview is close to what will show up on the device, but not 100% identical. You can fast preview your progress on your Mac, but only the device preview gives you the most accurate rendering.

Q: My passes show up and import to Passbook, but I don’t get updates from my Passkit web service. Why not?

A: This most probably means the device cannot connect to your web service.

• First check in your pass.json file – is the web service URL correct?
• Then check the following – developer devices can connect over HTTP to your web service (if enabled in Settings\Developer\PassKit Testing), but all customer devices can connect to your web service ONLY via HTTPS.
• Check again pass.json – is the URL starting with https?
• Also, is your web hosting SSL (https) enabled?

If all of these are fine – fall back to reading through your device’s console, as described in “What is wrong with my passes?” section in “Intermediate Passbook”.

Q: What size should the images for my pass be?

A: The images are scaled down/up with their aspect ratio preserved. If the image does not adhere to the image slot aspect ratio, your images will be cropped after being resized to fill the spot.

Important! Note all the sizes below are in pixels for the retina images:

• background@2x.png – 360px x 440px, the image is blurred and cropped a bit on all sides to fit visually inside passbook
• icon@2x.png – 58px x 58px, a shine is automatically applied
• logo@2x.png – 320px x 100px, usually you should not take up the whole width
• strip@2x.png – 624px x 220px (sometimes varies a bit), a shine is applied, you can use suppressStripShine in your pass.json to disable the shine if you don’t want it
• thumbnail@2x.png – 180px x 180px

Q: Can I change the font size/image size/layout of the pass?

A: Unfortunately you don’t have control over the layout. You’ll have to make the best with what Apple has decided for you. Inside “Beginning Passbook” you will find layout previews of the different types of passes, so you have a good idea what is more or less possible.

Q: Push notifications are not going through at all!

A: As noted in the book not every web host is OK to host a Passkit web service. Usually those all-in-one hosting packages won’t cut the cheeze for you.

Note that the PHP script that send push notifications connects to gateway.push.apple.com over SSL on port 2195. Many of the cheap hosting companies won’t allow outbound connections to custom port numbers. The best way to understand whether your hosting company allows that is to give them a friendly call and explain them what you need.

Q: I have trouble generating my pass certificate in the console following the instructions from “Beginning Passbook”.

A: If while working in terminal with the openssl command instead of the short cryptic success messages (like “MAC verified OK”) you see a lengthy output listing all the possible parameters to the openssl command that means the params to the command were somehow wrong.

This is due a hitch while copying the text from the PDF – sometimes the PDF viewer adds an extra space after “-” signs. Often we have readers having an extra space between “-” and the “passin” parameter. Double check your command to make sure there are no extra spaces.