This method enables user scripts to be registered from an extension's pages (such as the background page).
This method is very similar to the contentScripts.register()
API method (for example, they both return a promise that resolves to an API object with an unregister()
method for unregistering the script). There are, however, differences in the options supported.
This is an asynchronous method that returns a Promise
.
const registeredUserScript = await browser.userScripts.register( userScriptOptions // object ); …. await registeredUserScript.unregister();
userScriptOptions
object
. Represents the user scripts to register. It has similar syntax to contentScripts.register()
.
The UserScriptOptions
object has the following properties:
scriptMetadata
Optional
JSON
object containing arbitrary metadata properties associated with the registered user scripts. However, while arbitrary, the object must be serializable, so it is compatible with the structured clone algorithm. This metadata is used to pass details from the script to the API script
. For example, providing details of a subset of the APIs that need to be injected by the API script
. The API does not use this metadata,allFrames
Optional
all_frames
in the content_scripts
key.excludeGlobs
Optional
exclude_globs
in the content_scripts
key.excludeMatches
Optional
exclude_matches
in the content_scripts
key.includeGlobs
Optional
include_globs
in the content_scripts
key.js
file
, which is a URL starting at the extension's manifest.json and pointing to a JavaScript file to register, or a property named code
, which contains JavaScript code to register.matchAboutBlank
Optional
match_about_blank
in the content_scripts
key.matches
matches
in the content_scripts
key.matches
must be enabled by the host permissions defined in the manifest permission
property or enabled by the user from the optional_permissions
list. For example, if matches includes https://mozilla.org/a
a script is only registered if host permissions include, for example, https://mozilla.org/*
. If the URL pattern isn't enabled, the call to register fails with the error "Permission denied to register a user script for ORIGIN".runAt
Optional
run_at
in the content_scripts
key.Unlike content script options, the userScriptOptions object does not have a css property. Use contentScripts.register()
to dynamically register and unregister stylesheets.
A Promise
that is fulfilled with a RegisteredUserScript
object that is use to unregister the user scripts.
Note: User scripts are unregistered when the related extension page (from which the user scripts were registered) is unloaded, so you should register user scripts from an extension page that persists at least as long as you want the user scripts to stay registered.
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Chrome | Edge | Firefox | Internet Explorer | Opera | Safari | WebView Android | Chrome Android | Firefox for Android | Opera Android | Safari on IOS | Samsung Internet | |
register |
No |
No |
68
66
|
? |
No |
No |
? |
? |
68 |
? |
? |
? |
© 2005–2021 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts/register