Berichtoverdracht

Met Messaging API's kun je communiceren tussen verschillende scripts die worden uitgevoerd in contexten die aan je extensie zijn gekoppeld. Dit omvat communicatie tussen je serviceworker, chrome-extension://pages en contentscripts. Een RSS-lezer-extensie kan bijvoorbeeld contentscripts gebruiken om de aanwezigheid van een RSS-feed op een pagina te detecteren en de servicemedewerker vervolgens op de hoogte te stellen om het actie-icoon voor die pagina te updaten.

Er zijn 2 API's voor het doorgeven van berichten: een voor eenmalige verzoeken en een complexere voor langdurige verbindingen waarmee meerdere berichten kunnen worden gestuurd.

Ga naar het gedeelte Berichten tussen extensies voor meer informatie over hoe je berichten tussen extensies stuurt.

Eenmalige verzoeken

Als je één bericht naar een ander deel van je extensie wilt sturen en eventueel een reactie wilt krijgen, roep je runtime.sendMessage() of tabs.sendMessage() aan. Met deze methoden kun je een eenmalig JSON-serialiseerbaar bericht sturen van een contentscript naar de extensie of van de extensie naar een contentscript. Beide API's retourneren een Promise die wordt omgezet in de reactie van een ontvanger.

Zo stuur je een verzoek vanuit een contentscript:

content-script.js:

(async () => {
  const response = await browser.runtime.sendMessage({greeting: "hello"});
  // do something with response here, not outside the function
  console.log(response);
})();

Antwoorden

Gebruik de gebeurtenis browser.runtime.onMessage om naar een bericht te luisteren:

// Event listener
function handleMessages(message, sender, sendResponse) {
  if (message !== 'get-status') return;

  fetch('https://example.com')
    .then((response) => sendResponse({statusCode: response.status}))

  // Since `fetch` is asynchronous, must return an explicit `true`
  return true;
}

browser.runtime.onMessage.addListener(handleMessages);

// From the sender's context...
const {statusCode} = await browser.runtime.sendMessage('get-status');

Als de event-listener wordt aangeroepen, wordt een sendResponse-functie doorgegeven als de 3e parameter. Dit is een functie die kan worden aangeroepen om een reactie te geven. Standaard moet de callback sendResponse synchroon worden aangeroepen.

Als je sendResponse aanroept zonder parameters, wordt null als reactie gestuurd.

Als je een reactie asynchroon wilt sturen, heb je 2 opties: true retourneren of een promise retourneren.

Retourzending true

Als je asynchroon wilt reageren met sendResponse(), retourneer je een letterlijke true (niet alleen een waarheidsgetrouwe waarde) van de gebeurtenislistener. Zo blijft het berichtkanaal open voor de andere kant totdat sendResponse wordt aangeroepen, zodat je het later kunt aanroepen.

Een promise retourneren

Vanaf Chrome 148 kun je een promise van een berichtlistener retourneren om asynchroon te reageren. Deze update wordt geleidelijk uitgerold, dus deze is misschien nog niet beschikbaar in de browsers van alle gebruikers. Zorg dat je extensie kan omgaan met of deze mogelijkheid aanstaat of niet. Het gebruik van return true; blijft werken voor asynchrone reacties, of deze functie nu aanstaat of niet.

Als de promise wordt opgelost, wordt de opgeloste waarde als reactie gestuurd.

Als de promise wordt afgewezen, wordt de aanroep van de afzender sendMessage() afgewezen met de foutmelding. Ga naar het gedeelte Foutafhandeling voor meer informatie en voorbeelden.

Een voorbeeld dat een promise retourneert die kan worden opgelost of afgewezen:

// Event listener
function handleMessages(message, sender, sendResponse) {
  // Return a promise that wraps fetch
  // If the response is OK, resolve with the status. If it's not OK then reject
  // with the network error that prevents the fetch from completing.
  return new Promise((resolve, reject) => {
    fetch('https://example.com')
      .then(response => {
        if (!response.ok) {
          reject(response);
        } else {
          resolve(response.status);
        }
      })
      .catch(error => {
        reject(error);
      });
  });
}
browser.runtime.onMessage.addListener(handleMessages);

Je kunt een listener ook declareren als async om een promise te retourneren:

browser.runtime.onMessage.addListener(async function(message, sender) {
  const response = await fetch('https://example.com');
  if (!response.ok) {
    // rejects the promise returned by `async function`.
    throw new Error(`Fetch failed: ${response.status}`);
  }
  // resolves the promise returned by `async function`.
  return {statusCode: response.status};
});

Een promise retourneren: async-functie-addertjes onder het gras

