Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://developer.chrome.com/docs/extensions/reference/api/userScripts below:

chrome.userScripts | API | Chrome for Developers

Stay organized with collections Save and categorize content based on your preferences.

Use the userScripts API to execute user scripts in the User Scripts context.

userScripts

To use the User Scripts API, chrome.userScripts, add the "userScripts" permission to your manifest.json and "host_permissions" for sites you want to run scripts on.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

A user script is a snippet of code injected into a web page to modify its appearance or behavior. Unlike other extension features, such as Content Scripts and the chrome.scripting API, the User Scripts API lets you run arbitrary code. This API is required for extensions that run scripts provided by the user that cannot be shipped as part of your extension package.

After your extension receives the permission to use the userScripts API, users must enable a specific toggle to allow your extension to use the API. The specific toggle required, and the API's behavior when disabled, vary by Chrome version.

Use the following check to determine which toggle the user needs to enable, for example, during new user onboarding:

let version = Number(navigator.userAgent.match(/(Chrome|Chromium)\/([0-9]+)/)?.[2]);
if (version >= 138) {
  // Allow User Scripts toggle will be used.
} else {
  // Developer mode toggle will be used.
}

The following sections describe the different toggles and how to enable them.

AAs an extension developer, you already have Developer mode enabled in your installation of Chrome. Your users must also enable Developer mode.

You can copy and paste the following instructions into your extension's documentation for your users

1. Go to the Extensions page by entering chrome://extensions in a new tab. (By design chrome:// URLs are not linkable.)

2. Enable Developer Mode by clicking the toggle switch next to Developer mode.

   Extensions page (chrome://extensions)

The Allow User Scripts toggle is on each extension's details page (for example, chrome://extensions/?id=YOUR_EXTENSION_ID).

You can copy and paste the following instructions into your extension's documentation for your users:

1. Go to the Extensions page by entering chrome://extensions in a new tab. (By design chrome:// URLs are not linkable.)
2. Click the "Details" button on the extension card to view detailed information about the extension.
3. Click the toggle switch next to Allow User Scripts.

We recommend the following check to determine if the userScripts API is enabled, as it works in all Chrome versions. This check attempts to call a chrome.userScripts() method that should always succeed when the API is available. If this call throws an error, the API is not available:

function isUserScriptsAvailable() {
  try {
    // Method call which throws if API permission or toggle is not enabled.
    chrome.userScripts.getScripts();
    return true;
  } catch {
    // Not available.
    return false;
  }
}

Both user and content scripts can run in an isolated world or in the main world. An isolated world is an execution environment that isn't accessible to a host page or other extensions. This lets a user script change its JavaScript environment without affecting the host page or other extensions' user and content scripts. Conversely, user scripts (and content scripts) are not visible to the host page or the user and content scripts of other extensions. Scripts running in the main world are accessible to host pages and other extensions and are visible to host pages and to other extensions. To select the world, pass "USER_SCRIPT" or "MAIN" when calling userScripts.register().

To configure a content security policy for the USER_SCRIPT world, call userScripts.configureWorld():

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

Like content scripts and offscreen documents, user scripts communicate with other parts of an extension using messaging (meaning they can call runtime.sendMessage() and runtime.connect() as any other part of an extension would). However, they're received using dedicated event handlers (meaning, they don't use onMessage or onConnect). These handlers are called runtime.onUserScriptMessage and runtime.onUserScriptConnect. Dedicated handlers make it easier to identify messages from user scripts, which are a less-trusted context.

Before sending a message, you must call configureWorld() with the messaging argument set to true. Note that both the csp and messaging arguments can be passed at the same time.

chrome.userScripts.configureWorld({
  messaging: true
});

User scripts are cleared when an extension updates. You can add them back by running code in the runtime.onInstalled event handler in the extension service worker. Respond only to the "update" reason passed to the event callback.

This example is from the userScript sample in our samples repository.

The following example shows a basic call to register(). The first argument is an array of objects defining the scripts to be registered. There are more options than are shown here.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

The JavaScript world for a user script to execute within.

"MAIN"
Specifies the execution environment of the DOM, which is the execution environment shared with the host page's JavaScript.

• The document associated with the injection.

• The error, if any. error and result are mutually exclusive.

• The frame associated with the injection.

