Installation
Learn how to install and set up Sparkler in your macOS app development workflow. This guide covers all the necessary steps to integrate with the Sparkle framework.
1. Add the Framework
We'll use Swift Package Manager to add the Sparkle framework to your project.
Using Swift Package Manager:
- In your Xcode project, go to
File › Add Package Dependencies…
- Enter
https://github.com/sparkle-project/Sparkle
as the package repository URL - Choose the Package Options. The default options will let Xcode automatically update versions of Sparkle 2.
Important:
When prompted to pick a target to add the framework to, make sure you choose your main app as the target. It defaults to no target, so don't just accept the defaults!
📸 Screenshot placeholder: Xcode Add Package dialog
2. Create an Updater (using SwiftUI)
Next, you'll need to set up the updater in your SwiftUI app. Here's a complete example:
import SwiftUI
import Sparkle
// This view model class publishes when new updates can be checked by the user
final class CheckForUpdatesViewModel: ObservableObject {
@Published var canCheckForUpdates = false
init(updater: SPUUpdater) {
updater.publisher(for: \.canCheckForUpdates)
.assign(to: &$canCheckForUpdates)
}
}
// This is the view for the Check for Updates menu item
// Note this intermediate view is necessary for the disabled state on the menu item to work properly before Monterey.
// See https://stackoverflow.com/questions/68553092/menu-not-updating-swiftui-bug for more info
struct CheckForUpdatesView: View {
@ObservedObject private var checkForUpdatesViewModel: CheckForUpdatesViewModel
private let updater: SPUUpdater
init(updater: SPUUpdater) {
self.updater = updater
// Create our view model for our CheckForUpdatesView
self.checkForUpdatesViewModel = CheckForUpdatesViewModel(updater: updater)
}
var body: some View {
Button("Check for Updates…", action: updater.checkForUpdates)
.disabled(!checkForUpdatesViewModel.canCheckForUpdates)
}
}
@main
struct MyApp: App {
private let updaterController: SPUStandardUpdaterController
init() {
// If you want to start the updater manually, pass false to startingUpdater and call .startUpdater() later
// This is where you can also pass an updater delegate if you need one
updaterController = SPUStandardUpdaterController(startingUpdater: true, updaterDelegate: nil, userDriverDelegate: nil)
}
var body: some Scene {
WindowGroup {
}
.commands {
CommandGroup(after: .appInfo) {
CheckForUpdatesView(updater: updaterController.updater)
}
}
}
}
📸 Screenshot placeholder: Xcode with the updater code added
3. Set up your EdDSA Keypair
You'll need to generate cryptographic keys to sign your app updates securely.
Finding Sparkle Tools:
From Xcode's project navigator, right-click and show the Sparkle package in Finder. You will find Sparkle's tools to generate and sign updates in ../artifacts/sparkle/Sparkle/bin/
(in Finder you may need to go up one folder from checkouts via Go › Enclosing Folder).
Generate EdDSA (ed25519) Keys:
- Run
./bin/generate_keys
tool (from the Sparkle distribution root). This needs to be done only once. - This tool will generate a private key and save it in your login Keychain on your Mac. Keep it safe - you'll need it to sign updates.
- It will print your public key to embed into applications. Copy that key (it's a base64-encoded string).
- Add your public key to your app's
Info.plist
as aSUPublicEDKey
property.
A key has been generated and saved in your keychain. Add the `SUPublicEDKey` key to
the Info.plist of each app for which you intend to use Sparkle for distributing
updates. It should appear like this:
<key>SUPublicEDKey</key>
<string>pfIShU4dEXqPd5ObYNfDBiQWcXozk7estwzTnF9BamQ=</string>
For CI/CD:
We recommend storing your private key as a GitHub secret to use as part of your GitHub Actions workflow for automated builds and releases.
📸 Screenshot placeholder: Terminal showing generate_keys command
📸 Screenshot placeholder: Info.plist with SUPublicEDKey added
4. Add Appcast URL
Finally, you need to tell Sparkle where to check for updates by adding your appcast URL.
Add a SUFeedURL
property to your Info.plist
with the appcast URL from your Sparkler dashboard.
<key>SUFeedURL</key>
<string>https://your-sparkler-dashboard-url/appcast.xml</string>
Sparkler Dashboard:
Use the appcast URL provided in your Sparkler dashboard. This URL will automatically serve the correct appcast XML for your app's updates.
📸 Screenshot placeholder: Sparkler dashboard showing appcast URL
📸 Screenshot placeholder: Info.plist with SUFeedURL added
🎉 You're Ready!
Your app is now configured with Sparkle for automatic updates. Next, learn about the key concepts of how Sparkler manages your app updates and releases.