Houd er rekening mee dat een async-functie als listener altijd een promise retourneert, zelfs zonder een return-instructie. Als een async-listener geen waarde retourneert, wordt de promise impliciet omgezet in undefined en wordt null als reactie naar de afzender gestuurd. Dit kan onverwacht gedrag veroorzaken als er meerdere listeners zijn:

// content_script.js
function handleResponse(message) {
    // The first listener promise resolves to `undefined` before the second
    // listener can respond. When a listener responds with `undefined`, Chrome
    // sends null as the response.
    console.assert(message === null);
}
function notifyBackgroundPage() {
    const sending = browser.runtime.sendMessage('test');
    sending.then(handleResponse);
}
notifyBackgroundPage();

// background.js
browser.runtime.onMessage.addListener(async (message) => {
    // This just causes the function to pause for a millisecond, but the promise
    // is *not* returned from the listener so it doesn't act as a response.
    await new Promise(resolve => {
        setTimeout(resolve, 1, 'OK');
    });
   // `async` functions always return promises. So once we
   // reach here there is an implicit `return undefined;`. Chrome translates
   // `undefined` responses to `null`.
});

browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
  return new Promise((resolve) => {
    setTimeout(resolve, 1000, 'response');
  });
});

Probleemoplossing

Vanaf Chrome 146 geldt dat als een onMessage-listener een fout genereert (synchroon of asynchroon door een promise te retourneren die wordt afgewezen), de promise die door sendMessage() in de afzender wordt geretourneerd, wordt afgewezen met het bericht van de fout. Deze update wordt geleidelijk uitgerold, dus deze wijziging is misschien nog niet van kracht in de browsers van alle gebruikers. Zorg dat je extensie kan omgaan met deze wijziging, of deze nu aanstaat of niet.

Als een listener een reactie probeert te retourneren die niet kan worden geserialiseerd (zonder de resulterende TypeError op te vangen), wordt dit ook beschouwd als een fout die door de listener wordt veroorzaakt.

Als een listener een promise retourneert die wordt afgewezen, moet deze worden afgewezen met een Error-instantie zodat de afzender die foutmelding krijgt. Als de promise wordt afgewezen met een andere waarde (zoals null of undefined), wordt sendMessage() afgewezen met een algemene foutmelding.

Als er meerdere listeners zijn geregistreerd voor onMessage, heeft alleen de eerste listener die reageert, weigert of een fout genereert invloed op de afzender. Alle andere listeners worden uitgevoerd, maar de resultaten worden genegeerd.

Voorbeelden

Als een listener een promise retourneert die wordt afgewezen, wordt sendMessage() afgewezen:

// sender.js
try {
  await browser.runtime.sendMessage('test');
} catch (e) {
  console.log(e.message); // "some error"
}

// listener.js
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
  return Promise.reject(new Error('some error'));
});

Als een listener reageert met een waarde die niet kan worden geserialiseerd, wordt sendMessage() geweigerd:

// sender.js
try {
  await browser.runtime.sendMessage('test');
} catch (e) {
  console.log(e.message); // "Error: Could not serialize message."
}

// listener.js
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
  sendResponse(() => {}); // Functions are not serializable
  return true; // Keep channel open for async sendResponse
});

Als een listener synchroon een fout genereert voordat een andere listener reageert, wordt de sendMessage()-promise van de listener afgewezen:

// sender.js
try {
  await browser.runtime.sendMessage('test');
} catch (e) {
  console.log(e.message); // "error!"
}

// listener.js
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
  throw new Error('error!');
});

Maar als een listener reageert voordat een andere een fout genereert, slaagt sendMessage():

// sender.js
const response = await browser.runtime.sendMessage('test');
console.log(response); // "OK"

// listener.js
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
  sendResponse('OK');
});
browser.runtime.onMessage.addListener((message, sender, sendResponse) => {
  throw new Error('error!');
});

Langdurige verbindingen

Als je een herbruikbaar kanaal voor langdurige berichtuitwisseling wilt maken, roep je het volgende aan:

  • runtime.connect() om berichten van een contentscript door te geven aan een extensiepagina
  • tabs.connect() om berichten van een extensiepagina door te geven aan een contentscript.

Je kunt je kanaal een naam geven door een optieparameter met een name-sleutel door te geven om onderscheid te maken tussen verschillende soorten verbindingen:

const port = browser.runtime.connect({name: "example"});

Een mogelijke use case voor een langdurige verbinding is een extensie voor het automatisch invullen van formulieren. Het contentscript kan een kanaal openen naar de extensiepagina voor een specifieke login en een bericht naar de extensie sturen voor elk invoerelement op de pagina om de formuliergegevens op te vragen die moeten worden ingevuld. Via de gedeelde verbinding kan de extensie de status delen tussen extensiecomponenten.

