Update Notifier for Greasemonkey User Scripts

As of December 20, 2009, this script is deprecated as I am moving my scripts to usoCheckup. This script may be removed at any time. The following documentation remains for current users.

This page contains information for developers on using my update notifier for Greasemonkey user scripts. It's a JavaScript function that you can reference from your own scripts. With a small amount of work on your part, it can inform the users of your scripts of updates almost immediately.

This document refers to version 14 of the Update Notifier, unleashed to the world on October 12, 2009. It is released under the GNU GPL (version 3 or later), and as such, it comes with no warranty. Some of my older scripts contain earlier versions of the Update Notifier. They are forward-compatible with later versions. However, I recommend using the latest release, which can be found here.

Advantages

Why not choose another update notifier? Because with this one, you can

  • use it easily in any kind of script
  • check for updates without downloading a whole copy of the script (result: more frequent checks, less bandwidth usage)
  • allow users to postpone or turn off checking for updates
  • tell copies of your script to stop checking for updates

How It Works

The Update Notifier is a JavaScript function that is referenced a Greasemonkey user script. When the Update Notifier is run, it checks to see whether a certain interval has elapsed since it last checked for updates. If the interval has elapsed, it loads a text file hosted on a remote server. The text file either gives the latest version number of the script or says that the script will no longer be updated.

If it gives a version number that is higher than the version that the user is running, the Update Notifier will display a message at the top of the current web page:

Update notification

The first option is a link to the script's home page, where the user can review changes and, if desired, upgrade. The second option sets the Update Notifier not to notify the user of updates until the next version is released. The third option sets the Update Notifier never to check for updates. The third option simply closes the notification box; if the second or third options haven't been chosen, it will be displayed again after the specified interval has elapsed.

If the text file indicates that the script will no longer be updated, the Update Notifier will stop checking for updates. It may either do this quietly or display a message with a link where users can find more information:

Non-update notification

Using It in Your Scripts

To use the Update Notifier in your own script, your script must be licensed under the GNU GPL, version 3 or later.

You will need access to a web server that can host text files. Prevent the caching of them for too long if you can. I use the following .htaccess rule, but I'm not sure how well it helps. In any case, the amount of traffic the server will receive from this script is (probably) negligible.

<FilesMatch "\.txt$">
Header set Cache-Control "max-age=3500, must-revalidate"
</FilesMatch>

Add the following single line to your script's metadata block:

// @require http://www.theworldofstuff.com/greasemonkey/updatenotifier.js

Within the code, include the following function:

updateNotifier(scriptName, scriptURL, scriptVersion, updateURL, updateInterval);

For information on the function's arguments, see "Parameters" below.

Parameters

The Update Notifier function uses five parameters that can be unique for each script:

scriptName
A string. The name of the script.
scriptURL
A string. I recommend that this be the URL of a page about the script rather than the URL of the script itself.
scriptVersion
A number. The version of the script in which the Update Notifier is placed. Each scriptVersion must be numerically greater than the last. (I may change this in the future, but it would break forward-compatibility.)
updateURL
A string. The URL of the text file that gives the latest version number of the script.
updateInterval
A number. The number of seconds that should elapse between checking for updates.

Text File Syntax

The following examples represent options available for the text file. There are no spaces before, between, or after anything.

0.2
Indicates to running copies of the Update Notifier that the latest version is version 0.2; if an upgrade is necessary, display for the user a link to scriptURL as given in the script.
0.2;http://www.example.com/newscripturl.html
Same as above, but instructs the Update Notifier to change scriptURL to the URL given. (Include the new URL in the text file for as long as possible to ensure that users who are slow to upgrade will eventually be able to do so.)
-
Tells the Update Notifier to silently stop checking for updates.
-;http://www.example.com/explanation.html
Tells the Update Notifier to stop checking for updates and display to the user a link to the given URL, which may explain why the script is no longer being developed or suggest alternative scripts.

Privacy

In having scripts "phone home" periodically, I have tried to minimize the privacy issues involved. The GM_xmlhttprequest for the text file sends only two headers, which indicate that the user agent is Greasemonkey and that plaintext responses should be accepted. No information about what pages users visit or the contents of those pages is transmitted. The only information you could get this way are IP addresses, which are good for very little except to say "Someone in country X ran this script Y times today." In case a user objects even to this, he or she can stop the Update Notifier from contacting the remote server by clicking "Turn off these notifications" when being told of an update, by toggling checkForUpdates to false in about:config, or by simply removing the updateNotifier function call in the script.

Contact

If you have any other questions about using the Update Notifier, contact me.

Changelog

Version 14 (October 12, 2009)
The current Unix time is added to the updateURL as a query string, so the text file is never cached.
Version 13 (September 27, 2009)
Updated to be used with the @require key, introduced in Greasemonkey 0.8.20080609.0 (June 12, 2008).
Version 12 (June 19, 2008)
Increased the z-index of the notification box.
Version 11 (May 30, 2008)
Gives the user the option to stop being notified of updates until the next version of the script is released.
Version 10 (May 19, 2008)
The first version intended for general use.

Last updated September 27, 2009
Created May 7, 2008

Get E-mail Updates

Sub­scribe now, get an e-mail for every new post. No spam, I pro­mise.

Recently on Twit­ter

“It's a beau­ti­ful day, and Kate is here!” (5 days ago)

Fol­low @the­world­of­stuff

RSS

Sub­scribe in your favor­ite reader.

Blog­roll

Stan­dards Com­pli­ance

This page con­sists of valid XHTML + RDFa with valid CSS 3.