Modern browsers can add new functionality to sites and the browser itself through script-based extensions. This document specifies an API set that allows developers to create interoperable extensions for browsers that support the API set, as well as the packaging format to be used for such extensions.

If you wish to make comments regarding this document, please file issues on github. A public mailing list (subscribe, archives) is also available, but is reserved for high level discussions, and is not appropriate for specific comments about this document.

Work on this document is governed by the charter of the Browser Extension CG, which includes among other things the Communication, Decision, and Contribution policies of this community group.

Introduction

Because browsers supported different add-on models, extension authors wound up creating divergent codebases and delivering different browser-specific add-ons. This Community Group's goal is to make browser extension code much more interoperable across browsers by specifying common extension interfaces and well-defined browser behavior. This will allow extension authors to greatly reduce or eliminate the rework necessary to create extensions that target different browsers.

Core APIs

The goal for these core APIs is to provide functionality that extension authors need for:

Need to resolve ID issue before we can address messaging ('passing data')
GitHub Issues 14 & 17

API Availability

Overview

Browser extensions are authored primarily with JavaScript. In addition to the usual JavaScript Web APIs, additional APIs are available exclusively to extensions via the browser object. However, the specific APIs that are available to an extension from the browser object are dependent upon:

  • Execution context (e.g. background/event, popup, options, content, extension page)
  • Keys declared in the manifest (e.g. browser_action, page_action)
  • Permissions declared in the manifest (e.g. contextMenu, tabs, webNavigation, webRequest)
  • Content Security Policy (CSP) for the extension and target web page (for content scripts)

Content Security Policy (CSP) Restrictions

Use of some JavaScript APIs such as eval() are restricted due to CSP. If an explicit policy is not specified, the default policy is applied. The default CSP is discussed in the specification [[CSP3]] . If the browser extension author specifies a new CSP, it will override the default CSP.

Add a separate non-normative section on how content scripts interact with CSP
GitHub Issue 18

  • Script execution via eval() and inline script execution are not allowed
  • Only script from the extension's package can be executed
  • Executing script from the web is not allowed

Execution Context and Manifest Restrictions

Browser extension pages and their corresponding scripts are executed in one of the following contexts. The manifest declarations required to create each specific type of page are described below.

  • Browser extension contexts ("Window") - Most extension APIs are available to this context
    • Background page - use the "background" manifest key and specify "persistent" true
    • Event page - use the "background" manifest key and specify "persistent" false
    • Popup page - use the "browser_action" or "page_action" manifest key and specify "detault_popup"
    • Options page - use the "options_page" manifest key
    • Custom page - such as "browserext://<ext_id>/myCustomPage.html"
  • Content script context - A limited number of APIs are available to script that extensions use to interact with hosted web site pages
  • Internet-hosted web page context - Messaging APIs can be used to send messages from hosted web site pages such as https://en.wikipedia.org/wiki/Main_Page/index.html or https://w3c.github.io/html/index.html to extensions
Table: API Availability Summary

Some browser extension API require a specific manifest key or specific permission. If the key or permission are not declared or not granted, the object will not be available for scripting. These requirements are summarized in the table below. If manifest keys that are not defined in this specification are specified, other browsers MAY elect to ignore those additional keys.

API object Execution Context Required Declaration
Background page,Event page,Popup page,Options page,Custom page Content script page Internet-hosted web page Manifest key
browserAction Y1

"browser_action"1
contextMenus Y

"permissions":["context_menus"]
extension Y Y

i18n Y Y

"default_lang" : "<lang>"4
pageAction Y1

"page_action"1
runtime Y Y Y3 “externally_connectable”:[...] 2
tabs Y

"permissions":["tabs","activeTab"]
webNavigation Y

"permissions":["webNavigation"]
webRequest Y

"permissions":["webRequest"]
windows Y

1 Either browserAction or pageAction is allowed at the same time, not both
2The runtime object is available for use by extensions without declaring "externally_connectable" in the manifest. However, an extension will only receive messages sent from hosted web pages if this key is declared. The "externally_connectable" declaration will block messages from other extensions, unless the allowed extension ID is declared in the "ids" list.
3Internet-hosted web pages that use runtime.sendMessage to communicate with extensions MUST be explicitly specify the hosting site's domain in the manifest under the "externally_connectable" key.
4 Use of the browser.i18n object does not require a manifest permission declaration. However, the manifest does require a value (default_locale) that is necessary and cannot be specified by the extension author in script code.

Expressing Availability in WebIDL

This specification uses WebIDL [[webidl]] to describe the Browser Extensions API.

Attribute: Exposed

To express the aforementioned conditional situations in which certain APIs are made available due to context, the following contexts are used:

  • Window - The primary context for most browser extension APIs. This applies to background, event, popup, options and custom contexts
  • ContentScript - Applies to content script context

Extended Attribute: CheckAnyPermissions

To express the aforementioned conditional situations in which certain APIs are made available due to expressed manifest keys or permissions, the new WebIDL extended attribute "CheckAnyPermissions" is used.

API objectCheckAnyPermissions ValueManifest Key or Value
browser"browserExt"N/A
browser.browserAction"browserExtBrowserAction""browserAction":[...]
browser.contextMenu"browserExtContextMenus""permissions":["contextMenus"]
browser.extension"browserExt"

i18n"browserExt""default_language": "<code>"
pageAction"browserExtPageAction""pageAction":[...]
runtime"browserExt"

tabs"browserExtTabs""permissions":["tabs"] or
"permissions":["activeTab"]
webNavigation"browserExtWebNavigation""permissions":["webNavigation"]
webRequest"browserExtWebRequest""permissions":["webRequest"]
windows"browserExt"

Example: browser.i18n

In this example, the i18n API should be made available to both browser host scripts (background, event, popup, options, etc.) and content scripts. Use of this API does not require a manifest permission declaration. Additionally, however, the manifest does require a value (default_locale) that is necessary and cannot be specified by the extension author in script code. This is expressed as a BrowserExtManifest dictionary.

  1. First, declare the methods for the browser.i18n object.
    [NoInterfaceObject]
    interface BrowserI18n {
        DOMString getMessage(DOMString messageName, sequence<DOMString?> substitutions);
    };
    
  2. Next, we specify the available contexts ("Window" for background/event/popup/options...) and "ContentScript" for the content context.
    [NoInterfaceObject, Exposed=(Window,ContentScript)] 
    interface BrowserI18nAPI {
        readonly attribute BrowserI18n i18n;
    };
                            
  3. Connect the i18n object to the browser.* object.
    Browser implements BrowserI18nAPI;
    
  4. Finally, we express the locale from manifest.json. For example "default_locale": "en"
    partial dictionary BrowserExtManifest {
        DOMString? defaultLocaleCode;
    };
    

Definitions

BrowserI18n is TBD_define_here

getMessage returns TBD_define_here

BrowserI18nAPI is TBD_define_here

i18n is TBD_define_here

defaultLocaleCode is TBD_define_here

Events

Overview

Extension events are similar to DOM Events [DOM4]. However, extension events are dispatched only to objects in the relevant extension scope (background, event, options, content, etc.). Script in the extension scope can observe events by calling addListener().

[NoInterfaceObject]
dictionary BrowserExtRule {
    DOMString id;
    sequence<DOMString> tags;
    sequence<Any> conditions;
    sequence<Any> actions;
    unsigned short priority;
};
[NoInterfaceObject, Exposed=(Window,ContentScript), CheckAnyPermissions_browserExt_]
interface BrowserExtEvent {
    void    addListener(Function callback);
    void    removeListener(Function callback);
    boolean hasListener(Function callback);
    boolean hasListeners();
};

Definitions

BrowserExtRule is TBD_define_here

id is TBD_define_here

tags is TBD_define_here

conditions is TBD_define_here

actions is TBD_define_here

priority is TBD_define_here

BrowserExtEvent is TBD_define_here

addListener is TBD_define_here

removeListener is TBD_define_here

hasListener is TBD_define_here

hasListeners is TBD_define_here

The browser object

Overview

The core Browser Extension API objects are accessible from the browser object. Their availability varies, depending on conditions outlined in the API Availability section.

  • browserAction
  • contextMenus
  • extension
  • i18n
  • pageAction
  • runtime
  • tabs
  • webNavigation
  • webRequest
  • windows

Context

This API is available in Window context (background, event, popup, options and custom pages), Content Script context, and Internet-hosted web page context.

WebIDL Definition

A description of the special WebIDL syntax considerations for browser extensions are defined elsewhere in this document.