Als er een verbinding wordt gemaakt, krijgt elk uiteinde een runtime.Port-object om berichten te sturen en te krijgen via die verbinding.

Gebruik de volgende code om een kanaal te openen vanuit een contentscript en berichten te sturen en te beluisteren:

content-script.js:

const port = browser.runtime.connect({name: "knockknock"});
port.onMessage.addListener(function(msg) {
  if (msg.question === "Who's there?") {
    port.postMessage({answer: "Madame"});
  } else if (msg.question === "Madame who?") {
    port.postMessage({answer: "Madame... Bovary"});
  }
});
port.postMessage({joke: "Knock knock"});

Als je een verzoek van de extensie naar een contentscript wilt sturen, vervang je de aanroep naar runtime.connect() in het vorige voorbeeld door tabs.connect().

Als je inkomende verbindingen wilt verwerken voor een contentscript of een extensiepagina, stel je een event-listener voor runtime.onConnect in. Als een ander deel van je extensie connect() aanroept, wordt deze gebeurtenis en het object runtime.Port geactiveerd. De code voor het reageren op inkomende verbindingen ziet er zo uit:

service-worker.js:

browser.runtime.onConnect.addListener(function(port) {
  if (port.name !== "knockknock") {
    return;
  }
  port.onMessage.addListener(function(msg) {
    if (msg.joke === "Knock knock") {
      port.postMessage({question: "Who's there?"});
    } else if (msg.answer === "Madame") {
      port.postMessage({question: "Madame who?"});
    } else if (msg.answer === "Madame... Bovary") {
      port.postMessage({question: "I don't get it."});
    }
  });
});

Serialisatie

In Chrome gebruiken de API's voor berichtoverdracht JSON-serialisatie. Dit is anders dan bij andere browsers die dezelfde API's implementeren met het algoritme voor gestructureerd klonen.

Dit betekent dat een bericht (en reacties van ontvangers) elke geldige JSON.stringify()-waarde kan bevatten. Andere waarden worden gedwongen tot serialiseerbare waarden (met name undefined wordt geserialiseerd als null).

Limieten voor berichtgrootte

De maximale grootte van een bericht is 64 MiB.

Levensduur van poort

Poorten zijn ontworpen als een mechanisme voor communicatie in 2 richtingen tussen verschillende delen van een extensie. Als een deel van een extensie tabs.connect(), runtime.connect() of runtime.connectNative() aanroept, wordt er een poort gemaakt die onmiddellijk berichten kan sturen via postMessage().

Als er meerdere frames op een tabblad staan, wordt de gebeurtenis runtime.onConnect één keer voor elk frame op het tabblad geactiveerd als tabs.connect() wordt aangeroepen. Als runtime.connect() wordt aangeroepen, kan de gebeurtenis onConnect één keer worden geactiveerd voor elk frame in het extensieproces.

Je wilt misschien weten wanneer een verbinding wordt gesloten, bijvoorbeeld als je afzonderlijke statussen bijhoudt voor elke open poort. Luister hiervoor naar de gebeurtenis runtime.Port.onDisconnect. Deze gebeurtenis wordt geactiveerd als er geen geldige poorten aan het andere uiteinde van het kanaal zijn. Dit kan de volgende oorzaken hebben:

  • Er zijn geen luisteraars voor runtime.onConnect aan de andere kant.
  • Het tabblad met de poort wordt verwijderd (bijvoorbeeld als er naar het tabblad wordt genavigeerd).
  • Het frame waarin connect() is aangeroepen, is verwijderd.
  • Alle frames die de poort hebben gekregen (via runtime.onConnect) zijn verwijderd.
  • runtime.Port.disconnect() wordt gebeld door de andere kant. Als een connect()-aanroep resulteert in meerdere poorten aan de kant van de ontvanger en disconnect() wordt aangeroepen op een van deze poorten, wordt de onDisconnect-gebeurtenis alleen geactiveerd op de verzendende poort, niet op de andere poorten.

Berichten sturen tussen extensies

Naast berichten sturen tussen verschillende componenten in je extensie, kun je de berichten-API gebruiken om te communiceren met andere extensies. Zo kun je een openbare API beschikbaar maken voor andere extensies.

Gebruik de methoden runtime.onMessageExternal of runtime.onConnectExternal om te luisteren naar inkomende verzoeken en verbindingen van andere extensies. Hier volgt een voorbeeld van elk:

service-worker.js

// For a single request:
browser.runtime.onMessageExternal.addListener(
  function(request, sender, sendResponse) {
    if (sender.id !== allowlistedExtension) {
      return; // don't allow this extension access
    }
    if (request.getTargetData) {
      sendResponse({ targetData: targetData });
    } else if (request.activateLasers) {
      const success = activateLasers();
      sendResponse({ activateLasers: success });
    }
  }
);

