chrome.permissions

Beschreibung

Verwenden Sie die chrome.permissions API, um deklarierte optionale Berechtigungen zur Laufzeit statt zur Installation anzufordern, damit Nutzer verstehen, warum die Berechtigungen erforderlich sind, und nur die Berechtigungen gewähren, die wirklich erforderlich sind.

Übersicht

Berechtigungswarnungen beschreiben die von einer API gewährten Funktionen. Einige dieser Warnungen sind jedoch möglicherweise nicht offensichtlich. Mit der Berechtigungs-API können Entwickler Berechtigungswarnungen erklären und neue Funktionen nach und nach einführen, sodass Nutzer die Erweiterung risikofrei kennenlernen können. So können Nutzer festlegen, welchen Zugriff sie gewähren möchten und welche Funktionen sie aktivieren möchten.

Beispielsweise wird die „Neuer Tab“-Seite durch die Hauptfunktion der Erweiterung für optionale Berechtigungen überschrieben. Eine Funktion ist die Anzeige des Tagesziels des Nutzers. Für diese Funktion ist nur die Berechtigung Speicher erforderlich, für die keine Warnung angezeigt wird. Die Erweiterung hat eine zusätzliche Funktion, die Nutzer aktivieren können, indem sie auf die folgende Schaltfläche klicken:

Erweiterungsschaltfläche, mit der zusätzliche Funktionen aktiviert werden

Für die Anzeige der Top-Websites des Nutzers ist die Berechtigung topSites erforderlich. Dazu gilt die folgende Warnung:

Warnung zur Erweiterung der topSites API

Optionale Berechtigungen implementieren

Schritt 1: Festlegen, welche Berechtigungen erforderlich und welche optional sind

Für eine Erweiterung können sowohl erforderliche als auch optionale Berechtigungen deklariert werden. Im Allgemeinen gilt Folgendes:

  • Verwenden Sie erforderliche Berechtigungen, wenn sie für die grundlegenden Funktionen Ihrer Erweiterung erforderlich sind.
  • Verwenden Sie optionale Berechtigungen, wenn sie für optionale Funktionen in Ihrer Erweiterung erforderlich sind.

Vorteile von erforderlichen Berechtigungen:

  • Weniger Aufforderungen:Eine Erweiterung kann den Nutzer einmal auffordern, alle Berechtigungen zu akzeptieren.
  • Einfachere Entwicklung:Die erforderlichen Berechtigungen sind garantiert vorhanden.

Vorteile von optionalen Berechtigungen:

  • Mehr Sicherheit:Erweiterungen werden mit weniger Berechtigungen ausgeführt, da Nutzer nur die Berechtigungen aktivieren, die erforderlich sind.
  • Verbesserte Informationen für Nutzer:Eine Erweiterung kann erklären, warum eine bestimmte Berechtigung erforderlich ist, wenn der Nutzer die entsprechende Funktion aktiviert.
  • Einfachere Upgrades:Wenn Sie Ihre Erweiterung aktualisieren, wird sie in Chrome nicht für Ihre Nutzer deaktiviert, wenn das Upgrade optionale und keine erforderlichen Berechtigungen hinzufügt.

Schritt 2: Optionale Berechtigungen im Manifest angeben

Deklarieren Sie optionale Berechtigungen in Ihrem Manifest der Erweiterung mit dem Schlüssel optional_permissions im selben Format wie das Feld permissions:

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "optional_host_permissions": ["https://www.google.com/"],
  ...
}

Wenn Sie Hosts anfordern möchten, die Sie erst zur Laufzeit ermitteln, geben Sie "https://*/*" in das Feld optional_host_permissions Ihrer Erweiterung ein. So können Sie in Permissions.origins jeden Ursprung angeben, solange er ein übereinstimmendes Schema hat.

Berechtigungen, die nicht als optional angegeben werden können

Die meisten Berechtigungen für Chrome-Erweiterungen können mit Ausnahme der folgenden als optional angegeben werden.

Berechtigung Beschreibung
"debugger" Die chrome.debugger API dient als alternativer Transport für das Remote-Debugging-Protokoll von Chrome.
"declarativeNetRequest" Gewährt der Erweiterung Zugriff auf die chrome.declarativeNetRequest API.
"devtools" Ermöglicht es der Erweiterung, die Funktionalität der Chrome DevTools zu erweitern.
"experimental" Nur Canary und Entwicklerversion. Gewährt der Erweiterung Zugriff auf chrome.experimental APIs.
"geolocation" Ermöglicht es der Erweiterung, die Standortbestimmungs-API von HTML5 zu verwenden.
"mdns" Gewährt der Erweiterung Zugriff auf die chrome.mdns API.
"proxy" Gewährt der Erweiterung Zugriff auf die chrome.proxy API, um die Proxy-Einstellungen von Chrome zu verwalten.
"tts" Die chrome.tts API spielt synthetisierte Sprachausgabe (Text-to-Speech, TTS) ab.
"ttsEngine" Die chrome.ttsEngine API implementiert eine Text-to-Speech-Engine (TTS) mithilfe einer Erweiterung.
"wallpaper" Nur ChromeOS Mit der chrome.wallpaper API können Sie den ChromeOS-Hintergrund ändern.

