Why is usage of the downloadURL & updateURL keys called unusual and how do they work?

Question

I was reading GM's wiki to determine the difference between @downloadURL & @updateURL (which I didn't). But what confused me even more that both are unadvised:

It is unusual to specify this value. Most scripts should omit it.

I'm surprised by that as it's the only way for scripts to auto-update and I don't see why these keys shouldn't be used.

The wiki itself is pretty lacking and no other forum sources are advised, so I have to ask here. Also would appreciate more detailed info on these keys.

Ralina

Note that since 2017 these keys are (temporary) not supported and are ignored in Greasemonkey. https://mcmap.net/q/323637/-greasemonkey-script-not-updating – Amil

Answer 1

Use of those keys is discouraged mainly by Greasemonkey's lead developer. Most others, including the Tampermonkey team feel no need for such a warning.
Also note that those directives are not always required for auto-updates to work.

Some reasons why he would say that it was unusual and that "most" scripts should omit it:

1. In most all cases it is not needed, see how updates work and how those directives work, below.
2. Adding and using those directives are just more items that the script writer must check and maintain. Why make work if it is not needed?.
3. The update implementation and those directives have been buggy and, perhaps, not well implemented in Greasemonkey.
4. Tampermonkey, and other engines, implement updates, and those directives, in a slightly different manner. This means that code that works on Tampermonkey may fail on Greasemonkey.

Note that that wiki entry was made by Greasemonkey's lead developer (Arantius) himself; so it wasn't just wiki noise.

---

How updates work:

Script updates are conducted in 4 phases:

1. The enabled phase and/or "forced" updates.
2. The check phase.
3. The download phase.
4. The parse and install phase.

For this question, we are only concerned with the check and download phases. We stipulate that updates are enabled and that the updated script was valid and installed correctly.

When updating scripts, Greasemonkey (and Tampermonkey) download files twice:

1. The first download, controlled by the script's updateURL value, is just to check the file's @version (if any) and date -- to see if an update is available.

2. The second download, controlled by the script's downloadURL value, is the actual download of the new script to install. This download will only occur if the server file has a higher @version number than the local file and/or if the server file has a later date than the local file. (Beware that there are critical differences here between script engines.)

   See "Why you might use @downloadURL and @updateURL", below, for reasons why 2 file downloads are used.

---

How @downloadURL and @updateURL work:

@downloadURL merely overrides the default internal "download URL" location.
@updateURL merely overrides the default internal "update URL" (or check) location.
In most cases, there is no need to do this. See, below.

1. When you install a userscript, Greasemonkey automatically records the install location. No meta directive is needed. By default, this is where Greasemonkey will both check for updates and download any updates.
2. But, if @downloadURL is specified, then Greasemonkey will both check and download from the specified location rather than the stored location.
3. But, if @updateURL is specified, then Greasemonkey will check (not download) from the "update" location given.

So: @updateURL overrides both @downloadURL and the default location for checking operations only.
While: @downloadURL overrides the default location for both checking and downloading (unless @updateURL is present).

---

Why you might use @downloadURL and @updateURL:

First, there are 2 downloads and potentially 2 different locations mainly for speed and bandwidth reasons. Consider a scenario where a very large userscript has thousands of users:

• Those users' browsers would constantly hammer the host server checking to see if an update was available. Most of the time, one wouldn't be and the large file would be downloaded over and over again unnecessarily. This got to be a problem for sites like the now defunct userscripts.org.
• Thus a system developed whereby a separate file was created to just hold version (and date) information. So the server would now have veryLarge.user.js and veryLarge.meta.js
• veryLarge.meta.js would be updated (by the developer) every time the userscript was and would just contain the Metadata Block from veryLarge.user.js.
• So the thousands of browsers would just repeatedly download the much smaller veryLarge.meta.js -- saving everybody time and saving the server bandwidth.

Nowadays, both Greasemonkey and Tampermonkey will automatically look for a *.meta.js file, so there is normally no need to specify one separately.

So, why explicitly specify @downloadURL and/or @updateURL? Some possible reasons:

1. Your script can be installed multiple ways or from multiple sources (cut and paste, locally copied file, secondary server, etc.) and you only want to maintain one "master" version.
2. You want to track how many initial and/or upgrade downloads your script has.
3. @downloadURL is also a handy "self documenting" way of recording/conveying where the user got the script from.
4. You want the *.meta.js file on a different server than the userscript for some reason.
5. Possibly http versus https issues (need to dig into this some day).
6. You are a bad guy and you want the script to update a malicious version at some future date from a server that you control -- that is not where the script was installed from.

Some differences between Greasemonkey and Tampermonkey:

^{(Warning: I haven't verified all of this in a while. Subject to change anyway as Tampermonkey is constantly improving (and Greasemonkey changes a lot too).)}

1. Tampermonkey requires a @version directive on both the current and newer file. This is how Tampermonkey determines if an update is available.

   Greasemonkey will also use this method, so always include @version in scripts you might want to auto-update.

   However, Greasemonkey also requires that the update file be newer. And if no version is present, Greasemonkey will just compare the dates only. Note that this has caused problems in Greasemonkey in the past and also foolishly assumes that many different machines are accurately synched with the correct date and time.

2. Greasemonkey will only update from https:// schemes by default, but can optionally be set to allow http:// and ftp:// schemes.

3. Both engines never allow updates from file:// schemes.

Fenugreek

Thanks for an extensive answer. I read a mention of *.meta.js in the description if @updateURL, but wasn't sure how to use it as there were no details. Of course, I'd prefer users to update form original source rather then some (theoretical) side location, but if that really can cause problems, I'll avoid these keys. – Ralina

Tampermonkey does allow updates from file:// schemes if the option Allow access to file URLs is enabled. It’s configurable at the level of the Chrome extension. – Seena

@Synoli, you got any proof of that? I had tested updates with that option checked at the time of this answer. – Fenugreek

@BrockAdams This is how it works for me: To install a new script, open TamperMonkey, go to the Utilities tab, paste your file:// URL into the URL field, then click Import. To update a script, just do exactly the same. (If you don’t like memorizing URLs, you can always open the Edit - <plugin-name> tab; the Update URL field will offer the URL for you to copy). After you click Import the usual window will pop up and check whether the version number has changed; if yes, it will offer you an Update button. Otherwise, the button will say Reinstall but the effect is the same. – Seena

@Synoli, that is not using the @downloadURL nor the @updateURL directives. Nor is it auto updating which is the whole point! You are just manually updating and not even the easiest way. For example, you can just drag&drop the updated file to almost any Chrome tab, to accomplish the same thing. – Fenugreek

@BrockAdams Dragging my .js file onto a Chrome tab has never summoned TamperMonkey on my machine. Instead, it only displayed the JS content in the browser. The same happened when I pasted the file URL into the omnibox. I was just wondering why either would work for you but not for me; this led me to figure out that the script definitely needs a .user.js extension, not just .js. Neat! (I would have expected TamperMonkey not to rely on the file extension.) By the way, I was specifically referring to point #3 of your answer; I didn’t realize you meant auto-updating. Thanks for clarifying! – Seena

To add to your reasons for specifying both fields: If you host your scripts on GitHub Gists you need to specify both values, since installing the script by clicking on "Raw" will only open a URL pointing to a specific "commit" of the gist. In other words, the content of the default updateURL will never change, even when the gist is updated. To get around this, the downloadURL and updateURL have to be changed to the URL of the gist without the "commit" hash, which will then always point to the latest version and the script will update as it should. – Hoenack

@BrockAdams I drag & drop my update.js to chrome new tab, it only show me script content...but not update of tampermonkey. I do not know why – Tew