MDN self-hosted library · e01.org

runtime.onConnectExternal

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

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

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.

Examples

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

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:

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" });
});

Browser compatibility

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