runtime.onConnectExternal - Content

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 {{WebExtAPIRef("runtime.connect()")}}, passing the ID of the recipient in the extensionId parameter.

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

Syntax

js-nolint

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 {{WebExtAPIRef('runtime.Port')}} object connecting the current script to the other extension it is connecting to.

Examples

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

console.log("connecting to Gretel");
let myPort = browser.runtime.connect("[email protected]");

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:

let portFromHansel;

browser.runtime.onConnectExternal.addListener((port) => {
  console.log(port);
  if (port.sender.id === "[email protected]") {
    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" });
});

Browser compatibility

[!NOTE] This API is based on Chromium's chrome.runtime API. This documentation is derived from runtime.json in the Chromium code.