contentScripts.register()
Use this function to register one or more content scripts.
Use this function to register one or more content scripts.
It accepts one parameter, which is an object with similar properties to the objects given in the content_scripts manifest key (but note that content_scripts is an array of objects, while the argument to register() is one object).
The extension must have the appropriate host permissions for the patterns in contentScriptOptions, or the
API call is rejected.
Syntax
let registering = browser.contentScripts.register(
contentScriptOptions // object
)
Parameters
contentScriptOptions-
:
object. ARegisteredContentScriptOptionsobject representing the content scripts to register. It has similar syntax to the objects in thecontent_scriptsmanifest key array. The differences are:- property names use camel case, rather than underscores (snake case) — for example,
excludeMatches, notexclude_matches. - the
jsandcssproperties allow you to register strings as well as URLs, so their syntax has to distinguish these types.
The
RegisteredContentScriptOptionsobject has these properties: -allFrames- : Same asall_framesin thecontent_scriptskey. -cookieStoreId- : A string or array of strings. Registers the content script in the tabs that belong to one or more cookie store IDs. This enables scripts to be registered for all default or non-contextual identity tabs, private browsing tabs (if the extension is enabled in private browsing), the tabs of a contextual identity, or a combination of these. See Work with contextual identities for more information. -css- : An array of objects. Each object has either a property namedfile, which is a URL starting at the extension's manifest.json and pointing to a CSS file to register, or a property namedcode, which is some CSS code to register. -cssOrigin- :string. The style origin for the injection, either"user", to add the CSS as a user stylesheet, or"author", to add it as an author stylesheet. Defaults to"author". This property is case insensitive. -excludeGlobs- : Same asexclude_globsin thecontent_scriptskey. -excludeMatches- : Same asexclude_matchesin thecontent_scriptskey. -includeGlobs- : Same asinclude_globsin thecontent_scriptskey. -js- : An array of objects. Each object has either a property namedfile, which is a URL starting at the extension's manifest.json and pointing to a JavaScript file to register, or a property namedcode, which is some JavaScript code to register. -matchAboutBlank- : Same asmatch_about_blankin thecontent_scriptskey. -matchOriginAsFallback- : Same asmatch_origin_as_fallbackin thecontent_scriptskey. -matches- : Same asmatchesin thecontent_scriptskey. -runAt- : Same asrun_atin thecontent_scriptskey. -world- : The execution environment for a script to execute in. Same asworldin thecontent_scriptskey. - property names use camel case, rather than underscores (snake case) — for example,
Return value
A Promise that will be fulfilled with a contentScripts.RegisteredContentScript object that you can use to unregister the content scripts.
Currently, content scripts are unregistered when the related extension page (from which the content scripts were registered) is unloaded, so you should register a content script from an extension page that persists at least as long as you want the content scripts to stay registered.
Examples
This example registers the defaultCode content script for all .org URLs:
const defaultHosts = "*://*.org/*";
const defaultCode =
"document.body.innerHTML = '<h1>This page has been eaten<h1>'";
async function register(hosts, code) {
return await browser.contentScripts.register({
matches: [hosts],
js: [{ code }],
runAt: "document_idle",
});
}
let registered = register(defaultHosts, defaultCode);
This code registers the JS file at content_scripts/example.js:
const scriptObj = await browser.contentScripts.register({
js: [{ file: "/content_scripts/example.js" }],
matches: ["<all_urls>"],
allFrames: true,
runAt: "document_start",
});