UpdateKit Documentation


A Note from Mike Beasley

Hi! Thanks for checking out UpdateKit! I hope you find it useful. If you have any suggestions for how to improve on this, feel free to tweet me. Please be aware that I'm not actually a software developer so we may not speak exactly the same language, but I'll do my best!

Also, be sure to check out the new RoutinePub Shortcut, which provides an easy way to publish your Shortcuts to the RoutineHub service directly from your iOS device! I built it in collaboration with the creator of RoutineHub, and it will help simplify your Shortcut publishing flow, especially with the UpdateKit 2.0 integration discussed below.

Thanks again for checking this out!

-Mike




Getting Started with UpdateKit

You can download the release of UpdateKit from mikebeas.com/updatekit/download.

If you are using a self-hosted UpdateKit data file (more details on that throughout this document), you can use UpdateKit.js to embed your current version number, latest release date, and release notes, as well get the iCloud URL for the latest version of your Shortcut. For more information, check the comment at the top of the file.




What is UpdateKit?

UpdateKit is a drop-in automatic updater for your Shortcuts. You can call UpdateKit from within your own Shortcut to fetch update information and let users install updates to your Shortcut.

UpdateKit checks your web server for an Update file that contains metadata about the newest version. If the newest version number is higher than your Shortcut's current version number, the user will be prompted to install the update.

The easiest way to see UpdateKit in action is to download the latest version, edit it in the Shortcuts app, change the Current Version value in the Dictionary at the top of the workflow, and run it.




Requirements

You will need access to a web server where you can host two files with static URLs. One of these files will contain JSON that is necessary for UpdateKit to work. The other can point to any web page you want to use for your release notes (more details on this below).

Starting with UpdateKit 2.0, you can host your Shortcut on RoutineHub and the service will automatically generate the files for you. If you use RoutineHub you will not need your own web server.




UpdateKit Behavior

When your Shortcut calls UpdateKit, two update checks will be performed. UpdateKit will first check for any updates to your Shortcut, then, if no updates are found for your Shortcut (or if the user skips your update for now), it will run the same check on itself.

If an update is found for your Shortcut, users will be presented with an alert indicating that a new version is available. This alert will contain their current version number, the new version number, and the short change notes from your Update file.

After the user dismisses this alert, they will see a menu with four options:





Adding UpdateKit to Your Shortcut

