Arbeiten mit der Cookies-API

Um die Cookies-API zu nutzen, müssen Sie sowohl die Berechtigung "cookies" als auch Host-Berechtigungen für die Protokolle, Domains oder Websites anfordern, auf die Sie zugreifen möchten, oder "<all_urls>" verwenden, um auf jedes Protokoll und jede Domain zuzugreifen. Die Art und Weise, wie Sie Ihre Host-Berechtigungszeichenfolge definieren, beeinflusst die Fähigkeit Ihrer Erweiterung, Cookies zu lesen, zu schreiben und zu löschen.

Firefox stellt drei Arten von Cookie-Speichern bereit:

• Den Standard-Speicher, der Cookies aus dem normalen Browsing speichert.

• Speicher für den privaten Browsing-Modus, der Cookies speichert, die während einer privaten Browsing-Sitzung erstellt wurden. Diese Speicher und alle darin enthaltenen Cookies werden entfernt, wenn das zugehörige private Browsing-Fenster geschlossen wird.

  Hinweis: Nur sichtbar, wenn extension.isAllowedIncognitoAccess() true zurückgibt. Safari unterstützt keinen Zugriff auf private Cookies.

• Container-Tab-Speicher, die Cookies für jede kontextuelle Identität in Firefox speichern. Kontextuelle Identitäten ermöglichen es einem Benutzer, mehrere Identitäten innerhalb eines Browserfensters zu verwalten. Dies ist nützlich, wenn Sie beispielsweise ein Firmen- und ein privates E-Mail-Konto bei Gmail haben. Mit kontextuellen Identitäten können Sie einen Tab für eine persönliche Identität und einen zweiten Tab für eine geschäftliche Identität öffnen. Jeder Tab kann sich dann mit einem anderen Benutzernamen bei Google Mail anmelden, und die beiden Konten können nebeneinander verwendet werden. Für weitere Informationen siehe Security/Contextual Identity Project/Containers im Mozilla-Wiki.

Sie können herausfinden, welche Cookie-Speicher verfügbar sind, indem Sie cookies.getAllCookieStores verwenden, das ein Objekt mit der ID jedes Cookie-Speichers und einer Liste der ID der Tabs zurückgibt, die jeden Cookie-Speicher verwenden.

Das Beispiel der Erweiterung cookie-bg-picker ermöglicht es dem Benutzer, eine Farbe und ein Symbol auszuwählen, die auf den Hintergrund der Webseiten einer Site angewendet werden. Diese Auswahl wird auf einer site-spezifischen Basis mit cookies.set gespeichert. Wenn eine Seite von der Site geöffnet wird, liest cookies.get frühere Auswahlen, und die Erweiterung wendet sie auf die Webseite an. Eine Reset-Option entfernt das Hintergrundsymbol und die Farbe von der Site sowie das Cookie, wobei cookies.remove verwendet wird. Sie nutzt auch cookies.onChanged, um Änderungen an Cookies zu verfolgen und Details der Änderung an die Konsole zu senden.

Dieses Video zeigt die Erweiterung in Aktion:

Dieses Beispiel verwendet auch die Tabs- und Runtime-APIs, aber wir werden diese Funktionen nur am Rande besprechen.

Das Schlüsselmerkmal der manifest.json Datei im Zusammenhang mit der Verwendung der Cookies-API ist die Berechtigungsanfrage:

  "permissions": [
      "tabs",
      "cookies",
      "<all_urls>"
],

Hier fordert die Erweiterung die Berechtigung an, die Cookies-API ("cookies") mit allen Websites ("<all_urls>") zu verwenden. Dies ermöglicht es der Erweiterung, die Auswahl des Hintergrundfarbensymbols für jede Website zu speichern.

Die Benutzeroberfläche der Erweiterung verwendet einen Toolbar-Button (browserAction), der mit bgpicker.html implementiert ist, der bgpicker.js aufruft. Zusammen ermöglichen diese dem Benutzer, das Symbol auszuwählen und die Farbe einzugeben, die sie als Hintergrund der Site anwenden möchten. Sie bieten auch die Möglichkeit, diese Einstellungen zu löschen.

bgpicker.js verarbeitet die Auswahl eines Symbols oder die Eingabe einer Farbe für den Hintergrund in separaten Funktionen.

Um mit den Symbol-Schaltflächen umzugehen, sammelt das Skript zunächst alle Klassennamen, die für die Schaltflächen in der HTML-Datei verwendet werden:

let bgBtns = document.querySelectorAll(".bg-container button");

Dann durchläuft es alle Schaltflächen, weist ihnen ihr Bild zu und erstellt einen onclick-Listener für jede Schaltfläche:

