Using Sparkle with Enhanced Applets

Script Debugger 7’s Enhanced Applets include the Sparkle software update framework. Sparkle is used to update applications via the Internet. It’s the system used by most applications outside Apple’s Mac App Store, including Script Debugger.

This document describes how to configure an enhanced applet to update itself using Sparkle. For a full description of Sparkle and all its options, please refer to the Sparkle documentation. Script Debugger 7’s Enhanced Applets take care of items 1 & 2 in the Sparkle documentation for you – this document summarize items 3 and above.

When configured correctly, a “Check for Updates…” menu item will appear in an Enhanced Applet’s application menu.

To make your applet capable of being updated via Sparkle with the least hassle, you can follow these steps:

  1. Create public and private DSA keys. The is a once-only operation.

  2. Add your public DSA key to the application’s Resources directory.

  3. Add two entries your applet’s Info.plist file.

  4. When you are ready to distribute the applet, export it and codesign it with your Apple Developer ID.

To make an update to an applet available, you need to perform these additional steps.

  1. Create an archive of the updated and codesigned application plus an update appcast file. (An appcast is a kind of RSS feed.)

  2. Upload the two items to a server configured with HTTPS.

Although you only need to do steps 1 through 4 before distributing your initial version, it’s a good idea to do a dummy upgrade as a test first. Also, once you distribute a version, make sure the Bundle ID is the same for all updates.

Here are the steps above in more detail.

Creating DSA keys

You can download a script to create your DSA keys here. The script will create a folder containing a private key, called dsapriv.pem, and a public key, dsapub.pem. You should make a back-up of the private key, and make sure it is saved in a safe and private place. You only need to do this once; you use the same keys each update, and for every applet you add Sparkle updating to.

Add your public key to the applet

You should copy your public key file to the Resources folder of your applet; you can drag it there via the bottom section of the Resources Tab in Script Debugger.

Add entries to Info.list

You need to add at least two entries to your applet’s Info.plist file. Control-click on your application’s icon in the Finder, and locate Info.plist in the /Contents directory. You can edit this in Xcode, or — carefully — in a text editor like BBEdit.

The first entry you need to add is the URL of the appcast file you will create. The entry will have a key of SUFeedURL and a value of the URL. Obviously, this means knowing where you are going to be serving the update before going any further. In a text editor, the extra entry will look like this:

<key>SUFeedURL</key> <string>https://blah.com/path/to/app_name_appcast.xml</string>

The actual appcast file name is up to you; it’s probably easier if you base it on your applet’s name. (The presence of this key also tells the applet shell to include the Check for Updates... menu item.)

The second entry you need to add is the name of the DSA public key file you added to the Resources folder — unless you renamed it, it will be dsa_pub.pem. In this case the key is SUPublicDSAKeyFile. In a text editor, the entry will look like this:

<key>SUPublicDSAKeyFile</key> <string>dsa_pub.pem</string>

Export and codesign

You are now ready to export your Enhanced Applet in run-only form, and sign it with an Apple ID. Although you can use Sparkle updates without having an Apple ID, you risk warnings and permission problems with updated versions. The whole update provess is much smoother if you codesign with an Apple developer ID.

You also need to make the applet stay-open, otherwise you will have trouble choosing the update command, and the application may quit mid-update.

Create an archive and appcast file

You can create a .zip file of your applet, and use the command-line tools on the Sparkle site to help build your appcast file, but this script will do it all for you. Simply drag the codesigned applet over its icon, choose your private DSA key file when prompted, and wait (it can take a few minutes). It will produce both a .zip file and the appcast .xml file. You can then open the .xml file in a text editor and edit the HTML where it says <p>Details of update.</p>. The HTML you enter here appears in the Sparkle update dialog.

Upload to your server

Upload the appcast .xml file and the .zip archive to your server and you are good to go. It’s a good idea to launch a copy of your original applet and check that everything is working.

That’s it.