Using Sparkle: Integration

Now that you've got Sparkle installed, you've got to make it look just right with your application. This page details a few ways you can make things as smooth as possible.

Adding a checkbox for the check on startup preference

It’s not really fair to ask the user for a preference once and then to never let him change it. You should add a check box for checking on startup to your preferences panel. It couldn’t be easier: just add a check box to a window in Interface Builder and bind its value to the SUCheckAtStartup shared user defaults key. If you'd like a "Revert to Defaults" button in your preferences, you should set the initial value for this key with NSUserDefaults' setInitialValues method.

Checking for updates programmatically

If you’d like to add a button to check for updates to some part of your interface, all you need to do is call checkForUpdates: on your SUUpdater. If the check is automated or programmatic, use checkForUpdatesInBackground; it won’t report errors like “can’t connect to server” or “no update available.”

Programmatically determining if updates are available

If you need to programmatically check to see if an update is available (but without actually offering to perform the update), Sparkle provides a special class. SUStatusChecker is an SUUpdater subclass with a nice factory class method: + statusCheckerForDelegate:. Just call that with your relevant controller object as delegate, then call checkForUpdatesInBackground on it. Once SUStatusChecker gets an answer from the server, it will call this method on your delegate:

- (void)statusChecker:(SUStatusChecker *)statusChecker
         foundVersion:(NSString *)versionString
         isNewVersion:(BOOL)isNewVersion 

isNewVersion will be set to YES or NO depending on whether a new version was found. If one was, versionString will be set to the human-readable version string of the new version. Here's some sample code:

- (void)startCheck 
{ 
    [[[SUStatusChecker statusCheckerForDelegate:self] retain] checkForUpdatesInBackground]; 
} 

- (void)statusChecker:(SUStatusChecker *)statusChecker
         foundVersion:(NSString *)versionString
         isNewVersion:(BOOL)isNewVersion 
{ 
    if (!versionString) 
    { 
        NSLog(@”Couldn’t get new version information!”); 
        return; 
    } 
    NSLog(@”Newest version: %@”, versionString); 
    NSLog(@”Is newest? %@”, isNewVersion ? @”Yes” : @”No”); 
} 

Dealing with CFBundleShortVersionString

If you use an internal build number for your app with CFBundleVersion but set a display string for the version with CFBundleShortVersionString, you need to tell Sparkle about both in the appcast so it can display a pretty version string to the user. To specify a short version string for an update, you can use the sparkle:shortVersionString attribute on the <enclosure> tag. For example:

<enclosure sparkle:shortVersionString="3.0 beta 2"
    url="http://you.org/something_748.zip"
    length="12345"
    type="application/octet-stream"/>

The internal version here (corresponding to CFBundleVersion) is 748. The short version string (corresponding to CFBundleShortVersionString) is "3.0 beta 2".

Dealing with registration dialogs and other startup windows

If your application displays other introductory or “welcome”-ish windows when you start it up for the first time, it would be jarring and would create a poor first impression to have Sparkle’s check-on-startup dialog jump up, too.

In this case, you can take over the duty of presenting this option to the user by setting the SUCheckAtStartup key to <false/> (or No in Property List Editor) in Info.plist. Then add a checkbox to the last pane of your registration wizard or whatever that’s bound to this key in the user defaults.

Performing actions before relaunch

If you normally do some big, time-consuming action before quitting or need to clean something up before the app shuts down, Sparkle can help. It sends out a SUUpdaterWillRestartNotification before restarting; just observe this and perform the necessary actions. You’ll need to #import <Sparkle/Sparkle.h> to get access to this constant.