Monday, July 30, 2012

Adding a Retina-ready icon to your Mac app in three easy steps

I've been doing more OS X development recently, and coming from the iOS world, there's a lot that's familiar but I still stumble over many things. Creating an app icon is one of them. After some poking around, I've discovered what you need to do to create a custom icon for your modern Mac app.

Step 1: Create the icon images
Modern Mac icons pack five different resolutions in one .icns file, from 16x16 to 512x512:
  • icon_16x16.png
  • icon_32x32.png
  • icon_128x128.png
  • icon_256x256.png
  • icon_512x512.png
The dimensions are actually "points" rather than "pixels". On standard resolution displays, 1 point == 1 pixel; iOS developers are already familiar with handling "retina" resolution displays where 1 point == 2 pixels. These double resolution "retina" resources get "@2x" added to the base filename, so in addition to the five standard resolution icon images, you now need five double resolution ones:
  • icon_16x16@2x.png
  • icon_32x32@2x.png
  • icon_128x128@2x.png
  • icon_256x256@2x.png
  • icon_512x512@2x.png
The names describe the icon size in points, so icon_16x16@2x.png is 32 by 32 pixels and icon_512x512@2x.png is 1024 by 1024 pixels. Some of these images have equivalent pixel sizes: icon_32x32.png and icon_16x16@2x.png are both 32 by 32 pixels. You may be able to get away with using the same bitmap in many cases, but you (or your icon designer) may want to tweak each version to look best on their respective display types.

Step 2: Add an .iconset to the Xcode project
In the olden days, you would use the Icon Composer app to build your .icns file, but it's no longer being updated by Apple and doesn't support double resolution images. Today, Xcode will build your .icns file automatically for you. (Alternately you can use the iconutil command line utility to build .icns with high res images or to extract images from .icns files; see Apple's High Resolution Guidelines for OS X for details.)

The trick to making Xcode build your .icns automatically is to put your set of icon images in a folder named <ICON_NAME>.iconset, where <ICON_NAME> becomes the base name for your .icns file. Add this folder to your Xcode project and Xcode will then create <ICON_NAME>.icns when you build, and automatically copy it to your app bundle.

Note that the images in the .iconset directory need to have the names given above: "icon_16x16.png" through "icon_512x512@2x.png" or you will see a warning in Xcode when building your project and the mis-named images won't be included.

Step 3: Add the icon to the Info.plist
To set your app's main icon, add the "Icon File" key to your app's Info.plist file and set the value to <ICON_NAME> (without the .icns extension). If you used the standard Xcode template to create your app, your Info.plist will be named "<APP_NAME>-Info.plist", where <APP_NAME> is your app or project name. For those of you who like to edit your .plist files as XML, the key name is CFBundleIconFile.

You can also drag the .iconset directory from the finder or the Xcode project navigator to the "App Icon" pane of the Summary tab for your app's target (pictured above). If you use this approach, Xcode will insist on copying the .iconset into the root folder of your project, even if you've already added the .iconset somewhere else in your project's directory tree (<sarcasm>another great example of Apple's attention to detail</sarcasm>.) If you're not fussy about your project organization, you can simply let Xcode have its way; otherwise you can remove the copy Xcode makes and add the .iconset in a more appropriate place, like the Resources folder; just make sure to leave the "Icon File" key in your Info.plist and Xcode will show the icon in the "App Icon" pane.

Easy as 1-2-3
Not hard once you figure it out, and a nicer workflow than having to wrestle with a half-baked special purpose app like Icon Composer.

Monday, July 9, 2012

Download iTunes Connect sales reports with Autoindigestion

When you start selling your first app in the app store, it's very exciting to check you sales every day in iTunes Connect. After the initial excitement wears off and your app sales settle into a steady state, it's easy to get involved in your next project and forget to log into iTunes Connect periodically to download your daily or weekly sales reports. Apple only makes the last 14 days of daily reports and the last 13 weeks of weekly reports available; if you're not diligent, time can fly by and you will lose important sales records.

Apple does provide a tool to automate the retrieval of iTunes Connect sales reports: the Auto-Ingest tool, a small Java command line app. While it's good that Apple provides an officially supported tool, it's a very minimal one. The Auto-Ingest tool only downloads one report at a time and doesn't have any intelligence for determining which reports have already been downloaded, nor can it handle downloading multiple report types or multiple iTunes Connect vendor accounts without some scripting help. Enter Autoindigestion.

Autoindigestion is a command line utility for Mac OS X Lion that uses the Auto-Ingest tool to automatically download daily and weekly sales reports. The first time it runs, Autoindigestion will grab all available reports; on subsequent runs it will download new reports based on the current date and the dates of previously downloaded reports. If you miss a day because your system is off or iTunes Connect reports are delayed, Autoindigestion will catch up the next time it runs. Autoindigestion can also be configured to handle multiple iTunes Connect vendors, which is great if you handle sales reporting for clients.

Autoindigestion is open source and available under a BSD style license. It's currently available as source from the Autoindigestion GitHub page. It is a native OS X command line program written in Objective-C and requires Xcode to build. Complete instructions for installing and configuring Autoindigestion are included on the GitHub page. I enjoyed creating Autoindigestion and hope you find it useful.