6.1. Storing and retrieving persistent data [Dive Into Greasemonkey]

6.1. Storing and retrieving persistent data

Greasemonkey defines two functions, GM_setValue and GM_getValue, that allow user scripts to store and retrieve “private” data that only the user script can access. (Other scripts can't access them, not even other user scripts.) You can use these functions to store script-specific configuration, to maintain a cache that persists between pages, or to keep a permanent activity log.

Data stored with GM_setValue and retrieved with GM_getValue are similar to browser cookies, but there are important differences. Both are stored on the local machine, but while cookies are domain-specific and can only be accessed from their originating domain, Greasemonkey configuration values are script-specific and can only be accessed by the user script that created them (regardless of the URL that the user script is currently running on). And unlike cookies, user script data are never transmitted to remote servers.

GM_setValue stores a script-specific configuration value, and GM_getValue retrieves it.

function GM_setValue(key, value);

function GM_getValue(key, defaultValue);

key argument is a string of no fixed format. value may be a string, boolean, or integer. The defaultValue argument of GM_getValue is optional; if present, it will be returned if the requested key does not exist. If no defaultValue is given and the requested key does not exist, GM_getValue will return undefined.

These functions were introduced in Greasemonkey 0.3. You should test whether they exist and degrade gracefully if they do not.

Dive Into Greasemonkey

6.1. Storing and retrieving persistent data

Further reading

See also