SPUUpdaterDelegate

Objective-C

@protocol SPUUpdaterDelegate <NSObject>

Swift

protocol SPUUpdaterDelegate : NSObjectProtocol

Provides delegation methods to control the behavior of an SPUUpdater object.

  • Returns whether to allow Sparkle to check for updates.

    For example, this may be used to prevent Sparkle from interrupting a setup assistant. Alternatively, you may want to consider starting the updater after eg: the setup assistant finishes.

    Note in Swift, this method returns Void and is marked with the throws keyword. If this method doesn’t throw an error, the updater may perform an update check. Otherwise if an error is thrown (we recommend using an NSError), then the updater may not perform an update check.

    Declaration

    Objective-C

    - (BOOL)updater:(nonnull SPUUpdater *)updater
    mayPerformUpdateCheck:(SPUUpdateCheck)updateCheck
                    error:(NSError *_Nullable *_Nullable)error;

    Swift

    optional func updater(_ updater: SPUUpdater, mayPerform updateCheck: SPUUpdateCheck) throws

    Parameters

    updater

    The updater instance.
    updateCheck

    The type of update check that will be performed if the updater is allowed to check for updates.
    error

    The populated error object if the updater may not perform a new update check. The NSLocalizedDescriptionKey user info key should be populated indicating a description of the error.

    Return Value

    YES if the updater is allowed to check for updates, otherwise NO

  • Returns the set of Sparkle channels the updater is allowed to find new updates from.

    An appcast item can specify a channel the update is posted to. Without specifying a channel, the appcast item is posted to the default channel. For instance:

    <item>
   <sparkle:version>2.0 Beta 1</sparkle:version>
   <sparkle:channel>beta</sparkle:channel>
