To use this API, you need theuserScripts permission andhost_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 anoptional-only permission declared in theoptional_permissions manifest key. Your extension must check that the permission has been granted by checking the availability of theuserScripts API namespace or usingpermissions.contains() and, if not, request it usingpermissions.request().
• in Chrome,userScripts is an install time requested permission declared in thepermissions manifest key. However, to enable use of the API, users mustturn on the developer environment in Chrome.

When a user script is registered or updated (usinguserScripts.register() oruserScripts.update()), your extension can set it to run in an isolatedUSER_SCRIPT world or theMAIN world.

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

User scripts can share aUSER_SCRIPT world or isolate themselves in aUSER_SCRIPT world by setting theworldId property ofRegisteredUserScript. The API enables an extension to configure a content security policy (CSP) for aUSER_SCRIPT world usinguserScripts.configureWorld().

In theMAIN world, host pages and other extensions can see and access running user scripts. TheworldId property is not supported forMAIN worlds.

These execution world values are defined inExecutionWorld.

Like content scripts and other extension scripts, user scripts communicate with other parts of an extension with messages usingruntime.sendMessage() andruntime.connect(). However, extensions receive messages using the dedicatedruntime.onUserScriptMessage andruntime.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, calluserScripts.configureWorld() with themessaging argument set totrue before registering a user script.

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

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

userScripts.ExecutionWorld

The execution environment for a script injected withuserScripts.register()oruserScripts.update().

userScripts.RegisteredUserScript

Anobject returned bygetScripts() representing registered user scripts and used as input toregister() andupdate().

userScripts.ScriptSource

The code or a file source for a user script.

userScripts.UserScriptFilter

A list of user scripts to be processed byuserScripts.getScripts() oruserScripts.unregister().

userScripts.WorldProperties

The configuration of aUSER_SCRIPT execution environment.

userScripts.configureWorld()

Configures aUSER_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 aUSER_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-mv3

• browser.scripting