browser.permissions

Beschreibung

Verwenden Sie die chrome.permissions API, um deklarierte optionale Berechtigungen zur Laufzeit und nicht zur Installationszeit anzufordern. So verstehen Nutzer, warum die Berechtigungen erforderlich sind, und gewähren nur die erforderlichen Berechtigungen.

Konzepte und Verwendung

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

Die Hauptfunktion der Erweiterung für optionale Berechtigungen besteht beispielsweise darin, die Seite „Neuer Tab“ zu überschreiben. Eine Funktion ist die Anzeige des Tagesziels des Nutzers. Für diese Funktion ist nur die Berechtigung storage erforderlich, die keine Warnung enthält. Die Erweiterung hat eine zusätzliche Funktion, die Nutzer durch Klicken auf die folgende Schaltfläche aktivieren können:

Eine Erweiterungsschaltfläche, die zusätzliche Funktionen ermöglicht.
Eine Erweiterungsschaltfläche, die zusätzliche Funktionen ermöglicht.

Für die Anzeige der am häufigsten besuchten Websites des Nutzers ist die Berechtigung topSites erforderlich, für die die folgende Warnung gilt.

Erweiterungswarnung für die topSites API.
Eine Erweiterungswarnung für die topSites API

Optionale Berechtigungen implementieren

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

Eine Erweiterung kann sowohl erforderliche als auch optionale Berechtigungen deklarieren. Im Allgemeinen gilt Folgendes:

  • Verwenden Sie erforderliche Berechtigungen, wenn sie für die grundlegende Funktionalität 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 erforderlichen Berechtigungen aktivieren.
  • Bessere Informationen für Nutzer: Eine Erweiterung kann erklären, warum sie eine bestimmte Berechtigung benötigt, wenn der Nutzer die entsprechende Funktion aktiviert.
  • Einfachere Upgrades: Wenn Sie Ihre Erweiterung aktualisieren, wird sie von Chrome nicht für Ihre Nutzer deaktiviert, wenn durch das Upgrade optionale statt erforderliche Berechtigungen hinzugefügt werden.

Schritt 2: Optionale Berechtigungen im Manifest deklarieren

Deklarieren Sie optionale Berechtigungen in Ihrem Erweiterungsmanifest 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, fügen Sie "https://*/*" in das Feld optional_host_permissions Ihrer Erweiterung ein. So können Sie einen beliebigen Ursprung in "Permissions.origins" 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 als optional angegeben werden. Es gelten folgende Ausnahmen:

Berechtigung Beschreibung
"debugger" Die browser.debugger API dient als alternativer Transport für das Remote-Debugging-Protokoll von Chrome.
"declarativeNetRequest" Gewährt der Erweiterung Zugriff auf die browser.declarativeNetRequest API.
"devtools" Ermöglicht der Erweiterung, die Funktionalität der Chrome-Entwicklertools zu erweitern.
"geolocation" Ermöglicht der Erweiterung, die HTML5-API zur Standortbestimmung zu verwenden.
"mdns" Gewährt der Erweiterung Zugriff auf die browser.mdns API.
"proxy" Gewährt der Erweiterung Zugriff auf die browser.proxy API, um die Proxy-Einstellungen von Chrome zu verwalten.
"tts" Die browser.tts API gibt synthetisierte Text-zu-Sprache (TTS) wieder.
"ttsEngine" Die browser.ttsEngine API implementiert eine Text-zu-Sprache-Engine (TTS) mithilfe einer Erweiterung.
"wallpaper" Nur ChromeOS: Verwenden Sie die browser.wallpaper API, um den ChromeOS-Hintergrund zu ändern.

Weitere Informationen zu verfügbaren Berechtigungen und den entsprechenden Warnungen finden Sie unter Berechtigungen deklarieren.

Schritt 3: Optionale Berechtigungen anfordern

Fordern Sie die Berechtigungen innerhalb einer 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.
  browser.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, die Berechtigungen hinzuzufügen, wenn dies zu anderen Warnmeldungen führt als die, die der Nutzer bereits gesehen und akzeptiert hat. Der vorherige Code könnte beispielsweise zu einem Prompt wie diesem führen:

Beispiel für eine Aufforderung zur Bestätigung von Berechtigungen
Beispiel für eine Aufforderung zur Bestätigung der Berechtigung.

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 Satz von Berechtigungen hat:

