recursal/MDN huggingface dataset:
runtime.onConnect
=================

Fired when a connection is made with either an extension process or a content script.

Syntax
------


```js
browser.runtime.onConnect.addListener(listener)
browser.runtime.onConnect.removeListener(listener)
browser.runtime.onConnect.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Checks whether a `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`function`

The function called when this event occurs. The function is passed this argument:

`port`

A `runtime.Port` object connecting the current script to the other context it is connecting to.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

This content script:

* connects to the background script, and stores the `Port` in a variable `myPort`
* listens for messages on `myPort`, and logs them
* sends messages to the background script, using `myPort`, when the user clicks the document


```js
// content-script.js

let myPort = browser.runtime.connect({ name: "port-from-cs" });
myPort.postMessage({ greeting: "hello from content script" });

myPort.onMessage.addListener((m) => {
  console.log("In content script, received message from background script: ");
  console.log(m.greeting);
});

document.body.addEventListener("click", () => {
  myPort.postMessage({ greeting: "they clicked the page!" });
});
```


The corresponding background script:

* listens for connection attempts from the content script
* when it receives a connection attempt:
    + stores the port in a variable named `portFromCS`
    + sends the content script a message using the port
    + starts listening to messages received on the port, and logs them
* sends messages to the content script, using `portFromCS`, when the user clicks the extension's browser action


```js
// background-script.js

let portFromCS;

function connected(p) {
  portFromCS = p;
  portFromCS.postMessage({ greeting: "hi there content script!" });
  portFromCS.onMessage.addListener((m) => {
    console.log("In background script, received message from content script");
    console.log(m.greeting);
  });
}

browser.runtime.onConnect.addListener(connected);

browser.browserAction.onClicked.addListener(() => {
  portFromCS.postMessage({ greeting: "they clicked the button!" });
});
```


**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.onBrowserUpdateAvailable
================================

**Deprecated:** This feature is no longer recommended. Though some browsers might still support it, it may have already been removed from the relevant web standards, may be in the process of being dropped, or may only be kept for compatibility purposes. Avoid using it, and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.

Fired when an update for the browser is available, but it isn't installed immediately because a browser restart is required.

Syntax
------


```js
browser.runtime.onBrowserUpdateAvailable.addListener(listener)
browser.runtime.onBrowserUpdateAvailable.removeListener(listener)
browser.runtime.onBrowserUpdateAvailable.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Checks whether a `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`function`

The function called when this event occurs.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Listen for this event:


```js
function handleBrowserUpdateAvailable() {
  // handle event
}

browser.runtime.onBrowserUpdateAvailable.addListener(
  handleBrowserUpdateAvailable,
);
```


**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.reload()
================

Reloads the extension.

If there are any pending updates for the extension, that it has deferred by listening to `runtime.onUpdateAvailable`, then they will be applied on reload.

Syntax
------


```js
browser.runtime.reload()
```

### Parameters

None.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Reload the extension when the user clicks a browser action's icon:


```js
browser.browserAction.onClicked.addListener((tab) => {
  browser.runtime.reload();
});
```

### Example extensions

* runtime-examples

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.PlatformInfo
====================

An object containing information about the current platform.

Type
----

Values of this type are objects, which contain the following properties:

`os`

`runtime.PlatformOs`. The platform's operating system.

`arch`

`runtime.PlatformArch`. The platform's processor architecture.

`nacl_arch`

`runtime.PlatformNaclArch`. The native client architecture. This may be different from `arch` on some platforms.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.setUninstallURL()
=========================

Sets the URL to be visited when the extension is uninstalled. This can be used to clean up server-side data, do analytics, or implement surveys. The URL can be up to 1023 characters. This limit used to be 255, see Browser compatibility for more details.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let settingUrl = browser.runtime.setUninstallURL(
  url             // string
)
```

### Parameters

`url`

`string`. URL to open after the extension is uninstalled. This URL must have an `http` or `https` scheme. Can be up to 1023 characters. Set to an empty string to not open a new tab when the extension is uninstalled.

### Return value

A `Promise` fulfilled with no arguments when the URL is set or rejected with an error message if the operation fails.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------


```js
function onSetURL() {
  console.log("set uninstall URL");
}

function onError(error) {
  console.log(`Error: ${error}`);
}

