Gear Userscript Add-on Documentation

Gear's add-on engine is a new high-performance mobile Userscript engine that is compatible with Tampermonkey and Greasemonkey Userscript.

The basic Userscript demo

// ==UserScript==
// @name         {{name}}
// @version      0.1
// @description  New Userscript
// @author       You
// @match        *
// @run-at       document-end
// @grant        none
// ==/UserScript==

(function() {
    'use strict';
    // Your code here...
    
})();

Userscript headers

GM APIs

unsafeWindow

The shadow window object for full access to the page's JavaScript functions and variables.

Storage
Gear provides a high-performance storage engine. You save your script data here. It's standalone with the website and will be cleared up when the script is uninstalled. You can use those functions to save and delete data from the storage.
Set value to the storage.

GM_setValue(name, value) : void
GM.setValue(name, value) : Promise
Get value from the storage. You can provide a default value if nothing is found in the storage.

GM_getValue(name, defaultValue) : any
GM.getValue(name, defaultValue) : Promise
Delete a value from the storage.

GM_deleteValue(name) : void
GM.deleteValue(name) : Promise
List an array of keys from the storage.

GM_listValues() : array
GM.listValues() : Promise
Add a value listener to detect value change, and return the listenerId that you can remove by calling GM_removeValueChangeListener(listenerId).
GM_addValueChangeListener(name, function(name, oldValue, newValue, isRemote)) : string
Remove the value listener by listenerId.
GM_removeValueChangeListener(listenerId)
Insert a new CSS style to the head element.

GM_addStyle(style) : void
GM.addStyle(style) : void
Insert a new element to the document or parent node, and returns the element itself.

GM_addElement(parentNode, tagName, attributes) : node
GM_addElement(tagName, attributes) : node

GM_addElement('script', {
    src: 'https://abc.com/script.js',
    type: 'text/javascript'
});

GM_addElement(
    document.head,
    'script',
    {
        src: 'https://abc.com/script.js',
        type: 'text/javascript'
    }
);
Output log message to the console.

GM_log(message) : void
GM.log(message) : void
Get the raw content predefined from @resource.
GM_getResourceText(name) : String
Get the base64 encoded URI predefined from @resource.

GM_getResourceURL(name) : any
GM.getResourceUrl(name) : Promise
Register a menu command that can access from the running add-on menu.

GM_registerMenuCommand(name, fn, accessKey) : int
GM.registerMenuCommand(name, fn, accessKey) : int
Unregister the menu command by its id.

GM_unregisterMenuCommand(id) : void
GM.unregisterMenuCommand(id) : void
Open a new tab with options.

GM_openInTab(url, options) : TabObject
GM_openInTab(url, loadInBackground) : TabObject

TabObject = {
    // The tab is closed or not.
    'closed': Bool,

    // The event handler will be called when the tab is closed.
    'onclose': Function,

    // The method to close the newly opened tab.
    'close': Function
}
Create a new xmlHttpRequest.

GM_xmlhttpRequest(options) : RequestObject
GM.xmlHttpRequest(options) : RequestObject

// Contains abort() to cancel the request. The onabort handler will be called.
RequestObject = {'abort': Function}