browser.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. Nachdem eine Berechtigung entfernt wurde, wird sie durch den Aufruf von permissions.request() normalerweise wieder hinzugefügt, ohne dass der Nutzer dazu aufgefordert wird.

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

  • origins

    string[] optional

    Die Liste der Hostberechtigungen, einschließlich der im Manifest in den Schlüsseln optional_permissions oder permissions angegebenen Berechtigungen und der mit Inhaltsskripts verknüpften Berechtigungen.

  • Berechtigungen

    string[] optional

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

Methoden

addHostAccessRequest()

Chrome 133+ browser.* seit Chrome 148 MV3+ 
browser.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

Fügt eine Hostzugriffsanfrage hinzu. Die Anfrage wird dem Nutzer nur signalisiert, wenn der Erweiterung Zugriff auf den Host in der Anfrage gewährt werden kann. Die Anfrage wird bei der ursprungsübergreifenden Navigation zurückgesetzt. Wenn die Anfrage akzeptiert wird, wird dauerhafter Zugriff auf den Top-Origin der Website gewährt.

Parameter

  • Anfrage

    Objekt

    • documentId

      String optional

      Die ID eines Dokuments, in dem Hostzugriffsanfragen angezeigt werden können. Muss das Dokument auf oberster Ebene innerhalb eines Tabs sein. Falls 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, bei dem Hostzugriffsanfragen angezeigt werden können. Wenn angegeben, werden Hostzugriffsanfragen nur für URLs angezeigt, die diesem Muster entsprechen.

    • tabId

      number optional

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

Ausgabe

  • Promise<void>

contains()

browser.permissions.contains(
  permissions: Permissions,
): Promise<boolean>

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

Parameter

Ausgabe

  • Promise<boolean>

    Chrome 96+ browser.* seit Chrome 148

getAll()

browser.permissions.getAll(): Promise<Permissions>

Ruft die aktuellen Berechtigungen der Erweiterung ab.

Ausgabe

  • Promise<Permissions>

    Chrome 96+ browser.* seit Chrome 148

remove()

browser.permissions.remove(
  permissions: Permissions,
): Promise<boolean>

Entfernt den Zugriff auf die angegebenen Berechtigungen. Wenn beim Entfernen der Berechtigungen Probleme auftreten, wird das Promise abgelehnt.

Parameter

Ausgabe

  • Promise<boolean>

    Chrome 96+ browser.* seit Chrome 148

removeHostAccessRequest()

Chrome 133+ browser.* seit Chrome 148 MV3+ 
browser.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

Entfernt eine Hostzugriffsanfrage, falls vorhanden.

Parameter

  • Anfrage

    Objekt

    • documentId

      String optional

      Die ID eines Dokuments, aus dem die Hostzugriffsanfrage entfernt wird. Muss das Dokument auf oberster Ebene innerhalb eines Tabs sein. Dieser Wert oder tabId muss angegeben werden.

    • Muster

      String optional

      Das URL-Muster, für das die Anfrage zum Hostzugriff entfernt wird. Falls angegeben, muss dies genau mit dem Muster einer vorhandenen Hostzugriffsanfrage übereinstimmen.

    • tabId

      number optional

      Die ID des Tabs, auf dem die Anfrage für den Hostzugriff entfernt wird. Dieser Wert oder documentId muss angegeben werden.

Ausgabe

  • Promise<void>

request()

browser.permissions.request(
  permissions: Permissions,
): Promise<boolean>

Fordert Zugriff auf die angegebenen Berechtigungen an und zeigt dem Nutzer bei Bedarf eine Aufforderung an. Diese Berechtigungen müssen entweder im Feld optional_permissions des Manifests definiert sein oder es muss sich um erforderliche Berechtigungen handeln, die vom Nutzer nicht gewährt wurden. Pfade in Ursprungsmustern werden ignoriert. Sie können Teilmengen optionaler Ursprungsberechtigungen anfordern. Wenn Sie beispielsweise *://*\/* im Abschnitt optional_permissions des Manifests angeben, können Sie http://example.com/ anfordern. Wenn beim Anfordern der Berechtigungen Probleme auftreten, wird das Promise abgelehnt.

Parameter

Ausgabe

  • Promise<boolean>

    Chrome 96+ browser.* seit Chrome 148

Ereignisse

onAdded

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

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

Parameter

onRemoved

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

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

Parameter