Script AutoUpdaters: How to provide users with updates

Written by IzzySoft — Last update Nov 13, 2009

10 points

Intro

Sometimes the Scriptwright asks him/herself: How do I promote updates of my scripts? How to notify the users they should update? In fact, there are not only some possibilities to do this - but also a bunch of scripts helping you with it. This guide will give you an overview about methods used, as well as list and compare a selection of scripts using these different approaches.

Methods

Theoretically, there are at least five approaches:

  1. Hope the user visits your scripts page and notices the update
  2. Encourage the users to add your script to their favorites, so they get a notice of the updates from USO
  3. Send a notification to the users manually
  4. Have the users install a special update-script which checks for updates to locally installed scripts
  5. Include code with your script to check for updates
  6. @require some other script doing so for you

It is quite obvious that 1. is a naive approach, 2. is an unforeseeable case, and 3. exists only in theory - which sorts out 50% and leaves us with three approaches to discuss:

ApproachProContra
Separate local script
  • no changes are required to your script
  • will keep all locally installed scripts checked
  • no dependencies to worry about
  • you have no influence whether any of your users runs such a script
  • ...or if they ever notice your updates
Code copied into your script
  • you can check it thoroughly, and don't need to worry about its availibility later on (since the code is included with your script)
  • you have to maintain that code yourself, and keep an eye on possible updates to this
  • it may clutter your script, increase its size, and make it less easy to maintain
@required updater script
  • requires only minimal changes to your script (usually)
  • keeps your script clear and maintainable
  • no worry for updates, since they will be installed along when the user installs/updates your script
  • when the @required script becomes unavailable, your script is no longer working for new installs/updates - until you remove the @require statement and all calls to that scripts code
  • if that script gets broken, it is possible to have side-effects to your script

As you see, there is no clear favorite: all three approaches have their pros and cons. Nothing comes without a risk - but hey: no risk - no fun, right? For you as the Scriptwright, there are always two choices: You can leave the issue to the user (first approach) - or decide to care for it yourself. If you decide for the latter, again two choices: either write your own code - or use something existing. In the latter case, again two choices: include that code within your script - or use @require to select an external source. All quite clear, right? So let's stop the preamble, and look at some examples for our three approaches discussed:

Available scripts to the 3 methods discussed

User-side separate scripts

ScriptGUIUserSide config
Script Updater by alien_scum??
Script AutoUpdater by Eyal Sohavia about: URLsome

Nothing to explain here - the choice is completely on the users side.

Code to copy into your script

ScriptSetupPropsGUIUserOptsMLComments
User Script Updates by Richard Gibsonsome worksome??NoNot easy to set up on first glance, though highly configurable. Requires to copy a large script into yours. Last update 2006.
UserScript Update Notification by Seifereasy1Yes?No
AutoUpdateTest by TastyFlySoupeasyintervalJS AlertsNoNoSimply checks for updates.
Script Update Checker by Jaretteasy-JS Confirmtoggle On/OffNoSimply checks for updates. Hardcoded interval can be adjusted on code copy.
Userscript Auto-Update Add-in (NOT FOR INSTALL) by psycadelikeasy?JS Confirmforced checkNorequires Google Docs to store its values
SelfUpdaterExample by ScroogeMcPumpeasya lotJS Confirm?No
Script Version Checker by littlesparkOK-JS Confirmforced checkNo
easy userscript updater snippet by thomdeasysomeYes (DOM)-No
Easy Update Code by shoecreamummyesnot provided-Noyou have to provide your own callback handler (i.e. what to do when an update was found)
[deleted script] by devnull69OK-JS Confirmforced checkNo

Quite a lot of scripts available for this approach. None of them provides a multi-language GUI (column "ML") - but since you have to copy all that code into yours, you are free to either chose the language for user interaction yourself (by editing that code), or even provide some multi-language stuff (which would require some additional work). The integration into your script (column "Setup") requires more work then for the scripts in the next section - but already varies within this category from "easy" to "can get a bit messy".

Another point to take into consideration are whether you want to provide flexibility to the user (see column "UserOpts") and/or decide yourself what should be done and how. For the latter, the "Props" column may be worth to check: How easy is it to change things like e.g. the update interval? Of course, since you either copy the entire code into your script, you can also modify it inside the script code - but having a simple setting available makes it more easy.

Though functionality goes first in this context, the GUI provided to the user may to be considered as well. Most scripts in this section work with simple JavaScript "Confirms" - which are sufficient for the issue: the user may decide to update or not. While being sufficient from this point, JS Confirms/Alerts have one disadvantage: the fact that they immediately take the focus and are somehow "system modal" (you have to handle them before you can continue with whatever you was doing in the browser) may be annoying. A DOM GUI, on the other side, just blends in into the page the script was running on - but neither steals the focus, nor interrupts you from your actions on other browser tabs. Of course, the page it blends into will be overlayed - but that's far less annoying. Unfortunately, only one candidate in our above list offers this way of user communication.

