Appcast Feeds

Sketch v45 onwards uses Sparkle Appcast feeds to update plugins. To take advantage of native Sketch updates, you must provide an appcast.xml file and link it to your manifest.json. The appcast.xml file should contain all releases for your plugin, as well as urls to download each one.

Sketchpacks can help automate this process by generating, maintaining, and serving your plugins appcast feed to the Sketch community. The appcast feed also helps provide some insight into your plugin's user activity and retention.

You can also use skpm to automate building your appcast. Sketchpacks can be configured to serve your repositories appcast.xml instead of generating one.

For more information, be sure to read the Sketch developer documentation about publishing plugin updates: http://developer.sketchapp.com/guides/publishing-plugins/

Appcast Essentials

you must provide a HTTPS URL to your appcast.xml file
you must define the appcast property in your manifest.json
you may define the appcast property in your package.json

For more information, be sure to read the Sketch developer documentation about plugin manifests and how to use appcasts: http://developer.sketchapp.com/guides/plugin-bundles/#manifest

Appcast Setup

ensure your plugin meets the essentials for Sketchpacks
set the appcast property in your manifest.json or package.json to the Sketchpacks appcast URL for your plugin
(optional) set your plugin's appcast.xml path in the Sketchpacks settings file.
commit your changes to the repository
build and publish a new plugin release

Below is the endpoint for the Sketchpacks appcast feed. Replace the :identifier with your plugin's unique identifier.

https://api.sketchpacks.com/v1/plugins/:identifier/appcast

Setup Examples

Example manifest.json:

{
  "name" : "My Awesome Plugin",
  "identifier" : "my.awesome.plugin",
  "appcast": "https://api.sketchpacks.com/v1/plugins/my.awesome.plugin/appcast"
}

Example package.json if you are using skpm:

{
  "skpm": {
    "name": "awesome-plugin",
    "title": "My Awesome Plugin",
    "manifest": "src/manifest.json",
    "identifier": "my.awesome.plugin",
    "appcast": "https://api.sketchpacks.com/v1/plugins/my.awesome.plugin/appcast",
    "main": "awesome-plugin.sketchplugin"
  }
}

Managing your appcast feed

Sketchpacks supports two workflows for building your plugins appcast, the push and release workflows. If your repository contains releases, Sketchpacks will use the release workflow. Otherwise the push workflow will be used by default.

If you do not want Sketchpacks to generate your appcast feed, you can define a custom appcast feed, using an appcast.xml file in your repository.

Custom Appcast Feed

ensure your repository has an appcast.xml file present
set the appcast_path property in your plugin's settings file
commit your changes to the repository
build and publish a new plugin release

Push Workflow

When you push to your default branch, Sketchpacks will sync with the repository. To update your appcast, bump your plugin version and push the changes to your default branch.

You can use the npm versioning command:

npm version <new-version>

Or the skpm publish command:

skpm publish <new-version> --skip-release

However, you will only ever have one HEAD release in your appcast. If you need to support multiple versions for older Sketch clients, you will need to use the release workflow instead.

Note: Release notes are not available using the push workflow

Here is an example appcast from the plugin PDF export, which is using the push workflow:

<?xml version="1.0" encoding="utf-8"?>
<rss xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" xmlns:dc="http://purl.org/dc/elements/1.1/" version="2.0">
  <channel>
    <title>PDF export</title>
    <link>
      https://api.sketchpacks.com/v1/plugins/com.davidwilliames.sketch.pdf-export/appcast
    </link>
    <description>
      Export artboards to PDF — from the current page, all pages or current selection
    </description>
    <language>en</language>
    <item>
      <title>2.1</title>
      <pubDate>2017-03-12 17:20:54 UTC</pubDate>
      <enclosure url="https://api.sketchpacks.com/v1/plugins/com.davidwilliames.sketch.pdf-export/download/update/0.0.0?range==2.1" sparkle:version="2.1"/>
    </item>
  </channel>
</rss>

Release Workflow

When you create and publish new releases in your github repository, they will automatically be added to your appcast feed.

We recommend that you use SKPM to publish your releases. It simplifies building, versioning, and publishing your releases on GitHub.

skpm publish <new-version>

The release workflow is great for when you need to retain older versions for users on old Sketch clients. Also, it provides you with the ability to add change logs to your appcast feed.

Here is an example appcast for the plugin Keys For Sketch, which is using the release workflow:

<?xml version="1.0" encoding="utf-8"?>
<rss xmlns:sparkle="http://www.andymatuschak.org/xml-namespaces/sparkle" xmlns:dc="http://purl.org/dc/elements/1.1/" version="2.0">
  <channel>
    <title>Keys For Sketch</title>
    <link>
      https://api.sketchpacks.com/v1/plugins/com.vyacheslav-dubovitsky.KeysForSketch/appcast
    </link>
    <description>Advanced shortcut manager for Sketch</description>
    <language>en</language>
    <item>
      <title>0.8.7</title>
      <description>- #23 Sketch v48 capability</description>
      <pubDate>2017-12-06 12:30:51 UTC</pubDate>
      <enclosure url="https://api.sketchpacks.com/v1/plugins/com.vyacheslav-dubovitsky.KeysForSketch/download/update/0.0.0?range==0.8.7" sparkle:version="0.8.7"/>
    </item>
    <item>
      <title>0.8.6</title>
      <description>Fixed:
       - Additional conflict resolving issues.</description>
      <pubDate>2017-10-18 18:42:02 UTC</pubDate>
      <enclosure url="https://api.sketchpacks.com/v1/plugins/com.vyacheslav-dubovitsky.KeysForSketch/download/update/0.0.0?range==0.8.6" sparkle:version="0.8.6"/>
    </item>

    ... omitted for brevity ...

    <item>
      <title>0.7.0</title>
      <description>Initial release.</description>
      <pubDate>2017-08-09 23:46:27 UTC</pubDate>
      <enclosure url="https://api.sketchpacks.com/v1/plugins/com.vyacheslav-dubovitsky.KeysForSketch/download/update/0.0.0?range==0.7.0" sparkle:version="0.7.0"/>
    </item>
  </channel>
</rss>

Missing releases from your appcast?

Backfilling previous versions is done by tagging a past commit in your history.

Say for example, you forgot to tag your plugin at v1.2.3, which was a fix for some bugs. Just find the commit checksum (or SHA) where you commited the fixes (e.g. 9fceb02), and specify it at the end of the tag command.

$ git tag -a v1.2.3 9fceb02

Now push those commits to Github and begin drafting and publishing your releases.

$ git push --tags

By publishing your releases, they'll immediately become available from your plugin's Appcast feed URL.

Removing releases from your appcast

To remove a release from your appcast you need to delete the release from github. The new state will be synced with Sketchpacks and the releases will be removed from your appcast feed.

Appcast