Property List (Info.plist) changes

In the last installment of Preparing for Mac App Store Submission, I discussed the project modifications that are necessary (or recommended) for converting an existing Mac OS X project to one suitable for MAS submission.

This second part describes the changes to the information property list for your application that you should make for successful submission and to eschew rejections for simple issues.  As before, comments about any other issues or different experiences are certainly welcome.

Open the application information property list, usually named ‘Info.plist‘, in your project and follow these steps…

1. Update the bundle version format

First, update the format of the ‘Bundle version’ entry (CFBundleVersion) to contain exactly 3 period-separated integers representing the version number (e.g., “1.01.1“).  It cannot contain alphabetic characters (and although some documentation suggests that it may contain more or fewer integers, we did not take that chance).

For non-MAS applications, the format of this field was not enforced and, in fact, the default ‘About’ box encouraged the use of this field as a standard version description (alphanumeric string) by directly displaying it underneath the application name.  We used a format like, “1.01 (January 2012)”, which is more useful and aesthetically pleasing, but this was cause for rejection.

2. Add an application category

If you do not have one already, you will need to add an ‘Application Category’ entry (LSApplicationCategoryType).  The easiest way to set this value (in Xcode 4) is to select the ‘Summary’ tab for your target and select the appropriate setting in the ‘Application Category’ box.  In the case of Pretty Good Solitaire, we chose ‘Games – Card Games’ (public.app-category.card-games).

Note that Xcode 3 did not recognize this key, so it was necessary to explicitly add it, along with the appropriate category value, as found in the Information Property List Key Reference; fortunately, this is no longer necessary.

3. Set the minimum system version

Next, set the ‘Minimum system version’ entry (LSMinimumSystemVersion) to “10.6.6”, or higher if appropriate.

The Mac App Store does not work on versions of Mac OS X prior to 10.6.6 anyway, and leaving this at a lower setting (even if your downloadable versions support Leopard, Tiger, or even an earlier OS) may be cause for a rejection.

4. Review the supported document types

Finally, review the supported ‘Document types’ entry (CFBundleDocumentTypes), if any.  Remove any document types that will not be supported in your store version.

In our case, we supported a document type for saved games, which is still useful, but also a document type for automatic installation of extra card sets (which can be downloaded), or in the case of Pretty Good MahJongg, types for both extra tile sets and tile matching layouts.  Since downloading or installing any improvement to your application (outside of the Mac App Store) is verboten, we needed to remove this support.

Note that this initially passed muster with our first product, but it was cause for a rejection later on a different product using essentially identical functionality.  There is clearly some subjectivity to the application reviews, so a more thorough (or nitpicky) reviewer may find something previously allowed.  When a rejection can set your release schedule back a couple of weeks or more, it is not worth the risk.

Conclusion

With just these few changes to your information property list, your project should have the necessary application information for submission.  In the next installment, Part 3: Data and Resource guidelines, I will describe the issues you may encounter with your application data.

Project modifications

In Preparing for Mac App Store Submission, the first set of changes you should make are to the project itself.

This installment describes the project modifications that need to be made to an existing Mac OS X game project.  The general assumptions are that the existing project is working and properly tested, and that, ultimately, you will want to maintain a single set of source code with conditional compilation to differentiate the store version from other builds.  Note that these are the steps that we took for Pretty Good Solitaire Mac Edition; your project may require some adjustments to these steps.  (Comments where any significant change is necessary would be very appreciated.)

So, without further ado…

0. Create a duplicate store project

Before making any other changes, create a duplicate copy of the entire project folder and name the copy appropriately.  In our case, the original folder was ‘Pretty Good Solitaire’ (which builds full and trial versions of the game) and we created a separate ‘pgsse’ (Pretty Good Solitaire [Mac/]Store Edition) folder for MAS modifications.

The version of your project that you will submit to the Mac App Store is a separate SKU (Shelf Keeping Unit), a build that uses slightly different code and configuration and which is distributed via a different channel.  While it is possible to have the store target within the main project, certain features (e.g., Power PC support, Mac OS X 10.5 support, downloadable data) are not supported in MAS, so it is easier to separate them (at first, anyway).  In any event, doing so at the start gives you a safe playground for making changes without messing up your working project.

1. Update the project version number

As just noted, the store build is a separate version and, thus, should have a different version number.  In our case, we decided that odd minor versions (e.g., “1.01”) would represent the store editions, while even minor versions (e.g., “1.00”) represented the direct downloadable editions.

2. Rename the primary build target

In the new project (of course), rename the primary build target to something appropriate.  In our case, we renamed the full version target to ‘Pretty Good Solitaire store’, which is now the store version.  You could also delete any redundant or obsolete targets remaining in the project.  For example, we deleted the trial version target, as it is built in the original project and the MAS version cannot have any vestiges of a trial version.

Note that this step is not strictly required, but it is a good idea to differentiate between targets, so it is always immediately obvious which project is active, and also to minimize any excess baggage, which reduces the possibility of mistakes.

3. Build with a current Xcode version

Make sure that you build the project with a current version of Xcode.  Submissions to the Mac App Store now require Xcode 4 and, as of this writing, the latest version is Xcode 4.2.1.

If you have an older version of Xcode, this would be a good time to upgrade, and although it will not be mentioned explicitly, you should build the project regularly, ideally after every change, to make sure that the build is not broken and behaves as expected.

4. Define a preprocessor variable

To allow for conditional compilation of certain source code, it is a good idea to define a preprocessor variable, APPSTORE, for any build targets intended for MAS.  In the ‘Build Settings’ for the target (or the whole project, if you prefer), find the setting for ‘Preprocessor Macros’ and add “APPSTORE” to each configuration.  Note that it is common to have different variables for ‘Release’ and ‘Debug’ configurations, so be careful to define APPSTORE for each one without accidentally removing or altering any existing definitions.

Of course, there is no requirement that the preprocessor variable be named “APPSTORE”, but beware that simply using “STORE” results in a naming conflict in the latest Mac OS X SDK.

5. Add necessary frameworks/libraries

In order to test the validity of app receipts, you will need to add the IOKit and Security frameworks and the crypto library.  From the ‘Build Phases’ of the primary target, open the ‘Link Binary With Libraries’ section and, by clicking on the ‘+’ symbol, add ‘IOKit.framework‘, ‘Security.framework‘ and ‘libcrypto.dylib‘.

Note that Xcode 4 adds these frameworks/libraries at the top level of your project; you will probably want to drag them into the ‘External Framework and Libraries’ folder with the other frameworks.

6. Configure debugging symbols

Despite submitting a release version to MAS, Apple requires debugging information to be included with a submission.  To accede to this requirement, you must set ‘Generate Debug Symbols’ to “Yes” and also set ‘Debug Information Format’ to “DWARF with dSYM File” (at least for the ‘Release’ configuration) in the ‘Build Settings’ of the target.

In our original project, we had all debug information disabled and/or stripped from the release builds, but one of our early issues was the lack of the dSYM file with debugging information for Apple.

7. Set correct build architecture

Finally, set ‘Architectures’ to an Intel (only) setting; for our project, that is “32-bit Intel”.

Even if your code and original project supports both PPC and Intel via a “Universal” application, the presence of a PPC build in your submission will result in rejection.  (We found that out the hard/lengthy way.)  At least now there are settings for this; in Xcode 3, you had to use “i386”, which was not even listed as a choice.

Conclusion

At this point, you should have a new project with a store target and all of the build settings configured appropriately.  In the next installment, Part 2: Property List (Info.plist) changes, we will discuss the necessary adjustments and additions to the information property list for your project.