Release day

Unless your Internet tubes are broken, you’re probably aware that we released Frenzic for the iPhone today. It’s been a long time coming, but we’re all very proud of what we’ve accomplished—and very grateful for the great feedback we’ve been getting. As always it’s been a great pleasure working with Wolfgang Ante on this game.

But let’s go beyond all of this self congratulation and look at some of the details about how to coordinate your App Store release.

The first trick is setting your release date. As we all know, there can be some long wait times in the iTunes Connect queue. Indications are that the approvals are getting quicker, but it’s still an indeterminate value. And not knowing when your application is going to appear in iTunes means that it’s hard to coordinate press releases, website updates and other things that are dependent on having an product for sale.

The way to handle this is surprisingly simple: when you add or update your application in iTunes Connect, set the release date far into the future. Then, once you’ve been approved, you can update the release date to coordinate with PR. We knew that Frenzic would show up in the App Store on November 19th. But we didn’t know exactly when.

So what does it mean to “show up” in the App Store? iTunes is a worldwide enterprise so the date and time on your wall clock doesn’t mean much. There are timezones that will see November 19th before you do. Since Frenzic stores scores with unique ids and timestamps on its website, we collected some data that provides insight on how applications are deployed on iTunes.

The first scores started coming in just before midnight GMT on the 19th. The bulk of the traffic was coming from throughout Europe, although there were also some scores from Australia. As far as the listing in iTunes is concerned, we first saw it appear in the UK store. It then appeared in Sweden and Austria: this was not an exhaustive search, merely one of convenience (we have employees in these countries.)

The most important thing, of course, is getting the iTunes link for the product. This link is used throughout the site on buy links. We needed this information before doing a website deployment.

Happily, the link that showed up in the UK is also the same one that’s used in the US (we assumed it would be, but were reluctant to a deploy until we were sure.) You can get the link by control-clicking on the product icon in iTunes and selecting “Copy iTunes Store URL”. The resulting URL looks something like this:

Unfortuately, the only way to know this URL is by having it show up in iTunes. It would be nice to have this information ahead of time, and if you agree please submit a duplicate for ID# 6386452.

Updated November 19th, 2008: Thanks to Derek Del Conte there is a way to get the application ID. Just click on App Details in the “Manage Your Applications” list. The “Apple ID” can be used to create the link.

Another option for the purposes of deployment is to use a URL with the product name:

This format generates a redirect to the iTunes product URL. Unfortunately, it has been buggy in the past, so use it sparingly.

Finally, I’ll leave you with some eye candy. Wolfgang has posted some screenshots of Frenzic throughout its development:

  • The first prototype that we ever played on OS X. This is what got everyone at the Iconfactory hooked.
  • The game screen. The first pass at this used the same color scheme and contrast as the desktop version. That was a bad idea: put this screenshot in Photos and take it outside and you’ll see why.
  • The scores list. There is an art to making table views look nice. Both Wolfgang and I are lucky to work with some very talented designers :-)

So give Frenzic a try and if you like it as much as we do, tell your friends. Thanks!

Cooking with gas

One of the great things about the NDA being lifted is that a lot of great books about iPhone development are finally being published. It’s about time: for many months the top search hit on this site has been iphone app development. A lot of new developers need guidance.

Last week, Addison-Wesley contacted me saying that they wanted to mail a free copy of Erica Sadun’s new book, The iPhone Developer’s Cookbook. I guess that’s one of the benefits of having a web log that a lot of other iPhone developers read: I took them up on the offer since there were no strings attached.

To be honest, I wasn’t expecting to get much out of this book. After spending many months digging around in the bowels of the SDK, I thought I had seen it all. I’m happy to report that I was wrong.

If you’re an experienced iPhone developer, you won’t learn much from the beginning of the book: you already know about the application package, setting up Xcode, platform limitations, how UIKit uses MVC, and so on. If you’re new to the platform, this information will certainly be helpful and I found that it was presented clearly and concisely.

So what did I like about this book?