Weitere Informationen zu den verfügbaren Berechtigungen und den zugehörigen Warnungen finden Sie unter Berechtigungen angeben und Nutzer warnen.

Schritt 3: Optionale Berechtigungen anfordern

So fordern Sie die Berechtigungen über eine Nutzergeste mit permissions.request() an:

document.querySelector('#my-button').addEventListener('click', (event) => {
  // Permissions must be requested from inside a user gesture, like a button's
  // click handler.
  chrome.permissions.request({
    permissions: ['tabs'],
    origins: ['https://www.google.com/']
  }, (granted) => {
    // The callback argument will be true if the user granted the permissions.
    if (granted) {
      doSomething();
    } else {
      doSomethingElse();
    }
  });
});

Chrome fordert den Nutzer auf, wenn das Hinzufügen der Berechtigungen zu anderen Warnmeldungen führt, als er bereits gesehen und akzeptiert hat. Der vorherige Code kann beispielsweise zu einem Prompt wie diesem führen:

Beispiel für eine Aufforderung zur Berechtigungsbestätigung

Schritt 4: Aktuelle Berechtigungen der Erweiterung prüfen

Mit permission.contains() können Sie prüfen, ob Ihre Erweiterung eine bestimmte Berechtigung oder einen bestimmten Berechtigungssatz hat:

chrome.permissions.contains({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (result) => {
  if (result) {
    // The extension has the permissions.
  } else {
    // The extension doesn't have the permissions.
  }
});

Schritt 5: Berechtigungen entfernen

Sie sollten Berechtigungen entfernen, wenn Sie sie nicht mehr benötigen. Wenn eine Berechtigung entfernt wurde, wird sie durch Aufrufen von permissions.request() in der Regel wieder hinzugefügt, ohne dass der Nutzer dazu aufgefordert wird.

chrome.permissions.remove({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (removed) => {
  if (removed) {
    // The permissions have been removed.
  } else {
    // The permissions have not been removed (e.g., you tried to remove
    // required permissions).
  }
});

Typen

Permissions

Attribute

  • Ursprünge

    string[] optional

    Die Liste der Hostberechtigungen, einschließlich derjenigen, die in den Schlüsseln optional_permissions oder permissions im Manifest angegeben sind, und derjenigen, die mit Content-Scripts verknüpft sind.

  • Berechtigungen

    string[] optional

    Liste der benannten Berechtigungen (ohne Hosts oder Ursprünge).

Methoden

addSiteAccessRequest()

Promise AusstehendMV3+ 
chrome.permissions.addSiteAccessRequest(
  request: object,
  callback?: function,
)

Fügen Sie eine Anfrage für den Websitezugriff hinzu. Die Anfrage wird dem Nutzer nur angezeigt, wenn der Erweiterung Zugriff auf die Website in der Anfrage gewährt werden kann. Die Anfrage wird bei ursprungsübergreifender Navigation zurückgesetzt. Wenn akzeptiert, gewährt dauerhaften Zugriff auf den Hauptursprung der Website

Parameter

  • Anfrage

    Objekt

    • documentId

      String optional

      Die ID eines Dokuments, in dem Anfragen für den Websitezugriff angezeigt werden können. Muss das Dokument auf oberster Ebene in einem Tab sein. Wenn angegeben, wird die Anfrage auf dem Tab des angegebenen Dokuments angezeigt und entfernt, wenn das Dokument zu einem neuen Ursprung wechselt. Wenn Sie eine neue Anfrage hinzufügen, werden alle vorhandenen Anfragen für tabId überschrieben. Dieser Wert oder tabId muss angegeben werden.

    • Muster

      String optional

      Das URL-Muster, unter dem Anfragen für den Websitezugriff angezeigt werden können. Wenn angegeben, werden Anfragen für den Websitezugriff nur für URLs angezeigt, die mit diesem Muster übereinstimmen.

    • tabId

      number optional

      Die ID des Tabs, auf dem Anfragen für den Websitezugriff angezeigt werden können. Wenn angegeben, wird die Anfrage auf dem angegebenen Tab angezeigt und entfernt, wenn der Tab zu einer neuen Quelle wechselt. Wenn Sie eine neue Anfrage hinzufügen, wird eine vorhandene Anfrage für documentId überschrieben. Dieser Wert oder documentId muss angegeben werden.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Promise<void>

    Versprechen werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

contains()

Promise 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

Prüft, ob die Erweiterung die angegebenen Berechtigungen hat.

Parameter

  • Berechtigungen

    Berechtigungen

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (result: boolean) => void

    • Ergebnis

      boolean

      „True“, wenn die Erweiterung die angegebenen Berechtigungen hat. Wenn eine Quelle sowohl als optionale Berechtigung als auch als Übereinstimmungsmuster für Content-Scripts angegeben ist, wird false zurückgegeben, es sei denn, beide Berechtigungen sind gewährt.

Gibt Folgendes zurück:

  • Promise<boolean>

    Chrome 96 und höher

    Versprechen werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

getAll()

Promise 
chrome.permissions.getAll(
  callback?: function,
)

Ruft die aktuellen Berechtigungen der Erweiterung ab.

Parameter

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (permissions: Permissions) => void

    • Berechtigungen

      Berechtigungen

      Die aktiven Berechtigungen der Erweiterung. Die Eigenschaft origins enthält die genehmigten Ursprünge aus den im Manifest mit den Schlüsseln permissions und optional_permissions angegebenen Ursprüngen sowie die mit Content-Scripts verknüpften Ursprünge.

Gibt Folgendes zurück:

  • Promise<Permissions>

    Chrome 96 und höher

    Versprechen werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

remove()

Promise 
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

Entfernt den Zugriff auf die angegebenen Berechtigungen. Wenn beim Entfernen der Berechtigungen Probleme auftreten, wird runtime.lastError festgelegt.

Parameter

  • Berechtigungen

    Berechtigungen

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (removed: boolean) => void

    • entfernt

      boolean

      „Wahr“, wenn die Berechtigungen entfernt wurden.

Gibt Folgendes zurück:

  • Promise<boolean>

    Chrome 96 und höher

    Versprechen werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

removeSiteAccessRequest()

Promise AusstehendMV3+ 
chrome.permissions.removeSiteAccessRequest(
  request: object,
  callback?: function,
)

Entfernt eine Anfrage für den Websitezugriff, falls vorhanden.

Parameter

  • Anfrage

    Objekt

    • documentId

      String optional

      Die ID eines Dokuments, für das die Zugriffsanfrage entfernt werden soll. Muss das Dokument auf oberster Ebene in einem Tab sein. Dieser Wert oder tabId muss angegeben werden.

    • Muster

      String optional

      Das URL-Muster, für das die Zugriffsanfrage entfernt werden soll. Falls angegeben, muss dieses Muster genau mit dem Muster einer vorhandenen Anfrage für den Websitezugriff übereinstimmen.

    • tabId

      number optional

      Die ID des Tabs, auf dem die Zugriffsanfrage für die Website entfernt werden soll. Dieser Wert oder documentId muss angegeben werden.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Promise<void>

    Versprechen werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

request()

Promise 
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

Erfordert Zugriff auf die angegebenen Berechtigungen und zeigt gegebenenfalls eine Aufforderung an den Nutzer an. Diese Berechtigungen müssen entweder im Feld optional_permissions des Manifests definiert sein oder erforderliche Berechtigungen sein, die vom Nutzer verweigert wurden. Pfade in Ursprungsmustern werden ignoriert. Sie können Teilmengen der optionalen Berechtigungen für den Ursprung anfordern. Wenn Sie beispielsweise im Abschnitt optional_permissions des Manifests *://*\/* angeben, können Sie http://example.com/ anfordern. Wenn Probleme beim Anfordern der Berechtigungen auftreten, wird runtime.lastError festgelegt.

Parameter

  • Berechtigungen

    Berechtigungen

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (granted: boolean) => void

    • Berechtigung erteilt

      boolean

      „Wahr“, wenn der Nutzer die angegebenen Berechtigungen gewährt hat.

Gibt Folgendes zurück:

  • Promise<boolean>

    Chrome 96 und höher

    Versprechen werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

Ereignisse

onAdded

chrome.permissions.onAdded.addListener(
  callback: function,
)

Wird ausgelöst, wenn die Erweiterung neue Berechtigungen erhält.

Parameter

onRemoved

chrome.permissions.onRemoved.addListener(
  callback: function,
)

Wird ausgelöst, wenn der Zugriff auf Berechtigungen von der Erweiterung entfernt wurde.

Parameter