// For long-lived connections:
browser.runtime.onConnectExternal.addListener(function(port) {
  port.onMessage.addListener(function(msg) {
    // See other examples for sample onMessage handlers.
  });
});

Als je een bericht naar een andere extensie wilt sturen, geef je de ID van de extensie waarmee je wilt communiceren als volgt door:

service-worker.js

// The ID of the extension we want to talk to.
const laserExtensionId = "abcdefghijklmnoabcdefhijklmnoabc";

// For a minimal request:
browser.runtime.sendMessage(laserExtensionId, {getTargetData: true},
  function(response) {
    if (targetInRange(response.targetData))
      browser.runtime.sendMessage(laserExtensionId, {activateLasers: true});
  }
);

// For a long-lived connection:
const port = browser.runtime.connect(laserExtensionId);
port.postMessage(...);

Berichten sturen vanaf webpagina's

Extensies kunnen ook berichten van webpagina's ontvangen en erop reageren. Als je berichten van een webpagina naar een extensie wilt sturen, geef je in je manifest.json aan van welke websites je berichten wilt toestaan met de manifestsleutel "externally_connectable". Voorbeeld:

manifest.json

"externally_connectable": {
  "matches": ["https://*.example.com/*"]
}

Hiermee wordt de berichten-API beschikbaar gemaakt voor elke pagina die overeenkomt met de overeenkomstpatronen die je opgeeft.

Gebruik de API's runtime.sendMessage() of runtime.connect() om een bericht naar een specifieke extensie te sturen. Voorbeeld:

webpage.js

// The ID of the extension we want to talk to.
const editorExtensionId = 'abcdefghijklmnoabcdefhijklmnoabc';

// Check if extension is installed
if (chrome && browser.runtime) {
  // Make a request:
  browser.runtime.sendMessage(
    editorExtensionId,
    {
      openUrlInEditor: url
    },
    (response) => {
      if (!response.success) handleError(url);
    }
  );
}

Luister vanuit je extensie naar berichten van webpagina's met de API's runtime.onMessageExternal of runtime.onConnectExternal, zoals in berichten tussen extensies. Hier volgt een voorbeeld:

service-worker.js

browser.runtime.onMessageExternal.addListener(
  function(request, sender, sendResponse) {
    if (sender.url === blocklistedWebsite)
      return;  // don't allow this web page access
    if (request.openUrlInEditor)
      openUrl(request.openUrlInEditor);
  });

Het is niet mogelijk om een bericht van een extensie naar een webpagina te sturen.

Systeemeigen berichten

Extensies kunnen berichten uitwisselen met systeemeigen apps die zijn geregistreerd als een host voor native berichten. Ga naar Systeemeigen berichten voor meer informatie over deze functie.

Beveiligingsoverwegingen

Hier volgen enkele beveiligingsoverwegingen met betrekking tot berichten.

Contentscripts zijn minder betrouwbaar

Contentscripts zijn minder betrouwbaar dan de serviceworker van de extensie. Een schadelijke webpagina kan bijvoorbeeld het renderingproces in gevaar brengen dat de contentscripts uitvoert. Ga ervan uit dat berichten van een contentscript kunnen zijn gemaakt door een aanvaller en zorg dat je alle invoer valideert en opschoont. Ga ervan uit dat gegevens die naar het contentscript worden gestuurd, naar de webpagina kunnen lekken. Beperk het bereik van bevoorrechte acties die kunnen worden geactiveerd door berichten die zijn ontvangen van contentscripts.

Cross-site scripting

Zorg dat je je scripts beschermt tegen cross-site scripting. Als je gegevens krijgt van een niet-vertrouwde bron, zoals gebruikersinvoer, andere websites via een contentscript of een API, moet je ervoor zorgen dat deze niet worden geïnterpreteerd als HTML of worden gebruikt op een manier waardoor onverwachte code kan worden uitgevoerd.

Veiligere methoden

Gebruik waar mogelijk API's die geen scripts uitvoeren:

service-worker.js

browser.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) {
  // JSON.parse doesn't evaluate the attacker's scripts.
  const resp = JSON.parse(response.farewell);
});

service-worker.js

browser.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) {
  // innerText does not let the attacker inject HTML elements.
  document.getElementById("resp").innerText = response.farewell;
});
Onveilige methoden

Gebruik de volgende methoden niet, omdat ze je extensie kwetsbaar maken:

service-worker.js

browser.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) {
  // WARNING! Might be evaluating a malicious script!
  const resp = eval(`(${response.farewell})`);
});

service-worker.js

browser.tabs.sendMessage(tab.id, {greeting: "hello"}, function(response) {
  // WARNING! Might be injecting a malicious script!
  document.getElementById("resp").innerHTML = response.farewell;
});