chrome.contentSettings

Beschreibung

Mit der chrome.contentSettings API können Sie Einstellungen ändern, mit denen festgelegt wird, ob Websites Funktionen wie Cookies, JavaScript und Plug-ins verwenden können. Allgemein gesagt können Sie mit den Inhaltseinstellungen das Verhalten von Chrome nicht global, sondern für jede Website individuell anpassen.

Berechtigungen

contentSettings

Sie müssen die Berechtigung "contentSettings" im Manifest Ihrer Erweiterung deklarieren, um die API verwenden zu können. Beispiel:

{
  "name": "My extension",
  ...
  "permissions": [
    "contentSettings"
  ],
  ...
}

Konzepte und Verwendung

Muster für Inhaltseinstellungen

Mithilfe von Mustern können Sie die Websites angeben, auf die sich die einzelnen Inhaltseinstellungen auswirken. Mit https://*.youtube.com/* werden beispielsweise youtube.com und alle zugehörigen Subdomains angegeben. Die Syntax für Muster für Inhaltseinstellungen entspricht der für Übereinstimmungsmuster, mit einigen Unterschieden:

  • Bei http-, https- und ftp-URLs muss der Pfad ein Platzhalter (/*) sein. Bei file-URLs muss der Pfad vollständig angegeben sein und darf keine Platzhalter enthalten.
  • Im Gegensatz zu Übereinstimmungsmustern können in Mustern für Inhaltseinstellungen eine Portnummer angegeben werden. Wenn eine Portnummer angegeben ist, wird das Muster nur mit Websites mit diesem Port abgeglichen. Wenn keine Portnummer angegeben ist, stimmt das Muster mit allen Ports überein.

Mustervorrang

Wenn für eine bestimmte Website mehrere Regeln für Inhaltseinstellungen gelten, hat die Regel mit dem spezifischeren Muster Vorrang.

Die folgenden Muster sind beispielsweise nach Priorität sortiert:

  1. https://www.example.com/*
  2. https://*.example.com/* (stimmt mit beispiel.de und allen Subdomains überein)
  3. <all_urls> (entspricht jeder URL)

Es gibt drei Arten von Platzhaltern, die sich auf die Spezifität eines Musters auswirken:

  • Platzhalter im Port (z. B. https://www.example.com:*/*)
  • Platzhalter im Schema (z. B. *://www.example.com:123/*)
  • Platzhalter im Hostnamen (z. B. https://*.example.com:123/*)

Wenn ein Muster in einem Teil spezifischer als ein anderes Muster ist, aber in einem anderen Teil weniger spezifisch, werden die verschiedenen Teile in der folgenden Reihenfolge geprüft: Hostname, Schema, Port. Die folgenden Muster sind beispielsweise nach Priorität sortiert:

  1. https://www.example.com:*/* Gibt den Hostnamen und das Schema an.
  2. *:/www.example.com:123/* Nicht so hoch, da zwar der Hostname, aber nicht das Schema angegeben ist.
  3. https://*.example.com:123/* Niedriger, da er zwar den Port und das Schema angibt, aber einen Platzhalter im Hostnamen enthält.

Primäre und sekundäre Muster

Welche URL bei der Entscheidung berücksichtigt wird, welche Inhaltseinstellung angewendet werden soll, hängt vom Inhaltstyp ab. Bei contentSettings.notifications basieren die Einstellungen beispielsweise auf der URL, die in der Omnibox angezeigt wird. Diese URL wird als „primäre“ URL bezeichnet.

Bei einigen Inhaltstypen können zusätzliche URLs berücksichtigt werden. Ob eine Website beispielsweise eine contentSettings.cookies festlegen darf, wird anhand der URL der HTTP-Anfrage (in diesem Fall die primäre URL) sowie der in der Omnibox angezeigten URL (die sogenannte sekundäre URL) entschieden.

Wenn mehrere Regeln primäre und sekundäre Muster haben, hat die Regel mit dem spezifischeren primären Muster Vorrang. Wenn mehrere Regeln dasselbe primäre Muster haben, hat die Regel mit dem spezifischeren sekundären Muster Vorrang. Die folgende Liste von primären/sekundären Musterpaaren ist beispielsweise nach Vorrang sortiert:

VorrangPrimäres MusterSekundäres Muster
1https://www.moose.com/*,https://www.wombat.com/*
2https://www.moose.com/*,<all_urls>
3<all_urls>,https://www.wombat.com/*
4<all_urls>,<all_urls>

Sekundäre Muster werden für die Einstellung „Bildinhalt“ nicht unterstützt.

Ressourcen-IDs

Mithilfe von Ressourcen-IDs können Sie Inhaltseinstellungen für bestimmte Untertypen eines Inhaltstyps angeben. Derzeit ist nur der Inhaltstyp contentSettings.plugins für Ressourcen-IDs verfügbar. Dabei identifiziert eine Ressourcen-ID ein bestimmtes Plug-in. Beim Anwenden von Inhaltseinstellungen werden zuerst die Einstellungen für das jeweilige Plug-in geprüft. Wenn für das jeweilige Plug-in keine Einstellungen gefunden werden, werden die allgemeinen Inhaltseinstellungen für Plug-ins geprüft.

Wenn eine Regel für Inhaltseinstellungen beispielsweise die Ressourcen-ID adobe-flash-player und das Muster <all_urls> hat, hat sie Vorrang vor einer Regel ohne Ressourcen-ID und dem Muster https://www.example.com/*, auch wenn dieses Muster spezifischer ist.

Mit der Methode contentSettings.ContentSetting.getResourceIdentifiers() können Sie eine Liste der Ressourcen-IDs für einen Inhaltstyp abrufen. Die zurückgegebene Liste kann sich je nach den auf dem Computer des Nutzers installierten Plug-ins ändern. Chrome versucht jedoch, die IDs bei Plug-in-Updates stabil zu halten.

Beispiele

Wenn Sie diese API ausprobieren möchten, installieren Sie das Beispiel für die contentSettings API aus dem Repository chrome-extension-samples.

Typen

AutoVerifyContentSetting

Chrome 113 und höher

Enum

„allow“

"block"

CameraContentSetting

Chrome 46 und höher

Enum

„allow“

"block"

„ask“

ClipboardContentSetting

Chrome 121 und höher

Enum

„allow“

"block"

„ask“

ContentSetting

Attribute

  • löschen

    void

    Promise

    Alle Inhaltseinstellungsregeln löschen, die von dieser Erweiterung festgelegt wurden

    Die clear-Funktion sieht so aus: 

    (details: object, callback?: function) => {...}

    • Details

      Objekt

      • Bereich

        Umfang optional

        Wo die Einstellung gelöscht werden soll (Standard: regelmäßig).

    • callback

      function optional

      Der Parameter callback sieht so aus: 

      () => void

    • Gibt zurück

      Promise<void>

      Chrome 96 und höher

      Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

  • get

    void

    Promise

    Ruft die aktuelle Inhaltseinstellung für ein bestimmtes URL-Paar ab.

    Die get-Funktion sieht so aus: 

    (details: object, callback?: function) => {...}

    • Details

      Objekt

      • Inkognito

        boolescher Wert optional

        Ob die Inhaltseinstellungen für eine Inkognito-Sitzung geprüft werden sollen. (Standardeinstellung: „false“)

      • primaryUrl

        String

        Die primäre URL, für die die Inhaltseinstellung abgerufen werden soll. Die Bedeutung einer primären URL hängt vom Inhaltstyp ab.

      • resourceIdentifier

        ResourceIdentifier optional

        Eine genauere Kennzeichnung der Art der Inhalte, für die die Einstellungen abgerufen werden sollen.

      • secondaryUrl

        String optional

        Die sekundäre URL, für die die Inhaltseinstellung abgerufen werden soll. Standardmäßig ist die primäre URL festgelegt. Die Bedeutung einer sekundären URL hängt vom Inhaltstyp ab. Nicht alle Inhaltstypen verwenden sekundäre URLs.

    • callback

      function optional

      Der Parameter callback sieht so aus: 

      (details: object) => void

      • Details

        Objekt

        • Einstellung

          T

          Die Inhaltseinstellung. Die möglichen Werte finden Sie in der Beschreibung der einzelnen ContentSetting-Objekte.

    • Gibt zurück

      Promise<object>

      Chrome 96 und höher

      Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

  • getResourceIdentifiers

    void

    Promise

    Die getResourceIdentifiers-Funktion sieht so aus: 

    (callback?: function) => {...}

    • callback

      function optional

      Der Parameter callback sieht so aus: 

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] optional

        Eine Liste der Ressourcen-IDs für diesen Inhaltstyp oder undefined, wenn für diesen Inhaltstyp keine Ressourcen-IDs verwendet werden.

    • Gibt zurück

      Promise<ResourceIdentifier[]>

      Chrome 96 und höher

      Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

  • set

    void

    Promise

    Es wird eine neue Regel für die Inhaltseinstellung angewendet.

    Die set-Funktion sieht so aus: 

    (details: object, callback?: function) => {...}

    • Details

      Objekt

      • primaryPattern

        String

        Das Muster für die primäre URL. Weitere Informationen zum Format eines Musters finden Sie unter Muster für Inhaltseinstellungen.

      • resourceIdentifier

        ResourceIdentifier optional

        Die Ressourcen-ID für den Inhaltstyp.

      • Bereich

        Umfang optional

        Wo die Einstellung festgelegt werden soll (Standard: normal).

      • secondaryPattern

        String optional

        Das Muster für die sekundäre URL. Standardmäßig werden alle URLs abgeglichen. Weitere Informationen zum Format eines Musters finden Sie unter Muster für Inhaltseinstellungen.

      • Einstellung

        beliebig

        Die durch diese Regel angewendete Einstellung. Die möglichen Werte finden Sie in der Beschreibung der einzelnen ContentSetting-Objekte.

    • callback

      function optional

      Der Parameter callback sieht so aus: 

      () => void

    • Gibt zurück

      Promise<void>

      Chrome 96 und höher

      Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

CookiesContentSetting

Chrome 44 und höher

Enum

„allow“

"block"

"session_only"

FullscreenContentSetting

Chrome 44 und höher

Wert

„allow“

ImagesContentSetting

Chrome 44 und höher

Enum

„allow“

"block"

JavascriptContentSetting

Chrome 44 und höher

Enum

„allow“

"block"

LocationContentSetting

Chrome 44 und höher

Enum

„allow“

"block"

„ask“

MicrophoneContentSetting

Chrome 46 und höher

Enum

„allow“

"block"

„ask“

MouselockContentSetting

Chrome 44 und höher

Wert

„allow“

MultipleAutomaticDownloadsContentSetting

Chrome 44 und höher

Enum

„allow“

"block"

„ask“

NotificationsContentSetting

Chrome 44 und höher

Enum

„allow“

"block"

„ask“

PluginsContentSetting

Chrome 44 und höher

Wert

"block"

PopupsContentSetting

Chrome 44 und höher

Enum

„allow“

"block"

PpapiBrokerContentSetting

Chrome 44 und höher

Wert

"block"

ResourceIdentifier

Der einzige Inhaltstyp, für den Ressourcen-IDs verwendet werden, ist contentSettings.plugins. Weitere Informationen finden Sie unter Ressourcen-IDs.

Attribute

  • Beschreibung

    String optional

    Eine für Menschen lesbare Beschreibung der Ressource.

  • id

    String

    Die Ressourcen-ID für den angegebenen Inhaltstyp.

Scope

Chrome 44 und höher

Der Geltungsbereich der Inhaltseinstellung. Eine der folgenden Optionen:regular: Einstellung für das reguläre Profil, die vom Inkognitoprofil übernommen wird, sofern sie nicht anderswo überschrieben wirdincognito\_session\_only: Einstellung für das Inkognitoprofil, die nur während einer Inkognitositzung festgelegt werden kann und gelöscht wird, wenn die Inkognitositzung endet (überschreibt die regulären Einstellungen).

Enum

„regular“

"incognito_session_only"

Attribute

automaticDownloads

Ob Websites automatisch mehrere Dateien herunterladen dürfen. Eine der folgenden Optionen: allow: Websites dürfen nicht automatisch mehrere Dateien herunterladen block: Websites dürfen nicht automatisch mehrere Dateien herunterladen ask: Fragen, ob eine Website nach der ersten Datei automatisch Dateien herunterladen soll Der Standardwert ist ask. Die primäre URL ist die URL des Frames der obersten Ebene. Die sekundäre URL wird nicht verwendet.

Typ

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 und höher

Ob Websites die Private State Tokens API verwenden dürfen. Eine der folgenden Optionen:allow: Websites die Verwendung der Private State Tokens API erlaubenblock: Websites die Verwendung der Private State Tokens API blockieren Der Standardwert ist allow. Die primäre URL ist die URL des Frames der obersten Ebene. Die sekundäre URL wird nicht verwendet. HINWEIS: Beim Aufrufen von set() muss das primäre Muster „.“ sein.

Typ

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 und höher

Ob Websites auf die Kamera zugreifen dürfen. Eine der folgenden Optionen: allow: Websites den Zugriff auf die Kamera erlauben, block: Websites den Zugriff auf die Kamera nicht erlauben, ask: Fragen, wenn eine Website auf die Kamera zugreifen möchte. Der Standardwert ist ask. Die primäre URL ist die URL des Dokuments, für das der Kamerazugriff angefordert wurde. Die sekundäre URL wird nicht verwendet. HINWEIS: Die Einstellung „Zulassen“ ist nicht gültig, wenn beide Muster „"" sind.

Typ

ContentSetting<CameraContentSetting>

clipboard

Chrome 121 und höher

Gibt an, ob Websites über die erweiterten Funktionen der Async Clipboard API auf die Zwischenablage zugreifen dürfen. Zu den erweiterten Funktionen gehören alle Funktionen, die über das Schreiben von integrierten Formaten nach einer Nutzergeste hinausgehen, z.B. die Möglichkeit zum Lesen, zum Schreiben benutzerdefinierter Formate und zum Schreiben ohne Nutzergeste. Eine der folgenden Optionen: allow: Websites erlauben, erweiterte Zwischenablagefunktionen zu verwenden, block: Websites nicht erlauben, erweiterte Zwischenablagefunktionen zu verwenden, ask: Fragen, wenn eine Website erweiterte Zwischenablagefunktionen verwenden möchte. Der Standardwert ist ask. Die primäre URL ist die URL des Dokuments, für das der Zugriff auf die Zwischenablage angefordert wurde. Die sekundäre URL wird nicht verwendet.

Typ

ContentSetting<ClipboardContentSetting>

cookies

Ob das Speichern von Cookies und anderen lokalen Daten durch Websites zugelassen werden soll. Eine der folgenden Optionen: allow: Cookies akzeptieren, block: Cookies blockieren, session\_only: Cookies nur für die aktuelle Sitzung akzeptieren. Der Standardwert ist allow. Die primäre URL ist die URL, die den Cookie-Ursprung darstellt. Die sekundäre URL ist die URL des Frames der obersten Ebene.

Typ

ContentSetting<CookiesContentSetting>

fullscreen

Veraltet. Hat keine Auswirkungen mehr. Die Berechtigung für den Vollbildmodus wird jetzt automatisch für alle Websites erteilt. Der Wert ist immer allow.

Typ

ContentSetting<FullscreenContentSetting>

images

Ob Bilder angezeigt werden sollen. Eine der folgenden Optionen: allow: Bilder anzeigen, block: Bilder nicht anzeigen. Der Standardwert ist allow. Die primäre URL ist die URL des Frames der obersten Ebene. Die sekundäre URL ist die URL des Bildes.

Typ

ContentSetting<ImagesContentSetting>

javascript

Ob JavaScript ausgeführt werden soll. Eine der folgenden Optionen:allow: JavaScript ausführenblock: JavaScript nicht ausführen Der Standardwert ist allow. Die primäre URL ist die URL des Frames der obersten Ebene. Die sekundäre URL wird nicht verwendet.

Typ

ContentSetting<JavascriptContentSetting>

location

Gibt an, ob die Standortbestimmung zulässig ist. Eine der folgenden Optionen: allow: Websites erlauben, Ihren Standort zu ermitteln, block: Websites nicht erlauben, Ihren Standort zu ermitteln, ask: Vor dem Zulassen, dass Websites Ihren Standort ermitteln, um Erlaubnis bitten. Der Standardwert ist ask. Die primäre URL ist die URL des Dokuments, für das Standortdaten angefordert wurden. Die sekundäre URL ist die URL des Frames der obersten Ebene. Sie kann von der anfragenden URL abweichen.

Typ

ContentSetting<LocationContentSetting>

microphone

Chrome 46 und höher

Ob Websites auf das Mikrofon zugreifen dürfen. Eine der folgenden Optionen: allow: Websites Zugriff auf das Mikrofon gewähren, block: Websites keinen Zugriff auf das Mikrofon gewähren, ask: Fragen, wenn eine Website auf das Mikrofon zugreifen möchte. Der Standardwert ist ask. Die primäre URL ist die URL des Dokuments, für das der Mikrofonzugriff angefordert wurde. Die sekundäre URL wird nicht verwendet. HINWEIS: Die Einstellung „Zulassen“ ist nicht gültig, wenn beide Muster „"" sind.

Typ

ContentSetting<MicrophoneContentSetting>

mouselock

Veraltet. Hat keine Auswirkungen mehr. Die Berechtigung zur Maussperre wird jetzt automatisch für alle Websites erteilt. Der Wert ist immer allow.

Typ

ContentSetting<MouselockContentSetting>

notifications

Ob Websites Desktop-Benachrichtigungen anzeigen dürfen. Eine der folgenden Optionen: allow: Websites zulassen, Desktop-Benachrichtigungen anzuzeigen, block: Websites nicht zulassen, Desktop-Benachrichtigungen anzuzeigen, ask: Nachfragen, wenn eine Website Desktop-Benachrichtigungen anzeigen möchte. Der Standardwert ist ask. Die primäre URL ist die URL des Dokuments, für das die Benachrichtigung angezeigt werden soll. Die sekundäre URL wird nicht verwendet.

Typ

ContentSetting<NotificationsContentSetting>

plugins

Veraltet. Da Flash in Chrome 88 entfernt wurde, hat diese Berechtigung keine Auswirkungen mehr. Der Wert ist immer block. Aufrufe von set() und clear() werden ignoriert.

Typ

ContentSetting<PluginsContentSetting>

popups

Ob Websites Pop-ups anzeigen dürfen. Eine der folgenden Optionen: allow: Websites dürfen Pop-ups anzeigen lassenblock: Websites dürfen keine Pop-ups anzeigen lassen Der Standardwert ist block. Die primäre URL ist die URL des Frames der obersten Ebene. Die sekundäre URL wird nicht verwendet.

Typ

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

Veraltet. Bisher wurde damit gesteuert, ob Websites Plug-ins ohne Sandkasten ausführen dürfen. Da der Flash-Broker-Prozess in Chrome 88 entfernt wurde, hat diese Berechtigung jedoch keine Auswirkungen mehr. Der Wert ist immer block. Aufrufe von set() und clear() werden ignoriert.

Typ

ContentSetting<PpapiBrokerContentSetting>