Arbeiten mit der Cookies API

Um die Cookies-API zu verwenden, 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 bietet drei Arten von Cookie-Stores:

• Der Standard-Store, der Cookies aus dem normalen Browsen speichert.

• Stores für den privaten Modus, die Cookies speichern, die während einer privaten Browsersitzung erstellt wurden. Diese Stores und alle enthaltenen Cookies werden entfernt, wenn das dazugehörige private Browserfenster geschlossen wird.

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

• Stores für Container-Tabs, 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 zum Beispiel ein Geschäfts- und ein privates E-Mail-Konto auf 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. Weitere Informationen finden Sie im Security/Contextual Identity Project/Containers im Mozilla-Wiki.

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

Die Beispielerweiterung cookie-bg-picker ermöglicht es ihren Benutzern, eine Farbe und ein Symbol auszuwählen, die auf den Hintergrund von Webseiten einer Seite angewendet werden. Diese Auswahlmöglichkeiten werden auf Basis der Seite mithilfe von cookies.set gespeichert. Wenn eine Seite der Site geöffnet wird, liest cookies.get alle früheren Auswahlmöglichkeiten und die Erweiterung wendet sie auf die Webseite an. Eine Zurücksetzoption entfernt das Hintergrundsymbol und die Farbe von der Site sowie das Cookie durch die Verwendung von cookies.remove. Es wird auch cookies.onChanged verwendet, um Änderungen an Cookies zu überwachen und Details der Änderung an die Konsole zu senden.

Dieses Video zeigt die Erweiterung in Aktion:

Dieses Beispiel verwendet auch die APIs Tabs und Runtime, aber wir werden diese Funktionen nur beiläufig besprechen.

Das Schlüsselelement der manifest.json Datei in Bezug auf die Verwendung der Cookies API ist die Berechtigungsanforderung:

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

Hier beantragt die Erweiterung die Erlaubnis, die Cookies-API ("cookies") mit allen Websites ("<all_urls>") zu verwenden. Dies ermöglicht es der Erweiterung, die Hintergrundfarbenauswahl eines Symbols für jede Website zu speichern.

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

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

Um die Symbolschaltflächen zu verwalten, sammelt das Skript zunächst alle Klassennamen, die für die Schaltflächen im HTML-Dokument verwendet werden:

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

Anschließend 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, holt sich die zugehörige Listener-Funktion den Klassennamen der Schaltfläche und dann den Symbolpfad, den sie mit einer Nachricht an das Inhalts-Skript der Seite (updatebg.js) übergibt. Das Inhalts-Skript wendet dann das Symbol auf den Hintergrund der Webseite an. Währenddessen 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 behandelt, ausgelöst durch einen Listener im Farbeingabefeld. Wenn eine Farbe eingegeben wird, wird der aktive Tab entdeckt und die Farbauswahl mit einer Nachricht an das Inhalts-Skript der Seite gesendet, um auf den Hintergrund der Webseite angewendet zu werden. Dann wird die Farbauswahl dem Cookie hinzugefügt:

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

Wenn der Benutzer auf die Schaltfläche zum Zurücksetzen klickt, die der Variablen reset zugewiesen wurde:

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

findet reset.onclick zuerst den aktiven Tab. Dann, unter Verwendung der Tab-ID, wird eine Nachricht an das Inhalts-Skript der Seite (updatebg.js) gesendet, um das Symbol und die Farbe von der Seite zu entfernen. Die Funktion löscht dann die Cookie-Werte (damit die alten Werte nicht weitergeführt und auf ein für eine neue Symbol- oder Farbauswahl auf derselben Seite erstelltes Cookie geschrieben werden), bevor sie das Cookie entfernt:

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

Auch damit Sie sehen können, was mit den Cookies passiert, berichtet das Skript über alle Änderungen an Cookies in der Konsole:

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

Ein Hintergrundskript (background.js) bietet die Möglichkeit, dass der Benutzer in einer früheren Sitzung ein Hintergrundsymbol und eine Farbe für die Website ausgewählt hat. Das Skript hört auf Änderungen im aktiven Tab, entweder wenn der Benutzer zwischen Tabs wechselt oder wenn die URL der im Tab angezeigten Seite geändert wird. Wenn eines dieser Ereignisse eintritt, wird cookieUpdate() aufgerufen. cookieUpdate() verwendet wiederum getActiveTab(), um die ID des aktiven Tabs zu erhalten. Die Funktion kann dann überprüfen, ob für die Erweiterung ein Cookie existiert, indem die URL des Tabs verwendet wird:

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

Wenn das "bgpicker"-Cookie für die Website existiert, werden die Details des zuvor ausgewählten Symbols und der Farbe abgerufen und über 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 Details-Objekt, 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, schauen Sie sich folgende Ressourcen an:

• Cookies API Referenz.
• List-cookies Beispiel.