Skip to content
This repository

Basic Setup

Follow these simple steps, and you’ll have your app auto-updating in no time.

1. Linking the Sparkle Framework

  • Drag Sparkle.framework into the Linked Frameworks folder of your Xcode project.
    • Be sure to check the “copy items into the destination group’s folder” box in the sheet that appears.
    • If your app is garbage collected, use the Sparkle.framework in the “With Garbage Collection” folder of Sparkle’s distribution.
  • Create a new Copy Files build phase for your app’s target (Project > New Build Phase > New Copy Files Build Phase)
  • Choose “Frameworks” as the destination for your new build phase.
  • Click the disclosure triangle next to your app’s target, and drag Sparkle.framework from the Linked Frameworks folder to the Copy Files build phase you just created.

2. Set up a Sparkle updater object

  • Open up your MainMenu.nib in Interface Builder.
  • Go to File > Read Class Files… and choose all the files inside Sparkle.framework/Headers.
  • Drag a generic Object (a blue cube) from the Library to your document.
  • Select this object in your document window, and under the Information tab of the inspector, set the class of the object to SUUpdater. This will instantiate your Sparkle updater object.
  • If you’d like, make a “Check for Updates…” menu item in the application menu; set its target to the SUUpdater instance and its action to checkForUpdates:.
  • These instructions only work for .app bundles, because the SUUpdater instance instantiated in the nib will always be the sharedUpdater, which updates the hosting .app bundle. If you want to update a non-app bundle, such as a Preference Pane, see Updating a Bundle for alternative instructions.

3. Segue for security concerns

  • Since Sparkle is downloading executable code to your users’ systems, you must be very careful about security.
  • To let Sparkle be sure an update came from you (instead of a malicious attacker), you must do one of two things:
    • Include a DSA signature of the SHA-1 hash of your published update file.
    • Deliver your update and your appcast through SSL.
  • Signing your updates is easy. Start by making yourself a pair of DSA keys; Sparkle includes a tool to help:
    • (from the Sparkle distribution root):
      ruby generate_keys.rb
    • You can use the keys this tool generates to sign your updates.
    • Back up your private key (dsa_priv.pem) and keep it safe. You don’t want anyone else getting it, and if you lose it, you won’t be able to issue any new updates.
    • Add your public key (dsa_pub.pem) to the Resources folder of your Xcode project.
    • Add a SUPublicDSAKeyFile key to your Info.plist; set its value to your public key’s filename—unless you renamed it, this will be dsa_pub.pem.

4. Publish your appcast

  • Sparkle uses appcasts to get information about software updates.
  • An appcast is an RSS feed with some extra information for Sparkle’s purposes.
  • Make a copy of the sample appcast included in the Sparkle distribution.
  • Read the sample appcast to familiarize yourself with the format, then edit out all the items and add one for the new version of your app by following the instructions at Publishing an Update.
  • Upload your appcast to a webserver.
  • Add a SUFeedURL key to your Info.plist; set its value to the URL of your appcast.
  • Remember that your bundle must have a properly formatted CFBundleVersion key in your Info.plist.

5. Test Sparkle out

  • Make sure the version specified for the update in your appcast is greater than the CFBundleVersion of the app you’re running.
  • Run your app, then quit: Sparkle doesn’t ask the user about updates until the second launch, in order to make your users’ first-launch impression cleaner.
  • Run your app again. The update process should proceed as expected.

Next steps

That’s it! You’re done! You don’t have to do any more. But you might want to:

Something went wrong with that request. Please try again.