chrome.contentSettings

Beschreibung

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

Berechtigungen

contentSettings

Du musst die Berechtigung "contentSettings" im Manifest deiner 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. Beispiel: https://*.youtube.com/* gibt youtube.com und alle zugehörigen Subdomains an. 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 Abgleichsmustern kann mit Inhaltseinstellungsmustern 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/* (Übereinstimmung mit example.com und allen Subdomains)
  3. <all_urls> (Übereinstimmung mit jeder URL)

Es gibt drei Arten von Platzhaltern, die beeinflussen, wie spezifisch ein Muster ist:

  • 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 geordnet:

  1. https://www.example.com:*/* Gibt den Hostnamen und das Schema an.
  2. *:/www.example.com:123/* Nicht so hoch, weil damit zwar der Hostname angegeben wird, aber nicht das Schema.
  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 zum Beispiel eine contentSettings.cookies festlegen darf, wird anhand der URL der HTTP-Anfrage (in diesem Fall die primäre URL) und der in der Omnibox angezeigten URL (die „sekundäre“ URL genannt) bestimmt.

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 Priorität geordnet:

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 Inhaltseinstellung für Bilder nicht unterstützt.

Ressourcenkennzeichnungen

Mithilfe von Ressourcen-IDs können Sie Inhaltseinstellungen für bestimmte Untertypen eines Inhaltstyps angeben. Derzeit ist contentSettings.plugins der einzige Inhaltstyp, der Ressourcenkennzeichnungen unterstützt, wobei diese ein bestimmtes Plug-in identifiziert. 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 mit der Anzahl der auf dem Gerät des Nutzers installierten Plug-ins ändern. Chrome versucht jedoch, die IDs über Plug-in-Updates hinweg 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

CameraContentSetting

Chrome 46 und höher

Enum

ClipboardContentSetting

Chrome 121 und höher

Enum

ContentSetting

Attribute

  • löschen

    void

    Versprechen

    Alle von dieser Erweiterung festgelegten Regeln zur Inhaltseinstellung löschen.

    Die clear-Funktion sieht so aus: 

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

    • Details

      Objekt

      • Bereich

        Umfang optional

        Ort, an dem die Einstellung gelöscht werden soll (Standardeinstellung: Normal)

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      () => void

    • Gibt zurück

      Versprechen<void>

      Chrome 96 und höher

      Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. 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

    voidm

    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

        Gibt an, ob die Inhaltseinstellungen für eine Inkognitositzung überprü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

      Funktion 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 werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in demselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

  • getResourceIdentifiers

    voidm

    Versprechen

    Die getResourceIdentifiers-Funktion sieht so aus: 

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

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      (resourceIdentifiers?: ResourceIdentifier[]) => void

      • resourceIdentifiers

        ResourceIdentifier[] optional

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

    • Gibt zurück

      Promise<ResourceIdentifier[]>

      Chrome 96 und höher

      Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in demselben 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 Funktion set 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 zur Inhaltseinstellung.

      • 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 von dieser Regel angewendete Einstellung. Die möglichen Werte finden Sie in der Beschreibung der einzelnen ContentSetting-Objekte.

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      () => void

    • Gibt zurück

      Versprechen<void>

      Chrome 96 und höher

      Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in demselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

CookiesContentSetting

Chrome 44 und höher

Enum

"block" 
 

"session_only"

FullscreenContentSetting

Chrome 44 und höher

Wert

„allow“

ImagesContentSetting

Chrome 44 und höher

Enum

JavascriptContentSetting

Chrome 44 und höher

Enum

LocationContentSetting

Chrome 44 und höher

Enum

MicrophoneContentSetting

Chrome 46 und höher

Enum

MouselockContentSetting

Chrome 44 und höher

Wert

„allow“

MultipleAutomaticDownloadsContentSetting

Chrome 44 und höher

Enum

NotificationsContentSetting

Chrome 44 und höher

Enum

PluginsContentSetting

Chrome 44 und höher

Wert

PopupsContentSetting

Chrome 44 und höher

Enum

PpapiBrokerContentSetting

Chrome 44 und höher

Wert

ResourceIdentifier

Der einzige Inhaltstyp, der Ressourcenkennungen verwendet, 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 Bereich von ContentSetting. Eine der folgenden regular: Einstellung für das reguläre Profil (die vom Inkognitoprofil übernommen wird, wenn sie nicht an anderer Stelle überschrieben wird); incognito\_session\_only: Einstellung für ein Inkognitoprofil, das nur während einer Inkognitositzung festgelegt werden kann und gelöscht wird, wenn die Inkognitositzung beendet wird. Sie überschreibt die regulären Einstellungen.

Enum

Attribute

automaticDownloads

Gibt an, 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&lt;MultipleAutomaticDownloadsContentSetting&gt;

autoVerify

Chrome 113 oder höher

Gibt an, 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 auf oberster Ebene. Die sekundäre URL wird nicht verwendet. HINWEIS: Beim Aufrufen von set() muss das primäre Muster „.“ sein.

Typ

ContentSetting&lt;AutoVerifyContentSetting&gt;

camera

Chrome 46 und höher

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

Typ

ContentSetting<CameraContentSetting>

clipboard

Chrome 121 oder 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. das Lesen, das Schreiben benutzerdefinierter Formate und das Schreiben ohne Nutzergeste. Eine der folgenden Möglichkeiten: allow: Websites erlauben, erweiterte Funktionen für die Zwischenablage zu verwenden, block: Websites dürfen keine erweiterten Funktionen für die Zwischenablage verwenden, ask: Frag, wenn eine Website erweiterte Funktionen für die Zwischenablage 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&lt;ClipboardContentSetting&gt;

cookies

Gibt an, ob Cookies und andere lokale Daten von Websites gespeichert werden dürfen. 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 auf oberster Ebene.

Typ

ContentSetting&lt;CookiesContentSetting&gt;

fullscreen

Veraltet. Hat keine Auswirkungen mehr. Die Vollbildberechtigung wird jetzt automatisch für alle Websites gewährt. Der Wert ist immer allow.

Typ

ContentSetting<FullscreenContentSetting>

images

Legt fest, ob Bilder angezeigt werden. 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

Gibt an, 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 auf oberster Ebene. Die sekundäre URL wird nicht verwendet.

Typ

ContentSetting<JavascriptContentSetting>

location

Gibt an, ob die Standortbestimmung zulässig ist. Eine der folgenden Möglichkeiten: allow: Websites erlauben, meinen physischen Standort zu ermitteln, block: Websites dürfen meinen physischen Standort nicht abrufen ask: Frag nach, bevor Websites deinen physischen Standort abrufen dürfen. Der Standardwert ist ask. Die primäre URL ist die URL des Dokuments, das Standortdaten angefordert hat. Bei der sekundären URL handelt es sich um die URL des Frames auf oberster Ebene, die sich von der anfragenden URL unterscheiden kann oder nicht.

Typ

ContentSetting<LocationContentSetting>

microphone

Chrome 46 und höher

Gibt an, 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, das den Mikrofonzugriff angefordert hat. Die sekundäre URL wird nicht verwendet. HINWEIS: Die Einstellung „Zulassen“ ist nicht gültig, wenn beide Muster „"" sind.

Typ

ContentSetting&lt;MicrophoneContentSetting&gt;

mouselock

Veraltet. Dies 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

Gibt an, ob Websites Desktop-Benachrichtigungen anzeigen dürfen. Eine der folgenden Möglichkeiten: allow: Websites erlauben, Desktop-Benachrichtigungen anzuzeigen, block: Websites dürfen keine Desktop-Benachrichtigungen anzeigen, ask: Frag eine Website, 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&lt;NotificationsContentSetting&gt;

plugins

Veraltet. Da die Flash-Unterstützung in Chrome 88 entfernt wurde, hat diese Berechtigung keine Auswirkungen mehr. Der Wert ist immer block. Anrufe an set() und clear() werden ignoriert.

Typ

ContentSetting<PluginsContentSetting>

popups

Ob Websites Pop-ups anzeigen dürfen. Eine der folgenden Möglichkeiten: allow: Anzeige von Pop-ups für Websites zulassen, block: Anzeigen von Pop-ups für Websites nicht zulassen. 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&lt;PopupsContentSetting&gt;

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. Anrufe an set() und clear() werden ignoriert.

Typ

ContentSetting&lt;PpapiBrokerContentSetting&gt;