contentScripts.register()

Syntax

let registering = browser.contentScripts.register(
  contentScriptOptions       // object
)

Parameters

contentScriptOptions

object. A RegisteredContentScriptOptions object representing the content scripts to register. It has similar syntax to the objects in the content_scripts manifest key array. The differences are:

• property names use camel case, rather than underscores (snake case) — for example, excludeMatches, not exclude_matches.
• the js and css properties allow you to register strings as well as URLs, so their syntax has to distinguish these types.

The RegisteredContentScriptOptions object has these properties:

allFrames Optional

Same as all_frames in the content_scripts key.

cookieStoreId Optional

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 Optional

An array of objects. Each object has either a property named file, which is a URL starting at the extension's manifest.json and pointing to a CSS file to register, or a property named code, which is some CSS code to register.

cssOrigin Optional

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 Optional

Same as exclude_globs in the content_scripts key.

excludeMatches Optional

Same as exclude_matches in the content_scripts key.

includeGlobs Optional

Same as include_globs in the content_scripts key.

js Optional

An array of objects. Each object has either a property named 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 is some JavaScript code to register.

matchAboutBlank Optional

Same as match_about_blank in the content_scripts key.

matchOriginAsFallback Optional

Same as match_origin_as_fallback in the content_scripts key.

matches

Same as matches in the content_scripts key.

runAt Optional

Same as run_at in the content_scripts key.

world Optional

The execution environment for a script to execute in. Same as world in the content_scripts key.

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",
});

Example extensions

• content-script-register

Browser compatibility