• View
• Edit
• History
• Print

Customization

There are three main routes by which you can bend Sparkle's behavior to your will:

1. Info.plist Settings

2. Calls to SUUpdater

The SUUpdater object is the main controller for the updating system in your app. There is a singleton instance of this class for each bundle being updated. If you're trying to update the running .app, you can retrieve the appropriate SUUpdater by calling [SUUpdater sharedUpdater]. If you're trying to update some other bundle, you can use [SUUpdater updaterForBundle:(NSBundle *)myBundle].

Once you have the SUUpdater instance, there are a few interesting accessors you could use:

- (void)setAutomaticallyChecksForUpdates:(BOOL)automaticallyChecks;
- (BOOL)automaticallyChecksForUpdates;

- (void)setUpdateCheckInterval:(NSTimeInterval)interval;
- (NSTimeInterval)updateCheckInterval;

- (void)setFeedURL:(NSURL *)feedURL;
- (NSURL *)feedURL;

- (void)setSendsSystemProfile:(BOOL)sendsSystemProfile;
- (BOOL)sendsSystemProfile;

- (void)setAutomaticallyDownloadsUpdates:(BOOL)automaticallyDownloadsUpdates;
- (BOOL)automaticallyDownloadsUpdates;

If you want to make sure these settings are changed before the first automatic update check, you should do this in the NSApplication delegate method -applicationWillFinishLaunching:. For a non-app bundle you should then make the changes immediately after you first create the SUUpdater instance in your code.

A few more methods of interest:

// This IBAction is meant for a main menu item. Hook up any menu item to this action,
// and Sparkle will check for updates and report back its findings through UI.
- (IBAction)checkForUpdates:sender;

// This kicks off an update meant to be programmatically initiated. That is,
// it will display no UI unless it actually finds an update, in which case it
// proceeds as usual. If the automated downloading is turned on, however,
// this will invoke that behavior, and if an update is found, it will be
// downloaded and prepped for installation.
- (void)checkForUpdatesInBackground;

// This begins a "probing" check for updates which will not actually offer to
// update to that version. The delegate methods, though, (up to updater:didFindValidUpdate:
// and updaterDidNotFindUpdate:), are called, so you can use that information in your UI.
// Essentially, you can use this to UI-lessly determine if there's an update.
- (void)checkForUpdateInformation;

// Date of last update check. Returns null if no check has been performed.
- (NSDate *)lastUpdateCheckDate;

// Call this to appropriately schedule or cancel the update checking timer according
// to the preferences for time interval and automatic checks. If this SUUpdater instance
// was not present during the application's launch, you must call this method to start
// the update cycle explicitly.
- (void)resetUpdateCycle;

- (BOOL)updateInProgress;

- (void)setDelegate:(id)delegate; // See below for more information on the delegate.
- delegate;

3. SUUpdater delegate methods

You can control the SUUpdater's behavior a little more closely by providing it with a delegate. Here are the delegate methods you might implement:

// Use this to override the default behavior for Sparkle prompting the
// user about automatic update checks. You could use this to make Sparkle
// prompt for permission on the first launch instead of the second.
- (BOOL)updaterShouldPromptForPermissionToCheckForUpdates:(SUUpdater *)bundle;

- (void)updater:(SUUpdater *)updater didFinishLoadingAppcast:(SUAppcast *)appcast;

// If you're using special logic or extensions in your appcast, implement
// this to use your own logic for finding a valid update, if any, in the given appcast.
- (SUAppcastItem *)bestValidUpdateInAppcast:(SUAppcast *)appcast
                   forUpdater:(SUUpdater *)bundle;

- (void)updater:(SUUpdater *)updater didFindValidUpdate:(SUAppcastItem *)update;
- (void)updaterDidNotFindUpdate:(SUUpdater *)update;

// Sent immediately before installing the specified update.
- (void)updater:(SUUpdater *)updater willInstallUpdate:(SUAppcastItem *)update;

// Return YES to delay the relaunch until you do some processing.
// Invoke the provided NSInvocation to continue the relaunch.
- (BOOL)updater:(SUUpdater *)updater
        shouldPostponeRelaunchForUpdate:(SUAppcastItem *)update
        untilInvoking:(NSInvocation *)invocation;

// Called immediately before relaunching.
- (void)updaterWillRelaunchApplication:(SUUpdater *)updater;

// This method allows you to provide a custom version comparator.
// If you don't implement this method or return nil, the standard version
// comparator will be used. See SUVersionComparisonProtocol.h for more.
- (id <SUVersionComparison>)versionComparatorForUpdater:(SUUpdater *)updater;

// Returns the path which is used to relaunch the client after the update
// is installed. By default, the path of the host bundle.
- (NSString *)pathToRelaunchForUpdater:(SUUpdater *)updater;

// This method allows you to add extra parameters to the appcast URL,
// potentially based on whether or not Sparkle will also be sending along
// the system profile. This method should return an array of dictionaries
// with keys: "key", "value", "displayKey", "displayValue", the latter two
// being human-readable variants of the former two.
- (NSArray *)feedParametersForUpdater:(SUUpdater *)updater
             sendingSystemProfile:(BOOL)sendingProfile;

Other options

If these methods aren't enough to do what you need, you're going to have to dig into Sparkle's code. You might start by creating a different update driver: check out SUBasicUpdateDriver.h to get an idea.