SPUUserDriver

Objective-C

@protocol SPUUserDriver <NSObject>

Swift

protocol SPUUserDriver : NSObjectProtocol

The API in Sparkle for controlling the user interaction.

This protocol is used for implementing a user interface for the Sparkle updater. Sparkle’s internal drivers tell an object that implements this protocol what actions to take and show to the user.

Every method in this protocol can be assumed to be called from the main thread.

  • Show an updater permission request to the user

    Ask the user for their permission regarding update checks. This is typically only called once per app installation.

    Declaration

    Objective-C

    - (void)
        showUpdatePermissionRequest:(nonnull SPUUpdatePermissionRequest *)request
                              reply:(nonnull void (^)(
                                        SUUpdatePermissionResponse *_Nonnull))reply;

    Swift

    func show(_ request: SPUUpdatePermissionRequest) async -> SUUpdatePermissionResponse

    Parameters

    request

    The update permission request.

    reply

    A reply with a update permission response.

  • Show the user initiating an update check

    Respond to the user initiating an update check. Sparkle uses this to show the user a window with an indeterminate progress bar.

    Declaration

    Objective-C

    - (void)showUserInitiatedUpdateCheckWithCancellation:
        (nonnull void (^)(void))cancellation;

    Swift

    func showUserInitiatedUpdateCheck(cancellation: @escaping () -> Void)

    Parameters

    cancellation

    Invoke this cancellation block to cancel the update check before the update check is completed.

  • Show the user a new update is found.

    Let the user know a new update is found and ask them what they want to do. Before this point, -showUserInitiatedUpdateCheckWithCancellation: may be called.

    The potential stages on the updater state are:

    SPUUpdateStateNotDownloaded - Update has not been downloaded yet.

    SPUUpdateStateDownloaded - Update has already been downloaded in the background automatically (via SUAutomaticallyUpdate) but not started installing yet.

    SPUUpdateStateInstalling - Update has been downloaded and already started installing.

    The userInitiated property on the state indicates if the update was initiated by the user or if it was automatically scheduled in the background.

    Additionally, these properties on the appcastItem are of importance:

    appcastItem.informationOnlyUpdate indicates if the update is only informational and should not be downloaded. You can direct the user to the infoURL property of the appcastItem in their web browser. Sometimes information only updates are used as a fallback in case a bad update is shipped, so you’ll want to support this case.

    appcastItem.majorUpgrade indicates if the update is a major or paid upgrade.

    appcastItem.criticalUpdate indicates if the update is a critical update.

    A reply of SPUUserUpdateChoiceInstall begins or resumes downloading, extracting, or installing the update. If the state.stage is SPUUserUpdateStateInstalling, this may send a quit event to the application and relaunch it immediately (in this state, this behaves as a fast “install and Relaunch”). If the state.stage is SPUUpdateStateNotDownloaded or SPUUpdateStateDownloaded the user may be presented an authorization prompt to install the update after -showDownloadDidStartExtractingUpdate is called if authorization is required for installation. For example, this may occur if the update on disk is owned by a different user (e.g. root or admin for non-admin users), or if the update is a package install. Do not use a reply of SPUUserUpdateChoiceInstall if appcastItem.informationOnlyUpdate is YES.

    A reply of SPUUserUpdateChoiceDismiss dismisses the update for the time being. The user may be reminded of the update at a later point. If the state.stage is SPUUserUpdateStateDownloaded, the downloaded update is kept after dismissing until the next time an update is shown to the user. If the state.stage is SPUUserUpdateStateInstalling, the installing update is also preserved after dismissing. In this state however, the update will also still be installed after the application is terminated.

    A reply of SPUUserUpdateChoiceSkip skips this particular version and won’t notify the user again, unless they initiate an update check themselves. If appcastItem.majorUpgrade is YES, the major update and any future minor updates to that major release are skipped, unless a future minor update specifies a <sparkle:ignoreSkippedUpgradesBelowVersion> requirement. If the state.stage is SPUUpdateStateInstalling, the installation is also canceled when the update is skipped.

    Declaration

    Objective-C

    - (void)showUpdateFoundWithAppcastItem:(nonnull SUAppcastItem *)appcastItem
                                     state:(nonnull SPUUserUpdateState *)state
                                     reply:(nonnull void (^)(SPUUserUpdateChoice))
                                               reply;

    Swift

    func showUpdateFound(with appcastItem: SUAppcastItem, state: SPUUserUpdateState) async -> SPUUserUpdateChoice

    Parameters

    appcastItem

    The Appcast Item containing information that reflects the new update.

    state

    The current state of the user update. See above discussion for notable properties.

    reply

    The reply which indicates if the update should be installed, dismissed, or skipped. See above discussion for more details.

  • Show the user the release notes for the new update

    Display the release notes to the user. This will be called after showing the new update. This is only applicable if the release notes are linked from the appcast, and are not directly embedded inside of the appcast file. That is, this may be invoked if the releaseNotesURL from the appcast item is non-nil.

    Declaration

    Objective-C

    - (void)showUpdateReleaseNotesWithDownloadData:
        (nonnull SPUDownloadData *)downloadData;

    Swift

    func showUpdateReleaseNotes(with downloadData: SPUDownloadData)

    Parameters

    downloadData

    The data for the release notes that was downloaded from the new update’s appcast.

  • Show the user that the new update’s release notes could not be downloaded

    This will be called after showing the new update. This is only applicable if the release notes are linked from the appcast, and are not directly embedded inside of the appcast file. That is, this may be invoked if the releaseNotesURL from the appcast item is non-nil.

    Declaration

    Objective-C

    - (void)showUpdateReleaseNotesFailedToDownloadWithError:
        (nonnull NSError *)error;

    Swift

    func showUpdateReleaseNotesFailedToDownloadWithError(_ error: Error)

    Parameters

    error

    The error associated with why the new update’s release notes could not be downloaded.

  • Show the user a new update was not found

    Let the user know a new update was not found after they tried initiating an update check. Before this point, -showUserInitiatedUpdateCheckWithCancellation: may be called.

    There are various reasons a new update is unavailable and can’t be installed. The error object is populated with recovery and suggestion strings suitable to be shown in an alert.

    The userInfo dictionary on the error is also populated with two keys:

    SPULatestAppcastItemFoundKey: if available, this may provide the latest SUAppcastItem that was found.

    SPUNoUpdateFoundReasonKey: if available, this will provide the SUNoUpdateFoundReason. For example the reason could be because the latest version in the feed requires a newer OS version or could be because the user is already on the latest version.

    Declaration

    Objective-C

    - (void)showUpdateNotFoundWithError:(nonnull NSError *)error
                        acknowledgement:(nonnull void (^)(void))acknowledgement;

    Swift

    func showUpdateNotFoundWithError(_ error: Error, acknowledgement: @escaping () -> Void)

    Parameters

    error

    The error associated with why a new update was not found. See above discussion for more details.

    acknowledgement

    Acknowledge to the updater that no update found error was shown.

  • Show the user an update error occurred

    Let the user know that the updater failed with an error. This will not be invoked without the user having been aware that an update was in progress.

    Before this point, any of the non-error user driver methods may have been invoked.

    Declaration

    Objective-C

    - (void)showUpdaterError:(nonnull NSError *)error
             acknowledgement:(nonnull void (^)(void))acknowledgement;

    Swift

    func showUpdaterError(_ error: Error, acknowledgement: @escaping () -> Void)

    Parameters

    error

    The error associated with what update error occurred.

    acknowledgement

    Acknowledge to the updater that the error was shown.

  • Show the user that downloading the new update initiated

    Let the user know that downloading the new update started.

    Declaration

    Objective-C

    - (void)showDownloadInitiatedWithCancellation:
        (nonnull void (^)(void))cancellation;

    Swift

    func showDownloadInitiated(cancellation: @escaping () -> Void)

    Parameters

    cancellation

    Invoke this cancellation block to cancel the download at any point before -showDownloadDidStartExtractingUpdate is invoked.

  • Show the user the content length of the new update that will be downloaded

    Declaration

    Objective-C

    - (void)showDownloadDidReceiveExpectedContentLength:
        (uint64_t)expectedContentLength;

    Swift

    func showDownloadDidReceiveExpectedContentLength(_ expectedContentLength: UInt64)

    Parameters

    expectedContentLength

    The expected content length of the new update being downloaded. An implementor should be able to handle if this value is invalid (more or less than actual content length downloaded). Additionally, this method may be called more than once for the same download in rare scenarios.

  • Show the user that the update download received more data

    This may be an appropriate time to advance a visible progress indicator of the download

    Declaration

    Objective-C

    - (void)showDownloadDidReceiveDataOfLength:(uint64_t)length;

    Swift

    func showDownloadDidReceiveData(ofLength length: UInt64)

    Parameters

    length

    The length of the data that was just downloaded

  • Show the user that the update finished downloading and started extracting

    Sparkle uses this to show an indeterminate progress bar.

    Before this point, showDownloadDidReceiveDataOfLength: or showUpdateFoundWithAppcastItem:state:reply: may be called. An update can potentially resume at this point after having been automatically downloaded in the background (without the user driver) before.

    After extraction starts, the user may be shown an authorization prompt to install the update if authorization is required for installation. For example, this may occur if the update on disk is owned by a different user (e.g. root or admin for non-admin users), or if the update is a package install.

    Declaration

    Objective-C

    - (void)showDownloadDidStartExtractingUpdate;

    Swift

    func showDownloadDidStartExtractingUpdate()
  • Show the user that the update is extracting with progress

    Let the user know how far along the update extraction is.

    Before this point, -showDownloadDidStartExtractingUpdate is called.

    Declaration

    Objective-C

    - (void)showExtractionReceivedProgress:(double)progress;

    Swift

    func showExtractionReceivedProgress(_ progress: Double)

    Parameters

    progress

    The progress of the extraction from a 0.0 to 1.0 scale

  • Show the user that the update is ready to install & relaunch

    Let the user know that the update is ready to install and relaunch, and ask them whether they want to proceed. Note if the target application has already terminated, this method may not be invoked.

    A reply of SPUUserUpdateChoiceInstall installs the update the new update immediately. The application is relaunched only if it is still running by the time this reply is invoked. If the application terminates on its own, Sparkle will attempt to automatically install the update.

    A reply of SPUUserUpdateChoiceDismiss dismisses the update installation for the time being. Note the update may still be installed automatically after the application terminates.

    A reply of SPUUserUpdateChoiceSkip cancels the current update that has begun installing and dismisses the update. In this circumstance, the update is canceled but this update version is not skipped in the future.

    Before this point, -showExtractionReceivedProgress: or -showUpdateFoundWithAppcastItem:state:reply: may be called.

    Declaration

    Objective-C

    - (void)showReadyToInstallAndRelaunch:
        (nonnull void (^)(SPUUserUpdateChoice))reply;

    Swift

    func showReadyToInstallAndRelaunch() async -> SPUUserUpdateChoice

    Parameters

    reply

    The reply which indicates if the update should be installed, dismissed, or skipped. See above discussion for more details.

  • Show the user that the update is installing

    Let the user know that the update is currently installing.

    Before this point, -showReadyToInstallAndRelaunch: or -showUpdateFoundWithAppcastItem:state:reply: will be called.

    Declaration

    Objective-C

    - (void)
        showInstallingUpdateWithApplicationTerminated:(BOOL)applicationTerminated
                          retryTerminatingApplication:
                              (nonnull void (^)(void))retryTerminatingApplication;

    Swift

    func showInstallingUpdate(withApplicationTerminated applicationTerminated: Bool, retryTerminatingApplication: @escaping () -> Void)

    Parameters

    applicationTerminated

    Indicates if the application has been terminated already. If the application hasn’t been terminated, a quit event is sent to the running application before installing the update. If the application or user delays or cancels termination, there may be an indefinite period of time before the application fully quits. It is up to the implementor whether or not to decide to continue showing installation progress in this case.

    retryTerminatingApplication

    This handler gives a chance for the application to re-try sending a quit event to the running application before installing the update. The application may cancel or delay termination. This handler gives the user driver another chance to allow the user to try terminating the application again. If the application does not delay or cancel application termination, there is no need to invoke this handler. This handler may be invoked multiple times. Note this handler should not be invoked if applicationTerminated is already YES

  • Show the user that the update installation finished

    Let the user know that the update finished installing.

    This will only be invoked if the updater process is still alive, which is typically not the case if the updater’s lifetime is tied to the application it is updating. This implementation must not try to reference the old bundle prior to the installation, which will no longer be around.

    Before this point, -showInstallingUpdateWithApplicationTerminated:retryTerminatingApplication: will be called.

    Declaration

    Objective-C

    - (void)showUpdateInstalledAndRelaunched:(BOOL)relaunched
                             acknowledgement:
                                 (nonnull void (^)(void))acknowledgement;

    Swift

    func showUpdateInstalledAndRelaunched(_ relaunched: Bool, acknowledgement: @escaping () -> Void)

    Parameters

    relaunched

    Indicates if the update was relaunched.

    acknowledgement

    Acknowledge to the updater that the finished installation was shown.

  • Show the user the current presented update or its progress in utmost focus

    The user wishes to check for updates while the user is being shown update progress. Bring whatever is on screen to frontmost focus (permission request, update information, downloading or extraction status, choice to install update, etc).

    Declaration

    Objective-C

    - (void)showUpdateInFocus;

    Swift

    func showUpdateInFocus()
  • Dismiss the current update installation

    Stop and tear down everything. Dismiss all update windows, alerts, progress, etc from the user. Basically, stop everything that could have been started. Sparkle may invoke this when aborting or finishing an update.

    Declaration

    Objective-C

    - (void)dismissUpdateInstallation;

    Swift

    func dismissUpdateInstallation()
  • Deprecated

    Implement -showUpdateNotFoundWithError:acknowledgement: instead

    Undocumented

    Declaration

    Objective-C

    - (void)showUpdateNotFoundWithAcknowledgement:(void (^)(void))acknowledgement __deprecated_msg("Implement -showUpdateNotFoundWithError:acknowledgement: instead");

    Swift

    optional func showUpdateNotFound(acknowledgement: @escaping () -> Void)
  • Deprecated

    Implement -showUpdateInstalledAndRelaunched:acknowledgement: instead

    Undocumented

    Declaration

    Objective-C

    - (void)showUpdateInstallationDidFinishWithAcknowledgement:(void (^)(void))acknowledgement __deprecated_msg("Implement -showUpdateInstalledAndRelaunched:acknowledgement: instead");

    Swift

    optional func showUpdateInstallationDidFinish(acknowledgement: @escaping () -> Void)
  • Deprecated

    Transition to new UI appropriately when a new update is shown, when no update is found, or when an update error occurs.

    Undocumented

    Declaration

    Objective-C

    - (void)dismissUserInitiatedUpdateCheck __deprecated_msg("Transition to new UI appropriately when a new update is shown, when no update is found, or when an update error occurs.");

    Swift

    optional func dismissUserInitiatedUpdateCheck()
  • Deprecated

    Implement -showInstallingUpdateWithApplicationTerminated:retryTerminatingApplication: instead.

    Undocumented

    Declaration

    Objective-C

    - (void)showInstallingUpdate __deprecated_msg("Implement -showInstallingUpdateWithApplicationTerminated:retryTerminatingApplication: instead.");

    Swift

    optional func showInstallingUpdate()
  • Deprecated

    Implement -showInstallingUpdateWithApplicationTerminated:retryTerminatingApplication: instead.

    Undocumented

    Declaration

    Objective-C

    - (void)showSendingTerminationSignal __deprecated_msg("Implement -showInstallingUpdateWithApplicationTerminated:retryTerminatingApplication: instead.");

    Swift

    optional func showSendingTerminationSignal()
  • Deprecated

    Implement -showInstallingUpdateWithApplicationTerminated:retryTerminatingApplication: instead.

    Undocumented

    Declaration

    Objective-C

    - (void)showInstallingUpdateWithApplicationTerminated:(BOOL)applicationTerminated __deprecated_msg("Implement -showInstallingUpdateWithApplicationTerminated:retryTerminatingApplication: instead.");

    Swift

    optional func showInstallingUpdate(withApplicationTerminated applicationTerminated: Bool)