var request = GM_xmlhttpRequest({
    // @required string: The destination URL, support URL relative path.
    "url": "https://www.example.com",

    // string (GET|POST|HEAD): The request method.
    "method": "GET",

    // Key-value object: The request header.
    "headers": {
        "referer": "value"
    },

    // string | ArrayBuffer | Blob | DataView | FormData: The data will be sent with the request.
    "data": "foo",

    // Key-value object: The cookie data with the request.
    "cookie": {
        "foo": "bar"
    },

    // boolean: Should send data in binary mode.
    "binary": false,

    // boolean: Should send data without cache.
    "nocache": false,
    
    // boolean: Should revalidate the cached content.
    "revalidate": false,

    // int: The timeout in ms
    "timeout": 2000,
    
    // any: The value which will be added to the response object.
    "context": [],

    // string (text|json|blob|arraybuffer|document): The response data type.
    "responseType": "text",

    // string: The MIME type for the request.
    "overrideMimeType": "text/plain",

    // boolean: Should send the request without cookies if true.
    "anonymous": false,
    
    // string: The user name for request authentication.
    "user": "foo",
    // string: The password for request authentication.
    "password": "pwd",
    
    // The event handlers.
    "onabort": (event) => void,
    "onerror": (event) => void,
    "onload": (event) => void,
    "onloadend": (event) => void,
    "onloadstart": (event) => void,
    "onprogress": (event) => void,
    "onreadystatechange": (event) => void,
    "ontimeout": (event) => void,

    // The event object from handlers will contain the following attributes:
    // "finalUrl" - The final URL after all redirects from where the data was loaded.
    // "readyState" - The ready state.
    // "status" - The request status.
    // "statusText" - The request status text.
    // "responseHeaders" - The response headers.
    // "response" - The response data as an object if details.responseType was set.
    // "responseXML" - The response data as an XML document.
    // "responseText" - The response data a plain string.
});

// Call this method to cancel the request.
request.abort()
Create a new download task.

GM_download(options), GM_download(url, name) : RequestObject

// Contains abort() to cancel the download request. The onabort handler will be called.
RequestObject = {'abort': Function}

var request = GM_download({
    // @required string: The destination URL, support URL relative path.
    "url": "https://www.example.com/file.mp3",

    // @required string: The file name will be saved.
    "name": "my.mp3",

    // Key-value object: The download request header.
    "headers": {
        "referer": "value"
    },

    // boolean: Should show the save as prompt. 
    "saveAs": false,

    // int: The timeout in ms
    "timeout": 2000,

    // The event handlers.
    "onerror": (event) => void,
    "onprogress": (event) => void,
    "ontimeout": (event) => void,
    "onload": (event) => void,

    // The event object from handlers will contain the following attributes:
    // "finalUrl" - The final URL after all redirects from where the data was loaded.
    // "readyState" - The ready state.
    // "status" - The request status.
    // "statusText" - The request status text.
    // "responseHeaders" - The response headers.
    // "response" - The response data as an object if details.responseType was set.
    // "responseXML" - The response data as an XML document.
    // "responseText" - The response data a plain string.
});

// Call this method to cancel the download request.
request.abort()
Set value to the clipboard.

GM_setClipboard(data, info = 'text|html') : void
GM.setClipboard(data, info = 'text|html') : void
Get the tab object.

// This function is unsupported.
GM_getTab
Save the tab object.

// This function is unsupported.
GM_saveTab
Send notification.

// This function is unsupported.
GM_notification
Output script information.

// You don't need to declare this API on @grant to read this value.
console.log(GM_info)

[
    "script": [
        "uuid": string,
        "name": string,
        "author": string,
        "description": string,
        "namespace": string,
        "homepage": string,
        "version": string,
        "icon": string,
        "icon64": string,
        "excludes": array,
        "includes": array,
        "matches": array,
        "requires": array,
        "resources": object,
        "run-at": string,
        "updateURL": string,
        "downloadURL": string,
        "supportURL": string,
    ],
    "downloadMode": string = native,
    "scriptMetaStr": string,
    "scriptSource": string,
    "scriptUpdateURL": string,
    "scriptHandler": string = Tampermonkey,
    "isIncognito": bool,
    "version": string
]

API granting group

In order to prevent the lack of some related APIs when declaring, when you are declaring any APIs in the following groups, all related APIs will also be granted. API names started with GM. or GM_ are the same.

Compatibility Issues for iOS

On iOS, all web browser render engines are using the WKWebView framework based on WebKit for displaying web content. That means all web browsers on iOS including Safari, will have the same JavaScript engine for running JavaScript code. Although WKWebView and desktop browsers like Chrome, and Microsoft Edge are WebKit-based and Userscript can run on Gear just like a desktop without having significant modification, there are still some different compatibility issues that need to check out.