First off, there are the recipes. These short snippets of code show you how to do a lot of common tasks. Need to build some draggable views? Just look up the recipe “Dragging Views” and you have a few pages of pertinent information (including a brief introduction to UITouch.)

I much prefer this format over long, involved examples that are complete implementations. The recipes in this book act as a quick way to get up to speed and they help you find more detailed information in the Developer Documentation in Xcode. The recipe format gets you pointed in the right direction.

In going through these recipes I ended up learning some new things. For example, I didn’t realize that you can set the number of rows in a UIAlertView. Again, the short and sweet recipe format makes it easy to pick these things out.

There are also some clever recipes: I particularly enjoyed the one that added a UIProgressView as a subview to an empty UIActionSheet. A nice trick to leverage the existing UIKit classes in new and different ways.

But the real value of this book comes from Erica’s experience in working with the Jailbreak APIs. She goes where the Xcode documentation does not and lets us peek behind the curtains. (This book, in effect, summarizes a lot of the poking around she did during the early days of the iPhone.)

Personally, I will never use undocumented iPhone SDK calls. It’s just too dangerous: you risk not getting accepted into the App Store because you’ve broken the terms of the license agreement (section 3.3.1.) And even if you do sneak it through, what are you going to do if the unpublished API changes and breaks your app? You’ll have a hell of a lot of unhappy customers for the couple of weeks it takes to get a new version submitted and approved.

So why is Erica’s exploration into the undocumented side of the API so helpful? Because it shows us what Apple is using in their own applications. And if we need similar functionality, we can file enhancement requests using this inside knowledge.

As an example, there’s the page curl animation that is used in the Maps application. You won’t find it in the API documentation, but it’s there if you use @”mapCurl” or @”mapUnCurl” as the animation type. If you want to do that in your own app, write a Radar and let the developers at Apple know. Make sure to give them context for the enhancement request: tell them why exposing the API would make your app better.

Personally, I have written Radars for the inclusion of the UICalloutView class and UIToolbar customization functionality.

In summary, I highly recommended Erica’s book. If you’re a beginner, you’ll find code that helps get you started. For those of us who have more experience, you’ll find it to be a valuable reference for both public and private APIs.

If you’re planning to buy a copy, please make me rich with affiliate kickbacks at Amazon. Thanks!

The final test

During the early days of iPhone software development, there were no mechanisms for doing beta tests. Those of us on the bleeding edge were developing apps with very little peer review and beta testing.

Luckily, I have friends who are a lot smarter than me. And we banded together with one primary rule: you don’t talk about Fight Club. Despite the NDA, we were determined to test each others applications.

This was accomplished by distributing unsigned applications amongst the group. Each member of the group then signed the app with their own developer certificate and installed it with Xcode. We all got pretty good with the codesign utility because it was so exciting to see each others work.

But this essay isn’t about reminiscing. It’s about telling you how to test the applications you upload to iTunes Connect.

If you’ve submitted an application to the App Store, you know that sinking feeling of not being able to test your final build. The binary that gets signed with the “App Store” distribution mechanism cannot be run on your test devices: you can’t be sure that the final bits you send to Apple are complete.

But there’s a simple way around this problem and it’s called codesign. The same application we used for our pre-Ad Hoc beta testing can also be used for a final test on your App Store submissions.

The first step is to create your distribution build for the App Store. For this example, we’ll be using the Frenzic application and putting it into build/Distribution-iphoneos. After the build completes, make the ZIP file archive immediately. Put it in a safe place so you can upload it to iTunes Connect after you finish your final test.

Now verify that you’re dealing with the right application. Go to the build folder and issue the following command:

$ cd build/Distribution-iphoneos
$ codesign -d -vv

You’ll then see a verbose dump of the signature in the application:

Format=bundle with Mach-O thin (armv6)
Signature size=4331
Authority=iPhone Distribution: The Iconfactory
Authority=Apple Worldwide Developer Relations Certification Authority
Authority=Apple Root CA
Signed Time=Nov 12, 2008 1:46:07 PM

