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 dürfen. Allgemein gesagt, können Sie mit Inhaltseinstellungen das Verhalten von Chrome für einzelne Websites und nicht global anpassen.

Berechtigungen

contentSettings

Du musst die Berechtigung „"contentSettings"“ im Manifest deiner Erweiterung deklarieren, um die API nutzen zu können. Beispiel:

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

Konzepte und Nutzung

Muster für die Inhaltseinstellung

Mithilfe von Mustern können Sie die Websites angeben, auf die sich die jeweilige Inhaltseinstellung auswirkt. Beispiel: Durch https://*.youtube.com/* werden youtube.com und alle zugehörigen Subdomains angegeben. Die Syntax für Inhaltseinstellungsmuster ist bis auf einige Unterschiede die gleiche wie für Übereinstimmungsmuster:

  • Bei http-, https- und ftp-URLs muss der Pfad ein Platzhalter (/*) sein. Bei file-URLs muss der Pfad vollständig angegeben werden und dürfen keine Platzhalter enthalten.
  • Im Gegensatz zu Abgleichsmustern kann in Inhaltseinstellungsmustern eine Portnummer angegeben werden. Wenn eine Portnummer angegeben ist, stimmt das Muster nur mit Websites mit diesem Port überein. Wenn keine Portnummer angegeben ist, gilt das Muster für alle Ports.

Rangfolge von Mustern

Wenn für eine bestimmte Website mehrere Regeln für die Inhaltseinstellung 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 beispiel.de und allen Subdomains)
  3. <all_urls> (Übereinstimmung mit jeder URL)

Drei Arten von Platzhaltern 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, in einem anderen Teil jedoch weniger spezifisch ist, 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, weil damit zwar der Hostname, aber nicht das Schema angegeben wird.
  3. https://*.example.com:123/* Niedriger, da damit zwar Port und Schema angegeben werden, der Hostname aber einen Platzhalter hat.

Primäre und sekundäre Muster

Welche URL bei der Entscheidung, welche Inhaltseinstellung angewendet wird, berücksichtigt wird, hängt vom Inhaltstyp ab. Die Einstellungen für contentSettings.notifications basieren 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 „sekundäre“ URL) bestimmt.

Wenn mehrere Regeln primäre und sekundäre Muster haben, hat die Regel mit dem spezifischeren primären Muster Vorrang. Wenn es mehrere Regeln mit demselben primären Muster gibt, hat die Regel mit dem spezifischeren sekundären Muster Vorrang. Die folgende Liste mit primären/sekundären Musterpaaren ist beispielsweise nach Priorität 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>

Ressourcen-IDs

Mit Ressourcenkennungen können Sie Inhaltseinstellungen für bestimmte Untertypen eines Inhaltstyps angeben. Derzeit ist contentSettings.plugins der einzige Inhaltstyp, der Ressourcen-IDs unterstützt. Dabei identifiziert eine Ressourcen-ID ein bestimmtes Plug-in. Wenn Sie Inhaltseinstellungen anwenden, werden zuerst die Einstellungen für das jeweilige Plug-in überprüft. Wenn für ein bestimmtes Plug-in keine Einstellungen gefunden werden, werden die allgemeinen Inhaltseinstellungen für Plug-ins überprüft.

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

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

Beispiele

Wenn Sie diese API testen möchten, installieren Sie das contentSettings API-Beispiel aus dem Repository chrome-extension-sample.

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 für Inhaltseinstellungen löschen.

    Die Funktion clear sieht so aus: 

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

    • Details

      Objekt

      • Bereich

        Umfang optional

        Gibt an, wo die Einstellung gelöscht werden soll (Standardeinstellung: regulär).

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      ()=>void

    • Gibt zurück

      Promise<void>

      Chrome 96 oder 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 einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

  • get

    void

    Versprechen

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

    Die Funktion get sieht so aus: 

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

    • Details

      Objekt

      • inkognito

        Boolescher Wert optional

        Gibt an, ob die Inhaltseinstellungen für eine Inkognitositzung geprüft werden sollen. (Standardeinstellung „false“)

      • primaryUrl

        String

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

      • resourceIdentifier

        ResourceIdentifier optional

        Eine genauere Kennung für den Inhaltstyp, für den die Einstellungen abgerufen werden sollen.

      • secondaryUrl

        String optional

        Die sekundäre URL, für die die Inhaltseinstellung abgerufen werden soll. Die Standardeinstellung ist die primäre URL. Beachten Sie, dass die Bedeutung einer sekundären URL vom Inhaltstyp abhängt. Nicht für alle Inhaltstypen werden sekundäre URLs verwendet.

    • 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 oder 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 einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

  • getResourceIdentifiers

    void

    Versprechen

    Die Funktion getResourceIdentifiers sieht so aus: 

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

    • callback

      Funktion optional

      Der Parameter callback sieht so aus: 

      (resourceIdentifiers?: ResourceIdentifier[])=>void

      • resourceIdentifiers

        ResourceIdentifier[] optional

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

    • Gibt zurück

      Promise<ResourceIdentifier[]>

      Chrome 96 oder 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 einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

  • set

    void

    Versprechen

    Wendet eine neue Regel für die Inhaltseinstellung an.

    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 Inhaltseinstellungsmuster.

      • resourceIdentifier

        ResourceIdentifier optional

        Die Ressourcen-ID für den Inhaltstyp.

      • Bereich

        Umfang optional

        Hier wird die Einstellung festgelegt (Standard: regulär).

      • secondaryPattern

        String optional

        Das Muster für die sekundäre URL. Entspricht standardmäßig allen URLs. Weitere Informationen zum Format eines Musters finden Sie unter Muster für die Inhaltseinstellung.

      • 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

      Promise<void>

      Chrome 96 oder 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 einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

CookiesContentSetting

Chrome 44 und höher

Enum

"session_only"

FullscreenContentSetting

Chrome 44 und höher

Wert

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

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 Ressourcenkennzeichnungen.

Attribute

  • Beschreibung

    String optional

    Eine menschenlesbare Beschreibung der Ressource.

  • id

    String

    Die Ressourcen-ID für den angegebenen Inhaltstyp.

Scope

Chrome 44 und höher

Der Umfang von ContentSetting. Eine der regular: Einstellung für ein reguläres Profil, die vom Inkognitoprofil übernommen wird, wenn sie nicht an anderer Stelle überschrieben wird. incognito\_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 normalen Einstellungen).

Enum

"regular"

Attribute

automaticDownloads

Gibt an, ob Websites mehrere Dateien automatisch herunterladen dürfen. Eine der folgenden Optionen: allow: Websites dürfen automatisch mehrere Dateien herunterladen, block: Websites dürfen nicht automatisch mehrere Dateien herunterladen, ask: Websites fragen, wenn eine Website Dateien nach der ersten Datei automatisch herunterladen möchte. Der Standardwert ist ask. Die primäre URL ist die URL des Frames auf oberster Ebene. Die sekundäre URL wird nicht verwendet.

Typ

ContentSetting<MultipleAutomaticDownloadsContentSetting>

autoVerify

Chrome 113 und höher

Gibt an, ob Websites die Private State Tokens API verwenden dürfen. Eine der allow: Websites die Verwendung der Private State Tokens API erlauben, block: Websites daran hindern, die Private State Tokens API zu verwenden. 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 .

Typ

ContentSetting<AutoVerifyContentSetting>

camera

Chrome 46 und höher

Gibt an, ob Websites auf die Kamera zugreifen dürfen. Eine der folgenden Optionen: allow: Websites erlauben, auf die Kamera zuzugreifen, block: Websites nicht erlauben, auf die Kamera zuzugreifen, ask: Websites 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 „allow“ ist ungültig, wenn beide Muster auf „'“ festgelegt sind.

Typ

ContentSetting<CameraContentSetting>

clipboard

Chrome 121 und höher

Gibt an, ob Websites über erweiterte Funktionen der Async Clipboard API auf die Zwischenablage zugreifen dürfen. „Erweiterte“ Funktionen umfassen alles, was über das Schreiben von integrierten Formaten nach einer Nutzergeste hinaus möglich ist, d.h. die Fähigkeit, zu lesen, benutzerdefinierte Formate zu schreiben und ohne Nutzergeste zu schreiben. Eine der folgenden Optionen: allow: Websites dürfen erweiterte Funktionen der Zwischenablage verwenden, block: Websites dürfen keine erweiterten Funktionen der Zwischenablage verwenden, ask: Websites fragen, wenn sie erweiterte Funktionen für die Zwischenablage verwenden möchten. Der Standardwert ist ask. Die primäre URL ist die URL des Dokuments, das den Zugriff auf die Zwischenablage angefordert hat. Die sekundäre URL wird nicht verwendet.

Typ

ContentSetting<ClipboardContentSetting>

cookies

Gibt an, ob Cookies und andere lokale Daten von Websites gesetzt 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<CookiesContentSetting>

fullscreen

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

Typ

ContentSetting<FullscreenContentSetting>

images

Gibt an, ob Bilder angezeigt werden sollen. Eines der folgenden Elemente: allow: Bilder anzeigen, block: keine Bilder anzeigen. Der Standardwert ist allow. Die primäre URL ist die URL des Frames auf oberster 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ühren, block: 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 zugelassen wird. Eine der folgenden Optionen: allow: Websites dürfen meinen physischen Standort abrufen, block: Websites nicht erlauben, meinen physischen Standort zu erfassen, ask: Websites fragen, bevor sie meinen physischen Standort abrufen dürfen. Der Standardwert ist ask. Die primäre URL ist die URL des Dokuments, über das Standortdaten angefordert wurden. Die sekundäre URL ist die URL des Frames auf oberster Ebene. Sie kann sich von der anfragenden URL unterscheiden.

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 den Zugriff auf das Mikrofon erlauben, block: Websites dürfen nicht auf das Mikrofon zugreifen, ask: Websites 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 „allow“ ist ungültig, wenn beide Muster auf „'“ festgelegt sind.

Typ

ContentSetting<MicrophoneContentSetting>

mouselock

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

Typ

ContentSetting<MouselockContentSetting>

notifications

Gibt an, ob Websites Desktop-Benachrichtigungen anzeigen dürfen. Eine der folgenden Optionen: allow: Anzeige von Desktop-Benachrichtigungen auf Websites zulassen, block: Anzeigen von Desktop-Benachrichtigungen nicht zulassen, ask: Nachfragen, wenn eine Website Desktop-Benachrichtigungen anzeigen möchte. Der Standardwert ist ask. Die primäre URL ist die URL des Dokuments, in dem die Benachrichtigung angezeigt werden soll. Die sekundäre URL wird nicht verwendet.

Typ

ContentSetting<NotificationsContentSetting>

plugins

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

Typ

ContentSetting<PluginsContentSetting>

popups

Gibt an, ob Websites Pop-ups anzeigen dürfen. Eine der folgenden Optionen: allow: Websites dürfen Pop-ups anzeigen, block: Websites dürfen keine Pop-ups anzeigen. Der Standardwert ist block. Die primäre URL ist die URL des Frames auf oberster Ebene. Die sekundäre URL wird nicht verwendet.

Typ

ContentSetting<PopupsContentSetting>

unsandboxedPlugins

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

Typ

ContentSetting<PpapiBrokerContentSetting>