• The result of the script execution.

• 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.

• documentIds

  string[] optional

  The IDs of specific documentIds to inject into. This must not be set if frameIds is set.

• frameIds

  number[] optional

  The IDs of specific frames to inject into.

• The ID of the tab into which to inject.

• allFrames

  boolean optional

  If 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.

• excludeGlobs

  string[] optional

  Specifies wildcard patterns for pages this user script will NOT be injected into.

• excludeMatches

  string[] optional

  Excludes pages that this user script would otherwise be injected into. See Match Patterns for more details on the syntax of these strings.

• The ID of the user script specified in the API call. This property must not start with a '_' as it's reserved as a prefix for generated script IDs.

• includeGlobs

  string[] optional

  Specifies wildcard patterns for pages this user script will be injected into.

• The list of ScriptSource objects defining sources of scripts to be injected into matching pages. This property must be specified for ${ref:register}, and when specified it must be a non-empty array.

• matches

  string[] optional

  Specifies which pages this user script will be injected into. See Match Patterns for more details on the syntax of these strings. This property must be specified for ${ref:register}.

• Specifies when JavaScript files are injected into the web page. The preferred and default value is document_idle.

• The JavaScript execution environment to run the script in. The default is `USER_SCRIPT`.

• Specifies the user script world ID to execute in. If omitted, the script will execute in the default user script world. Only valid if world is omitted or is USER_SCRIPT. Values with leading underscores (_) are reserved.

• A string containing the JavaScript code to inject. Exactly one of file or code must be specified.

• The path of the JavaScript file to inject relative to the extension's root directory. Exactly one of file or code must be specified.

• getScripts only returns scripts with the IDs specified in this list.

• injectImmediately

  boolean optional

  Whether the injection should be triggered in the target as soon as possible. Note that this is not a guarantee that injection will occur prior to page load, as the page may have already loaded by the time the script reaches the target.

• The list of ScriptSource objects defining sources of scripts to be injected into the target.

• Details specifying the target into which to inject the script.

• The JavaScript "world" to run the script in. The default is USER_SCRIPT.

• Specifies the user script world ID to execute in. If omitted, the script will execute in the default user script world. Only valid if world is omitted or is USER_SCRIPT. Values with leading underscores (_) are reserved.

• Specifies the world csp. The default is the `ISOLATED` world csp.

• messaging

  boolean optional

  Specifies whether messaging APIs are exposed. The default is false.

• Specifies the ID of the specific user script world to update. If not provided, updates the properties of the default user script world. Values with leading underscores (_) are reserved.

chrome.userScripts.configureWorld(
  properties: WorldProperties,
): Promise<void>

Configures the `USER_SCRIPT` execution environment.

• Contains the user script world configuration.

chrome.userScripts.execute(
  injection: UserScriptInjection,
): Promise<InjectionResult[]>

Injects a script into a target context. By default, the script will be run at document_idle, or immediately if the page has already loaded. If the injectImmediately property is set, the script will inject without waiting, even if the page has not finished loading. If the script evaluates to a promise, the browser will wait for the promise to settle and return the resulting value.

• If specified, this method returns only the user scripts that match it.

chrome.userScripts.getWorldConfigurations(): Promise<WorldProperties[]>

Retrieves all registered world configurations.

chrome.userScripts.register(
  scripts: RegisteredUserScript[],
): Promise<void>

Registers one or more user scripts for this extension.

• Contains a list of user scripts to be registered.

chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
): Promise<void>

Resets the configuration for a user script world. Any scripts that inject into the world with the specified ID will use the default world configuration.

• The ID of the user script world to reset. If omitted, resets the default world's configuration.

chrome.userScripts.unregister(
  filter?: UserScriptFilter,
): Promise<void>

Unregisters all dynamically-registered user scripts for this extension.

• If specified, this method unregisters only the user scripts that match it.

chrome.userScripts.update(
  scripts: RegisteredUserScript[],
): Promise<void>

Updates one or more user scripts for this extension.

• Contains a list of user scripts to be updated. A property is only updated for the existing script if it is specified in this object. If there are errors during script parsing/file validation, or if the IDs specified do not correspond to a fully registered script, then no scripts are updated.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-08-11 UTC.

[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-11 UTC."],[],[]]

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4