The most important part of that output are the lines beginning with “Authority”. It shows that the “iPhone Distribution” certificate for The Iconfactory is being used. This is what Apple needs, but it’s also the thing that keeping you from running the app on your test devices.

So let’s change it.

The first thing you need to do is define an environment variable that gets the correct version of codesign_allocate (the one in /usr/bin doesn’t currently support ARM):

$ export CODESIGN_ALLOCATE=/Developer/Platforms/iPhoneOS.platform/Developer/usr/bin/codesign_allocate

If you forget to do this, you’ll see this error message when you try to sign the binary:

codesign_allocate: unknown architecture specification flag: -a armv6 6720

Now you can sign the application using your own certificate:

$ codesign -f -s "iPhone Developer" -vv

The -s parameter should be the same value as the Code Signing Identity > Any iPhone OS Device setting in your Xcode project. The -f parameter tells codesign to force the replacement of the signature. As the command executes, you’ll see the following output as the signature is replaced: replacing existing signature signed bundle with Mach-O thin (armv6) [com.iconfactory.Frenzic]

After you’ve re-signed the app, you’ll see that I am now the authority. But you probably already knew that:

$ codesign -d -vv Executable=/Users/craig/Projects/FrenzicTouch/build/Distribution-iphoneos/
Format=bundle with Mach-O thin (armv6)
Signature size=4302
Authority=iPhone Developer: Craig Hockenberry
Authority=Apple Worldwide Developer Relations Certification Authority
Authority=Apple Root CA
Signed Time=Nov 12, 2008 6:35:06 PM

Now you can move the updated application onto a test device and make sure that the final build is OK. Everything except the signature is the same: if there’s a missing file or something that’s messed up, you’ll be able to find it before the QA engineers at Apple do (and with 10 day turnaround times, that’s a very good thing.)

Once you’re happy that everything looks good, upload the ZIP file you created earlier to iTunes Connect and crack open a beer. As you’re enjoying that beer, take a look at the codesign man page for more information on this essential utility. Or write an essay for your web log :-)

Updated July 2nd, 2009: Note that this procedure can also be used if you are beta testing. This is particularly helpful in cases where you’ve upgraded to an iPhone 3GS and the Ad Hoc .mobileprovision file for the beta contains the UDID for your older device. Many developers have hit the 100 device limit since the release of the new phone, and can’t add devices into a new .mobileprovision file. You’ll be able to test the beta releases after signing the code with your own certificate. The only case where this won’t work is when the app being resigned uses the keychain.

Debugging with backups

If you’ve written an application for the iPhone, you’ll eventually encounter a customer problem that you can’t reproduce. Of course, you’ll want to get a copy of the customer’s data and preferences so you can replicate the environment they are working in. And then you’ll realize that it’s a total pain in the ass for both you and your customer.

iTunes creates backups every time a user syncs their device, but these backups are meant to be read by a machine, not a human. Your customer will have to wade through a bunch of GUIDs in the MobileSync/Backup folder: getting the right backup for your application has been a headache.

Fortunately, things got much better last week with the release of Pádraig Kennedy’s iPhone Backup Extractor. Pádraig is the author of the Python script some of us have been using to extract data from the .mdbackup files. Having this script in a GUI that the end user can run is a huge improvement.

You can instruct your customer to download the application, sync their device with iTunes and then have them select the latest backup and your application within that backup. The resulting output contains the documents and preferences in use by the application at the time it was synced and can easily be put in a ZIP archive.

Getting this information into your development environment is then just a matter of hacking around with the Simulator folder structure in ~/Library/Application Support/iPhone Simulator/User/Applications. The bug won’t stand a chance at this point :-)

Thankfully, Pádraig has made this a free application. Your customers won’t need to pay for anything before they help you out. You, on the other hand, won’t be using it directly but will still benefit immensely. Make sure to click on the Donate button so that this application will continue to see development and maintenance. I just did.