Using Sparkle: the Basics

Follow this guide, and you’ll have Sparkle up and running in your application in no time at all! Just a few quick steps:

  1. Link the framework: Drag Sparkle.framework into the Linked Frameworks folder in the Files list of your Xcode project, making sure to check the “Copy items into destination group’s folder” box in the resulting sheet.
  2. Deploy the framework:
    1. Create a new Copy Files build phase (Project > New Build Phase) and select Frameworks for the destination.
    2. Switch to the Project page (⌘-0), find your Target in the files list, and reveal its contents by clicking the disclosure triangle next to it.
    3. Drag Sparkle.framework from the Linked Frameworks folder to the new Copy Files phase.
  3. Instantiate the updater:
    1. Open MainMenu.nib in Interface Builder.
    2. Click the Classes tab.
    3. Go to Classes > Read Files..., navigate to your project directory, then import Sparkle.framework/Headers/SUUpdater.h. SUUpdater should now appear in the class list.
    4. Select SUUpdater and go to Classes > Instantiate SUUpdater.
    5. Create a “Check for updates...” menu item in the application menu and connect it to checkForUpdates: in SUUpdater (using Control+drag).
  4. Make an appcast:
    1. Sparkle uses appcasts for update information. If you already have one, you can skip this section.
    2. Appcasts are simple: they are RSS feeds with enclosures around software. For Sparkle, these enclosures contain updates to your application. You can make RSS feeds by hand or with the help of another application (Feeder is a nice one).
    3. Whenever you release a new version of your application, compress the .app into an archive (zip, tar, tbz, tgz, or dmg), name it with the format: YourApp_VersionNumber.zip. For example: Pixen_2.4.zip. Then add a new item to your appcast enclosing that archive.
    4. The description property (or body) should contain release notes for the update (use HTML, but escape < and > with &lt; and &gt; or CDATA tags) or the URL of a web page with the release notes to display. If you don’t want to display release notes, set SUShowReleaseNotes to <false/> (or No in Property List Editor) in Info.plist.
    5. Sparkle adds some new attributes and properties to the RSS standard (more on those later). To use these features, you’ll need to add a URI to your <rss> tag like this:
      <rss version="2.0" xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle">
    6. See the Appcast Sample section later in this document for a sample feed you can use.
  5. Enter your appcast’s URL: open your target’s Info.plist and add an SUFeedURL key set to the URL of your appcast:
    <key>SUFeedURL</key> <string>http://www.yourdomain.com/app/example.xml</string>

And that’s it! You’re done! Build and run, and Sparkle should be up and running. You might want to create a test update in your appcast to see how everything works.