[CheckAnyPermissions_browserExt_]
interface BrowserExtGlobal {
    readonly attribute Browser browser;
};
Window implements BrowserExtGlobal;
[NoInterfaceObject] 
interface Browser { 
};
dictionary BrowserExtIcon {
    DOMString path;
    DOMString size;
};
typedef sequence<BrowserExtIcon> BrowserExtIconArray;
dictionary BrowserExtDeveloper {
    DOMString name;
    DOMString? url;
};
dictionary BrowserExtBrowserOrPageAction {
    BrowserExtIcon defaultIcon; 
    DOMString defaultPopup;
    DOMString defaultTitle;
};
dictionary BrowserExtKeyValue {
    DOMString key;
    DOMString? value;
};
dictionary BrowserExtBrowserSpecificSettings {
    DOMString browserName;
    sequence<KeyValue> keyValue;
};
dictionary BrowserExtBackroundOrEvent {
    DOMString page;
    boolean persistent;
    sequence<DOMString> scripts;
};
dictionary BrowserExtContentScripts {
    boolean allFrames;
    sequence<DOMString> css;
    sequence<DOMString> excludeMatches;
    sequence<DOMString> js;
    sequence<DOMString> matches;
    DOMString runAt;
};
dictionary BrowserExtManifest {
    BrowserExtBackground background;
    BrowserExtBrowserOrPageAction browserAction;
    BrowserExtBrowserSpecificSettings browserSpecificSettings;
    BrowserExtContentScripts contentScripts;
    DOMString contentSecurityPolicy;
    DOMString defaultLocale;
    DOMString? description;
    BrowserExtDeveloper developer;
    BrowserExtIconArray icons;
    unsigned short manifestVersion;
    DOMString name;
    DOMString optionsPage;
    BrowserExtBrowserOrPageAction pageAction;
    sequence<DOMString> permissions;
    sequence<DOMString> requiredKeys;
    DOMString version;
    sequence<DOMString> webAccessibleResources;
};

Definitions

BrowserExtGlobal is TBD_define_here

browser is TBD_define_here

Browser is TBD_define_here

BrowserExtIcon is TBD_define_here

path is TBD_define_here

size is TBD_define_here

BrowserExtIconArray is TBD_define_here

BrowserExtDeveloper is TBD_define_here

name is TBD_define_here

url is TBD_define_here

BrowserExtBrowserOrPageAction is TBD_define_here

defaultIcon is TBD_define_here

defaultPopup is TBD_define_here

defaultTitle is TBD_define_here

BrowserExtKeyValue is TBD_define_here

key is TBD_define_here

value is TBD_define_here

BrowserExtBrowserSpecificSettings is TBD_define_here

browserName is TBD_define_here

keyValue is TBD_define_here

BrowserExtBackroundOrEvent is TBD_define_here

page is TBD_define_here

persistent is TBD_define_here

scripts is TBD_define_here

BrowserExtContentScripts is TBD_define_here

allFrames is TBD_define_here

css is TBD_define_here

excludeMatches is TBD_define_here

js is TBD_define_here

matches is TBD_define_here

runAt is TBD_define_here

BrowserExtManifest is TBD_define_here

background is TBD_define_here

browserAction is TBD_define_here

browserSpecificSettings is TBD_define_here

contentScripts is TBD_define_here

contentSecurityPolicy is TBD_define_here

defaultLocale is TBD_define_here

description is TBD_define_here

developer is TBD_define_here

icons is TBD_define_here

manifestVersion is TBD_define_here

name is TBD_define_here

optionsPage is TBD_define_here

pageAction is TBD_define_here

permissions is TBD_define_here

requiredKeys is TBD_define_here

version is TBD_define_here

webAccessibleResources is TBD_define_here

The browserAction object

Overview

The browserAction object adds an always-visible button to the browser application, usually near the top of the browser application UI in the toolbar area. An extension that declares a browserAction cannot have a pageAction, and vice-versa.

Manifest

The "browser_action" and "default_title" keys are required. The other keys are optional.
"browser_action": {                               // Required
    "default_icon": {...},                        // Same format as "icons"
    "default_popup": "Page URL",                  // Optional
    "default_title": "Title string"               // Required
}

Context

This API is available in Window context (background, event, popup, options and custom pages).

WebIDL Definition

A description of the special WebIDL syntax considerations for browser extensions are defined elsewhere in this document.

Need to find all strings that support null and add ? to DOMString (DOMString?).
GitHub Issue 21

dictionary BrowserExtBrowserActionDefaults {
    BrowserExtIconArray defaultIcon;
    DOMString? defaultPopup;
    DOMString  defaultTitle;
};
partial dictionary BrowserExtManifest {
    BrowsereExtBrowserActionDefaults? browserActionDefaults;
};
typedef sequence<unsigned short> BrowserExtColorArray;
dictionary BrowserExtTabIdDetails {
    unsigned short tabId;
};
dictionary BrowserExtBadgeColorArrayTabId {
    ColorArray color;
    unsigned short tabId;
};
dictionary BrowserExtBadgePathTabId {
    DOMString path;
    unsigned short tabId;
};
dictionary BrowserExtBadgeTextTabId {
    unsigned short tabId;
    DOMString text;
};
dictionary BrowserExtBadgeTabIdPopup {
    DOMString popupHTMLFileName;
    unsigned short tabId;
};



callback BrowserExtBrowserActionOnClickedCallback = void (BrowserExtTabsTab tab);

[NoInterfaceObject]
interface BrowserExtBrowserAction {
    void disable(unsigned short tabId);
    void enable(unsigned short tabId);
    Promise<ColorArray> getBadgeBackgroundColor(BrowserExtTabIdDetails details);
    Promise<DOMString> getBadgeText(BrowserExtTabIdDetails details);
    Promise<DOMString> getPopup(BrowserExtTabIdDetails details);
    BrowserExtEvent onClicked(BrowserExtBrowserActionOnClickedCallback callback);
    void setBadgeBackgroundColor(BrowserExtBadgeColorArrayTabId details);
    void setBadgeText(BrowserExtBadgeTextTabId details);
    Promise<void> setIcon(BadgePathTabId details);
    void setPopup(BrowserExtBadgeTabIdPopup details);
};
[NoInterfaceObject, Exposed=Window, CheckAnyPermissions_browserExtBrowserAction_]
interface BrowserExtBrowserActionAPI {
    readonly attribute BrowserExtBrowserAction browserAction; 
};
Browser implements BrowserExtBrowserActionAPI;

BrowserExtBrowserActionDefaults is TBD_define_here

defaultIcon is TBD_define_here

defaultPopup is TBD_define_here

defaultTitle is TBD_define_here

browserActionDefaults is TBD_define_here

BrowserExtColorArray is TBD_define_here

BrowserExtTabIdDetails is TBD_define_here

tabId is TBD_define_here

BrowserExtBadgeColorArrayTabId is TBD_define_here

color is TBD_define_here

tabId is TBD_define_here

BrowserExtBadgePathTabId is TBD_define_here

path is TBD_define_here

tabId is TBD_define_here

BrowserExtBadgeTextTabId is TBD_define_here

tabId is TBD_define_here

text is TBD_define_here

BrowserExtBadgeTabIdPopup is TBD_define_here

popupHTMLFileName is TBD_define_here

tabId is TBD_define_here

BrowserExtBrowserActionOnClickedCallback is TBD_define_here

BrowserExtBrowserAction is TBD_define_here

disable is TBD_define_here

enable is TBD_define_here

getBadgeBackgroundColor is TBD_define_here

getBadgeText is TBD_define_here

getPopup is TBD_define_here

onClicked is TBD_define_here

setBadgeBackgroundColor is TBD_define_here

setBadgeText is TBD_define_here

setIcon is TBD_define_here

setPopup is TBD_define_here

BrowserExtBrowserActionAPI is TBD_define_here

browserAction is TBD_define_here

The contextMenus object

Overview

The contextMenus object allows additional entries to be added to the browser's context menu. The menu will be selectively be shown for various browser UI elements (browser action or page action button) or page elements (frame, image, link, page, selection, etc.).

Manifest

A "contextMenus" entry MUST be declared in the "permissions" key. The icon keys are optional.

"permissions": [                                  // Required
    "contextMenus"                                // Required
],                                                // Required
"icons": {                                        // Optional
    "<size>":"<name.png>"                         // Optional, size 16 recommended
}                                                 // Optional

Context

This API is available in Window context (background, event, popup, options and custom pages).

WebIDL Definition

A description of the special WebIDL syntax considerations for browser extensions are defined elsewhere in this document.

enum BrowserExtContextType { "all", "audio", "browser_action", "editable", "frame", "image", "link", "page", "page_action", "selection", "video" };
enum BrowserExtItemType { "checkbox","normal","radio","separator" };
dictionary BrowserExtContextMenuCreateDetails {
    boolean checked;
    sequence<ContextType> contexts;
    sequence<DOMString> documentUrlPatterns;
    boolean enabled;
    DOMString id;
    Function onclick;
    (unsigned short or DOMString) parentId;
    sequence<DOMString> targetUrlPatterns;
    DOMString title;
    DOMString type;
};
dictionary BrowserExtContextMenuUpdateDetails {
    boolean checked;
    sequence<BrowserExtContextType> contexts;
    sequence<DOMString> documentUrlPatterns;
    boolean enabled;
    Function onclick;
    unsigned short parentId;
    sequence<DOMString> targetUrlPatterns;
    DOMString title;
    ItemType type;
};
dictionary BrowserExtContextMenuOnClickedDetails {
    boolean checked;
    boolean editable;
    unsigned short frameId;
    DOMString frameUrl;
    DOMString linkUrl;
    DOMString mediaType;
    (unsigned short or DOMString) menuItemId;
    DOMString pageUrl;
    (unsigned short or DOMString) parentMenuItemId;             
    DOMString selectionText;
    DOMString srcUrl;
    boolean wasChecked;
};

