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
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!
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 on your website, 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.
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.
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.
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
After the user dismisses this alert, they will see a menu with four options:
iCloud URLto your latest update and allow users to install it immediately.
Release Notes URL. If this option is selected, the page will open in a Safari View Controller and users will see this menu again upon exiting the page, except they will not have the option of viewing the release notes page again (unless they cancel out and restart the update check).
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
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 this video.
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
Updatefile (discussed below).
Release Notespage for your Shortcut (discussed below).
1.0.1as equal to
1.0. I recommend using only one decimal in your version numbers, if you use any.
1.10would be seen as equal to
1.1and thus would not prompt the user to update. To avoid this, you should use only one digit beyond the decimal. Unfortunately, this means that in many cases a Facebook-style
3.0version number system for even minor updates might be the most suitable for older versions of UpdateKit.
2.01and then later release version
2.2, users in countries that use commas in place of decimals will not be able to get
2.2or any other update. This is because their Shortcuts app ignores decimals when doing math calculations, causing
2.2to render as
2.01to render as
201where the number
201is always greater than
22. This causes UpdateKit to believe it is running a newer version and not show the available update. If only one digit past the decimal is used (and used consistently --
2), then UpdateKit will still work in these countries because it will see the number
2.1as being greater than the number
RoutineHub is an online gallery of user-submitted
Shortcuts that has partnered with UpdateKit to provide an all-in-one solution for publishing your
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
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
RoutineHub ID would be
If your users have an older version of UpdateKit installed that does not support
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.
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
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 Versionsetting. If called through the standard method, it will still report back the version number, but it will be included in a
Dictionarywith the key
UpdateKit Version. For more details on this change, see the section on reading UpdateKit's
Exit Modevariable below.
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
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.
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
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,
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
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
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
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
True as a
Text element. Pass this
Dictionary to the
Run Shortcut action. Then receive the output from the
Run Shortcut action, feed it
If action set to
Less Than with a value of
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
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.
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
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
Exit Modewill tell your Shortcut which option the user selected during the regular update flow. There are six possible results. You can use an
Ifaction to check the
Exit Modereturned by UpdateKit for your Shortcut and respond accordingly.
Installbutton and opened the iCloud URL for your update. It is not possible for UpdateKit or any Shortcut to detect whether they tapped the link on the iCloud page to install the update, but if they did not you should generally handle that situation the same way you would if they had tapped the install button.
Skip This Version Foreveroption when prompted to update your Shortcut.
Remind Me Lateroption, which runs the rest of your Shortcut without installing any updates. They will be prompted to install the available update again next time your Shortcut runs.
Check Versionfunction while offline, and will return the expected result of only the UpdateKit version number.
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
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.
Versionkey is the version number of the latest version to be released. See the implementation section for version number limitations.
URLkey points to the iCloud sharing URL for the latest version (details on how to get are in the section on releasing an update).
Noteskey is a short update note that indicates what changes have been made. This will be displayed in the update alert when a user is informed of a new version, so it is best to keep it brief. You can expand on the changes on your full change log page.
Releasekey contains the release date for the latest version. This is not currently used in UpdateKit and may be formatted however you want. However, do note that if a future UpdateKit release begins using this (likely for displaying update release dates to users, not for any comparison), you may want to have a human-friendly date format.
"Notes": "UpdateKit initial release.",
"Release": "September 23, 2018"
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.
Current Versionin your UpdateKit
Sharebutton 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)
Updatefile to include the latest version number, short release notes, and the iCloud Link you copied in step 2
Current Versionin your UpdateKit
Sharebutton on your Shortcut, then tap