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. Either sign it or host it over HTTPS.

Option A. Sign your update

• 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.

Option B. Host your appcast and your download over HTTPS

For this to work, the `SUFeedURL` entry in your Info.plist must begin with “https”. In your appcast’s XML, the url in the enclosure tag must also begin with https.

You must also remove the `SUPublicDSAKeyFile` entry in your Info.plist if you’ve added one there already; otherwise signing will still be used.

• 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="
                   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 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 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>

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.