Integrating UpdateKit into your Shortcut is easy! All you have to do is define four variables in a Dictionary (only three if you're using the RoutineHub integration, see below for details) and then use the Run Shortcut action to activate UpdateKit.

It is recommended that you only call UpdateKit at the very end of your Shortcut after all other processes have finished running to avoid interrupting your Shortcut's workflow. Because there are Cancel buttons in some of the UpdateKit menus which will exit your entire Shortcut, running UpdateKit should always be the last thing that your Shortcut does to prevent users from unintentionally exiting your workflow early. This is a limitation of the Shortcuts app and cannot be worked around.

It is also recommended that you first use the Get Shortcuts action to find a list of the user's installed shortcuts, then use an If statement to see if the input contains UpdateKit before defining your variables in a Dictionary or running UpdateKit. If UpdateKit is not installed, fail gracefully by doing nothing. Since the call to UpdateKit is done after running the rest of your Shortcut, it will naturally move to the end of the workflow and exit the Shortcut with no further action.

If the user does not have have UpdateKit installed when your Shortcut runs the first time, the Shortcuts app may lose the value of the Run Shortcut action. To prevent this, you can define the word UpdateKit in a Text action (or any other action that can be used to store a text value, including as a value in your UpdateKit Dictionary) and then fill in the Run Shortcut value using the Magic Variable for that action. This will cause Shortcuts to fill in the value on each run, rather than discard it the first time the Shortcut is run and then save the new version of the Shortcut with the null value. Note that this step is not shown in the screenshot for this section.

You should also disable Show While Running on the Run Shortcut action to make the process appear seamless.

Optionally, you can prompt your user to download UpdateKit if they do not have it installed by using the Otherwise statement. This is not ideal, as it will prompt them on every run of your Shortcut and will get annoying. If you do go this route, it is probably best to save a file to the user's iCloud Drive indicating the last time they were prompted to install UpdateKit and then check each time your Shortcut runs to see how long it has been since they were prompted before prompting them again. I will not provide instructions or support for any of this, but it is an option if you decide that your Shortcut would greatly benefit from your users having UpdateKit installed and working.

You can see a full-size version of the screenshot to the right by clicking on it. You can find advanced implementation tips for limiting how often UpdateKit runs inside your Shortcut in the video below.

The four variables you need to define in your UpdateKit Dictionary must be named precisely as they are listed below to ensure that UpdateKit can find them. They do not need to be defined in any particular order.







RoutineHub Integration Requires UpdateKit 2.0

RoutineHub is an online gallery of user-submitted Shortcuts that has partnered with UpdateKit to provide an all-in-one solution for publishing your Shortcuts.

Starting in UpdateKit 2.0, if your Shortcut is hosted on RoutineHub, you can specify the RoutineHub ID instead of the Update URL and the Release Notes URL in your UpdateKit Dictionary. UpdateKit will use your Shortcut's RoutineHub ID to automatically determine the URLs for these files.

When you are creating a new listing for a Shortcut on RoutineHub, you will see two buttons at the bottom of the screen: Create and add version and Continue with RoutinePub. Clicking on Continue with RoutinePub will show the RoutineHub ID for the Shortcut, allowing you to plug that number into your Shortcut's UpdateKit Dictionary and add support for fetching updates from RoutineHub.

You can also find the RoutineHub ID by clicking the RoutinePub button on the listing for the Shortcut on the RoutineHub website (you will only see this button on your own Shortcuts when you are logged in). You can also find it in the Shortcut's RoutineHub URL; for example, in the URL https://routinehub.co/shortcut/1, the RoutineHub ID would be 1.

If your users have an older version of UpdateKit installed that does not support RoutineHub ID, they will see errors when trying to run or update your Shortcut. You should ensure that users are running UpdateKit 2.0 or newer if you plan to use the RoutineHub ID to update by employing the Check Version mode described in the section on requiring a minimum version of UpdateKit.

If you publish your Shortcuts to RoutineHub, you may also want to take a look at RoutinePub, a Shortcut that allows you to publish updates to existing RoutineHub Shortcuts right from your iOS device.

If you have RoutinePub installed, you can fetch the RoutineHub ID for any of your RoutineHub Shortcuts by running RoutinePub without any input (by tapping it in the Shortcuts widget or app). RoutinePub will log into your RoutineHub account, get a list of your Shortcuts (both published and unpublished) and allow you to select one to see its RoutineHub ID. You will then have the option of copying the RoutineHub ID, copying the sharing URL that will link users to the RoutineHub download page, or opening an iOS share sheet to share the URL immediately.

You can see a full-size version of the screenshot to the right by clicking on it.




Requiring a Minimum UpdateKit Version Requires UpdateKit 1.1

As UpdateKit is enhanced with new features, you may find that you rely on a certain function that is not available in older versions. To accommodate this dependency, you can require users to update to a newer version of UpdateKit. This is not recommended unless you absolutely must have certain features of newer UpdateKit versions.

Starting with version 1.1, UpdateKit will report its own version number as output when called inside your Shortcut. Because running a full update at the beginning of your Shortcut is not advisable, UpdateKit now allows for a new key to be passed in with your Dictionary. The new key is Check Version.

You can start your Shortcut by creating a Dictionary with a single key, Check Version, and the value True as a text string. It is important that you use a Text element and not a Boolean type for this, as it will change the value that is passed into UpdateKit, and UpdateKit will not properly handle the Boolean type. Once you have defined this single-item Dictionary, pass it into UpdateKit using the Run Shortcut action.

When UpdateKit is called using the Check Version: True value, it does not perform any update checks at all and never pings a server. It simply reports its own version number back as output, which is then returned back to your Shortcut. You can immediately follow the Run Shortcut action with an If action and check to see if the returned version number is less than your required version. If the Less Than check is true, you can show a requirement message with an option to download UpdateKit from mikebeas.com/updatekit. If the check shows that the version number is equal to our greater than your required version, run the main Shortcut body by including it in the Otherwise statement.

If you are in a country or using an iOS device set to a region that uses commas in place of decimals in numbers, the Shortcuts app will automatically determine the proper format for the numbers and compare them correctly, meaning that if you enter 1,3 as the required version of UpdateKit, 1.3 and later will still return the expected result, while 1.2 will accurately fail to pass the check. You do not need to worry about converting commas to decimals or vice versa for this comparison.

Implementation example:
If you want to require UpdateKit 1.3 for your Shortcut, you would start by checking to see if the user has any version of UpdateKit installed. To do this, start the Shortcut off using a Get My Shortcuts action followed by an If statement to determine if the list returned by that action Contains UpdateKit.

If UpdateKit is not installed, the result will be false. Use the Otherwise action for this If statement to execute whatever result you want to run for a failed dependency check. Ideally this would explain the reason for the failure to the user and provide an option to either download UpdateKit from mikebeas.com/updatekit, or ignore the issue and exit the Shortcut. This chain of actions should always end with an Exit Shortcut action no matter the outcome (for example, if the user chooses a menu item, every menu item should eventually end with an Exit Shortcut action) so that the rest of your Shortcut will not be executed if the dependency fails. You can omit this entire Otherwise block if you don't care that UpdateKit is not installed (i.e., it doesn't have to be installed, but if it is installed it should be at least a specific version).