Scripts to be used via @require

Just a word in advance, though I guess it's no secret: A script intended to be used via @require can of course also be directly included in your code. See the pros and cons about it above.

ScriptextSetupPropsGUIUserOptsMLComments
usoCheckup - DOMNotify Theme by Marti (see also Martis guide)Yesvery easymanyJS Confirm or nice DOM bartoggle On/OffYesmany parameters. Additional UserMenus can be designed manually. Requires to create an external Account (3rd party website).
Marti kept his script(s) modular, so there's a basic usoCheckup with different themes - the script linked here is one of those themes (a very nice one, besides).
Userscripts Updater by lazyttrickYesvery easy2nice (DOM)good?Nice user GUI popup also allows to change interval, toggle the script On/Off, influence design. Plugs into USO (to import other scripts). Default interval configurable. No external Account required.
GM Script Update Control by Sylvain ComteNoeasysome???You may use @require or copy all, but have to configure at least a few lines.
Another Auto Update Script by sizzlemctwizzleNoeasyintervalGMInsttoggle On/Off, forced checkNoSimply checks for updates. Directly calls GM Installer when an update was found.
Includes : CheckForUpdate [DISCONTINUED] by w35l3yNoOKa lotJS Confirmforced checkNoConfiguration done via a bunch of additional MetaTags (most of them optional)
GM_ScriptUpdater by IzzySoftNoeasyyessimple (DOM)interval, language; more via APIYesOptional recursive check (for other scripts @required by your script), extensible with own translations, API to call if you want to provide user configuration (e.g. via GM_config Extender by the same author), GM menus to toggle On/Off, force an immediate check, etc.
Userscripts - AutoUpdater by BuzzyYeseasy-nice (DOM)intervalNoYou must provide the current version number as a parameter on call
[deleted script] by undefined_userNoeasyYesnice (DOM)interval?Many possibilities to configure, e.g. to show script history. You must provide the current version number as a parameter on call

Here the list is as long as in the previous section - and we get even more options. Some of the scripts already offer a multi-language GUI to please users with different native languages, some even offer an API to extend these translations easily for languages not yet covered. Something that may impress your users almost as much as a nice GUI. A propos GUI: see also the paragraph on JavaScript Confirm/Alert boxes versus DOM GUI in the previous section. With the @required scripts, half of them offer the DOM way - which I personally find great. Variants go from some easy DOM interface to real stylish ones - you've got the selection.

An important point here you find noticed in the second column: Some of the scripts are hosted externally. This means, if their service is unreachable at the time the user goes to install/update your script, installation will fail (or be broken). How likely this issue is, depends on the reliability of the external provider used. One script even requires you to register a separate account on its side - it's up to you to decide if you like this.

Integration into your script (column "Setup") is - with one exception, maybe - done quite easily with these @required scripts. From this point, the question of flexibility is a bit stronger than above, since you cannot adapt the code of the updater script directly. Which means, you need to take a closer look at the "Props" (how to influence things from within your code) and "UserOpts" (what can the end-user do to change the updaters behaviour) columns. The least to be provided to the end-user should be the possibility to "toggleOn/Off" - or changing the interval for updates. OK, this is my personal view.

The last question is "flexibility versus simplicity": Do you simply want some update mechanism to be integrated easily, and don't care about all the "nice to haves" like options and GUI - or do you want high flexibility to offer to the user? Does your script already provide a configuration interface, and you want the updater to integrate smoothly with it (in this case, a provided API may be a big plus)? Above table should make it easier for you to pick the updater fitting best to your requirements.

Epilogue

This guide does not claim to be complete (in fact, I may extend it at some point) - neither are the lists of scripts. With the hundreds of thousands of scripts available here on USO, it is very likely I did not find all of the update scripts. But at least, this guide should have shown you some aspects to consider, gave you an idea about different approaches, and makes it easier for you to find the right updater for your script(s).

If you think I missed to cover some issue, or an important script that should be listed here: just send me a PM with the information you miss; credit will be given to you. Of course, your comments and good ratings are welcome as well :-)

Further readings

For more information on this topic, the following links may be of interest for you (thanks to Marti for providing this information):

Userscripts Updaters
An USO group for Scriptwrights interested in this topic. Holds a collection of scripts as well as discussions on the topic.
usoCheckup group
An USO group for Martis usoCheckup collection (see above).
usoCheckup guide
The guide for Martis usoCheckup
USO Updater guide
An USO guide for Tims updater script

Scripts mentioned in guide

Users mentioned in guide