callback BrowserExtContextMenuOnClickedCallback = void (BrowserExtContextMenuOnClickedDetails details, BrowserExtTabsTab tab);
[NoInterfaceObject]
interface BrowserExtContextMenus {
    Promise<unsigned short> create(BrowserExtContextMenuCreateDetails details);
    BrowserExtEvent onClicked_TBD(BrowserExtContextMenuOnClickedCallback callback);
	Promise<void> remove((unsigned short or DOMString) itemId);
    Promise<void>  removeAll();
    Promise<void>  update((unsigned short or DOMString) itemId, BrowserExtContextMenuUpdateDetails details);
};
[NoInterfaceObject, Exposed=Window, CheckAnyPermissions_browserExtContextMenus_]
interface BrowserExtContextMenusAPI {
    readonly attribute BrowserExtContextMenus contextMenus; 
};
Browser implements BrowserExtContextMenusAPI;

BrowserExtContextType is TBD_define_here

all is TBD_define_here

audio is TBD_define_here

browser_action is TBD_define_here

editable is TBD_define_here

frame is TBD_define_here

image is TBD_define_here

link is TBD_define_here

page is TBD_define_here

page_action is TBD_define_here

selection is TBD_define_here

video is TBD_define_here

BrowserExtItemType is TBD_define_here

checkbox is TBD_define_here

normal is TBD_define_here

radio is TBD_define_here

separator is TBD_define_here

BrowserExtContextMenuCreateDetails is TBD_define_here

checked is TBD_define_here

contexts is TBD_define_here

documentUrlPatterns is TBD_define_here

enabled is TBD_define_here

id is TBD_define_here

onclick is TBD_define_here

parentId is TBD_define_here

targetUrlPatterns is TBD_define_here

title is TBD_define_here

type is TBD_define_here

BrowserExtContextMenuUpdateDetails is TBD_define_here

checked is TBD_define_here

contexts is TBD_define_here

documentUrlPatterns is TBD_define_here

enabled is TBD_define_here

onclick is TBD_define_here

parentId is TBD_define_here

targetUrlPatterns is TBD_define_here

title is TBD_define_here

type is TBD_define_here

BrowserExtContextMenuOnClickedDetails is TBD_define_here

checked is TBD_define_here

editable is TBD_define_here

frameId is TBD_define_here

frameUrl is TBD_define_here

linkUrl is TBD_define_here

mediaType is TBD_define_here

menuItemId is TBD_define_here

pageUrl is TBD_define_here

parentMenuItemId is TBD_define_here

selectionText is TBD_define_here

srcUrl is TBD_define_here

wasChecked is TBD_define_here

BrowserExtContextMenuOnClickedCallback is TBD_define_here

BrowserExtContextMenus is TBD_define_here

create is TBD_define_here

onClicked_TBD is TBD_define_here

remove is TBD_define_here

removeAll is TBD_define_here

update is TBD_define_here

BrowserExtContextMenusAPI is TBD_define_here

contextMenus is TBD_define_here

The i18n object

Overview

The i81n object provides a way to access strings that have been localized into supported languages.

Manifest

When providing localized strings, you MUST specify a default locale using a two-character code. Codes can be found at RFC1766 or IETF BCP47. When localizing manifest strings, the following syntax is used.

"default_locale" : "<twoCharLocaleCode>",              // Required
"name" : "__MSG_<yourCustomNameStringIdentifier>__",
"description" : "__MSG_<yourCustomDescriptionStringIdentifier>__",
For example
"default_locale" : "en",              // English
"name" : "__MSG_MySampleExtension__",
"description" : "__MSG_MySampleExensionDecription__",

Localized Strings

Each supported locale MUST have its own messages.json file stored in the folder _locales/<twoCharLocaleCode>. The two-character codes used for directory names here the same as are used in the mainfest.json to specify default_locale.

Locale Codes and Matching

Locale codes used in file/directory names and returned by the API, contrary to common standards, are in the form:

<language>[_<region>]

Which is to say, a two-letter language code, optionally followed by an underscore and a two-letter region code. Locale codes are matched such that an exact match is used if available, falling back to the least-specific, closest match. Therefore, for "en_US", the following locales would be chosen, in order of preference:

  • en_US
  • en_US_var
  • en
  • en_GB
  • en_GB_var

String tokens

Strings are localized by pre-processing messages, replacing |$[a-zA-Z0-9@_]+$| tokens with the value of their replacements. Later, it processes the resulting string for |$[0-9]| replacements.

Any number of sequential |$|s are permitted, and are replaced with that number minus 1. Instances of |$| followed by any number of sequential digits is also permitted, but a localized string which provides more than 9 substitutions are ignored.

Locale Message Replacement

Locale messages in the form __MSG_<message name>_ are automatically replaced with the appropriate localized message in CSS files and certain manifest.json string values. Specifically, the replacements are done according to the regular expression __MSG_([A-Za-z0-9@_]+?)__, meaning that the first occurrence of __ terminates the message name immediately.

CSS files are pre-processed as a raw text stream, with no considerations for CSS syntax. manifest.json values are processed after the JSON has been parsed, and the results are always treated as literal strings. The following manifest keys are processed for localization messges:

  • name
  • short_name
  • description
  • author
  • homepage_url
  • developer.name
  • developer.url
  • browser_action.default_title
  • browser_action.default_url
  • page_action.default_title
  • page_action.default_url

Placeholders

It is possible for a translated string to contain substrings that will not be translated or will be replaced with variable content. For example

