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!
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.
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 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.
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 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
RoutineHub ID would be
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.
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 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.
Dictionarywith a single key,
Check Version, and the value
Trueas a text string. It is important that you use a
Textelement and not a
Booleantype for this, as it will change the value that is passed into UpdateKit, and UpdateKit will not properly handle the
Booleantype. Once you have defined this single-item
Dictionary, pass it into UpdateKit using the
Check Version: Truevalue, 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 Shortcutaction with an
Ifaction and check to see if the returned version number is less than your required version. If the
Less Thancheck 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
1,3as the required version of UpdateKit,
1.3and later will still return the expected result, while
1.2will accurately fail to pass the check. You do not need to worry about converting commas to decimals or vice versa for this comparison.
Get My Shortcutsaction followed by an
Ifstatement to determine if the list returned by that action
Otherwiseaction for this
Ifstatement 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 Shortcutaction no matter the outcome (for example, if the user chooses a menu item, every menu item should eventually end with an
Exit Shortcutaction) so that the rest of your Shortcut will not be executed if the dependency fails. You can omit this entire
Otherwiseblock 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).
Ifstatement, create a
Dictionarywith the key
Check Versionand the value
Textelement. Pass this
Run Shortcutaction. Then receive the output from the
Run Shortcutaction, feed it into another
Ifaction set to
Less Thanwith a value of
Ifstatement, include another copy of the failure result from the step above (including an
Exit Shortcuton each possible ending), indicating the reason for the failure and prompting the user to install UpdateKit or exit the Shortcut. You can remove the
Otherwiseportion of this
Ifaction, as we will not be needing it. If UpdateKit's current version is greater than the required version, your Shortcut will simply bypass this
Ifand move on to the next step in the workflow.
Ifstatements. It should be a top-level action (that is, not indented in the editor, not at the top of the action list).
Check Versionkey 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 URLalong with the
Check Versionkey. UpdateKit 1.0 will attempt to fetch an update for your Shortcut and then return the word
UpdateKitas 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.
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
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 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.
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