If UpdateKit is installed, the result of this first check will be will be true. In the true portion of the If statement, create a Dictionary with the key Check Version and the value True as a Text element. Pass this Dictionary to the Run Shortcut action. Then receive the output from the Run Shortcut action, feed it into another If action set to Less Than with a value of 1.3.

In the main section of this If statement, include another copy of the failure result from the step above (including an Exit Shortcut on each possible ending), indicating the reason for the failure and prompting the user to install UpdateKit or exit the Shortcut. You can remove the Otherwise portion of this If action, as we will not be needing it. If UpdateKit's current version is greater than the required version, your Shortcut will simply bypass this If and move on to the next step in the workflow.

Now that the dependency check is complete, you can put the body of your Shortcut after all of the If statements. It should be a top-level action (that is, not indented in the editor, not at the top of the action list).

Note that UpdateKit 1.0 will fail to run when passed only a Check Version key and will return an error of Invalid URL: when run this way, which will crash out of your Shortcut. This should be a rare circumstance, but if you are worried about it, you can add an additional safeguard. To do this, pass in your Update URL along with the Check Version key. UpdateKit 1.0 will attempt to fetch an update for your Shortcut and then return the word UpdateKit as its output. You can check for this and assume that version 1.0 is being run, then prompt the user to update. Again, this is likely a rare scenario, but it is possible to handle.

You can see a full-size version of the screenshot to the right by clicking on it. The Shortcut shown in the screenshot requires UpdateKit 1.3 or newer, and will stop the entire workflow from running if an older version or no version at all is installed. If an acceptable version of UpdateKit is installed, it will run any actions at the bottom below the comment.




Checking UpdateKit's Exit Mode Requires UpdateKit 1.3

UpdateKit offers users a number of options for dealing with updates, as seen in the section on UpdateKit behavior. Starting with version 1.3, UpdateKit will also include the Exit Mode when called using the standard method (i.e., not using Check Version mode).

With this change, the complete Dictionary output from a full run of UpdateKit will contain two keys and values. The first is Exit Mode and the second is UpdateKit Version, which includes the version number of the current UpdateKit installation, as described in the section on requiring a minimum version of UpdateKit. Both of these values are presented as Text elements.

The Exit Mode will tell your Shortcut which option the user selected during the regular update flow. There are six possible results. You can use an If action to check the Exit Mode returned by UpdateKit for your Shortcut and respond accordingly.





Setting Up Your Server

If you are self-hosting your UpdateKit data, you will need to host two files on your server.

If you are hosting your Shortcut on RoutineHub, you can skip server setup, as RoutineHub will generate and host these files for you automatically. All you need to do is add your RoutineHub ID to your UpdateKit Dictionary in place of the usual pair of URLs. You can find more details in the section on RoutineHub integration.

The first file that you will need to host is the Release Notes file. This can be formatted however you'd like, from a simple text document to a fully-designed page on your own website or a Twitter page that contains your update log. The main function of this page is to provide users with a way to see historical update notes in case it has been a while since they ran or updated your Shortcut so that they know what changes to expect when getting the latest version.

The second file is the Update file. This file will contain JSON, but does not necessarily need to have the .json extension. It is possible to use it without any extension at all, or with the .txt extension. Other extensions may also work, but there isn't much point in trying to find a different extension to use here. In my own Shortcuts I use a plaintext file with no extension. The URLs do not end in an extension and appear to be directories, but are in fact individual files. This does not cause any issues with UpdateKit's ability to read the file.


Example Update JSON:

{
  "Version": "1.0",
  "URL": "https://www.icloud.com/shortcuts/1f40b16a82c04e989261dfb0054928d0",
  "Notes": "UpdateKit initial release.",
  "Release": "September 23, 2018"
}




Releasing an Update for Your Shortcut

There are a few steps you will need to take after developing an update to your Shortcut. These steps should be done in order to prevent any potential issues.

If your Shortcut is hosted on RoutineHub, you can use RoutinePub to upload new versions of your Shortcut directly from your iOS device with no need to edit files or own a web server. Follow the appropriate set of steps below to release your update. Bear in mind that RoutineHub shortcuts must be set to the Published status on the RoutineHub website in order to be updated via RoutinePub.

Self-Hosted
  1. Change the Current Version in your UpdateKit Dictionary
  2. Press the Share button on your Shortcut, then tap Copy iCloud Link (you can also AirDrop, iMessage, or otherwise share it to yourself to get the URL; you will want to have it on whatever device you use for updating your web server)
  3. Add your detailed release notes to your Release Notes file
  4. Modify your Update file to include the latest version number, short release notes, and the iCloud Link you copied in step 2
Using RoutinePub
  1. Change the Current Version in your UpdateKit Dictionary
  2. Press the Share button on your Shortcut, then tap Shortcuts » RoutinePub
  3. Select the Shortcut on your RoutineHub account that you wish to update from the list that is presented
  4. Enter your new version number and release notes when prompted