let settingUrl = browser.runtime.setUninstallURL("https://example.org");
settingUrl.then(onSetURL, onError);
```


**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.MessageSender
=====================

An object containing information about the sender of a message or connection request that is passed to the `runtime.onMessage()` listener.

It is also a property of `runtime.Port`, but only in the `Port` instance passed into the `runtime.onConnect()` or `runtime.onConnectExternal()` listeners.

Type
----

Values of this type are objects. They contain the following properties:

`documentId` Optional

`string`. A UUID of the document that opened the connection.

`documentLifecycle` Optional

`string`. The lifecycle state the document that opened the connection was in when the port was created. Note that the lifecycle state of the document may have changed since the port was created.

`frameId` Optional

`integer`. The frame that opened the connection. Zero for top-level frames, positive for child frames. This is only set when `tab` is set.

`id` Optional

`string`. The ID of the extension that sent the message, if the message was sent by an extension. If the sender has an ID explicitly set using the browser\_specific\_settings key in manifest.json, then `id` has this value. Otherwise, it has the ID that was generated for the sender.

`origin` Optional

`string`. The origin of the page or frame that opened the connection. It can differ from the `url` property (e.g., about:blank) or be opaque (e.g., sandboxed iframes). This is useful for identifying if the origin can be trusted if it isn't apparent from the URL.

`tab` Optional

`tabs.Tab`. The `tabs.Tab` which opened the connection. This property is only present when the connection was opened from a tab (including content scripts).

`tlsChannelId` Optional

`string`. The TLS channel ID of the page or frame that opened the connection, if requested by the extension and available.

`url` Optional

`string`. The URL of the page or frame hosting the script that sent the message.

If the sender is a script running in an extension page (such as a background page, an options page, or a browser action or page action popup), the URL is in the form `"moz-extension://<extension-internal-id>/path/to/page.html"`. If the sender is a background script and you haven't included a background page, it is `"moz-extension://<extension-internal-id>/_generated_background_page.html"`.

If the sender is a script running in a web page (including content and normal page scripts), then `url` is the web page URL. If the script is running in an iframe, `url` is the iframe's URL.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.OnRestartRequiredReason
===============================

The reason that the `onRestartRequired` event is being dispatched.

Type
----

Values of this type are strings. Possible values are:

* `"app_update"`: The application is being updated to a newer version.
* `"os_update"`: The browser/OS is updated to a newer version.
* `"periodic"`: The system has run for more than the permitted uptime set in the enterprise policy.
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.onInstalled
===================

Fired when the extension is first installed, when the extension is updated to a new version, and when the browser is updated to a new version.

Note that `runtime.onInstalled` is not the same as `management.onInstalled`. The `runtime.onInstalled` event is fired only for your extension. The `browser.management.onInstalled` event is fired for any extensions.

Syntax
------


```js
browser.runtime.onInstalled.addListener(listener)
browser.runtime.onInstalled.removeListener(listener)
browser.runtime.onInstalled.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Checks whether a `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`function`

The function called when this event occurs. The function is passed these arguments:

`details`

An object with the following properties:

`id` Optional

`string`. The ID of the imported shared module extension that updated. This is present only if the `reason` value is `shared_module_update`.

`previousVersion` Optional

`string`. The previous version of the extension just updated. This is only present if the `reason` value is `update`.

`reason`

An `runtime.OnInstalledReason` value, stating the reason that this event is being dispatched.

`temporary`

`boolean`. True if the add-on was installed temporarily. For example, using the "about:debugging" page in Firefox or using web-ext run. False otherwise.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

When the extension is installed, log the install reason and open https://example.com:


```js
function handleInstalled(details) {
  console.log(details.reason);
  browser.tabs.create({
    url: "https://example.com",
  });
}

browser.runtime.onInstalled.addListener(handleInstalled);
```

### Example extensions

* runtime-examples

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.onRestartRequired
=========================

Fired when an app or the device that it runs on needs to be restarted. The app should close all its windows at its earliest convenience to let the restart happen. If the app does nothing, a restart will be enforced after a 24-hour grace period has passed. Currently, this event is only fired for ChromeOS kiosk apps.

Syntax
------


```js
browser.runtime.onRestartRequired.addListener(listener)
browser.runtime.onRestartRequired.removeListener(listener)
browser.runtime.onRestartRequired.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Checks whether a `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`function`

The function called when this event occurs. The function is passed this argument:

`reason`

A `runtime.OnRestartRequiredReason` value — the reason that the event is being dispatched.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.onSuspendCanceled
=========================

Sent after `runtime.onSuspend` to indicate that the app won't be unloaded after all.

Syntax
------


```js
browser.runtime.onSuspendCanceled.addListener(listener)
browser.runtime.onSuspendCanceled.removeListener(listener)
browser.runtime.onSuspendCanceled.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Checks whether a `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Listen for `SuspendCanceled` events:


```js
function handleSuspendCanceled() {
  console.log("Suspend canceled");
}

