runtime.connect()
=================

Make a connection between different contexts inside the extension.

You can call this:

* in an extension's content scripts, to establish a connection with the extension's background scripts (or similarly privileged scripts, like popup scripts or options page scripts).
* in an extension's background scripts (or similarly privileged scripts), to establish a connection with a different extension.

Note that you can't use this function to connect an extension to its content scripts. To do this, use `tabs.connect()`.

By default, this connection enables the extension to exchange messages with itself or any other extension (if `extensionId` is specified). However, the `externally_connectable` manifest key can be used to limit communication to specific extensions and enable communication with websites. Connections within the extension trigger the `runtime.onConnect` event, connections from other extensions or web pages trigger the `runtime.onConnectExternal` event.

Syntax
------


```js
let port = browser.runtime.connect(
  extensionId, // optional string
  connectInfo  // optional object
)
```

### Parameters

`extensionId` Optional

`string`. The ID of the extension to connect to. If the target has set an ID explicitly using the browser\_specific\_settings key in manifest.json, then `extensionId` should have that value. Otherwise it should have the ID that was generated for the target.

`connectInfo` Optional

`object`. Details of the connection:

`name` Optional

`string`. Will be passed into `runtime.onConnect` for processes that are listening for the connection event.

`includeTlsChannelId` Optional

`boolean`. Whether the TLS channel ID will be passed into `runtime.onConnectExternal` for processes that are listening for the connection event.


### Return value

`runtime.Port`. Port through which messages can be sent and received. The port's `onDisconnect` event is fired if the extension does not exist.

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 called `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.