userScripts

Use this API to register user scripts, third-party scripts designed to manipulate webpages or provide new features. Registering a user script instructs the browser to attach the script to pages that match the URL patterns specified during registration.

This API offers capabilities similar to scripting but with features suited to handling third-party scripts.

Permissions

To use this API, you need the userScripts permission and host_permissions for sites where you want to run scripts. However, the approach to enabling the use of this API varies between browsers:

• In Firefox, userScripts is an optional-only permission declared in the optional_permissions manifest key. Your extension must check that the permission has been granted by checking the availability of the userScripts API namespace or using permissions.contains() and, if not, request it using permissions.request().
• in Chrome, userScripts is an install time requested permission declared in the permissions manifest key. However, to enable use of the API, users must turn on the developer environment in Chrome.

Execution worlds

When a user script is registered or updated (using userScripts.register() or userScripts.update()), your extension can set it to run in an isolated USER_SCRIPT world or the MAIN world.

A USER_SCRIPT world provides an isolated execution environment that isn't accessible to a host page or other extensions. This isolation is similar to a content script environment, except USER_SCRIPT worlds cannot access extension APIs.

User scripts can share a USER_SCRIPT world or isolate themselves in a USER_SCRIPT world by setting the worldId property of RegisteredUserScript. The API enables an extension to configure a content security policy (CSP) for a USER_SCRIPT world using userScripts.configureWorld().

In the MAIN world, host pages and other extensions can see and access running user scripts. The worldId property is not supported for MAIN worlds.

These execution world values are defined in ExecutionWorld.

Messaging

Like content scripts and other extension scripts, user scripts communicate with other parts of an extension with messages using runtime.sendMessage() and runtime.connect(). However, extensions receive messages using the dedicated runtime.onUserScriptMessage and runtime.onUserScriptConnect. Dedicated handlers are used as they make it easier to identify messages from user scripts, which are a less-trusted context.

To enable messaging APIs, call userScripts.configureWorld() with the messaging argument set to true before registering a user script.

browser.userScripts.configureWorld({
 messaging: true,
});

Extension updates

When an extension updates, user scripts are cleared. To restore scripts, add code to the extension's runtime.onInstalled event handler that responds to the "update" reason.

Types

userScripts.ExecutionWorld

The execution environment for a script injected with userScripts.register() or userScripts.update().

userScripts.RegisteredUserScript

An object returned by getScripts() representing registered user scripts and used as input to register() and update().

userScripts.ScriptSource

The code or a file source for a user script.

userScripts.UserScriptFilter

A list of user scripts to be processed by userScripts.getScripts() or userScripts.unregister().

userScripts.WorldProperties

The configuration of a USER_SCRIPT execution environment.

Methods

userScripts.configureWorld()

Configures a USER_SCRIPT execution environment for the extension.

userScripts.getScripts()

Returns user scripts registered by the extension.

userScripts.getWorldConfigurations()

Returns all the extension's registered world configurations.

userScripts.register()

Registers user scripts for the extension.

userScripts.resetWorldConfiguration()

Resets the configuration for a USER_SCRIPT world registered by the extension.

userScripts.unregister()

Unregisters user scripts registered by the extension.

userScripts.update()

Updates user scripts registered by the extension.

userScripts.execute()

Injects a user script into a target context.

Example extensions

• userScripts-mv3

Browser compatibility

See also

• browser.scripting