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:

  1. In your Xcode project, go to File › Add Package Dependencies…
  2. Enter https://github.com/sparkle-project/Sparkle as the package repository URL
  3. 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:

Swift
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:

  1. Run ./bin/generate_keys tool (from the Sparkle distribution root). This needs to be done only once.
  2. 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.
  3. It will print your public key to embed into applications. Copy that key (it's a base64-encoded string).
  4. Add your public key to your app's Info.plist as a SUPublicEDKey property.
Example generate_keys output
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.

Info.plist example
<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.