Sparkle’s standard user interface handles many standard behaviors for you. However, some applications may want their own tailored user interface. Before switching to a custom UI for your updater, you should consider if your application will provide the updating functionality users want. For example, users appreciate viewing release notes when being shown a new update is available. Some users may also prefer to reduce update notifications/badges/alerts/custom UI indicators altogether by automatically downloading and installing updates in the future. You may also want to check gentle update reminders for changing how Sparkle’s standard update alert can be presented.
SPUUserDriver is a protocol that drives the user interface of SPUUpdater.
To create your own user interface, you can create your own class which conforms to SPUUserDriver. Please read the API documentation for all the methods you implement. Then you can instantiate a SPUUpdater with your user driver instead of creating the typical SPUStandardUpdaterController.
Reference classes in Sparkle’s repository that implement SPUUserDriver are:
Futher sections below highlight scenarios you will need to consider when implementing a custom UI.
By default, Sparkle asks users for their permission to check for new updates automatically on your application’s second launch (along with options like if updates should also be downloaded and installed automatically). To add support for this permission request, a user driver needs to implement -[SPUUserDriver showUpdatePermissionRequest:reply:].
To test this permision request, you can reset the response by running:
# Automatic checks for updates
defaults delete my-app-bundle-id SUEnableAutomaticChecks
# Automatic downloading/installing of updates
defaults delete my-app-bundle-id SUAutomaticallyUpdate
# Sending anonymous system profile information
defaults delete my-app-bundle-id SUSendProfileInfo
Applications that don’t want to ask the user permission for update checking may opt-out by specifying SUEnableAutomaticChecks in Info.plist. In this case, this user driver method will not be called.
Custom user interfaces need to handle updates that require user authorization to install them. Before installing an update, users on some systems may be requested for an administrator username/password to authorize the installation. While user authorization is always required for package updates, authorization can also be required for regular updates on certain systems (e.g. updating a bundle in /Applications on standard user accounts or managed systems). To test authorized installs, you can change the ownership of a bundle to root before checking for updates:
sudo chown root path-to-app-bundle
This implies your user interface needs to let the user be in control of installing an update once an update is found so they do not receive an unexpected authorization prompt. If you want as much as the downloading and installing of an update to be done in the background before a user’s input or presenting an update is needed, you can opt into automatic updates via SUAutomaticallyUpdate.
When a new update is found the updater can be in one of several different stages. The most regular stage is when an update has not been downloaded yet. The second most typical stage is when the update has already begun installing in the background (due to automatic updates via SUAutomaticallyUpdate); in this case, the application may be immediately relaunched if the user chooses to install the update, or just installed on quit without any additional input. Another stage is when the update has been automatically downloaded but not begun installing yet, which is typically for automatic updates when the updater needs to request for user authorization.
Lastly, custom user interfaces should be able to handle informational only updates as a safety net in case updates cannot be served normally.
Please read the documentation for -[SPUUserDriver showUpdateFoundWithAppcastItem:state:reply:] for detailed information on different update states.
After an update has been shown, a user can check for updates again to bring the update UI back in frontmost focus. To support this you need to implement -[SPUUserDriver showUpdateInFocus]. This method used to be required but is now optional since Sparkle 2.8. Don’t implement this method if bringing an update back in focus does not make sense for your user interface (e.g. update UI is always in frontmost focus).