activeTab-Berechtigung

Die activeTab-Berechtigung anfordern

Ihre Erweiterung fordert activeTab über den Manifest-Schlüssel permissions an:

"permissions": ["activeTab"]

activeTab ist eine API-Berechtigung, keine Host-Berechtigung.

Sie können activeTab auch in optional_permissions aufnehmen und die Berechtigung zur Laufzeit mit permissions.request() anfordern. Sie gehört zu den Berechtigungen, die ohne Nachfrage beim Benutzer erteilt werden.

Wie activeTab erteilt wird

Der Browser erteilt activeTab, wenn jemand mit der Erweiterung interagiert. Diese Interaktionen werden als Benutzeraktionen bezeichnet. Dazu gehört:

• ein Klick auf die Symbolleistenschaltfläche oder eine Page Action der Erweiterung;
• die Auswahl eines Eintrags im Kontextmenü der Erweiterung, wodurch das Ereignis menus.onClicked ausgelöst wird;
• die Verwendung eines von der Erweiterung über die commands-API definierten Tastaturkürzels, wodurch das Ereignis commands.onCommand ausgelöst wird;
• ein Klick auf einen Vorschlag der Erweiterung in der Adressleiste (Omnibox), wodurch das Ereignis omnibox.onInputEntered ausgelöst wird (ab Firefox 142).

Normalerweise wird activeTab für den aktiven Tab erteilt. Es gibt eine Ausnahme: Eine Erweiterung kann mit der menus-API einen Menüeintrag erstellen, der angezeigt wird, wenn jemand das Kontextmenü eines Tabs in der Tableiste öffnet. Wird dieser Eintrag ausgewählt, erhält die Erweiterung activeTab für den angeklickten Tab, auch wenn dieser nicht aktiv ist.

Was activeTab ermöglicht

Solange activeTab für einen Tab erteilt ist, kann die Erweiterung:

• JavaScript oder CSS mit der scripting-API in den Tab einfügen (oder in Manifest V2 mit tabs.executeScript() und tabs.insertCSS()). Siehe Content Scripts laden.
• Die geschützten Eigenschaften des tabs.Tab-Objekts des Tabs auslesen: url, title und favIconUrl. Andernfalls erfordern diese Eigenschaften die Berechtigung "tabs" oder eine passende Host-Berechtigung.
• Den Inhalt des Tabs mit tabs.captureVisibleTab() erfassen (ab Firefox 126).
• Die für den Tab zutreffenden Regeln mit declarativeNetRequest.getMatchedRules() auslesen, ohne die Berechtigung "declarativeNetRequestFeedback" zu benötigen.

Umfang des Zugriffs

activeTab gewährt Zugriff zum Ausführen von Skripten auf der obersten Seite im Tab und in Frames derselben Origin. Das Ausführen von Skripten oder Ändern von Stilen in Cross-Origin-Frames erfordert zusätzliche Host-Berechtigungen.

Die Einschränkungen und Beschränkungen, die für bestimmte Websites und URI-Schemata gelten, gelten auch für activeTab. Auf einigen speziellen Seiten können keine Skripte eingefügt werden. Dazu gehören die Leseansicht, die Quelltextansicht, der PDF-Viewer und andere integrierte Seiten der Browseroberfläche.

Wann der Zugriff endet

Die Erweiterung kann nur auf den Tab beziehungsweise die Daten zugreifen, die zum Zeitpunkt der Benutzeraktion vorhanden waren. Wenn der Tab zu einer anderen Seite navigiert, verliert die Erweiterung die Zugriffsberechtigung. Sie muss ihre Arbeit mit dem Tab daher abschließen oder die benötigten Daten erfassen, solange die Berechtigung besteht. Benötigt sie später erneut Zugriff, muss die Benutzeraktion wiederholt werden.

Der Zeitpunkt, zu dem der Zugriff endet, unterscheidet sich je nach Browser. Siehe Wann der Zugriff entzogen wird.

Beispiel

Diese Erweiterung fügt ein Skript in die aktuelle Seite ein, wenn jemand auf ihre Symbolleistenschaltfläche klickt. Sie benötigt keine Host-Berechtigungen.

manifest.json:

{
  "manifest_version": 3,
  "name": "Heading highlighter",
  "version": "1.0",
  "permissions": ["activeTab", "scripting"],
  "action": {
    "default_title": "Highlight headings"
  },
  "background": {
    "scripts": ["background.js"]
  }
}

background.js:

function highlightHeadings() {
  for (const heading of document.querySelectorAll("h1, h2, h3")) {
    heading.style.backgroundColor = "yellow";
  }
}

