Going Incognito

Raising User Awareness

Proper Private Behavior

Registering A User Script

const registeredUserScript = await browser.userScripts.register(
   userScriptOptions       // object
);

...
await registeredUserScript.unregister();

• • It does not support a css property (use browser.contentScripts.register to dynamically register/unregister stylesheets).

• • It supports an optional property, scriptMetadata, a plain JSON object which contains metadata properties associated with the registered user script.

Providing User Script Functionality

• • runs in the content processes
  • has access to the window and document globals related to the webpage attached to it
  • can use the same subset of WebExtension APIs usually available in a content script

manifest.json
{
  ...

  "user_scripts": {
    "api_script": "apiscript.js",
  }
}

• metadata – The scriptMetadata property that was set when the user script was registered via the userScripts.register API.
• global – Provides access to the isolated sandbox for this particular user script.
• defineGlobals – An API method that exports an object containing globally available properties and methods to the user script sandbox.  This method must be called synchronously to guarantee that the user script has not already executed.
• export – An API method that converts a given value to a value that the user script code is allowed to access (this method can be used in API methods exported to the userScript to result or resolve non primitive values, the exported objects can also provide methods that the userScripts code is allowed to access and call).

browser.userScripts.onBeforeScript.addListener(function (script) {

  script // This is an API object that represents the userScript
         // that is going to be executed.

  script.metadata // Access the userScript metadata (returns the
                  // value of the scriptMetadata property from
                  // the call to userScripts.register

  // Export some global properties into the userScript sandbox
  // (this method has to be called synchronously from the
  // listener, otherwise the userScript may have been already
  // be executed).
  script.defineGlobals({
    aGlobalPropertyAccessibleFromUserScriptCode: “prop value”,

    myCustomAPIMethod(param1, param2) {
      // Custom methods exported from the API script can use
      // the WebExtensions APIs available to the extension
      // content scripts
      browser.runtime.sendMessage(...);
      ...

      return 123; // primitive values can be returned directly
      ...

      // Non primitive values have to be exported explicitly
      // using the export method provided by the script API
      // object
      return script.export({{
        objKey1: {
          nestedProp: "nestedvalue",
        },
        // Explicitly exported objects can also provide methods.
        objMethod() { ... }
    },

    async myAsyncMethod(param1, param2, param2) {
    // exported methods can also be declared as async
    },
  });
});

• Support for setting storage.managed values via an enterprise policy.
• Extension context menus now respect any enterprise policy that has restricted the removal of extensions.
• It is now possible to theme the foreground and background colors of the selected text in the URL bar.
• Corrected the implementation of runtime.setUninstallURL to honor `null` as an accepted value.
• Preserved the state of tabs, including lazy loading, when moving between windows.
• Updated the browser_style CSS to properly style invalid input elements.
• Prevented the built-in CTRL+Page Up/Down keyboard shortcut from being assigned to an extension.
• Made the UI for extensions with a lot of keyboard shortcuts much easier to understand and navigate.
• Any optional permissions granted to extensions are now properly removed when the extension is uninstalled.
• Match patterns now properly support IPv6 literals.