Home

Basic Setup

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

These steps apply to Xcode 4. If you’re still on Xcode 3, read Instructions (Xcode 3).

First, we’ll link the Sparkle framework to your target:
- Drag Sparkle.framework into the 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.
- Make sure the box is checked for your app’s target in the sheet’s Add to targets list.
- If your app is garbage collected, use the Sparkle.framework in the “With Garbage Collection” folder of Sparkle’s distribution.
Now we’ll make sure the framework is copied into your app bundle:
- Click on your project in the Project Navigator.
- Click your target in the project editor.
- Click on the Build Phases tab.
- Click the Add Build Phase button at the bottom and choose Add Copy Files.
- Click the disclosure triangle next to the new build phase.
- Choose Frameworks from the Destination list.
- Drag Sparkle.framework from the Project Navigator left sidebar to the list in the new Copy Files phase.

Open up your MainMenu.nib.
Choose View → Utilities → Object Library…
Type “Object” in the search field under the object library (at the bottom of the right sidebar) and drag an Object into the left sidebar of the document editor.
Select the Object that was just added.
Choose View → Utilities → Identity Inspector.
Type SUUpdater in the Class box of the Custom Class section in the inspector.
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.

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:
- (targeting 10.6 and later): Sign your updates via Apple’s Developer ID program or your own certificate. Sparkle will ensure the new version’s author matches the old version’s. You’ll need to build your own Sparkle from Github’s master branch for this to work—Sparkle 1.5b6 does not include this feature. And this feature doesn’t work with .pkg-based updates: for those, you’ll have to use the signatures described below.
- If you can’t code sign your app, you can include a DSA signature of the SHA-1 hash of your published update file.
  - First, make 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.

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.

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.

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