for (let i = 0; i < bgBtns.length; i++) {
  let imgName = bgBtns[i].getAttribute("class");
  let bgImg = "url('images/" + imgName + ".png')";
  bgBtns[i].style.backgroundImage = bgImg;

  bgBtns[i].onclick = (e) => {

Wenn eine Schaltfläche geklickt wird, ruft ihre entsprechende Listener-Funktion den Klassennamen der Schaltfläche und dann den Symbolpfad ab, den sie an das Inhalts-Skript der Seite (updatebg.js) mittels einer Nachricht übergibt. Das Inhalts-Skript wendet dann das Symbol auf den Hintergrund der Webseite an. In der Zwischenzeit speichert bgpicker.js die Details des auf den Hintergrund angewendeten Symbols in einem Cookie:

cookieVal.image = fullURL;
browser.cookies.set({
  url: tabs[0].url,
  name: "bgpicker",
  value: JSON.stringify(cookieVal),
});

Die Farbeinstellung wird auf ähnliche Weise verarbeitet, wobei ein Listener im Farbeingabefeld ausgelöst wird. Wenn eine Farbe eingegeben wird, wird der aktive Tab entdeckt und die Farbwahl-Details mittels einer Nachricht an das Inhalts-Skript der Seite gesendet, um auf den Webseitenshintergrund angewendet zu werden. Dann wird die Farbwahl dem Cookie hinzugefügt:

cookieVal.color = currColor;
browser.cookies.set({
  url: tabs[0].url,
  name: "bgpicker",
  value: JSON.stringify(cookieVal),
});

Wenn der Benutzer die Zurücksetzen-Schaltfläche klickt, die der Variable reset zugewiesen wurde:

let reset = document.querySelector(".color-reset button");

Sucht reset.onclick zunächst den aktiven Tab. Dann übergibt es, unter Verwendung der Tab-ID, eine Nachricht an das Inhalts-Skript der Seite (updatebg.js), um das Symbol und die Farbe von der Seite zu entfernen. Die Funktion löscht dann die Cookie-Werte (damit die alten Werte nicht weitergetragen und auf ein Cookie geschrieben werden, das für eine neue Symbol- oder Farbauswahl auf derselben Seite erstellt wurde), bevor das Cookie entfernt wird:

cookieVal = { image: "", color: "" };
browser.cookies.remove({
  url: tabs[0].url,
  name: "bgpicker",
});

Außerdem, damit Sie sehen können, was mit den Cookies passiert, gibt das Skript alle Änderungen an Cookies in der Konsole aus:

browser.cookies.onChanged.addListener((changeInfo) => {
  console.log(`Cookie changed:\n
    * Cookie: ${JSON.stringify(changeInfo.cookie)}\n
    * Cause: ${changeInfo.cause}\n
    * Removed: ${changeInfo.removed}`);
});

Ein Hintergrund-Skript (background.js) sorgt dafür, dass der Benutzer in einer früheren Sitzung möglicherweise ein Hintergrundsymbol und eine Hintergrundfarbe für die Website ausgewählt hat. Das Skript hört auf Änderungen am aktiven Tab, entweder wenn der Benutzer zwischen Tabs wechselt oder die URL der in dem Tab angezeigten Seite ändert. Wenn eines dieser Ereignisse eintritt, wird cookieUpdate() aufgerufen. cookieUpdate() verwendet seinerseits getActiveTab(), um die aktive Tab-ID zu erhalten. Die Funktion kann dann überprüfen, ob ein Cookie für die Erweiterung existiert, unter Verwendung der URL des Tabs:

let gettingCookies = browser.cookies.get({
  url: tabs[0].url,
  name: "bgpicker",
});

Wenn das Cookie "bgpicker" für die Website existiert, werden die Details des vorher ausgewählten Symbols und der Farbe abgerufen und mittels Nachrichten an das Inhalts-Skript updatebg.js übergeben:

gettingCookies.then((cookie) => {
  if (cookie) {
    let cookieVal = JSON.parse(cookie.value);
    browser.tabs.sendMessage(tabs[0].id, { image: cookieVal.image });
    browser.tabs.sendMessage(tabs[0].id, { color: cookieVal.color });
  }
});

Zusätzlich zu den bisher erwähnten APIs bietet die Cookies-API auch cookies.getAll. Diese Funktion nimmt das Detailobjekt, um Filter für die ausgewählten Cookies anzugeben, und gibt ein Array von cookies.Cookie-Objekten zurück, die den Filterkriterien entsprechen.

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

• Cookies API Referenz.
• List-cookies Beispiel.