Including iTunesArtwork in Ad Hoc distributions

When submitting an App to Apple’s App Store, one must include a full sized 512×512 pixel version of the App icon to be shown inside iTunes. For Ad Hoc distributions, there is no place to upload such an icon. Instead, testers will usually just get to see a nondescript default icon when they drag your IPA file into iTunes. That is, unless you include an iTunes artwork icon directly inside your application bundle.

Unfortunately, Apple’s documentation on how to include iTunes artwork with Ad Hoc distributed Apps, is a little thin. Searching the Web brings up plenty of tutorials, but many of them turn out to be useless for legit Ad Hoc distributions. The reason is, that many of these tutorials explain how to add an icon file to your application bundle after it is already built. For example, they may recommend, that you first unzip your built IPA file, then add a PNG named iTunesArtwork to its content, and finally zip it all up again. Well, this might have worked at some time past, not sure, although even then probably only for installs on jailbroken devices. Today, iTunes will reject any modified IPA file, since such a modification after code signing makes the App appear as if it has been tampered. So, unless you want to go through the pain of re-signing the modified IPA file, for legit Ad Hoc distributions this approach simply does not work.

What must be done instead, is to already include the iTunes artwork icon while building. Judging from the tone of other tutorials, this might have been a problem in older versions of XCode. With today’s XCode, all one needs to do, is to drag and drop the icon file into the project’s root directory and name it iTunesArtwork. If you try this, simply make sure, that the file represents an image of 512×512 pixels, which can be stored either in JPEG (not recommended) or PNG format. No property list needs to be edited, no target settings need to be changed. Just “Build and Archive”, export the result as an IPA file to your disk using the “Share…” button in the Organizer, and you are done.

There is only one caveat to watch out for: The filename must match iTunesArtwork exactly, without any file extension! When saving a JPEG or PNG file on the Mac, most graphics programs will automatically add a file extension, which may not always be displayed in folder views. So, if after building following these instructions, iTunes still only shows its default icon, the first thing you should check for is, whether you might have accidentally saved iTunesArtwork with a file extension.

This entry was posted in iOS Development. Bookmark the permalink.

4 Responses to Including iTunesArtwork in Ad Hoc distributions

  1. is it possible to reject my app since i forget itunes artwork icon?

    • Sorry for totally neglecting this blog and not responding to your question any sooner. I am sure that you have found your answer elsewhere in the meantime, but nevertheless…

      I am no expert on this, since so far I have not submitted anything to the App Store. (My only App in making is still in Beta.) But from what I have read, it seems impossible to submit an App without including the iTunes Artwork icon, since it is asked for in a separate non-optional form field when uploading. For App Store submissions, the iTunes Artwork icon is provided to Apple as a separate file, not bundled into the App as described here.

      The procedure described here applies only to “Ad Hoc” releases to be sent out to Beta testers. With Ad Hoc releases, the iTunes Artwork is optional. However, including it is still advisable, since this will give your App a more professional look during the testing phase, which may be also considered a demo phase. It will also give your testers the most complete and realistic impression of the finished product, allowing them among other things to provide you with feedback on the icon design as well.

  2. Dennis Ferry says:

    We are using the command line interface xcodebuild to build our applications and then using PackageApplication to package them (it fits into our build system where GUI xcode does not). Do you know how to include the iTunesArtwork using command line tools?

    • I have not tried to build any iOS Apps through the command line tools yet. From what I understand, the iTunesArtwork plays no role during the build step, but is only included when the App is archived into an .ipa file. The way you explained the build process, that second step is done with a separate command line tool (xcrun -sdk iphoneos PackageApplication … correct?), which takes the .app folder created in the build step, and converts it into a signed .ipa file. Maybe you could do an experiment, and copy the iTunesArtwork file into the .app folder before creating the .ipa file? Does this work?

Comments are closed.