</item>

    This example posts an update to the beta channel, so only updaters that are allowed to use the beta channel can find this update.

    If the <sparkle:channel> element is not present, the update item is posted to the default channel and can be found by any updater.

    You can pick any name you’d like for the channel. The valid characters for channel names are letters, numbers, dashes, underscores, and periods.

    Note to use this feature, all app versions that your users may update from in your feed must use a version of Sparkle that supports this feature. This feature was added in Sparkle 2.

    Declaration

    Objective-C

    - (nonnull NSSet<NSString *> *)allowedChannelsForUpdater:
    (nonnull SPUUpdater *)updater;

    Swift

    optional func allowedChannels(for updater: SPUUpdater) -> Set<String>

    Return Value

    The set of channel names the updater is allowed to find new updates in. An empty set is the default behavior, which means the updater will only look for updates in the default channel.

  • Returns a custom appcast URL used for checking for new updates.

    Override this to dynamically specify the feed URL.

    Declaration

    Objective-C

    - (nullable NSString *)feedURLStringForUpdater:(nonnull SPUUpdater *)updater;

    Swift

    optional func feedURLString(for updater: SPUUpdater) -> String?

    Parameters

    updater

    The updater instance.

    Return Value

    An appcast feed URL to check for new updates in, or nil for the default behavior and if you don’t want to be delegated this task.

  • Returns additional parameters to append to the appcast URL’s query string.

    This is potentially based on whether or not Sparkle will also be sending along the system profile.

    Declaration

    Objective-C

    - (nonnull NSArray<NSDictionary<NSString *, NSString *> *> *)
    feedParametersForUpdater:(nonnull SPUUpdater *)updater
        sendingSystemProfile:(BOOL)sendingProfile;

    Swift

    optional func feedParameters(for updater: SPUUpdater, sendingSystemProfile sendingProfile: Bool) -> [[String : String]]

    Parameters

    updater

    The updater instance.
    sendingProfile

    Whether the system profile will also be sent.

    Return Value

    An array of dictionaries with keys: key, value, displayKey, displayValue, the latter two being specifically for display to the user.

  • Returns whether Sparkle should prompt the user about checking for new updates automatically.

    Use this to override the default behavior.

    Declaration

    Objective-C

    - (BOOL)updaterShouldPromptForPermissionToCheckForUpdates:
    (nonnull SPUUpdater *)updater;

    Swift

    optional func updaterShouldPromptForPermissionToCheck(forUpdates updater: SPUUpdater) -> Bool

    Parameters

    updater

    The updater instance.

    Return Value

    YES if the updater should prompt for permission to check for new updates automatically, otherwise NO

  • Returns an allowed list of system profile keys to be appended to the appcast URL’s query string.

    By default all keys will be included. This method allows overriding which keys should only be allowed.

    Declaration

    Objective-C

    - (nullable NSArray<NSString *> *)allowedSystemProfileKeysForUpdater:
    (nonnull SPUUpdater *)updater;

    Swift

    optional func allowedSystemProfileKeys(for updater: SPUUpdater) -> [String]?

    Parameters

    updater

    The updater instance.

    Return Value

    An array of system profile keys to include in the appcast URL’s query string. Elements must be one of the SUSystemProfiler*Key constants. Return nil for the default behavior and if you don’t want to be delegated this task.

  • Called after Sparkle has downloaded the appcast from the remote server.

    Implement this if you want to do some special handling with the appcast once it finishes loading.

    Declaration

    Objective-C

    - (void)updater:(nonnull SPUUpdater *)updater
    didFinishLoadingAppcast:(nonnull SUAppcast *)appcast;

    Swift

    optional func updater(_ updater: SPUUpdater, didFinishLoading appcast: SUAppcast)

    Parameters

    updater

    The updater instance.
    appcast

    The appcast that was downloaded from the remote server.

  • Called when a new valid update is found by the update driver.

    Declaration

    Objective-C

    - (void)updater:(nonnull SPUUpdater *)updater
    didFindValidUpdate:(nonnull SUAppcastItem *)item;

    Swift

    optional func updater(_ updater: SPUUpdater, didFindValidUpdate item: SUAppcastItem)

    Parameters

    updater

    The updater instance.
    item

    The appcast item corresponding to the update that is proposed to be installed.

  • Called when a valid new update is not found.

    There are various reasons a new update is unavailable and can’t be installed.

    The userInfo dictionary on the error is populated with three keys:

    Declaration

    Objective-C

    - (void)updaterDidNotFindUpdate:(nonnull SPUUpdater *)updater
                          error:(nonnull NSError *)error;

    Swift

    optional func updaterDidNotFindUpdate(_ updater: SPUUpdater, error: Error)

    Parameters

    updater

    The updater instance.
    error

    An error containing information on why a new valid update was not found

  • Called when a valid new update is not found.

    If more information is needed on why an update was not found, use -[SPUUpdaterDelegate updaterDidNotFindUpdate:error:] instead.

    Declaration

    Objective-C

    - (void)updaterDidNotFindUpdate:(nonnull SPUUpdater *)updater;

    Swift

    optional func updaterDidNotFindUpdate(_ updater: SPUUpdater)

    Parameters

    updater

    The updater instance.

  • Returns the item in the appcast corresponding to the update that should be installed.

    Please consider using or migrating to other supported features before adopting this method. Specifically:

    • If you want to filter out certain tagged updates (like beta updates), consider -[SPUUpdaterDelegate allowedChannelsForUpdater:] instead.
    • If you want to treat certain updates as informational-only, consider supplying <sparkle:informationalUpdate> with a set of affected versions users are updating from.

    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.

    Do not base your logic by filtering out items with a minimum or maximum OS version or minimum autoupdate version because Sparkle already has logic for determining whether or not those items should be filtered out.

    Also do not return a non-top level item from the appcast such as a delta item. Delta items will be ignored. Sparkle picks the delta item from your selection if the appropriate one is available.

    This method will not be invoked with an appcast that has zero items. Pick the best item from the appcast. If an item is available that has the same version as the application or bundle to update, do not pick an item that is worse than that version.

    This method may be called multiple times for different selections and filters. This method should be efficient.

    Return +[SUAppcastItem emptyAppcastItem] if no appcast item is valid.

    Return nil if you don’t want to be delegated this task and want to let Sparkle handle picking the best valid update.

    Declaration

    Objective-C

    - (nullable SUAppcastItem *)
    bestValidUpdateInAppcast:(nonnull SUAppcast *)appcast
                  forUpdater:(nonnull SPUUpdater *)updater;

    Swift

    optional func bestValidUpdate(in appcast: SUAppcast, for updater: SPUUpdater) -> SUAppcastItem?

    Parameters

    appcast

    The appcast that was downloaded from the remote server.
    updater

    The updater instance.

    Return Value

    The best valid appcast item.

  • Returns whether or not the updater should proceed with the new chosen update from the appcast.

    By default, the updater will always proceed with the best selected update found in an appcast. Override this to override this behavior.

    If you return NO and populate the error, the user is not shown this updateItem nor is the update downloaded or installed.

    Note in Swift, this method returns Void and is marked with the throws keyword. If this method doesn’t throw an error, the updater will proceed with the update. Otherwise if an error is thrown (we recommend using an NSError), then the will not proceed with the update.

    Declaration

    Objective-C

    - (BOOL)updater:(nonnull SPUUpdater *)updater
    shouldProceedWithUpdate:(nonnull SUAppcastItem *)updateItem
                updateCheck:(SPUUpdateCheck)updateCheck
                      error:(NSError *_Nullable *_Nullable)error;

    Swift

    optional func updater(_ updater: SPUUpdater, shouldProceedWithUpdate updateItem: SUAppcastItem, updateCheck: SPUUpdateCheck) throws

    Parameters

    updater

    The updater instance.
    updateItem

    The selected update item to proceed with.
    updateCheck

    The type of update check that would be performed if proceeded.
    error

    An error object that must be populated by the delegate if the updater should not proceed with the update. The NSLocalizedDescriptionKey user info key should be populated indicating a description of the error.

    Return Value

    YES if the updater should proceed with updateItem, otherwise NO if the updater should not proceed with the update with an error populated.

  • Called when a user makes a choice to install, dismiss, or skip an update.

    If the choice is SPUUserUpdateChoiceDismiss and state.stage is SPUUserUpdateStageDownloaded the downloaded update is kept around until the next time Sparkle reminds the user of the update.

    If the choice is SPUUserUpdateChoiceDismiss and state.stage is SPUUserUpdateStageInstalling the update is still set to install on application termination.

    If the choice is SPUUserUpdateChoiceSkip the user will not be reminded in the future for this update unless they initiate an update check themselves.

    If updateItem.isInformationOnlyUpdate is YES the choice cannot be SPUUserUpdateChoiceInstall.

    Declaration

    Objective-C

    - (void)updater:(nonnull SPUUpdater *)updater
    userDidMakeChoice:(SPUUserUpdateChoice)choice
            forUpdate:(nonnull SUAppcastItem *)updateItem
                state:(nonnull SPUUserUpdateState *)state;

    Swift

    optional func updater(_ updater: SPUUpdater, userDidMake choice: SPUUserUpdateChoice, forUpdate updateItem: SUAppcastItem, state: SPUUserUpdateState)

    Parameters

    updater

    The updater instance.
    choice

    The choice (install, dismiss, or skip) the user made for this updateItem
    updateItem

    The appcast item corresponding to the update that the user made a choice on.
    state

    The current state for the update which includes if the update has already been downloaded or already installing.

  • Returns whether the release notes (if available) should be downloaded after an update is found and shown.

    This is specifically for the <releaseNotesLink> element in the appcast item.

    Declaration

    Objective-C

    - (BOOL)updater:(nonnull SPUUpdater *)updater
    shouldDownloadReleaseNotesForUpdate:(nonnull SUAppcastItem *)updateItem;

    Swift

    optional func updater(_ updater: SPUUpdater, shouldDownloadReleaseNotesForUpdate updateItem: SUAppcastItem) -> Bool

    Parameters

    updater

    The updater instance.
    updateItem

    The update item to download and show release notes from.

    Return Value

    YES to download and show the release notes if available, otherwise NO. The default behavior is YES.

  • Called immediately before downloading the specified update.

    Declaration

    Objective-C

    - (void)updater:(nonnull SPUUpdater *)updater
    willDownloadUpdate:(nonnull SUAppcastItem *)item
           withRequest:(nonnull NSMutableURLRequest *)request;

    Swift

    optional func updater(_ updater: SPUUpdater, willDownloadUpdate item: SUAppcastItem, with request: NSMutableURLRequest)

    Parameters

    updater

    The updater instance.
    item

    The appcast item corresponding to the update that is proposed to be downloaded.
    request

    The mutable URL request that will be used to download the update.

  • Called immediately after successful download of the specified update.

    Declaration

    Objective-C

    - (void)updater:(nonnull SPUUpdater *)updater
    didDownloadUpdate:(nonnull SUAppcastItem *)item;

    Swift

    optional func updater(_ updater: SPUUpdater, didDownloadUpdate item: SUAppcastItem)

    Parameters

    updater

    The SUUpdater instance.
    item

    The appcast item corresponding to the update that has been downloaded.

  • Called after the specified update failed to download.

    Declaration

    Objective-C

    - (void)updater:(nonnull SPUUpdater *)updater
    failedToDownloadUpdate:(nonnull SUAppcastItem *)item
                     error:(nonnull NSError *)error;

    Swift

    optional func updater(_ updater: SPUUpdater, failedToDownloadUpdate item: SUAppcastItem, error: Error)

    Parameters

    updater

    The updater instance.
    item

    The appcast item corresponding to the update that failed to download.
    error

    The error generated by the failed download.

  • Called when the user cancels an update while it is being downloaded.

    Declaration

    Objective-C

    - (void)userDidCancelDownload:(nonnull SPUUpdater *)updater;

    Swift

    optional func userDidCancelDownload(_ updater: SPUUpdater)

    Parameters

    updater

    The updater instance.

  • Called immediately before extracting the specified downloaded update.

    Declaration

    Objective-C

    - (void)updater:(nonnull SPUUpdater *)updater
    willExtractUpdate:(nonnull SUAppcastItem *)item;

    Swift

    optional func updater(_ updater: SPUUpdater, willExtractUpdate item: SUAppcastItem)

    Parameters

    updater

    The SUUpdater instance.
    item

    The appcast item corresponding to the update that is proposed to be extracted.

  • Called immediately after extracting the specified downloaded update.

    Declaration

    Objective-C

    - (void)updater:(nonnull SPUUpdater *)updater
    didExtractUpdate:(nonnull SUAppcastItem *)item;

    Swift

    optional func updater(_ updater: SPUUpdater, didExtractUpdate item: SUAppcastItem)

    Parameters

    updater

    The SUUpdater instance.
    item

    The appcast item corresponding to the update that has been extracted.

  • Called immediately before installing the specified update.

    Declaration

    Objective-C

    - (void)updater:(nonnull SPUUpdater *)updater
    willInstallUpdate:(nonnull SUAppcastItem *)item;

    Swift

    optional func updater(_ updater: SPUUpdater, willInstallUpdate item: SUAppcastItem)

    Parameters

    updater

    The updater instance.
    item

    The appcast item corresponding to the update that is proposed to be installed.

  • Returns whether the relaunch should be delayed in order to perform other tasks.

    This is not called if the user didn’t relaunch on the previous update, in that case it will immediately restart.

    This may also not be called if the application is not going to relaunch after it terminates.

    Declaration

    Objective-C

    - (BOOL)updater:(nonnull SPUUpdater *)updater
    shouldPostponeRelaunchForUpdate:(nonnull SUAppcastItem *)item
                 untilInvokingBlock:(nonnull void (^)(void))installHandler;

    Swift

    optional func updater(_ updater: SPUUpdater, shouldPostponeRelaunchForUpdate item: SUAppcastItem, untilInvokingBlock installHandler: @escaping () -> Void) -> Bool

    Parameters

    updater

    The updater instance.
    item

    The appcast item corresponding to the update that is proposed to be installed.
    installHandler

    The install handler that must be completed before continuing with the relaunch.

    Return Value

    YES to delay the relaunch until installHandler is invoked.

  • Returns whether the application should be relaunched at all.

    Some apps cannot be relaunched under certain circumstances. This method can be used to explicitly prevent a relaunch.

    Declaration

    Objective-C

    - (BOOL)updaterShouldRelaunchApplication:(nonnull SPUUpdater *)updater;

    Swift

    optional func updaterShouldRelaunchApplication(_ updater: SPUUpdater) -> Bool

    Parameters

    updater

    The updater instance.

    Return Value

    YES if the updater should be relaunched, otherwise NO if it shouldn’t.

  • Called immediately before relaunching.

    Declaration

    Objective-C

    - (void)updaterWillRelaunchApplication:(nonnull SPUUpdater *)updater;

    Swift

    optional func updaterWillRelaunchApplication(_ updater: SPUUpdater)

    Parameters

    updater

    The updater instance.

  • Returns an object that compares version numbers to determine their arithmetic relation to each other.

    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.

    Note that the standard version comparator may be used during installation for preventing a downgrade, even if you provide a custom comparator here.

    Declaration

    Objective-C

    - (nullable id<SUVersionComparison>)versionComparatorForUpdater:
    (nonnull SPUUpdater *)updater;

    Swift

    optional func versionComparator(for updater: SPUUpdater) -> SUVersionComparison?

    Parameters

    updater

    The updater instance.

    Return Value

    The custom version comparator or nil if you don’t want to be delegated this task.

  • Called when a background update will be scheduled after a delay.

    Automatic update checks need to be enabled for this to trigger.

    Declaration

    Objective-C

    - (void)updater:(nonnull SPUUpdater *)updater
    willScheduleUpdateCheckAfterDelay:(NSTimeInterval)delay;

    Swift

    optional func updater(_ updater: SPUUpdater, willScheduleUpdateCheckAfterDelay delay: TimeInterval)

    Parameters

    delay

    The delay in seconds until the next scheduled update will occur. This is an approximation and may vary due to system state.
    updater

    The updater instance.

  • Called when no update checks will be scheduled in the future.

    This may later change if automatic update checks become enabled.

    Declaration

    Objective-C

    - (void)updaterWillNotScheduleUpdateCheck:(nonnull SPUUpdater *)updater;

    Swift

    optional func updaterWillNotScheduleUpdateCheck(_ updater: SPUUpdater)

    Parameters

    updater

    The updater instance.

  • Returns the decryption password (if any) which is used to extract the update archive DMG.

    Return nil if no password should be used.

    Declaration

    Objective-C

    - (nullable NSString *)decryptionPasswordForUpdater:
    (nonnull SPUUpdater *)updater;

    Swift

    optional func decryptionPassword(for updater: SPUUpdater) -> String?

    Parameters

    updater

    The updater instance.

    Return Value

    The password used for decrypting the archive, or nil if no password should be used.

  • Called when an update is scheduled to be silently installed on quit after downloading the update automatically.

    If the updater is given responsibility, it can later remind the user an update is available if they have not terminated the application for a long time.

    Also if the updater is given responsibility and the update item is marked critical, the new update will be presented to the user immediately after.

    Even if the immediateInstallHandler is not invoked, the installer will attempt to install the update on termination.

    Declaration

    Objective-C

    - (BOOL)updater:(nonnull SPUUpdater *)updater
       willInstallUpdateOnQuit:(nonnull SUAppcastItem *)item
    immediateInstallationBlock:(nonnull void (^)(void))immediateInstallHandler;

    Swift

    optional func updater(_ updater: SPUUpdater, willInstallUpdateOnQuit item: SUAppcastItem, immediateInstallationBlock immediateInstallHandler: @escaping () -> Void) -> Bool

    Parameters

    updater

    The updater instance.
    item

    The appcast item corresponding to the update that is proposed to be installed.
    immediateInstallHandler

    The install handler for the delegate to immediately install the update. No UI interaction will be shown and the application will be relaunched after installation. This handler can only be used if YES is returned and the delegate handles installing the update. For Sparkle 2.3 onwards, this handler can be invoked multiple times in case the application cancels the termination request.

    Return Value

    YES if the delegate will handle installing the update or NO if the updater should be given responsibility.

  • Called after the update driver aborts due to an error.

    The update driver runs when checking for updates. This delegate method is called an error occurs during this process.

    Some special possible values of error.code are:

    • SUNoUpdateError: No new update was found.

    • SUInstallationCanceledError: The user canceled installing the update when requested for authorization.

    Declaration

    Objective-C

    - (void)updater:(nonnull SPUUpdater *)updater
    didAbortWithError:(nonnull NSError *)error;

    Swift

    optional func updater(_ updater: SPUUpdater, didAbortWithError error: Error)

    Parameters

    updater

    The updater instance.
    error

    The error that caused the update driver to abort.

  • Called after the update driver finishes.

    The update driver runs when checking for updates. This delegate method is called when that check is finished.

    An update may be scheduled to be installed during the update cycle, or no updates may be found, or an available update may be dismissed or skipped (which is the same as no error).

    If the error is nil, no error has occurred.

    Some special possible values of error.code are:

    • SUNoUpdateError: No new update was found.

    • SUInstallationCanceledError: The user canceled installing the update when requested for authorization.

    Declaration

    Objective-C

    - (void)updater:(nonnull SPUUpdater *)updater
    didFinishUpdateCycleForUpdateCheck:(SPUUpdateCheck)updateCheck
                                 error:(nullable NSError *)error;

    Swift

    optional func updater(_ updater: SPUUpdater, didFinishUpdateCycleFor updateCheck: SPUUpdateCheck, error: Error?)

    Parameters

    updater

    The updater instance.
    updateCheck

    The type of update check was performed.
    error

    The error that caused the update driver to abort. This is nil if the update driver finished normally and there is no error.

  • Deprecated

    Please use -[SPUUpdaterDelegate updater:mayPerformUpdateCheck:error:] instead.

    Undocumented

    Declaration

    Objective-C

    - (BOOL)updaterMayCheckForUpdates:(SPUUpdater *)updater __deprecated_msg("Please use -[SPUUpdaterDelegate updater:mayPerformUpdateCheck:error:] instead.");

    Swift

    optional func updaterMayCheck(forUpdates updater: SPUUpdater) -> Bool

  • Deprecated

    Please use -[SPUUpdaterDelegate updater:userDidMakeChoice:forUpdate:state:] instead.

    Undocumented

    Declaration

    Objective-C

    - (void)updater:(SPUUpdater *)updater userDidSkipThisVersion:(SUAppcastItem *)item __deprecated_msg("Please use -[SPUUpdaterDelegate updater:userDidMakeChoice:forUpdate:state:] instead.");

    Swift

    optional func updater(_ updater: SPUUpdater, userDidSkipThisVersion item: SUAppcastItem)