browser.action.onClicked.addListener((tab) => {
  // activeTab is granted for `tab` because the user clicked the toolbar button.
  browser.scripting.executeScript({
    target: { tabId: tab.id },
    func: highlightHeadings,
  });
});

Durch denselben Klick werden auch die geschützten Eigenschaften des Tabs lesbar. tab.url und tab.title enthalten daher tatsächliche Werte statt undefined.

Weitere Beispiele

Die folgenden Beispiele aus dem Repository mit Beispielerweiterungen unter https://github.com/mdn/webextensions-examples verwenden die Berechtigung activeTab:

Browser-Kompatibilität

Firefox, Safari und Chromium-basierte Browser, darunter Chrome und Edge, unterstützen activeTab. Allerdings unterscheiden sich die Bedingungen für die Erteilung, die damit verbundenen Möglichkeiten und der Zeitpunkt des Entzugs.

Aktionen, durch die activeTab erteilt wird

Gewährte Möglichkeiten

Auch der Zugriff, den Browser mit activeTab gewähren, unterscheidet sich:

• Firefox gewährt nur Zugriff auf den aktiven Tab.
• Chrome und Safari gewähren die aus der URL des Tabs abgeleiteten Host-Berechtigungen.

Chrome und Safari können damit mehr Zugriff ermöglichen als Firefox, zum Beispiel:

• In Chrome können Skripte auch in einem anderen Tab mit derselben Origin ausgeführt werden, in Firefox nicht.
• Ein Erweiterungsskript, etwa ein Hintergrundskript oder das Skript eines Popups, kann in Chrome eine Cross-Origin-Anfrage an die URL des Tabs senden, in Firefox nicht.
• Die cookies-API erfordert Host-Berechtigungen, um auf Cookies bestimmter Domains zuzugreifen. Chrome erlaubt dies mit activeTab, Firefox nicht.

Diese Liste ist nicht vollständig.

Wann der Zugriff entzogen wird

In allen Browsern wird der Zugriff entzogen, wenn der Tab geschlossen wird. Navigationen innerhalb desselben Dokuments, etwa eine Änderung des Fragments (Hash) oder ein Aufruf von History.pushState(), entziehen den Zugriff dagegen nicht: Das Dokument und seine Origin bleiben unverändert.

Bei Navigationen, die ein neues Dokument laden, unterscheidet sich das Verhalten:

• Chrome: Der Zugriff bleibt bestehen, solange der Tab auf derselben Origin bleibt, auch beim Neuladen. Er wird entzogen, wenn der Tab zu einer anderen Origin navigiert.
• Safari: Der Zugriff ist an das Dokument gebunden, das sich zum Zeitpunkt der Benutzeraktion im Tab befand. Er wird entzogen, wenn der Tab zu einer anderen URL navigiert.
• Firefox: Der Zugriff ist an das Dokument gebunden, das sich zum Zeitpunkt der Benutzeraktion im Tab befand. Jede Navigation, die zu einem neuen Dokument führt, beendet den Zugriff. Danach muss die Benutzeraktion wiederholt werden. Wird das Dokument aus dem Back/Forward-Cache wiederhergestellt, erhält es seinen Zugriff zurück.

Weitere Unterschiede

• Berechtigungsabfragen: Firefox und Chrome erteilen einer Erweiterung die angeforderten Host-Berechtigungen bei der Installation. Mit activeTab lässt sich daher eine Warnung bei der Installation vermeiden. Safari setzt Host-Berechtigungen dagegen standardmäßig auf „Nachfragen“ und fragt beim ersten Zugriffsversuch auf eine Website nach. Dabei stehen Für einen Tag erlauben und Immer erlauben zur Auswahl. Mit activeTab entfällt diese Nachfrage, da Safari die Interaktion mit der Erweiterung als Erteilung der Berechtigung wertet.
• Manifest V2 und V3: In Manifest V3 funktioniert activeTab in den Browsern auf dieselbe Weise. In Firefox mit Manifest V2 ermöglicht activeTab zusätzlich, dass scripting.executeScript() auf einen iframe mit einer anderen Origin zugreift (siehe Bug 1839200). Dieses Verhalten wurde in MV3 entfernt.

Siehe auch

• Manifest-Schlüssel permissions
• Manifest-Schlüssel optional_permissions
• Benutzeraktionen
• Content Scripts
• Die richtigen Berechtigungen anfordern im Extension Workshop
• Die Berechtigung „activeTab“ in der Dokumentation zu Chrome-Erweiterungen