Arbeiten mit kontextbezogenen Identitäten

APIs für die Arbeit mit kontextbezogenen Identitäten

Je nach Art Ihrer Erweiterung möchten Sie möglicherweise kontextbezogene Identitäten verwalten, Objekte, die Ihre Erweiterung manipuliert, mit kontextbezogenen Identitäten assoziieren, oder beides.

Verwaltung von kontextbezogenen Identitäten

Um kontextbezogene Identitäten zu verwalten, nutzen Sie die contextualIdentities API. Diese API ermöglicht es Ihnen, kontextbezogene Identitäten hinzuzufügen, abzufragen, zu aktualisieren und zu löschen. Wenn Sie eine kontextbezogene Identität erstellen, erhält sie eine eindeutige cookieStoreId. Sie verwenden diese ID, um mit Entitäten zu arbeiten, die mit der kontextbezogenen Identität verbunden sind.

Unterstützte Farben und Symbole

Wenn Sie eine kontextbezogene Identität erstellen oder aktualisieren, müssen Sie gültige color- und icon-Werte angeben. Für Firefox Version 153 und später verwenden Sie contextualIdentities.getSupportedColors() und contextualIdentities.getSupportedIcons(), um die Liste der unterstützten Werte abzurufen, anstatt diese hartkodiert einzugeben. Firefox 153 hat zwei Farben umbenannt und eine hinzugefügt, und zukünftige Versionen könnten weitere Änderungen einführen. Das Abfragen dieser Methoden hält Ihre Erweiterung kompatibel, ohne dass jedes Mal Updates erforderlich sind, wenn sich die unterstützten Werte ändern.

Für Erweiterungen, die Firefox-Versionen vor 153 unterstützen, sind vollständige Listen der unterstützten Werte, einschließlich der in Firefox 153 geänderten, auf den Referenzseiten von contextualIdentities.getSupportedColors() und contextualIdentities.getSupportedIcons() verfügbar.

Verwendung von cookieStoreId

Mehrere Erweiterungs-APIs beinhalten die cookieStoreId in Objekten, um den Erweiterungen zu ermöglichen, diese Objekte mit bestimmten kontextbezogenen Identitäten zu assoziieren.

• browsingData.removeCookies() und browsingData.removeLocalStorage(), bei denen Sie browsingData.removalOptions verwenden, um die Cookie-Speicher-Elemente festzulegen, von denen entfernt werden soll.
• contentScripts.register ermöglicht es Ihnen, ein Content-Script zu registrieren, das auf Dokumente beschränkt ist, die mit einem oder mehreren cookieStoreIds assoziiert sind.
• downloads, bei dem Sie einen Download mit einem Cookie-Speicher assoziieren können.
• proxy, bei dem die in den proxy.onRequest-Listener übergebenen Details den mit der Anfrage assoziierten Cookie-Speicher identifizieren.
• tabs, bei dem Sie in einem Container-Tab einen Tab erstellen, die cookieStoreId für einen Tab abrufen und Tabs basierend auf ihrem zugehörigen Cookie-Speicher abfragen können.
• userScripts.register() (nur Legacy-Version, Manifest V2) ermöglicht es Ihnen, ein Content-Script zu registrieren, das auf Dokumente beschränkt ist, die mit einem oder mehreren cookieStoreIds assoziiert sind.
• webRequest, bei dem alle Ereignisse die cookieStoreId der Anfrage zurückgeben.
• windows.create, bei dem Sie den Cookie-Speicher für die Tabs angeben können, die zu einem Fenster hinzugefügt werden, wenn es erstellt wird.

Berechtigungen

Um die contextualIdentities API zu verwenden, müssen Sie die Berechtigung "contextualIdentities" in Ihrer manifest.json-Datei aufnehmen.

Wenn eine API es ermöglicht, Cookies zu modifizieren, benötigen Sie die "cookies"-Berechtigung. Zum Beispiel erfordert die Verwendung von cookieStoreId in tabs.query nicht die "cookies"-API, da das Lesen der Eigenschaft die Cookies in den Containern nicht beeinflusst. Die Verwendung von tabs.create erfordert jedoch die Berechtigung, da der geöffnete Tab Cookies in einem Container lesen und modifizieren kann.

Beispielanleitung

Die Beispielerweiterung contextual-identities bietet eine Symbolleistenschaltfläche mit einem Popup, das die Identitäten im Browser auflistet. Für jede Identität bietet die Erweiterung Optionen an, um einen Tab mit seinem Cookie-Container zu erstellen oder alle seine Tabs zu entfernen.

Hier ist ein kurzes Video der Erweiterung in Aktion:

manifest.json

Die Hauptmerkmale der manifest.json-Datei sind:

• die Berechtigungsanfrage:

  json

    "permissions": [
        "contextualIdentities",
        "cookies"
    ],
  