browser.runtime.onSuspendCanceled.addListener(handleSuspendCanceled);
```


**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.lastError
=================

This value is used to report an error message from an asynchronous API, when the asynchronous API is given a callback. This is useful for extensions that are using the callback-based version of the WebExtension APIs.

You don't need to check this property if you are using the promise-based version of the APIs: instead, pass an error handler to the promise:


```js
const gettingCookies = browser.cookies.getAll();
gettingCookies.then(onGot, onError);
```


The `runtime.lastError` property is set when an asynchronous function has an error condition that it needs to report to its caller.

If you call an asynchronous function that may set `lastError`, you are expected to check for the error when you handle the result of the function. If `lastError` has been set and you don't check it within the callback function, then an error will be raised.

Syntax
------


```js
let myError = browser.runtime.lastError;  // null or Error object
```

### Value

An `Error` object representing the error. The `message` property is a `string` with a human-readable description of the error. If `lastError` has not been set, the value is `null`.

Examples
--------

Set a cookie, using a callback to log the new cookie or report an error:


```js
function logCookie(c) {
  if (browser.runtime.lastError) {
    console.error(browser.runtime.lastError);
  } else {
    console.log(c);
  }
}

browser.cookies.set({ url: "https://developer.mozilla.org/" }, logCookie);
```


The same, but using a promise to handle the result of `setCookie()`:


```js
function logCookie(c) {
  console.log(c);
}

function logError(e) {
  console.error(e);
}

const setCookie = browser.cookies.set({
  url: "https://developer.mozilla.org/",
});

setCookie.then(logCookie, logError);
```


**Note:** `runtime.lastError` is an alias for `extension.lastError`. They are set together, and checking either one will work.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

### Example extensions

* menu-demo

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.PlatformNaclArch
========================

The native client architecture. This may be different from arch on some platforms.

Type
----

Values of this type are strings. Possible values are: `"arm"`, `"x86-32"`, `"x86-64"`.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.getPackageDirectoryEntry()
==================================

Returns a `DirectoryEntry` object representing the package directory.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingEntry = browser.runtime.getPackageDirectoryEntry()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with a `DirectoryEntry` object representing the package directory.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------


```js
function gotDirectoryEntry(directoryEntry) {
  console.log(directoryEntry);
}

let gettingEntry = browser.runtime.getPackageDirectoryEntry();
gettingEntry.then(gotDirectoryEntry);
```


**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.openOptionsPage()
=========================

If your extension has an options page defined, this method opens it.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let openingPage = browser.runtime.openOptionsPage()
```

### Parameters

None.

### Return value

A `Promise` that will be fulfilled with no arguments when the options page has been created successfully, or rejected with an error message if the operation failed.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Open the options page when the user clicks a browser action's icon:


```js
function onOpened() {
  console.log(`Options page opened`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

let opening = browser.runtime.openOptionsPage();
opening.then(onOpened, onError);
```

### Example extensions

* favourite-colour

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.PlatformArch
====================

The machine's processor architecture.

Type
----

Values of this type are strings. Possible values are:

`"arm"`

The platform is based on arm architecture.

`"x86-32"`

The platform is based on x86 32-bit architecture.

`"x86-64"`

The platform is based on x86 64-bit architecture.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.
runtime.onConnectExternal
=========================

Fired when an extension receives a connection request from a different extension.

To send a message which will be received by the `onConnectExternal` listener, use `runtime.connect()`, passing the ID of the recipient in the `extensionId` parameter.

The listener is passed a `runtime.Port` object which it can then use to send and receive messages. The `Port` object also contains a `sender` property, which is a `runtime.MessageSender` object, and which the recipient can use to check the sender's ID.

Syntax
------


```js
browser.runtime.onConnectExternal.addListener(listener)
browser.runtime.onConnectExternal.removeListener(listener)
browser.runtime.onConnectExternal.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Checks whether a `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`function`

The function called when this event occurs. The function is passed this argument:

`port`

A `runtime.Port` object connecting the current script to the other extension it is connecting to.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

In this example the extension Hansel connects to the extension Gretel:


```js
console.log("connecting to Gretel");
let myPort = browser.runtime.connect("gretel@mozilla.org");

myPort.onMessage.addListener((message) => {
  console.log(`From Gretel: ${message.content}`);
});

browser.browserAction.onClicked.addListener(() => {
  myPort.postMessage({ content: "Hello from Hansel" });
});
```


Gretel listens for the connection and checks that the sender is really Hansel:


```js
let portFromHansel;

browser.runtime.onConnectExternal.addListener((port) => {
  console.log(port);
  if (port.sender.id === "hansel@mozilla.org") {
    console.log("connection attempt from Hansel");
    portFromHansel = port;
    portFromHansel.onMessage.addListener((message) => {
      console.log(`From Hansel: ${message.content}`);
    });
  }
});

browser.browserAction.onClicked.addListener(() => {
  portFromHansel.postMessage({ content: "Message from Gretel" });
});
```


**Note:** This API is based on Chromium's `chrome.runtime` API. This documentation is derived from `runtime.json` in the Chromium code.