"messageExample": {
    "message": "You clicked $URL$.",
    "description": "Tells the user which link they clicked.",
    "placeholders": {
      "url" : {
        "content" : "$1"
        "example" : "https://www.w3c.org"
      }

The placeholder name ("url" in the above example) is used to represent the placeholder in the substitution string (e.g. "url" becomes $URL$). It is case insensitive and can contain the same characters as a message string name.

The "content" item defines the content of the placeholder. This can be a hardcoded string, such as "My placeholder", but it can also include values obtained from a i18n.getMessage() call.

The optional "example" item is intended to help translators by showing them an example of how the placeholder would appear to end users, allowing them to make the best choice when localizing the file.

Predefined messages

Predefined messages are accessed in the same way as other messages. The syntax for standard messages is:

__MSG_extensionName__

Predefined messages use exactly the same syntax, except with @@ before the message name. For example:

__MSG_@@ui_locale__

The following table shows the different available predefined messages:

Message nameDescription
@@extension_idThe extension or app ID; you might use this string to construct URLs for resources inside the extension. Even unlocalized extensions can use this message. Note that you can't use this message in a manifest file.
@@ui_localeThe current locale; you might use this string to construct locale-specific URLs.
@@bidi_dirThe text direction for the current locale, either "ltr" for left-to-right languages such as English or "rtl" for right-to-left languages such as Arabic.
@@bidi_reversed_dirIf the @@bidi_dir is "ltr", then this is "rtl"; otherwise, it's "ltr".
@@bidi_start_edgeIf the @@bidi_dir is "ltr", then this is "left"; otherwise, it's "right".
@@bidi_end_edgeIf the @@bidi_dir is "ltr", then this is "right"; otherwise, it's "left".

Context

This API is available in Window context (background, event, popup, options and custom pages) and Content Script context.

WebIDL Definition

A description of the special WebIDL syntax considerations for browser extensions are defined elsewhere in this document.

    
[NoInterfaceObject]
interface BrowserExtI18n {
    DOMString getMessage_TBD(DOMString messageName, sequence<DOMString?> substitutions);
};
[NoInterfaceObject, Exposed=(Window,ContentScript), CheckAnyPermissions_browserExt_] 
interface BrowserExtI18nAPI {
        readonly attribute BrowserExtI18n i18n;
};
Browser implements BrowserExtI18nAPI;
partial dictionary BrowserExtManifest {
    DOMString? defaultLocaleValue;
};

BrowserExtI18n is TBD_define_here

getMessage_TBD is TBD_define_here

BrowserExtI18nAPI is TBD_define_here

i18n is TBD_define_here

defaultLocaleValue is TBD_define_here

The pageAction object

Overview

The pageAction object adds a button to the browser application, usually within the address bar. This button typically appears only when the extension has detected that it can perform an action on the current page for the active tab. An extension that declares a browserAction cannot have a pageAction, and vice-versa.

Manifest

The "page_action" and "default_title" keys are required. The other keys are optional.

"page_action": {                               // Required
    "default_icon": {...},                        // Same format as "icons"
    "default_popup": "Page URL",                  // Optional
    "default_title": "Title string"               // Required
}

Context

This API is available in Window context (background, event, popup, options and custom pages).

WebIDL Definition

A description of the special WebIDL syntax considerations for browser extensions are defined elsewhere in this document.

dictionary BrowserExtPageActionDefaults {
    BrowserExtIconArray defaultIcon;
    DOMString? defaultPopup;
    DOMString  defaultTitle;
};
partial dictionary BrowserExtManifest {
    BrowserExtPageActionDefaults? pageActionDefaults;
};
dictionary BrowserExtBadgePath {
    DOMString path;
};

callback BrowserExtPageActionOnClickedCallback = void (BrowserExtTabsTab tab);

interface BrowserExtPageAction {
    Promise<DOMString> getPopup_TBD(BrowserExtTabIdDetails details);
    Promise<DOMString> getTitle(BrowserExtTabIdDetails details);
    void hide(unsigned short tabId);
    BrowserExtEvent onClicked_TBD2(BrowserExtPageActionOnClickedCallback callback);
    Promise<void> setIcon_TBD(BrowserExtBadgePath path);
    void setPopup_TBD(BrowserExtBadgePathTabId details);
    void setTitle(BrowserExtBadgeTextTabId details);
    void show(unsigned short tabId);
};
[NoInterfaceObject, Exposed=Window, CheckAnyPermissions_browserExtPageAction_]
interface BrowserExtPageActionAPI {
    readonly attribute BrowserExtPageAction pageAction; 
};
Browser implements BrowserExtPageActionAPI;

BrowserExtPageActionDefaults is TBD_define_here

defaultIcon is TBD_define_here

defaultPopup is TBD_define_here

defaultTitle is TBD_define_here

pageActionDefaults is TBD_define_here

BrowserExtBadgePath is TBD_define_here

path is TBD_define_here

BrowserExtPageActionOnClickedCallback is TBD_define_here

BrowserExtPageAction is TBD_define_here

getPopup_TBD is TBD_define_here

getTitle is TBD_define_here

hide is TBD_define_here

onClicked_TBD2 is TBD_define_here

setIcon_TBD is TBD_define_here

setPopup_TBD is TBD_define_here

setTitle is TBD_define_here

show is TBD_define_here

BrowserExtPageActionAPI is TBD_define_here

pageAction is TBD_define_here

The runtime object

Overview

The runtime object is used to send and receive messages across contexts, as well as access extension-level information such as the id, manifest, and absolute path to resources.

Manifest

There are no additional manifest entries required for an extension to use this object. However, an extension will only receive messages sent from hosted web pages if the “externally_connectable” key is declared. Also, an extension will block messages from other extensions by specifying only approved extensions. Note that if this key is used to allow web pages to send messages, unless "ids" : ["*"] is specified, all messages from other extensions will be blocked. URLs in the "matches" array MUST include a top-level domain. This list does not affect content scripts.

"externally_connectable" : [
    "ids":[...], // Identifiers for other extensions that are allowed to send messages
    "matches":[...] // URL patterns for hosted web pages allowed to send messages 
    ]

Context

This API is available in Window context (background, event, popup, options and custom pages), Content Script context, and Internet-hosted web page context.

WebIDL Definition

A description of the special WebIDL syntax considerations for browser extensions are defined elsewhere in this document.

enum BrowserExtRuntimeOnInstalledReason {"browser_update", "extension_install", "extension_update"};

dictionary BrowserExtRuntimeOnInstalledDetails {
    BrowserExtRuntimeOnInstalledReason reason;
    DOMString previousVersion;
    DOMString id;
};
dictionary BrowserExtRuntimePort {
    Function disconnect;
    DOMString name;
    object onDisconnect;
    object onMessage;
    Function postMessage;
    BrowserExtRuntimeMessageSender sender;
};
dictionary BrowserExtRuntimeMessageSender {
    DOMString id;
    unsigned short frameId;
    BrowserExtTabsTab tab;
    DOMString url;
};

callback BrowserExtRuntimeOnConnectCallback = void (BrowserExtRuntimePort port);
callback BrowserExtRuntimeOnInstalledCallback = void (BrowserExtRuntimeOnInstalledDetails details);
callback BrowserExtRuntimeOnMessageCallback = void (optional any message, BrowserExtRuntimeMessageSender sender, BrowserExtRuntimeSendResponseCallback callback);

[NoInterfaceObject]
interface BrowserExtBrowserRuntime {
    object getManifest();
    DOMString getURL(DOMString path);
    attribute DOMString id;
    void onConnect(BrowserExtRuntimeOnConnectCallback callback);
    void onInstalled(BrowserExtRuntimeOnInstalledCallback callback);
    void onMessage(BrowserExtRuntimeOnMessageCallback callback);
    Promise<any> sendMessage(optional DOMString extensionId, any message);
    attribute BrowserExtRuntimePort Port;
    attribute BrowserExtRuntimeMessageSender MessageSender;
};
[NoInterfaceObject, Exposed=Window, CheckAnyPermissions_browserExt_]
interface BrowserExtRuntimeAPI {
    readonly attribute BrowserExtRuntime runtime; 
};
Browser implements BrowserExtRuntimeAPI;

BrowserExtRuntimeOnInstalledReason is TBD_define_here

browser_update is TBD_define_here

extension_install is TBD_define_here

extension_update is TBD_define_here

BrowserExtRuntimeOnInstalledDetails is TBD_define_here

reason is TBD_define_here

previousVersion is TBD_define_here

id is TBD_define_here

BrowserExtRuntimePort is TBD_define_here

disconnect is TBD_define_here

name is TBD_define_here

onDisconnect is TBD_define_here

onMessage is TBD_define_here

postMessage is TBD_define_here

sender is TBD_define_here

BrowserExtRuntimeMessageSender is TBD_define_here

id is TBD_define_here

frameId is TBD_define_here

tab is TBD_define_here

url is TBD_define_here

BrowserExtRuntimeOnConnectCallback is TBD_define_here

BrowserExtRuntimeOnInstalledCallback is TBD_define_here

BrowserExtRuntimeOnMessageCallback is TBD_define_here

BrowserExtBrowserRuntime is TBD_define_here

getManifest is TBD_define_here

getURL is TBD_define_here

id is TBD_define_here

onConnect is TBD_define_here

onInstalled is TBD_define_here

onMessage is TBD_define_here

sendMessage is TBD_define_here

Port is TBD_define_here

MessageSender is TBD_define_here

BrowserExtRuntimeAPI is TBD_define_here

runtime is TBD_define_here

The tabs object

Overview

The tabs object is used to access metadata about a tab, such as its title, or to access the current content within the tab itself.

Manifest

The "tabs" permission is required to use this object.

{
    "permissions": [                               // Required
        "tabs"                                     // Either "tabs" or "activeTab" is required
        "activeTab"                                // Either "tabs" or "activeTab" is required
    ]                                              // Required   
}

Context

This API is available in Window context (background, event, popup, options and custom pages).

WebIDL Definition

A description of the special WebIDL syntax considerations for browser extensions are defined elsewhere in this document.

enum BrowserExtTabMutedReasonDetails { "user", "capture", "extension" };
enum BrowserExtRunAt { "document_end", "document_idle", "document_start" };
enum BrowserExtTabStatus { "complete", "loading" };
enum BrowserExtWindowTypes { "app", "normal", "panel", "popup" };
enum BrowserExtTabsCaptureVisibleTabFormat { "jpeg", "png" };

dictionary BrowserExtTabsTab {
    boolean active;
    boolean audible;
    DOMString favIconUrl;
    boolean highlighted;
    unsigned short height;
    unsigned short id;
    boolean incognito;
    unsigned short index;
    TabMutedDetails mutedDetails;
    unsigned short openerTabId;
    boolean pinned;
    DOMString sessionId;
    DOMString status;
    DOMString title;
    DOMString url;
    unsigned short width;
    unsigned short windowId;
};

dictionary BrowserExtTabMutedDetails {
    DOMString extensionId;
    boolean muted;
    TabMutedReasonDetails reason;
};
    dictionary BrowserExtTabConnectDetails {
    unsigned short frameId;
    DOMString name;
};
dictionary BrowserExtTabCreateDetails {
    boolean active;
    unsigned short index;
    unsigned short openerTabId;
    boolean pinned;
    DOMString url;
    unsigned short windowId;
};


dictionary BrowserExtTabScriptAndCSSDetails {
    boolean allFrames;
    DOMString code;
    DOMString file;
    unsigned short frameId;
    boolean matchAboutBlank;
    BrowserExtRunAt runAt;
};


dictionary BrowserExtTabsCaptureVisibleTabDetails {
    BrowserExtTabsCaptureVisibleTabFormat imageCaptureormat;
    unsigned short jpegQuality;
};
dictionary BrowserExtTabQueryDetails {
    boolean active;
    boolean audible;  
    boolean currentWindow;
    boolean highlighted;
    unsigned short index;
    boolean lastFocusedWindow;
    boolean muted;
    boolean pinned;
    TabStatus status;
    DOMString title;
    (DOMString or sequence<DOMString>) url;
    unsigned short windowId;
    WindowType windowType;
};
dictionary BrowserExtTabReloadDetails {
    boolean bypassCache;
};
dictionary BrowserExtTabSendMessageDetails {
    unsigned short frameId;
};
dictionary BrowserExtTabUpdateDetails {
    boolean active;
    boolean highlighted;
    boolean muted;
    unsigned short openerTabId;
    boolean pinned;
    DOMString url;
};
dictionary BrowserExtTabIdWindowId {
    unsigned short tabId;
    unsigned short windowId;
};
dictionary BrowserExtTabsWindowIdIsWindowClosing {
    boolean isWindowClosing;
    unsigned short tabId;
};
dictionary BrowserExtTabsOnUpdatedChangeDetails {
    boolean audible;    
    DOMString favIconUrl;
    TabMutedDetails mutedDetails;
    boolean pinned;
    DOMString status;
    DOMString title;
    DOMString url;
};
callback BrowserExtTabsOnActivatedCallback = void (BrowserExtTabIdWindowId activeDetails);
callback BrowserExtTabsOnCreatedCallback = void (BrowserExtTabTab tab);
callback BrowserExtTabsOnRemovedCallback = void (BrowserExtTabsWindowIdIsWindowClosing removeDetails);
callback BrowserExtTabsOnUpdatedCallback = void (unsigned short tabId, BrowserExtTabsOnUpdatedChangeDetails details, BrowserExtTabsTab tab);

[NoInterfaceObject]
interface BrowserExtBrowserTabs {
    Promise<DOMString> captureVisibleTab(unsigned short windowId, BrowserExtTabsCaptureVisibleTabDetails details);
    RuntimePort connect(unsigned short tabId, BrowserExtTabConnectDetails details);
    Promise<BrowserExtTabsTab> create(BrowserExtTabCreateDetails details);
    void executeScript(unsigned short tabId, BrowserExtTabScriptAndCSSDetails details);
    Promise<BrowserExtTabsTab> get(unsigned short tabId);
    Promise<BrowserExtTabsTab> getCurrent();
    void insertCSS(unsigned short tabId, BrowserExtTabScriptAndCSSDetails details);
    void onActivated(BrowserExtTabsOnActivatedCallback callback);
    void onCreated(BrowserExtTabsOnCreatedCallback callback);
    void onRemoved(BrowserExtTabsOnRemovedCallback callback);
    void onUpdated(BrowserExtTabsOnUpdatedCallback callback);
    Promise<BrowserExtTabsTab> query(BrowserExtTabQueryDetails queryDetails);
    Promise<void> reload(BrowserExtTabReloadDetails details);
    Promise<void> remove((unsigned short or sequence<unsigned short>) tabIds);
    Promise<any> sendMessage_TBD(unsigned short tabId, any message, optional BrowserExtTabSendMessageOptions details);
    Promise<BrowserExtTabsTab> update(optional unsigned short tabId, BrowserExtTabUpdateDetails details);
};
[NoInterfaceObject, Exposed=Window, CheckAnyPermissions_browserExtTabs_]
interface BrowserExtTabsAPI {
readonly attribute BrowserExtTabs tabs; 
};
Browser implements BrowserExtTabsAPI;

BrowserExtTabMutedReasonDetails is TBD_define_here

user is TBD_define_here

capture is TBD_define_here

extension is TBD_define_here

BrowserExtRunAt is TBD_define_here

document_end is TBD_define_here

document_idle is TBD_define_here

document_start is TBD_define_here

BrowserExtTabStatus is TBD_define_here

complete is TBD_define_here

loading is TBD_define_here

BrowserExtWindowTypes is TBD_define_here

app is TBD_define_here

normal is TBD_define_here

panel is TBD_define_here

popup is TBD_define_here

BrowserExtTabsCaptureVisibleTabFormat is TBD_define_here

jpeg is TBD_define_here

png is TBD_define_here

BrowserExtTabsTab is TBD_define_here

active is TBD_define_here

audible is TBD_define_here

favIconUrl is TBD_define_here

highlighted is TBD_define_here

height is TBD_define_here

id is TBD_define_here

incognito is TBD_define_here

index is TBD_define_here

mutedDetails is TBD_define_here

openerTabId is TBD_define_here

pinned is TBD_define_here

sessionId is TBD_define_here

status is TBD_define_here

title is TBD_define_here

url is TBD_define_here

width is TBD_define_here

windowId is TBD_define_here

BrowserExtTabMutedDetails is TBD_define_here

extensionId is TBD_define_here

muted is TBD_define_here

reason is TBD_define_here

BrowserExtTabConnectDetails is TBD_define_here

frameId is TBD_define_here

name is TBD_define_here

BrowserExtTabCreateDetails is TBD_define_here

active is TBD_define_here

index is TBD_define_here

openerTabId is TBD_define_here

pinned is TBD_define_here

url is TBD_define_here

windowId is TBD_define_here

BrowserExtTabScriptAndCSSDetails is TBD_define_here

allFrames is TBD_define_here

code is TBD_define_here

file is TBD_define_here

frameId is TBD_define_here

matchAboutBlank is TBD_define_here

runAt is TBD_define_here

BrowserExtTabsCaptureVisibleTabDetails is TBD_define_here

imageCaptureormat is TBD_define_here

jpegQuality is TBD_define_here

BrowserExtTabQueryDetails is TBD_define_here

active is TBD_define_here

audible is TBD_define_here

currentWindow is TBD_define_here

highlighted is TBD_define_here

index is TBD_define_here

lastFocusedWindow is TBD_define_here

muted is TBD_define_here

pinned is TBD_define_here

status is TBD_define_here

title is TBD_define_here

url is TBD_define_here

windowId is TBD_define_here

windowType is TBD_define_here

BrowserExtTabReloadDetails is TBD_define_here

bypassCache is TBD_define_here

BrowserExtTabSendMessageDetails is TBD_define_here

frameId is TBD_define_here

BrowserExtTabUpdateDetails is TBD_define_here

active is TBD_define_here

highlighted is TBD_define_here

muted is TBD_define_here

openerTabId is TBD_define_here

pinned is TBD_define_here

url is TBD_define_here

BrowserExtTabIdWindowId is TBD_define_here

tabId is TBD_define_here

windowId is TBD_define_here

BrowserExtTabsWindowIdIsWindowClosing is TBD_define_here

isWindowClosing is TBD_define_here

tabId is TBD_define_here

BrowserExtTabsOnUpdatedChangeDetails is TBD_define_here

audible is TBD_define_here

favIconUrl is TBD_define_here

mutedDetails is TBD_define_here

pinned is TBD_define_here

status is TBD_define_here

title is TBD_define_here

url is TBD_define_here

BrowserExtTabsOnActivatedCallback is TBD_define_here

BrowserExtTabsOnCreatedCallback is TBD_define_here

BrowserExtTabsOnRemovedCallback is TBD_define_here

BrowserExtTabsOnUpdatedCallback is TBD_define_here

BrowserExtBrowserTabs is TBD_define_here

captureVisibleTab is TBD_define_here

connect is TBD_define_here

create is TBD_define_here

executeScript is TBD_define_here

get is TBD_define_here

getCurrent is TBD_define_here

insertCSS is TBD_define_here

onActivated is TBD_define_here

onCreated is TBD_define_here

onRemoved is TBD_define_here

onUpdated is TBD_define_here

query is TBD_define_here

reload is TBD_define_here

remove is TBD_define_here

sendMessage_TBD is TBD_define_here

update is TBD_define_here

BrowserExtTabsAPI is TBD_define_here

tabs is TBD_define_here

The webNavigation object

Overview

The webNavigation object is used to monitor events related to networking requests.

Manifest

The "webNavigation" permission is required to use this object.

{
    "permissions": [                               // Required
        "webNavigation"                            // Required
    ]                                              // Required   
}

Context

This API is available in Window context (background, event, popup, options and custom pages).

WebIDL Definition

A description of the special WebIDL syntax considerations for browser extensions are defined elsewhere in this document.

enum BrowserExtTransitionType { "link", "typed" };
dictionary BrowserExtWebNavigationOnBeforeNavigateDetails {
    unsigned short frameId;
    unsigned short parentFrameId;
    unsigned short tabId;
    double timeStamp;
    DOMString url;
};
dictionary BrowserExtWebNavigationOnCommittedDetails {
    unsigned short frameId;
    unsigned short processId;
    unsigned short tabId;
    double timeStamp;
    TransitionType transitionType;
    DOMString url;
};
dictionary BrowserExtWebNavigationOnCompletedDetails {
    unsigned short frameId;
    unsigned short processId;
    unsigned short tabId;
    double timeStamp;
    DOMString url;
};
dictionary BrowserExtWebNavigationOnDOMContentLoadedDetails {
    unsigned short frameId;
    unsigned short processId;
    unsigned short tabId;
    double timeStamp;
    DOMString url;
};
dictionary BrowserExtWebNavigationOnErrorOccurredDetails {
    DOMString error;
    unsigned short frameId;
    unsigned short tabId;
    double timeStamp;
    DOMString url;
};
dictionary BrowserExtWebNavigationOnReferenceFragmentUpdatedDetails {
    unsigned short frameId;
    unsigned short processId;
    unsigned short tabId;
    double timeStamp;                           
    BrowserExtTransitionType transitionType;
    DOMString url;
};
callback BrowserExtWebNavigationOnBeforeNavigateCallback = void (BrowserExtWebNavigationOnBeforeNavigateDetails details);
callback BrowserExtWebNavigationOnCommittedCallback = void (BrowserExtWebNavigationOnCommittedDetails details);
callback BrowserExtWebNavigationOnCompletedCallback = void (BrowserExtWebNavigationOnCompletedDetails details);
callback BrowserExtWebNavigationOnDOMContentLoadedCallback = void (BrowserExtWebNavigationOnDOMContentLoadedDetails details);
callback BrowserExtWebNavigationOnErrorOccurredCallback = void (BrowserExtWebNavigationOnErrorOccurredDetails details);
callback BrowserExtWebNavigationOnReferenceFragmentUpdated = void (BrowserExtWebNavigationOnReferenceFragmentUpdatedDetails details);
[NoInterfaceObject]
interface BrowserExtBrowserWebNavigation {
    void onBeforeNavigate(BrowserExtWebNavigationOnBeforeNavigateCallback callback);
    void onCommitted(BrowserExtWebNavigationOnCommittedCallback callback);
    void onCompleted(BrowserExtWebNavigationOnCompletedCallback callback);
    void onDOMContentLoaded(BrowserExtWebNavigationOnDOMContentLoadedCallback callback);
    void onErrorOccurred(BrowserExtWebNavigationOnErrorOccurredCallback callback);
    void onReferenceFragmentUpdated(BrowserExtWebNavigationOnReferenceFragmentUpdated callback);
};
    
[NoInterfaceObject, Exposed=Window, CheckAnyPermissions_browserExtWebNavigation_]
interface BrowserExtWebNavigationAPI {
    readonly attribute BrowserExtWebNavigation webNavigation; 
};
Browser implements BrowserExtWebNavigationAPI;

BrowserExtTransitionType is TBD_define_here

link is TBD_define_here

typed is TBD_define_here

BrowserExtWebNavigationOnBeforeNavigateDetails is TBD_define_here

frameId is TBD_define_here

parentFrameId is TBD_define_here

tabId is TBD_define_here

timeStamp is TBD_define_here

url is TBD_define_here

BrowserExtWebNavigationOnCommittedDetails is TBD_define_here

frameId is TBD_define_here

processId is TBD_define_here

tabId is TBD_define_here

timeStamp is TBD_define_here

transitionType is TBD_define_here

url is TBD_define_here

BrowserExtWebNavigationOnCompletedDetails is TBD_define_here

frameId is TBD_define_here

processId is TBD_define_here

tabId is TBD_define_here

timeStamp is TBD_define_here

url is TBD_define_here

BrowserExtWebNavigationOnDOMContentLoadedDetails is TBD_define_here

frameId is TBD_define_here

processId is TBD_define_here

tabId is TBD_define_here

timeStamp is TBD_define_here

url is TBD_define_here

BrowserExtWebNavigationOnErrorOccurredDetails is TBD_define_here

error is TBD_define_here

frameId is TBD_define_here

tabId is TBD_define_here

timeStamp is TBD_define_here

url is TBD_define_here

BrowserExtWebNavigationOnReferenceFragmentUpdatedDetails is TBD_define_here

frameId is TBD_define_here

processId is TBD_define_here

tabId is TBD_define_here

timeStamp is TBD_define_here

transitionType is TBD_define_here

url is TBD_define_here

BrowserExtWebNavigationOnBeforeNavigateCallback is TBD_define_here

BrowserExtWebNavigationOnCommittedCallback is TBD_define_here

BrowserExtWebNavigationOnCompletedCallback is TBD_define_here

BrowserExtWebNavigationOnDOMContentLoadedCallback is TBD_define_here

BrowserExtWebNavigationOnErrorOccurredCallback is TBD_define_here

BrowserExtWebNavigationOnReferenceFragmentUpdated is TBD_define_here

BrowserExtBrowserWebNavigation is TBD_define_here

onBeforeNavigate is TBD_define_here

onCommitted is TBD_define_here

onCompleted is TBD_define_here

onDOMContentLoaded is TBD_define_here

onErrorOccurred is TBD_define_here

onReferenceFragmentUpdated is TBD

BrowserExtWebNavigationAPI is TBD_define_here

webNavigation is TBD_define_here

The webRequest object

Overview

The webRequest object is used to modify or cancel networking requests.

Manifest

The "webRequest" permission is required to use this object.

{
    "permissions": [                           // Required
        "webRequest"                            // Required
        "webRequestBlocking"                    // Optional
        "<URL pattern>"                         // Optional, e.g. "*://*.w3c.org/"
    ]                                          // Required   
}

Context

This API is available in Window context (background, event, popup, options and custom pages).

WebIDL Definition

A description of the special WebIDL syntax considerations for browser extensions are defined elsewhere in this document.

##27## unsigned short was used in many places in this spec to represent both unsigned integers and signed integers. Need to go back and find the places where negative numbers are allowed and changed from unsigned short to short.
NOTE: Frame ID can be 64-bit (long), ask Kris about others

enum BrowserExtResourceType { "font", "image", "main_frame", "object", "other", "ping", "script", "stylesheet", "sub_frame", "xmlhttprequest" };
dictionary BrowserExtWebRequestUploadDetails {
    any bytes;
    DOMString file;
};
dictionary BrowserExtWebRequestRequestBody {
    DOMString error;
    object formData;
    sequence<BrowserExtWebRequestUploadData> rawData;
};
dictionary BrowserExtWebRequestHttpHeader {
    DOMString keyName;
    any value;
};
dictionary BrowserExtWebRequestHttpHeaders {
    sequence<BrowserExtWebRequestHttpHeader> data; 
};
dictionary BrowserExtWebRequestOnBeforeRequestDetails {
    unsigned short frameId;
    DOMString method;
    unsigned short parentFrameId;
    BrowserExtWebRequestRequestBody requestBody;
    DOMString requestId;
    unsigned short tabId;
    double timeStamp;
    BrowserExtResourceType type;
    DOMString url;
};


dictionary BrowserExtWebRequestOnBeforeSendHeadersDetails {
    unsigned short frameId;
    DOMString method;
    unsigned short parentFrameId;
    DOMString requestId;
    unsigned short tabId;
    double timeStamp;
    BrowserExtResourceType type;
    DOMString url;
};


dictionary BrowserExtWebRequestOnCompletedDetails {
    unsigned short frameId;
    boolean fromCache;
    DOMString method;
    unsigned short parentFrameId;
    DOMString requestId;
    BrowserExtWebRequestHttpHeaders responseHeaders;
    DOMString serverIP;
    unsigned short statusCode;
    DOMString statusLine;
    unsigned short tabId;
    double timeStamp;   
    BrowserExtResourceType type;
    DOMString url;
}; 


dictionary BrowserExtWebRequestOnHeadersReceivedDetails {
    unsigned short frameId;
    DOMString method;
    unsigned short parentFrameId;
    DOMString requestId;
    BrowserExtWebRequestHttpHeaders responseHeaders;
    unsigned short statusCode;
    DOMString statusLine;
    unsigned short tabId;
    double timeStamp;   
    BrowserExtResourceType type;
    DOMString url;
};
dictionary BrowserExtWebRequestOnSendHeadersDetails {
    unsigned short frameId;
    DOMString method;
    unsigned short parentFrameId;
    BrowserExtWebRequestHttpHeaders requestHeaders;
    DOMString requestId;
    unsigned short tabId;
    double timeStamp;   
    BrowserExtResourceType type;
    DOMString url;
};

callback BrowserExtWebRequestOnBeforeRequestCallback = void (BrowserExtWebRequestOnBeforeRequestDetails details);
callback BrowserExtWebRequestOnBeforeSendHeadersCallback = void (BrowserExtWebRequestOnBeforeSendHeadersDetails details);
callback BrowserExtWebRequestOnCompletedCallback = void (BrowserExtWebRequestOnCompletedDetails details);
callback BrowserExtWebRequestOnHeadersReceivedCallback = void (BrowserExtWebRequestOnHeadersReceivedDetails details);
callback BrowserExtWebRequestOnSendHeadersCallback = void (BrowserExtWebRequestOnSendHeadersDetails details);
[NoInterfaceObject]
interface BrowserExtBrowserWebRequest {
    void onBeforeRequest(BrowserExtWebRequestOnBeforeRequestCallback callback);
    void onBeforeSendHeaders(BrowserExtWebRequestOnBeforeSendHeadersCallback callback);
    void onCompleted_TBD(BrowserExtWebRequestOnCompletedCallback callback);
    void onHeadersReceived(BrowserExtWebRequestOnHeadersReceivedCallback callback);
    void onSendHeaders(Function callback);
};
[NoInterfaceObject, Exposed=Window, CheckAnyPermissions_browserExtWebRequest_]
interface BrowserExtWebRequestAPI {
    readonly attribute BrowserExtWebRequest webRequest; 
};
Browser implements BrowserWebRequestAPI;

BrowserExtResourceType is TBD_define_here

font is TBD_define_here

image is TBD_define_here

main_frame is TBD_define_here

object is TBD_define_here

other is TBD_define_here

ping is TBD_define_here

script is TBD_define_here

stylesheet is TBD_define_here

sub_frame is TBD_define_here

xmlhttprequest is TBD_define_here

BrowserExtWebRequestUploadDetails is TBD_define_here

bytes is TBD_define_here

file is TBD_define_here

BrowserExtWebRequestRequestBody is TBD_define_here

error is TBD_define_here

formData is TBD_define_here

rawData is TBD_define_here

BrowserExtWebRequestHttpHeader is TBD_define_here

keyName is TBD_define_here

value is TBD_define_here

BrowserExtWebRequestHttpHeaders is TBD_define_here

data is TBD_define_here

BrowserExtWebRequestOnBeforeRequestDetails is TBD_define_here

frameId is TBD_define_here

method is TBD_define_here

parentFrameId is TBD_define_here

requestBody is TBD_define_here

requestId is TBD_define_here

tabId is TBD_define_here

timeStamp is TBD_define_here

type is TBD_define_here

url is TBD_define_here

BrowserExtWebRequestOnBeforeSendHeadersDetails is TBD_define_here

frameId is TBD_define_here

method is TBD_define_here

parentFrameId is TBD_define_here

requestId is TBD_define_here

tabId is TBD_define_here

timeStamp is TBD_define_here

type is TBD_define_here

url is TBD_define_here

BrowserExtWebRequestOnCompletedDetails is TBD_define_here

frameId is TBD_define_here

fromCache is TBD_define_here

method is TBD_define_here

parentFrameId is TBD_define_here

requestId is TBD_define_here

responseHeaders is TBD_define_here

serverIP is TBD_define_here

statusCode is TBD_define_here

statusLine is TBD_define_here

tabId is TBD_define_here

timeStamp is TBD_define_here

type is TBD_define_here

url is TBD_define_here

BrowserExtWebRequestOnHeadersReceivedDetails is TBD_define_here

frameId is TBD_define_here

method is TBD_define_here

parentFrameId is TBD_define_here

requestId is TBD_define_here

responseHeaders is TBD_define_here

statusCode is TBD_define_here

statusLine is TBD_define_here

tabId is TBD_define_here

timeStamp is TBD_define_here

type is TBD_define_here

url is TBD_define_here

BrowserExtWebRequestOnSendHeadersDetails is TBD_define_here

frameId is TBD_define_here

method is TBD_define_here

parentFrameId is TBD_define_here

requestHeaders is TBD_define_here

requestId is TBD_define_here

tabId is TBD_define_here

timeStamp is TBD_define_here

type is TBD_define_here

url is TBD_define_here

BrowserExtWebRequestOnBeforeRequestCallback is TBD_define_here

BrowserExtWebRequestOnBeforeSendHeadersCallback is TBD_define_here

BrowserExtWebRequestOnCompletedCallback is TBD_define_here

BrowserExtWebRequestOnHeadersReceivedCallback is TBD_define_here

BrowserExtWebRequestOnSendHeadersCallback is TBD_define_here

BrowserExtBrowserWebRequest is TBD_define_here

onBeforeRequest is TBD_define_here

onBeforeSendHeaders is TBD_define_here

onCompleted_TBD is TBD_define_here

onHeadersReceived is TBD_define_here

onSendHeaders is TBD_define_here

BrowserExtWebRequestAPI is TBD_define_here

webRequest is TBD_define_here

The windows object

Overview

The windows object is used to access the UI windows managed by the browser.

Manifest

There are no additional manifest entries required for an extension to use this object.

Context

This API is available in Window context (background, event, popup, options and custom pages).

WebIDL Definition

A description of the special WebIDL syntax considerations for browser extensions are defined elsewhere in this document.

enum BrowserExtWindowsWindowType { "detached_panel", "normal", "panel", "popup" };
enum BrowserExtWindowsWindowState { "docked", "fullscreen", "maximized", "minimized", "normal" };
dictionary BrowserExtCreateWindowDetails {
    boolean focused;
    unsigned short height;
    boolean incognito;
    unsigned short left;
    BrowserExtWindowsWindowState state;
    unsigned short tabId;
    unsigned short top;
    (DOMString or sequence<DOMString>) url;
    unsigned short width;
    BrowserExtWindowsWindowType windowType;
};
dictionary BrowserExtGetWindowDetails {
    boolean populate;
    sequence<BrowserExtWindowType> windowTypes;
};
dictionary BrowserExtWindowUpdateDetails {
    boolean drawAttention;
    boolean focused;
    unsigned short height;
    unsigned short left;
    unsigned short top;
    unsigned short width;
    BrowserExtWindowState windowState;
};
dictionary BrowserExtWindowsWindow {
    boolean alwaysOnTop;
    boolean focused;
    unsigned short height;
    unsigned short id;
    boolean incognito;
    unsigned short left;
    sequence<BrowserExtTabsTab> tabs;
    unsigned short top;
    DOMString sessionId;
    BrowserExtWindowsWindowState state;
    unsigned short width;
    BrowserExtWindowsWindowType windowType;
};
callback BrowserExtWindowsOnFocusChangedCallback = void (unsigned short windowId);
[NoInterfaceObject]
interface BrowserExtWindows {
    Promise<BrowserExtWindowsWindow> create(CreateWindowDetails details);
    Promise<BrowserExtWindowsWindow> get(unsigned short windowId, optional BrowserExtGetWindowDetails details);
    Promise<sequence<BrowserExtWindowsWindow>> getAll(optional BrowserExtGetWindowDetail details);
    Promise<BrowserExtWindowsWindow> getCurrent_TBD(optional BrowserExtGetWindowDetail details);
    Promise<BrowserExtWindowsWindow> getLastFocused(optional BrowserExtGetWindowDetail details);
    void onFocusChanged(BrowserExtWindowsOnFocusChangedCallback callback);
    Promise<BrowserExtWindowsWindow> update(unsigned short windowId, optional BrowserExtWindowUpdateDetails details);
};
    
[NoInterfaceObject, Exposed=Window, CheckAnyPermissions_browserExt_]
interface BrowserExtWindowsAPI {
readonly attribute BrowserExtWindows windows; 
};
Browser implements BrowserExtWindowsAPI;

BrowserExtWindowsWindowType is TBD_define_here

detached_panel is TBD_define_here

normal is TBD_define_here

panel is TBD_define_here

popup is TBD_define_here

BrowserExtWindowsWindowState is TBD_define_here

docked is TBD_define_here

fullscreen is TBD_define_here

maximized is TBD_define_here

minimized is TBD_define_here

normal is TBD_define_here

BrowserExtCreateWindowDetails is TBD_define_here

focused is TBD_define_here

height is TBD_define_here

incognito is TBD_define_here

left is TBD_define_here

state is TBD_define_here

tabId is TBD_define_here

top is TBD_define_here

url is TBD_define_here

width is TBD_define_here

windowType is TBD_define_here

BrowserExtGetWindowDetails is TBD_define_here

populate is TBD_define_here

windowTypes is TBD_define_here

BrowserExtWindowUpdateDetails is TBD_define_here

drawAttention is TBD_define_here

focused is TBD_define_here

height is TBD_define_here

left is TBD_define_here

top is TBD_define_here

width is TBD_define_here

windowState is TBD_define_here

BrowserExtWindowsWindow is TBD_define_here

alwaysOnTop is TBD_define_here

focused is TBD_define_here

height is TBD_define_here

id is TBD_define_here

incognito is TBD_define_here

left is TBD_define_here

tabs is TBD_define_here

top is TBD_define_here

sessionId is TBD_define_here

state is TBD_define_here

width is TBD_define_here

windowType is TBD_define_here

BrowserExtWindowsOnFocusChangedCallback is TBD_define_here

BrowserExtWindows is TBD_define_here

create is TBD_define_here

get is TBD_define_here

getAll is TBD_define_here

getCurrent_TBD is TBD_define_here

getLastFocused is TBD_define_here

onFocusChanged is TBD_define_here

update is TBD_define_here

BrowserExtWindowsAPI is TBD_define_here

windows is TBD_define_here

Native Messaging

Native Messaging is covered in another specification. Refer to the Native Messaging for Browser Extensions specification [[browserext-native]] for more information.

Manifest Format

Pre-parsing

Standards-compliant browsers are expected to ignore "//" comments. Disregarding comments, the manifest.json file format for browser extensions is expected to be fully JSON compliant. Malformed JSON files are not supported. If manifest keys that are not defined in this specification are specified, other browsers MAY ignore those keys.

Permissions URL patterns

##28## Define how and where permission patterns are used

Full Example

// Standards-compliant browsers are expected to ignore "//" comments. Disregarding comments, 
// the manifest.json file format for browser extensions is expected to be fully JSON compliant. 
// Malformed JSON files are not supported.
//
// Other manifest keys that are well-formed JSON but are not listed here MUST be ignored.
//
// Note that some fields marked as Optional here are required by vendor-specific distribution Stores.
{
  "name": "The Name of Your Extension",             // Required
  "version": "Your Extension Version",              // Required
  "default_locale": "en",                           // Required if locales are used. Otherwise, not allowed
  "description": "Description for Your Extensions",   
  "icons": {...},                                    
  "developer": {                                    
       "name": "Your Name or Company",              
       "url": "Company Website"                      
  }
  // Note: Some browsers require an extension to use either browser_action or page_action, but not both simultaneously
  "browser_action": {  
      "default_icon": {...},                        // Same format as "icons"
      "default_popup": "Page URL",
      "default_title": "Title string"
  },
  "page_action": {...},                             // Same format as "browser_action"
  
  "browser_specific_settings": {                    
       "<browser_name>": {                          // Examples "gecko","opera","edge"
            "<key>": "<value>"                      // Examples "strict_min_version": "42.0", "id": "addon@example.com"
       }
  },
  "background": {                                   
      "page": "Page URL",                           // Only one of "page" or "scripts" is supported, but not both simultaneously
      "scripts": [],                                // Only one of "page" or "scripts" is supported, but not both simultaneously
      "persistent": false                           // Required if "background" is specified
  },
  "content_scripts": {                                                    
      "all_frames": false,                          
      "css": [],                                   
      "exclude_matches": [],                        
      "js": [],                                     
      "matches": [],                                
      "run_at" : "document_start"                   // Also "document_end", "document_idle"
  }
  "content_security_policy": "<policy-string>",     
  
  "options_page": "Page URL",                            // Optional
  "manifest_version": 2,                            // Not used
  "required_keys": [],                              // If a browser does not recognize a key in this list, it MUST 
                                                    // reject the manifest (e.g. "sidebar_action")
                                                    // FEEDBACK: Rename to "required_capabilities"
  "permissions": {                                  
       "activeTab",                                                
       "contextMenus",                              
       "storage",                                   
       "tabs",                                      
       "webNavigation",                            
       "webRequest",                                
       "webRequestBlocking",                        
       "<url-pattern>"                              // Examples "http://*/*", "<all_urls>"
  },
  "web_accessible_resources": [...]    
  "externally_connectable" : [
       "ids":[...], // Identifiers for other extensions that are allowed to send messages
       "matches":[...] // URL patterns for hosted web pages allowed to send messages 
  ]                             
}

Extension Resources

The browserext:// protocol

To access resources within the extension, such as browserext://<ext_id>/options.html, the browserext:// protocol is used.

Extension IDs

Each extension has an extension ID that follows the browserext:// protocol. For example

browserext://MyExtension_c1wakc4j0nefm/options.html browserext://dfcijpibodeoenkablikbkiobbdnkfki/options.html

The algorithms that generate these IDs are different for each browser. To access these resources, do not hardcode the ID generated by a particular browser. Instead, use the runtime.getURL() method to convert a relative file name or path to the absolute name or path, which includes the extension ID.

Content Security Polity (CSP)

The default CSP is discussed in the specification [[CSP3]] .

##29## Complete this section, discussing special considerations for extensions and CSP.

Testing Extensions with WebDriver

Browsers vendors MAY choose to implement WebDriver support in their browsers to allow for the automated testing of browser extensions. To implement this support, the browser MUST support:

[ISSUE] (2016.09.22) ##31## Title should be enough to identify extension, but do we want to add an extensionId or extensionName property? Will consult BE CG

[ISSUE] (2016.09.22) ##33## Add extension during session at runtime

[ISSUE] (2016.09.22) ##34## For installing, you will need an endpoint for installing/activating at runtime

[ISSUE] (2016.09.22) Support user permissions/prompts (Need to follow up with Kris)

[ISSUE] (2016.09.22) Should be overlap with Permissions API – chat with them (need to discuss, not sure what this means)

Protocol

List of Endpoints

In addition to the endpoints defined in the WebDriver specification [[webdriver]], support for browser extensions requires these additional endpoints.

Method URI Template Command
GET /session/{sessionId}/browserext/actions Get Browser Extension Actions
POST /session/{sessionId}/browserext/actions/{ExtensionActionID} Take Browser Extension Action
POST /session/{sessionId}/element/{element id}/browserext/contextMenu Select Browser Extension Context Menu
POST /session/{sessionId}/element/{element id}/browserext/contextMenu/{item} Select Browser Extension Context Menu Item

Handling Errors

In addition to the codes defined in the Handling Errors section of the WebDriver specification [[webdriver]], support support for browser extensions requires support the following additional error codes:

Error Code HTTP Status JSON Error Code Description
no such browser extension 400 no such browser extension There is no available browser extension on the current page with the given id.
no such browser extension popup 400 no such browser extension popup A request to switch to a browser extension popup could not be satisfied because there is no browser extension popup currently open.
no such browser extension context menu item 400 no such browser extension context menu item A request to select an extension context menu item could not be completed because there is no matching extension context menu item for the given element.

Capabilities

In addition to the Capabilities defined in the WebDriver specification [[webdriver]], support support for browser extensions requires the following additional entry on the server capabilities JSON object:

"enabledExtensions"
An array of relative paths which point to the location of browser extension files. The path MUST point to either a single file appropriate for a specific brower (e.g. .crx) or a folder which contains the extension source files. If a folder is specified, the folder itself MUST contain a manifest.json file. Subfolders containing manifest.json files will not be searched.

Extension Lifetime

No browser extension will be installed or pre-loaded during a WebDriver session unless it is explicitly specified in the enabledExtensions array. Browser extensions loaded during the session will not be available to other active instances of the browser that are not part of the WebDriver session. When the session ends, the array of browser extensions are unloaded and uninstalled.

Browser Extensions Commands

Users interact with extensions through several means. First there are actions embedded in the chrome of the browser, which can do something directly or open a popup. If the extension uses a popup, it can contain any html content. Finally, extensions can add items to the browser's context menu. WebDriver needs to be able to emulate user actions for all three of these controls in order to completely emulate user interaction.

In addition to the commands defined in the WebDriver specification [[webdriver]], support support for browser extensions requires the following additional commands.

getBrowserExtActions()

HTTP Method Path Template Notes
GET /session/{sessionId}/browserext/actions

This command returns a list of browser extension actions available on the current page. Note that this can change from page to page. It MUST return a list of objects which describes the available browser extension actions using the following algorithm for each action:

  • Let action be a new JSON Object.

  • Set the property id on action to a string which is unique for the current session.

  • Set the property actionTitle on action to the mouseover text for the action.

  • Set the property icon on action to the filename of the icon file or an empty string if none is displayed. If the icon is dynamically generated, the current icon MUST be returned as a lossless PNG image encoded using Base64.

  • Set the property badgeText on action to the badge text displayed over the action or an empty string if none is present.

  • Return success with data action

takeBrowserExtAction()

HTTP Method Path Template Notes
POST /session/{sessionId}/browserext/action/{browserExtActionId}

This command causes a browser extension to be activated, as if the user had clicked the browser extension's browser action icon in the browser's chrome. Depending on the browser extension, this could cause a popup to be opened.

DOMString browserExtActionId
The unique identifier of the browser extension action to be taken, as returned by the getBrowserExtActions() command.

If the id specified does not correspond to a browser extension on the current page, a no such browser extension status code MUST be returned.

selectBrowserExtContextMenu()

HTTP Method Path Template Notes
POST /session/{sessionId}/element/{elementId}/browserext/contexMenu

This command opens a context menu for a given element. It MUST return a list of objects which describes the available context menu items using the following algorithm for each menu item:

  • Let menuitem be a new JSON Object.

  • Set the property id on menuitem to a string which is unique for the current session.

  • Set the property menuItemTitle on menuitem to the text that is displayed in the UI.

  • Set the property icon on menuitem to the filename of the icon file or an empty string if none is displayed. If the icon is set because of the type of the context menu item (such as a radio button or checkbox), the icon property MUST be set to a string which is consistent for all icons of that type and status (e.g. checked), including across sessions.

  • Set the property parent on menuitem to the id of the item's parent or an empty string if the menuitem does not have a parent.

  • Set the property itemType on menuitem to a string value identifying the control type.

    String Value Description
    checkbox A checkbox element
    normal A standard menuItem element (text label)
    radio A radio element. Within a radio group, only one menuItem will have a value of true
    separator A horizontal line separator, typically used between groups of related items such as radio groups
  • Set the property itemChecked on menuitem to a boolean value indicating state of the item according to the following table. This applies only to items of itemType checkbox or radio. Within a radio group, only one menuItem will have a value of true.

    Boolean Value Description
    true Selected
    false Not selected
  • Return success with data menuitem

This list MUST contain all context menu items added by browser extensions and MUST NOT contain any other context menu items.

After this command has been run, the context menu MUST remain open until the next command that dismisses it (e.g. clicking, navigation) has been run.

WebElement elementId
The id of the element for which the context menu should be opened.

selectBrowserExtContextMenuItem()

HTTP Method Path Template Notes
POST /session/{sessionId}/element/{elementId}/browserext/contextMenu/{menuitemId}

This command causes a context menu item to be selected. This MUST have the same effect as a user clicking or tapping the item in the open context menu. If the menu item is a parent of other menu items, this command MAY open a submenu, but MUST NOT have any other effect.

This command MUST be executed even if there is no context menu open.

String menuitemId
The context menu item id, as returned by the selectBrowserExtContextMenu() command.

If no popup is currently open, a no such extension context menu item status code MUST be returned.

Packaging

Browser extensions MAY be distributed and subsequently loaded as individual files or via a container, such as a *.zip archive. Regardless of the packaging format, these containers must contain the following:

Digital signatures

This is TBD.

Acknownledgements

Many thanks to the members of the Browser Extension Community Group for their detailed feedback on this specification. Thanks to the members of the Browser Testing and Tools Working Group for their recommendations and feedback on WebDriver support.

Some sections are reproduced from MDN: