One of the most confusing parts of iPhone development is dealing with the iPhone Developer Program side of things. You know, all that fun stuff with certificates, devices, provisioning profiles, distribution profiles, etc. Oh, the hours of “fun” you can spend with that.

Last night was particularly frustrating because I had just called it “beta” on Flower Garden and celebrated with the requisite victory dance, when the fun of sending out the beta build started. What I thought would be a ten-minute task, turned into a long nightmare and I didn’t get the build out until 1AM.

This is not the first time I run into issues with provisioning profiles and distribution in general. It’s a very finicky process, and other developers are going through the same pains. Mark Johnson suggested I collected all the gotchas I’ve learned into a single place so it can serve as a form of reference. That’s a great idea, because the process is so byzantine that I will have forgotten most of them next time I need to do another big submission.

This is not a “how to” document on preparing your builds for ad-hoc or App Store distribution. Apple has the basic flow documented in their site, and other people have also talked about the process. This is intended to be more of an appendix explaining details, clarifying assumptions, and correcting things that are just plain wrong.

To make this more comprehensive, I’d like to open it up to other people’s experiences, not just mine. If you have gone through some pains with the iPhone Developer Program (and who hasn’t?) and found a way to deal with them, please post in the comments and I’ll update this page to reflect it.

iPhone Developer Program

1. App identifier is case sensitive. This is the string you need to enter when you create an app ID through the developer web site, and the one you need to set in your Info.plist. My usual development id is com.snappytouch.* so I can use it for anything I do. But in preparation for sending out the beta build, I created one just for Flower Garden: com.snappytouch.flowergarden. I thought that everything on the build side of things would be fine because my default app ID was: com.snappytouch.${PRODUCT_NAME:identifier}. Unfortunately, this failed to create a working build without any helpful errors. After much hair-pulling, I figured that was because my app is called “FlowerGarden” not “flowergarden”. Changing the app ID in XCode to com.snappytouch.flowergarden fixed that.

2. Easy UDIDs. Forget about asking your testers to go to iTunes and get the UDID from there. Instead, tell them to get BetaHelper and email you all the information directly. Easy and no typing errors!

3. Bulk device upload. I got a great response to the call for beta testers for Flower Garden, so I was left with about 30 new device UDIDs to enter in the developer web site. Entering them one at a time with a slow-as-molasses interface isn’t my idea of fun so I decided to use the bulk upload option. Unfortunately the format isn’t described exactly anywhere, and the errors displayed if the format doesn’t match exactly are meaningless.

The exact format is:

Device ID	Device Name
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx	Whatever name here
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx	Lalalala
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx	Whatever

So, tab separated, not comma separated. First column is the device ID (40 digits). Second is the name, no quotes around it. First line is ignored. Here’s the killer: You cannot have any blank lines after the last entry. And the error message if you do is simply a “Bad format”. Come on Apple, throw us a bone over here! One last thing: You can’t upload a device ID that is already in your database. Really annoying. Still, beats cut and pasting all those IDs by hand.

4. Ad-hoc zip file for Windows users. Apparently it can’t be created with the Compress option in finder because it puts extra files. I used zip from the command line and it worked correctly. (Thanks to Mark Johnson for that one).

5. App Store zip file has to be created through Finder with Compress. I heard that on Twitter somewhere, but needs confirmation. Anyone?

6. Adding provisioning profiles. Forget about dragging them on XCode and manage them manually. Check out my earlier entry about it.

7. Set correct provisioning profile everywhere. And I mean everywhere. You need to do it both in the Info for the target and the info for the project itself. Yes, both dialog boxes look identical and have 99% the same information, but the provisioning profile setting is different apparently. Fail to set it in both places, and your app won’t load in the device.

I’m sure there are a lot more. If you’ve found some of your own, leave a comment and I’ll update the list.

Today I join the ranks of proud iPhone owners (maybe not so much in Japan though). Yes, it an extra expense I can barely afford, but my previous cell phone contract was pretty much over and it made sense. So far I had been doing all my development on an iPod Touch, but I could really use a real iPhone for beta testing Flower Garden with all the reports of significant performance differences between the iPod Touch 2nd gen and iPhone. Besides, with 360iDev and GDC coming up, being able to have constant internet access for email and Twitter is a huge bonus.

Or maybe I just had gadget envy. Whatever.

But I’m not writing to rub in what a cool gadget I have now. I had a couple interesting experiences adding new devices to XCode and I figured I would share them with other iPhone devs.

SDK and firmware compatibility

This is something I noticed a few weeks ago, but I was able to confirm it with my new iPhone. Each new version of the iPhone SDK warns you to upgrade your device firmware to that version before you attempt to run any programs on it with the new SDK. I always took that literally, but I realized it’s not as restrictive as it sounds.

With each version of the SDK, you have the option to target your build to that version or any of the previous ones. I discovered quite by accident that is perfectly fine to use a certain SDK (like 2.2.1) to build for an earlier version (2.0) and run it on a device with older firmware matching that version. It really makes a lot of sense, because otherwise the only way you could test your app on older firmware would be by reinstalling an old SDK. So maybe this is old news to most people, but it was certainly nice to first upgrade the SDK, and only later the firmware to minimize potential for problems.

Updating provisioning profile

So with my new shiny iPhone in hand (actually, it was a $99 refurbished model, but it shines like new and has that new car smell… oh wait), I set to run Flower Garden on it. The process involved the following steps:

• Add a new device with the UDID of my iPhone to the Apple Developer Program account. I made the mistake of having to type it manually from iTunes–didn’t realize that XCode allows you to copy and paste it, doh!. Check.
• Add the new device to the development provisioning profile I was using. Check.
• Download the updated provisioning profile and add it to XCode and my iPhone. Since the iPhone was plugged, all I had to do was drag it onto XCode. Check.
• Clean all, build, run. And….

Yeah, you guessed it, I got an error. Otherwise I wouldn’t be writing this if it had behaved as expected, would I? The error kindly informed me that the provisioning profile I was using to build the app wasn’t available on my device. But I could see it in the organizer window of XCode. I double checked it was the correct one and that Flower Garden was being built with that one. Check. Check.

What was going on?

Here’s the fun part, which took me a few minutes of digging through the docs. When I added the updated provisioning profile, XCode decided that it was a different one from the one I was trying to replace. But, here’s the kicker, they both had the same name and description. So XCode was still building my app with the old one, but it was the new one that was installed on the iPhone.

I discovered this by going to the source. XCode stores all the provisioning profiles in the folder ~/Library/MobileDevice/Provisioning Profiles. You can’t tell much of anything by looking at the filenames since they’re a bunch of UIDS, but you can crack the files open with a good text editor and you’ll see they’re a mix of text and binary data. From there, you can see which file corresponds to which profile by looking at the text between the <Name> tags. All I had to do was delete the two development provisioning profiles, re-add the new one to XCode and the iPhone and I was back in business.

I had heard so many horror stories of upgrades to 2.2.1 that I was afraid I was hitting one of those. Fortunately it was quite simple. Next time I’ll know where to look right away.

Now it’s back to work for me. I still need to finish the slides for 360iDev and then I need to fix a couple of things in Flower Garden and get it ready for the first round of beta testing. Sleep? What’s that?