You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Here are the main routes by which you can bend Sparkle's behavior to your will:
8
+
Besides the `SUFeedURL` and `SUPublicEDKey` options, Sparkle will choose defaults for your app's update behavior. However you can change these settings if you want different behavior.
9
+
10
+
For example:
11
+
12
+
* If you do not want Sparkle to prompt the user (on second app launch) asking for permission if your app can check for updates automatically in the background, set `SUEnableAutomaticChecks` in your app's Info.plist.
13
+
* If you want Sparkle to automatically download and install updates silently in the background instead of notifying users of updates every time by default, enable `SUAutomaticallyUpdate` in your app's Info.plist.
14
+
15
+
Some of the Info.plist settings below are also paired with an updater API to change the settings at runtime, like `SUEnableAutomaticChecks` with [automaticallyChecksForUpdates](/documentation/api-reference/Classes/SPUUpdater.html#/c:objc(cs)SPUUpdater(py)automaticallyChecksForUpdates). The Info.plist settings are meant for default configuration, while the runtime APIs are in response to user setting changes. Please do not use the runtime APIs for setting initial default behavior. Check how to [add update settings](/documentation/preferences-ui/) for examples on changing user settings.
9
16
10
17
### Info.plist Settings
11
18
12
19
{:.table .table-bordered}
13
20
| Key | Type | Value |
14
21
| --- | ---- | ----- | ------- |
15
-
|`SUFeedURL`| String | The URL of your appcast, e.g. `https://example.com/appcast.xml`. It's recommended to always set it in Info.plist, even if you change it later programmatically. |
22
+
|`SUFeedURL`| String | The URL of your appcast, e.g. `https://example.com/appcast.xml`. It's recommended to set it in Info.plist, even if you change it later programmatically. |
16
23
|`SUPublicEDKey`| String | The base64-encoded public EdDSA key. Use Sparkle's `generate_keys` tool to get it. |
17
-
|`SUEnableAutomaticChecks`| Boolean | By default when this is not set, automatic checking for updates is initially disabled but users will be prompted for permission for Sparkle to check for updates automatically on second launch. If permission is granted, automatic checks for updates then becomes enabled. As of Sparkle 2.4 or later, the user will also have an option to opt into or out of automatic downloading of updates; the default state is based on the `SUAutomaticallyUpdate` setting.<br/>Setting this to `YES` enables automatic checking for updates (but not installation) by default, without asking your users for permission first.<br>Setting this to `NO` disables automatic checking for updates by default, also without asking your users for permission.<br/>This default property can later be overridden by setting [automaticallyChecksForUpdates](/documentation/api-reference/Classes/SPUUpdater.html#/c:objc(cs)SPUUpdater(py)automaticallyChecksForUpdates) in response to user setting changes. |
18
-
|`SUEnableSystemProfiling`|Boolean|Default: `NO`. Enables anonymous system profiling. See [System Profiling](/documentation/system-profiling) for more. |
19
-
|`SUScheduledCheckInterval`|Number|The number of seconds between updates. The default is `86400` (1 day). Setting to 0 disables updates.<br /><br />**Note:** this has a minimum bound of 1 hour in order to keep you from accidentally overloading your servers. |
24
+
|`SUEnableAutomaticChecks`| Boolean | By default when this is not set, automatic checking for updates is initially disabled but users will be prompted for permission for Sparkle to check for updates automatically on second launch. If permission is granted, automatic checks for updates then becomes enabled. As of Sparkle 2.4 or later, the user will also have an option to opt in or out of automatic downloading of updates; the default state is based on the `SUAutomaticallyUpdate` setting.<br/>Setting this to `YES` enables automatic checking for updates (but not installation) by default, without asking your users for permission first.<br>Setting this to `NO` disables automatic checking for updates by default, also without asking your users for permission.<br/>This default property can later be overridden by setting [automaticallyChecksForUpdates](/documentation/api-reference/Classes/SPUUpdater.html#/c:objc(cs)SPUUpdater(py)automaticallyChecksForUpdates) in response to user setting changes. |
25
+
|`SUScheduledCheckInterval`|Number|The number of seconds between updates. The default is `86400` (1 day).<br /><br />**Note:** this has a minimum bound of 1 hour in order to keep you from accidentally overloading your servers. |
26
+
| `SUAutomaticallyUpdate` | Boolean | Default: `NO`. Enables automatic download and installation of updates by default. If set to `YES`, Sparkle will attempt to download and install new updates silently in the background. Updates may be downloaded but not installed automatically if authorization is required. If the application hasn't quit for 1 week the user will be presented with installing the downloaded update (unless the updater delegate overrides this).<br/>This default property can later be overridden by setting [automaticallyDownloadsUpdates](/documentation/api-reference/Classes/SPUUpdater.html#/c:objc(cs)SPUUpdater(py)automaticallyDownloadsUpdates)in response to user setting changes (for example, the standard update alert has a checkbox for changing this).
20
27
|`SUAllowsAutomaticUpdates`| Boolean | By default, Sparkle automatically presents your users with the *option* to allow to automatically download and install any available updates if automatic checking of updates is enabled.<br/>Set this to `NO` to disallow automatic updates and require manual installation every time.<br/>Set this to `YES` to always allow automatic updates even if automatic checking of updates is disabled. |
21
-
| `SUAutomaticallyUpdate` | Boolean | Default: `NO`. Enables automatic download and installation of updates by default. If set to `YES`, Sparkle will attempt to download and install new updates silently in the background. In Sparkle 1, updates won't be opted into this if users need to provide authorization. In Sparkle 2, updates will be downloaded but not installed automatically if authorization is required. In all versions of Sparkle, if the application hasn't quit for 1 week the user will be presented with installing the downloaded update (unless the updater delegate overrides this).<br/>This default property can later be overridden by setting [automaticallyDownloadsUpdates](/documentation/api-reference/Classes/SPUUpdater.html#/c:objc(cs)SPUUpdater(py)automaticallyDownloadsUpdates) in response to user setting changes.
28
+
|`SUEnableSystemProfiling`| Boolean | Default: `NO`. Enables anonymous system profiling. See [System Profiling](/documentation/system-profiling) for more. |
22
29
|`SUVerifyUpdateBeforeExtraction`| Boolean | Default: `NO`. Set this to `YES` to force verification of updates before Sparkle extracts the downloaded update. Use this setting if you want stronger update validation and you aren't likely to lose access to your private EdDSA key (typically stored inside the macOS Keychain). EdDSA signing is required to use this setting. [Key rotation](/documentation/#rotating-signing-keys) is still possible by using Apple Developer ID code signed disk images as fallback. This setting is available in Sparkle 2.7 and later. |
23
30
|`SUShowReleaseNotes`| Boolean | Default: `YES`. Set this to `NO` to hide release notes display from the update alert. |
24
31
| `SUAllowedURLSchemes` | Array of Strings | An array of custom URL schemes allowed to be clicked from Sparkle's release notes view. By default, Sparkle only allows clicks to links that have a safe known URL scheme (like `https`). This setting is available in Sparkle 2.5 and later.
@@ -39,128 +46,6 @@ Here are the Info.plist settings relevant to use for Sandboxed applications usin
39
46
|`SUEnableInstallerConnectionService`| Boolean | Default: `NO`. Set this to `YES` to enable using the Installer Connection Service. This service is usually not needed due to being able to [add a mach name lookup exception entitlement](/documentation/sandboxing#installer-connection--status-services) instead. This service is not included in Sparkle's framework distribution by default. |
40
47
|`SUEnableInstallerStatusService`| Boolean | Default: `NO`. Set this to `YES` to enable using the Installer Status Service. This service is usually not needed due to being able to [add a mach name lookup exception entitlement](/documentation/sandboxing#installer-connection--status-services) instead. This service is not included in Sparkle's framework distribution by default. |
41
48
42
-
### Sparkle 2 APIs
43
-
44
-
Please visit the [Sparkle 2 API Reference](/documentation/api-reference).
45
-
46
-
### Sparkle 1 APIs
47
-
48
-
#### Calls to SUUpdater
49
-
50
-
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](/documentation/bundles/), you can use `[SUUpdater updaterForBundle:(NSBundle *)myBundle]`.
51
-
52
-
Once you have the `SUUpdater` instance, there are a few interesting accessors you could use. Please use them only if you need dynamic behavior (e.g. user preferences). Do not use these functions to set default configuration. Use Info.plist keys to set default configuration instead.
There is a risk of race conditions. 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.
72
-
73
-
A few more methods of interest:
74
-
75
-
```objc
76
-
// This IBAction is meant for a main menu item. Hook up any menu item to this action,
77
-
// and Sparkle will check for updates and report back its findings through UI.
78
-
- (IBAction)checkForUpdates:sender;
79
-
80
-
// This kicks off an update meant to be programmatically initiated. That is,
81
-
// it will display no UI unless it actually finds an update, in which case it
82
-
// proceeds as usual. If the automated downloading is turned on, however,
83
-
// this will invoke that behavior, and if an update is found, it will be
84
-
// downloaded and prepped for installation.
85
-
//
86
-
// You do not need to call this. Sparkle calls it automatically according to
87
-
// the update schedule.
88
-
- (void)checkForUpdatesInBackground;
89
-
90
-
// This begins a "probing" check for updates which will not actually offer to
91
-
// update to that version. The delegate methods, though, (up to updater:didFindValidUpdate:
92
-
// and updaterDidNotFindUpdate:), are called, so you can use that information in your UI.
93
-
// Essentially, you can use this to UI-lessly determine if there's an update.
94
-
- (void)checkForUpdateInformation;
95
-
96
-
// Date of last update check. Returns nil if no check has been performed.
97
-
- (NSDate *)lastUpdateCheckDate;
98
-
99
-
// Call this to appropriately schedule or cancel the update checking timer according
100
-
// to the preferences for time interval and automatic checks. If this SUUpdater instance
101
-
// was not present during the application's launch, you must call this method to start
102
-
// the update cycle explicitly.
103
-
- (void)resetUpdateCycle;
104
-
105
-
- (BOOL)updateInProgress;
106
-
107
-
- (void)setDelegate:(id)delegate; // See below for more information on the delegate.
108
-
- delegate;
109
-
```
110
-
111
-
#### SUUpdater delegate methods
112
-
113
-
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:
114
-
115
-
```objc
116
-
// Use this to override the default behavior for Sparkle prompting the
117
-
// user about automatic update checks. You could use this to make Sparkle
118
-
// prompt for permission on the first launch instead of the second.
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.
51
+
Please visit the [Sparkle 2 API Reference](/documentation/api-reference) for full documentation on class and delegate APIs.
Copy file name to clipboardExpand all lines: documentation/preferences-ui/index.md
+8-48Lines changed: 8 additions & 48 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,20 +4,18 @@ id: documentation
4
4
title: Adding a Settings UI
5
5
---
6
6
7
-
## Sparkle 2
8
-
9
-
### Adding a Settings UI in Cocoa
7
+
## Adding a Settings UI in Cocoa
10
8
11
9
These instructions below are for adding settings in a Cocoa nib and assume you have a Settings nib with its `File's Owner` being set to your Settings controller class (e.g, a `NSWindowController` subclass). The controller class should have an `updater` property set to your application's `SPUUpdater`, which may be passed from your application's delegate.
12
10
13
-
####Enable automatic checking
11
+
### Enable automatic checking
14
12
15
13
* Drag a check button from the Library to your document.
16
14
* Set the title to something like "Automatically check for updates".
17
15
* Select the check button, and under the Bindings tab, select Value.
18
16
* Check the Bind to: check button, choose `File's Owner` from the popup, and set the Model Key Path to `updater.automaticallyChecksForUpdates`.
19
17
20
-
####Update check interval
18
+
### Update check interval
21
19
22
20
* Drag a popup button from the Library to your document.
23
21
* Set the titles of the menu items to e.g. "Hourly", "Daily", "Weekly", "Monthly".
@@ -26,11 +24,11 @@ These instructions below are for adding settings in a Cocoa nib and assume you h
26
24
* Check the Bind to: check button, choose `File's Owner` from the popup, and set the Model Key Path to `updater.updateCheckInterval`.
27
25
* Select Enabled, check the Bind to: check button, choose `File's Owner` from the popup, and set the Model Key Path to `updater.automaticallyChecksForUpdates`.
28
26
29
-
####Other settings
27
+
### Other settings
30
28
31
-
Follow directions similar to [Enable automatic checking](#enable-automatic-checking) to bind a check button to `updater.sendsSystemProfile` or `updater.automaticallyDownloadsUpdates`. See [customization](/documentation/customization/#infoplist-settings) for details on the available keys.
29
+
Follow directions similar to [Enable automatic checking](#enable-automatic-checking) to bind a check button to `updater.automaticallyDownloadsUpdates` or `updater.sendsSystemProfile`. See [customization](/documentation/customization/#infoplist-settings) for details on the available keys.
32
30
33
-
###Adding Settings in SwiftUI
31
+
## Adding Settings in SwiftUI
34
32
35
33
This is a continuation from [Creating an Updater in SwiftUI](/documentation/programmatic-setup#create-an-updater-in-swiftui).
36
34
@@ -81,7 +79,7 @@ var body: some Scene {
81
79
}
82
80
```
83
81
84
-
###Adding Settings in Qt
82
+
## Adding Settings in Qt
85
83
86
84
This is a continuation from [Creating an Updater in Qt](/documentation/programmatic-setup#create-an-updater-in-qt) and illustrates one way of adding updater settings.
87
85
@@ -144,44 +142,6 @@ Note that [automaticallyChecksForUpdates](/documentation/api-reference/Classes/S
144
142
145
143
---
146
144
147
-
## Sparkle 1
148
-
149
-
These instructions below are for adding settings in a Cocoa nib and assume you have a Settings nib with its `File's Owner` being set to your Settings controller class (e.g, a `NSWindowController` subclass). The controller class should have an `updater` property set to your application's `SUUpdater`, which may be passed from your application's delegate.
150
-
151
-
### Enable automatic checking
152
-
153
-
* Drag a check button from the Library to your document.
154
-
* Set the title to something like "Automatically check for updates".
155
-
* Select the check button, and under the Bindings tab, select Value.
156
-
* Check the Bind to: check button, choose `File's Owner` from the popup, and set the Model Key Path to `updater.automaticallyChecksForUpdates`.
157
-
158
-
### Update check interval
159
-
160
-
* Drag a popup button from the Library to your document.
161
-
* Set the titles of the menu items to e.g. "Hourly", "Daily", "Weekly", "Monthly".
162
-
* Set the tags of the menu items to the corresponding times in seconds, e.g. 3600, 86400, 604800, 2629800.
163
-
* Select the popup button, and under the Bindings tab, select Selected Tag.
164
-
* Check the Bind to: check button, choose `File's Owner` from the popup, and set the Model Key Path to `updater.updateCheckInterval`.
165
-
* Select Enabled, check the Bind to: check button, choose `File's Owner` from the popup, and set the Model Key Path to `updater.automaticallyChecksForUpdates`.
166
-
167
-
### Other settings
168
-
169
-
Follow directions similar to [Enable automatic checking](#enable-automatic-checking). to bind a check button to `sendsSystemProfile` or `automaticallyDownloadsUpdates`. See [customization](/documentation/customization/#infoplist-settings) for details on the available keys.
170
-
171
-
### Settings for non-app bundles
172
-
173
-
These directions do not work for non-app bundles, as the updater you add to the nib will be the `sharedUpdater` for the application bundle. To be able to bind to the updater for your bundle, you can add the following accessor to your settings controller (the owner of the nib):
Then just bind the controls to the File's Owner, and start the Model Key Path with updater., e.g. updater.automaticallyChecksForUpdates.
182
-
183
-
---
184
-
185
-
### Watch out for Preference Caching
145
+
## Watch out for Preference Caching
186
146
187
147
macOS caches plist files in `~/Library/Preferences`, so don't edit them directly. If you want to tweak these files for testing (e.g. change last update check date), use the `defaults` command.
0 commit comments