• die Spezifikation der Symbolleistenschaltfläche (browserAction), die Zugriff auf die Funktionen der Erweiterung bietet:

  json

    "browser_action": {
      "default_title": "Contextual Identities",
      "default_popup": "context.html",
      "default_icon": {
        "128": "identity.svg"
      }
  

context.html

Ein Popup auf der Symbolleistenschaltfläche bietet die Benutzeroberfläche der Erweiterung. context.html implementiert dieses Popup, ist jedoch nur eine Hülle, in die das Skript context.js die Liste der kontextbezogenen Identitäten und deren zugehörige Optionen schreibt.

<body>
  <div class="panel">
    <div id="identity-list"></div>
  </div>
  <script src="context.js"></script>
</body>

context.js

Alle Funktionen der Erweiterung werden durch context.js implementiert, das aufgerufen wird, wann immer das Symbolleisten-Popup angezeigt wird.

Das Skript ruft zuerst das <div> Element 'identity-list' von context.html ab. Dann überprüft es, ob die Funktion für kontextbezogene Identitäten im Browser aktiviert ist. Falls nicht, wird dem Popup eine Information hinzugefügt, wie diese aktiviert werden kann.

Firefox wird mit deaktivierter Funktion für kontextbezogene Identitäten installiert. Diese wird aktiviert, wenn eine Erweiterung installiert wird, die die contextualIdentities API verwendet. Der Nutzer kann die Funktion jedoch über eine Option auf der Einstellungsseite (about:preferences) deaktivieren, daher die Notwendigkeit der Prüfung.

Das Skript verwendet nun contextualIdentities.query, um festzustellen, ob im Browser kontextbezogene Identitäten definiert sind. Wenn keine vorhanden sind, wird dem Popup eine Nachricht hinzugefügt und das Skript wird angehalten.

const div = document.getElementById("identity-list");
if (browser.contextualIdentities === undefined) {
  div.innerText =
    "browser.contextualIdentities not available. Check that the privacy.userContext.enabled pref is set to true, and reload the add-on.";
} else {
  browser.contextualIdentities.query({}).then((identities) => {
    if (!identities.length) {
      div.innerText = "No identities returned from the API.";
      return;
    }
    for (const identity of identities) {
      const row = document.createElement("div");
      const span = document.createElement("span");
      span.className = "identity";
      span.innerText = identity.name;
      span.style = `color: ${identity.color}`;
      console.log(identity);
      row.appendChild(span);
      createOptions(row, identity);
      div.appendChild(row);
    }
  });
}

Wenn kontextbezogene Identitäten vorhanden sind—Firefox wird mit vier Standardidentitäten geliefert—iteriert das Skript durch jede und fügt ihren Namen, mit der gewählten Farbe gestylt, dem <div> Element hinzu. Die Funktion createOptions() fügt dann die Optionen "erstellen" oder "alle schließen" zum <div> hinzu, bevor es dem Popup hinzugefügt wird.

function createOptions(node, identity) {
  for (const option of ["Create", "Close All"]) {
    const a = document.createElement("a");
    a.href = "#";
    a.innerText = option;
    a.dataset.action = option.toLowerCase().replace(" ", "-");
    a.dataset.identity = identity.cookieStoreId;
    a.addEventListener("click", eventHandler);
    node.appendChild(a);
  }
}

Das Skript wartet nun darauf, dass der Nutzer eine Option im Popup auswählt.

Wenn der Nutzer die Option auswählt, einen Tab für eine Identität zu erstellen, wird einer unter Verwendung von tabs.create geöffnet, indem die Cookie-Store-ID der Identität übergeben wird.

Wenn der Nutzer die Option auswählt, alle Tabs für die Identität zu schließen, führt das Skript eine tabs.query aus, um alle Tabs abzurufen, die den Cookie-Store der Identität verwenden. Das Skript übergibt dann diese Liste von Tabs an tabs.remove.

function eventHandler(event) {
  if (event.target.dataset.action === "create") {
    browser.tabs.create({
      url: "about:blank",
      cookieStoreId: event.target.dataset.identity,
    });
  }

  if (event.target.dataset.action === "close-all") {
    browser.tabs
      .query({
        cookieStoreId: event.target.dataset.identity,
      })
      .then((tabs) => {
        browser.tabs.remove(tabs.map((i) => i.id));
      });
  }
  event.preventDefault();
}

Mehr erfahren

Wenn Sie mehr über die contextualIdentities API erfahren möchten, sehen Sie sich folgende Ressourcen an:

• contextualIdentities API Referenz.
• Multi-Account Containers Erweiterungsquellcode. Dies ist der Code für die Firefox Multi-Account Containers Erweiterung. Diese Erweiterung bietet Nutzern erweiterte Funktionalität für kontextbezogene Identitäten, wie die Möglichkeit, die neue Tab-Taste lange zu drücken und dann die Identität auszuwählen, die im neuen Tab verwendet werden soll. Es zeigt die Fähigkeiten der kontextbezogenen Identitäten und ist definitiv einen Blick wert.