Publishing An Update

So you’re ready to release a new version of your app. How do you go about doing that?

• Archive your app. Either:
  • Put a copy of your .app (with the same name as the version it’s replacing) in a .zip, .dmg, .tar.gz, or .tar.bz2.
  • Create an Installer .pkg with the same name as your app and put that .pkg in one of the archive formats above.

• Secure your update.
  • In order to prevent man-in-the-middle attacks against your users, you must cryptographically sign your updates.
  • You can do that using Apple’s code signing tools, with a Developer ID or with your own certificate. If you’re already signing your app, and you’re targeting 10.6 or later, you’re good to go.
  • If you can’t code sign your app, you can make a DSA signature of the archive instead.
    • Sparkle includes a script to help you sign your update. From the Sparkle distribution root:
    • ruby sign_update.rb path_to_your_update.zip path_to_your_dsa_priv.pem
    • The string outputted is your update’s DSA signature; you’ll add this as an attribute to your enclosure in the next step. You can remove any newlines in this string.

• Update your appcast:
  • You need to create an <item> for your update in your appcast. See the sample appcast for an example.
  • Here’s a template you might use:
    

     <item>
        <title>Version 2.0 (2 bugs fixed; 3 new features)</title>
        <sparkle:releaseNotesLink>
            http://you.com/app/2.0.html
        </sparkle:releaseNotesLink>
        <pubDate>Wed, 09 Jan 2006 19:20:11 +0000</pubDate>
        <enclosure url="http://you.com/app/Your Great App 2.0.zip"
                   sparkle:version="2.0"
                   sparkle:dsaSignature="MC0CFBfeCa1JyW30nbkBwainOzrN6EQuAh=" <!-- if you're not code signing -->
                   length="1623481"
                   type="application/octet-stream" />
    </item>

• Test your update
  • And you’re done!

Delta updates

If your app is large, or if you’re updating primarily only a small part of it, you may find “delta updates” useful: they allow you users to only download the bits that have changed.

Internal build numbers

If you use internal build numbers for your CFBundleVersion key (like an SVN revision number) and a human-readable CFBundleShortVersionString, you can make Sparkle hide the internal version from your users.

Set the sparkle:version attribute on your enclosure to the internal version (ie: “248”). Then set a sparkle:shortVersionString attribute on the enclosure to the human readable version (ie: “2.0”).

Remember that the internal version number (CFBundleVersion and sparkle:version) is intended to be machine-readable and is not generally suitable for formatted text.

Minimum system version requirements

If an update to your application raises the required version of Mac OS X, you can only offer that update to qualified users.

Add a sparkle:minimumSystemVersion child to the <item> in question specifying the required system version, such as “10.5.5”:

<item>
    <title>Version 2.0 (2 bugs fixed; 3 new features)</title>
    <sparkle:minimumSystemVersion>10.5.5</sparkle:minimumSystemVersion>
</item>

Offering separate Intel and PowerPC downloads

By default, Sparkle does not offer a way to specify that an item is only available for Intel or PPC architectures. But here’s a trick that comes close to it:

Use two items for your separate downloads, the first using this extra entry inside <item>:

<sparkle:minimumSystemVersion>10.6.0</sparkle:minimumSystemVersion>

Make this item provide the Intel-only download, while the second item provides a PPC-only or Universal download.

Sparkle will thus ignore the first item if the OS version is below 10.6. Since OSX for PPC is only available up to 10.5.x, this ensures that any computer running a PPC architecture will only see the second item, making sure that users on PPC Macs will not get the Intel-only version.

The only drawback is that Intel Macs running 10.4 or 10.5 will also be offered the second item. It’s up to you if those users would then get a PPC-only version (which would run more slowly in the PPC emulator), or a universal app (which is unnecessarily large for PPC users).

Embedded release notes

Instead of linking external release notes using the element, you can also embed the release notes directly in the appcast item, inside a element. If you wrap it in <![CDATA[ … ]]>, you can use unescaped HTML.

<item>
    <title>Version 2.0 (2 bugs fixed; 3 new features)</title>
    <description><![CDATA[
        <h2>New Features</h2>
        ...
    ]]>
    </description>
    ...
</item>

Localization

You can provide additional release notes for localization purposes. For instance:

<sparkle:releaseNotesLink>http://you.com/app/2.0.html</sparkle:releaseNotesLink>
<sparkle:releaseNotesLink xml:lang="de">http://you.com/app/2.0_German.html</sparkle:releaseNotesLink>

Use the xml:lang attribute with the appropriate two-letter country code for each localization. You can also use this attribute with the <description> tag.

Xcode integration

Here’s a description of how to automate the archiving and signing process with a script build phase in Xcode.

Alternate download locations for other operating systems

While Sparkle is originally designed for OS X only, it should be possible to allow it to be used on other platforms, e.g. Windows and Linux, just as well, provided someone writes a framework for it.

To keep the appcast file compatible with the standard Sparkle implementation, a new tag has to be used for x-platform support. It is suggested to use the following to specify downloads for non-OSX systems:

<sparkle:enclosure sparkle:os="os_name" ...>

Replace os_name with either “windows” or “linux”, respectively (mind the lower case!). Feel free to add other OS names as needed.