scripting API
Use the scripting API to execute script in different contexts.
Permissions
Functions
executeScript(injection)
Injects a script into a target context. The script will be run at document_idle.
Parameters
The details of the script which to inject.
Return type (Promise)
array of InjectionResult
Required permissions
getRegisteredContentScripts([filter])
Returns all dynamically registered content scripts for this extension that match the given filter.
Parameters
An object to filter the extension’s dynamically registered scripts.
Return type (Promise)
array of RegisteredContentScript
Required permissions
insertCSS(injection)
Inserts a CSS stylesheet into a target context. If multiple frames are specified, unsuccessful injections are ignored.
Parameters
The details of the styles to insert.
Required permissions
registerContentScripts(scripts)
Registers one or more content scripts for this extension.
Parameters
Contains a list of scripts to be registered. If there are errors during script parsing/file validation, or if the IDs specified already exist, then no scripts are registered.
Required permissions
removeCSS(injection)
Removes a CSS stylesheet that was previously inserted by this extension from a target context.
Parameters
The details of the styles to remove. Note that the css, files, and origin properties must exactly match the stylesheet inserted through insertCSS. Attempting to remove a non-existent stylesheet is a no-op.
Required permissions
unregisterContentScripts([filter])
Unregisters one or more content scripts for this extension.
Parameters
If specified, only unregisters dynamic content scripts which match the filter. Otherwise, all of the extension’s dynamic content scripts are unregistered.
Required permissions
updateContentScripts(scripts)
Updates one or more content scripts for this extension.
Parameters
scripts
(array of object)
Contains a list of scripts to be updated. If there are errors during script parsing/file validation, or if the IDs specified do not already exist, then no scripts are updated.
Required permissions
Types
CSSInjection
object
Details specifying the target into which to inject the CSS.
[css]
(string, optional)
A string containing the CSS to inject. Exactly one of files and css must be specified.
[files]
(array of string, optional)
The path of the CSS files to inject, relative to the extension’s root directory. Exactly one of files and css must be specified.
[origin]
(string, optional)
The style origin for the injection. Defaults to ‘AUTHOR’.
Supported values:
USER
AUTHOR
ContentScriptFilter
object
[ids]
(array of string, optional)
The IDs of specific scripts to retrieve with getRegisteredContentScripts() or to unregister with unregisterContentScripts().
ExecutionWorld
The JavaScript world for a script to execute within. ISOLATED is the default execution environment of content scripts, MAIN is the web page’s execution environment.
string
Supported values:
ISOLATED
MAIN
InjectionResult
Result of a script injection.
object
frameId
(integer)
The frame ID associated with the injection.
[error]
(any, optional)
The error property is set when the script execution failed. The value is typically an (Error) object with a message property, but could be any value (including primitives and undefined) if the script threw or rejected with such a value.
[result]
(any, optional)
The result of the script execution.
InjectionTarget
object
tabId
(number)
The ID of the tab into which to inject.
[allFrames]
(boolean, optional)
Whether the script should inject into all frames within the tab. Defaults to false. This must not be true if frameIds is specified.
[frameIds]
(array of number, optional)
The IDs of specific frames to inject into.
RegisteredContentScript
object
id
(string)
The id of the content script, specified in the API call.
[allFrames]
(boolean, optional)
If specified true, it will inject into all frames, even if the frame is not the top-most frame in the tab. Each frame is checked independently for URL requirements; it will not inject into child frames if the URL requirements are not met. Defaults to false, meaning that only the top frame is matched.
The list of CSS files to be injected into matching pages. These are injected in the order they appear in this array.
[excludeMatches]
(array of string, optional)
Excludes pages that this content script would otherwise be injected into.
The list of JavaScript files to be injected into matching pages. These are injected in the order they appear in this array.
[matchOriginAsFallback]
(boolean, optional)
If matchOriginAsFallback is true, then the code is also injected in about:, data:, blob: when their origin matches the pattern in ‘matches’, even if the actual document origin is opaque (due to the use of CSP sandbox or iframe sandbox). Match patterns in ‘matches’ must specify a wildcard path glob. By default it is false.
[matches]
(array of string, optional)
Specifies which pages this content script will be injected into. Must be specified for registerContentScripts().
[persistAcrossSessions]
(boolean, optional)
Specifies if this content script will persist into future sessions. Defaults to true.
Specifies when JavaScript files are injected into the web page. The preferred and default value is document_idle.
The JavaScript world for a script to execute within. Defaults to “ISOLATED”.
ScriptInjection
Details of a script injection
object
Details specifying the target into which to inject the script.
[args]
(array of any, optional)
The arguments to curry into a provided function. This is only valid if the func parameter is specified. These arguments must be JSON-serializable.
[files]
(array of string, optional)
The path of the JS files to inject, relative to the extension’s root directory. Exactly one of files and func must be specified.
[func]
(function, optional)
A JavaScript function to inject. This function will be serialized, and then deserialized for injection. This means that any bound parameters and execution context will be lost. Exactly one of files and func must be specified.
[injectImmediately]
(boolean, optional)
Whether the injection should be triggered in the target as soon as possible (but not necessarily prior to page load).
External Types
The following types are not defined by this API, but by the underlying Mozilla WebExtension code base. They are included here, because there is no other public documentation available.
ExtensionURL
A path relative to the root of the extension.
string