web_accessible_resources

Beschreibung

Manchmal möchten Sie Ressourcen – zum Beispiel Bilder, HTML, CSS oder JavaScript – mit Ihrer Erweiterung verpacken und sie Webseiten und anderen Erweiterungen verfügbar machen.

Zum Beispiel ersetzt die Beastify Beispielerweiterung eine Webseite mit einem vom Benutzer ausgewählten Bild eines Monsters. Die Monsterbilder sind mit der Erweiterung verpackt. Um das ausgewählte Bild sichtbar zu machen, fügt die Erweiterung <img>-Elemente hinzu, deren src-Attribut auf das Bild des Monsters zeigt. Damit die Webseite die Bilder laden kann, müssen sie webzugänglich gemacht werden.

Mit dem Schlüssel web_accessible_resources können Sie alle verpackten Ressourcen auflisten, die Sie Webseiten zur Verfügung stellen möchten. Sie geben sie als Pfade relativ zur manifest.json-Datei an.

Beachten Sie, dass Inhalts-Skripte nicht als webzugängliche Ressourcen aufgelistet werden müssen.

Wenn eine Erweiterung webRequest oder declarativeNetRequest verwenden möchte, um eine öffentliche URL (z.B. HTTPS) auf eine Seite umzuleiten, die in der Erweiterung verpackt ist, muss die Erweiterung die Seite im Schlüssel web_accessible_resources auflisten.

Syntax in Manifest V2

In Manifest V2 werden webzugängliche Ressourcen als Array unter dem Schlüssel hinzugefügt, so:

"web_accessible_resources": [
  "images/my-image.png"
]

Syntax in Manifest V3

In Manifest V3 ist der Schlüssel web_accessible_resources ein Array von Objekten, so:

{
  // …
  "web_accessible_resources": [
    {
      "resources": ["test1.png", "test2.png"],
      "matches": ["https://web-accessible-resources-1.example.com/*"]
    },
    {
      "resources": ["test3.png", "test4.png"],
      "matches": ["https://web-accessible-resources-2.example.com/*"],
      "use_dynamic_url": true
    }
  ]
  // …
}

Jedes Objekt muss eine "resources"-Eigenschaft und entweder eine "matches"- oder "extension_ids"-Eigenschaft aus den folgenden Eigenschaften enthalten:

Verwendung von web_accessible_resources

Angenommen, Ihre Erweiterung enthält eine Bilddatei unter images/my-image.png, so:

my-extension-files/
    manifest.json
    my-background-script.js
    images/
        my-image.png

Um einer Webseite die Verwendung eines <img>-Elements zu ermöglichen, dessen src-Attribut auf dieses Bild zeigt, würden Sie web_accessible_resources so spezifizieren:

"web_accessible_resources": ["images/my-image.png"]

Die Datei ist dann über eine URL verfügbar. Diese URL verwendet ein browser-spezifisches Schema:

• Chrome und auf Chromium-basierten Browsern verwenden chrome-extension://.
• Firefox verwendet moz-extension://.
• Safari verwendet safari-web-extension:// (WebKit verwendet webkit-extension://).

Zum Beispiel nimmt die Ressourcen-URL in Firefox diese Form an:

moz-extension://<extension-UUID>/images/my-image.png

<extension-UUID> ist nicht die ID Ihrer Erweiterung. Diese ID wird für jede Browserinstanz zufällig generiert. Dies verhindert, dass Websites einen Browser durch Überprüfung der installierten Erweiterungen erkennen.

Der empfohlene Ansatz, um die URL der Ressource zu erhalten, besteht darin, runtime.getURL zu verwenden und den Pfad relativ zur manifest.json zu übergeben, zum Beispiel:

browser.runtime.getURL("images/my-image.png");
// something like:
// moz-extension://944cfddf-7a95-3c47-bd9a-663b3ce8d699/images/my-image.png

Dieser Ansatz gibt Ihnen die korrekte URL, unabhängig davon, auf welchem Browser Ihre Erweiterung läuft.

In Chrome kann eine statische CSS-Datei die Nachricht @@extension_id verwenden, um eine URL für eine Erweiterungsressource zu erstellen:

body {
  background-image: url("chrome-extension://__MSG_@@extension_id__/images/my-image.png");
}

Platzhalter

Einträge in web_accessible_resources können Platzhalter enthalten. Zum Beispiel würde der folgende Eintrag auch funktionieren, um die Ressource unter "images/my-image.png" einzubeziehen:

  "web_accessible_resources": ["images/*.png"]

Sicherheit

Wenn Sie eine Seite webzugänglich machen, kann jede Website auf diese Seite verlinken oder sie umleiten. Die Seite sollte dann alle Eingaben (z. B. POST-Daten) so behandeln, als kämen sie aus einer nicht vertrauenswürdigen Quelle, genau wie eine normale Webseite.

Webzugängliche Erweiterungsressourcen werden nicht von CORS oder CSP blockiert. Aufgrund dieser Fähigkeit, Sicherheitsüberprüfungen zu umgehen, sollten Erweiterungen die Verwendung von webzugänglichen Skripten nach Möglichkeit vermeiden. Ein webzugängliches Erweiterungsskript kann unerwartet von bösartigen Websites missbraucht werden, um die Sicherheit anderer Websites zu schwächen. Befolgen Sie die Sicherheitsbest Practices, indem Sie die injektion von moz-extension:-URLs in Webseiten vermeiden und sicherstellen, dass Drittanbieterbibliotheken auf dem neuesten Stand sind.

Beispiel

Manifest V2 Beispiel

"web_accessible_resources": ["images/my-image.png"]

Machen Sie die Datei unter "images/my-image.png" webzugänglich für jede Website und Erweiterung.

Manifest V3 Beispiel

"web_accessible_resources": [
  {
    "resources": [ "images/my-image.png" ],
    "extension_ids": ["*"],
    "matches": [ "*://*/*" ]
  }
]

Machen Sie die Datei unter "images/my-image.png" webzugänglich für jede Website und Erweiterung.

Es wird empfohlen, extension_ids oder matches nur anzugeben, wenn erforderlich. Zum Beispiel, wenn die Ressource nur für Webseiten unter example.com zugänglich sein muss:

"web_accessible_resources": [
  {
    "resources": [ "images/my-image.png" ],
    "matches": [ "https://example.com/*" ]
  }
]

Beispielerweiterungen

• beastify
• dnr-redirect-url

Browser-Kompatibilität