Beschreibung
Verwenden Sie die chrome.permissions
API, um deklarierte optionale Berechtigungen nicht während der Installation, sondern zur Laufzeit anzufordern. So können Nutzer nachvollziehen, warum die Berechtigungen erforderlich sind, und nur die notwendigen Berechtigungen erteilen.
Konzepte und Nutzung
Berechtigungswarnungen existieren, um die von einer API gewährten Berechtigungen zu beschreiben. Einige dieser Warnungen sind jedoch möglicherweise nicht offensichtlich. Mit der Berechtigungen API können Entwickler Berechtigungswarnungen erklären und nach und nach neue Funktionen einführen. So haben Nutzer eine sichere Einführung in die Erweiterung. Auf diese Weise können Nutzer angeben, wie viel Zugriff sie gewähren möchten und welche Funktionen sie aktivieren möchten.
Beispielsweise überschreibt die Hauptfunktion der optionalen Berechtigungserweiterung die Seite „Neuer Tab“. Eine Funktion ist die Anzeige des Tagesziels der Nutzenden. Für diese Funktion ist nur die Berechtigung Speicher erforderlich, die keine Warnung enthält. Die Erweiterung verfügt über eine zusätzliche Funktion, die Nutzer aktivieren können, indem sie auf die folgende Schaltfläche klicken:
![Eine Erweiterungsschaltfläche, mit der zusätzliche Funktionen aktiviert werden können.](https://developer.chrome.google.cn/static/docs/extensions/reference/api/permissions/images/extension-button-enables-c53fe17733b8f.png?authuser=6&hl=de)
Damit die Top-Websites des Nutzers angezeigt werden können, ist die Berechtigung topSites erforderlich, die die folgende Warnung enthält.
![Axtension-Warnung für die topSites API.](https://developer.chrome.google.cn/static/docs/extensions/reference/api/permissions/images/extension-warning-topsit-8927d6b7cb863.png?authuser=6&hl=de)
topSites
APIOptionale Berechtigungen implementieren
Schritt 1: Festlegen, welche Berechtigungen erforderlich und welche optional sind
Eine Erweiterung kann sowohl erforderliche als auch optionale Berechtigungen deklarieren. Im Allgemeinen sollten Sie Folgendes tun:
- Verwenden Sie die erforderlichen 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 erforderlicher Berechtigungen:
- Weniger Aufforderungen:Eine Erweiterung kann den Nutzer einmal auffordern, alle Berechtigungen zu gewähren.
- Einfachere Entwicklung:Erforderliche Berechtigungen sind garantiert vorhanden.
Vorteile von optionalen Berechtigungen:
- Bessere Sicherheit:Erweiterungen werden mit weniger Berechtigungen ausgeführt, da Nutzer nur erforderliche 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 ein Upgrade Ihrer Erweiterung durchführen, wird es 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
. Verwenden Sie dabei dasselbe Format wie im Feld permissions:
{
"name": "My extension",
...
"optional_permissions": ["tabs"],
"optional_host_permissions": ["https://www.google.com/"],
...
}
Wenn Sie Hosts anfordern möchten, die Sie nur während der Laufzeit erkennen, geben Sie "https://*/*"
in das Feld optional_host_permissions
Ihrer Erweiterung ein. Auf diese Weise 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 optional festgelegt werden. Es gibt jedoch einige Ausnahmen:
Berechtigung | Beschreibung |
---|---|
"debugger" |
Die chrome.debugger 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 der Erweiterung, die Funktion der Chrome-Entwicklertools zu erweitern. |
"geolocation" |
Die Erweiterung kann die HTML5 geolocation API 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 ab. |
"ttsEngine" |
Die chrome.ttsEngine API implementiert mithilfe einer Erweiterung eine Sprachausgabe-Engine. |
"wallpaper" |
Nur ChromeOS Sie können den ChromeOS-Hintergrund über die chrome.wallpaper API ändern. |
Unter Erklärung von Berechtigungen finden Sie weitere Informationen zu verfügbaren Berechtigungen und den zugehörigen Warnungen.
Schritt 3: Optionale Berechtigungen anfordern
Fordern Sie die Berechtigungen aus 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.
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();
}
});
});
Der Nutzer wird in Chrome gefragt, ob das Hinzufügen der Berechtigungen zu anderen Warnmeldungen führt, als er bereits gesehen und akzeptiert hat. Der vorherige Code könnte beispielsweise so zu einer Eingabeaufforderung führen:
![Beispiel für eine Aufforderung zur Bestätigung der Berechtigung](https://developer.chrome.google.cn/static/docs/extensions/reference/api/permissions/images/perms-optional.png?authuser=6&hl=de)
Schritt 4: Aktuelle Berechtigungen der Erweiterung prüfen
Mit permission.contains()
kannst du prüfen, ob deine Erweiterung eine bestimmte Berechtigung oder eine Reihe von Berechtigungen 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. Nachdem eine Berechtigung entfernt wurde, wird die Berechtigung durch einen Aufruf von permissions.request()
normalerweise 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 der im
optional_permissions
- oderpermissions
-Schlüssel im Manifest angegebenen und mit Content Scripts verknüpften Berechtigungen. -
Berechtigungen
string[] optional
Liste der benannten Berechtigungen (ohne Hosts oder Ursprünge).
Methoden
contains()
chrome.permissions.contains(
permissions: Permissions,
callback?: function,
)
Überprüft, ob die Erweiterung die angegebenen Berechtigungen hat.
Parameters
-
Berechtigungen
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(result: boolean) => void
-
Ergebnis
boolean
„True“, wenn die Erweiterung die angegebenen Berechtigungen hat. Wenn ein Ursprung sowohl als optionale Berechtigung als auch als Inhaltsskript-Übereinstimmungsmuster angegeben ist, wird
false
zurückgegeben, sofern nicht beide Berechtigungen gewährt werden.
-
Rückgaben
-
Promise<boolean>
Chrome 96 oder höherPromise-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.
getAll()
chrome.permissions.getAll(
callback?: function,
)
Ruft die aktuellen Berechtigungen der Erweiterung ab.
Parameters
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(permissions: Permissions) => void
-
Berechtigungen
Die aktiven Berechtigungen der Erweiterung. Das Attribut „
origins
“ enthält gewährte Ursprünge, die von den in den Schlüsselnpermissions
undoptional_permissions
im Manifest angegebenen sowie von den mit Content Scripts verknüpften Ursprüngen stammen.
-
Rückgaben
-
Promise<Berechtigungen>
Chrome 96 oder höherPromise-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.
remove()
chrome.permissions.remove(
permissions: Permissions,
callback?: function,
)
Entfernt den Zugriff auf die angegebenen Berechtigungen. Sollten beim Entfernen der Berechtigungen Probleme auftreten, wird runtime.lastError
festgelegt.
Parameters
-
Berechtigungen
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(removed: boolean) => void
-
entfernt
boolean
True, wenn die Berechtigungen entfernt wurden.
-
Rückgaben
-
Promise<boolean>
Chrome 96 oder höherPromise-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.
request()
chrome.permissions.request(
permissions: Permissions,
callback?: function,
)
Fordert Zugriff auf die angegebenen Berechtigungen an. Für den Nutzer wird gegebenenfalls eine Aufforderung angezeigt. Diese Berechtigungen müssen entweder im Feld „optional_permissions
“ des Manifests definiert werden oder es müssen erforderliche Berechtigungen sein, die vom Nutzer verweigert wurden. Pfade für Ursprungsmuster werden ignoriert. Du kannst Teilmengen optionaler Ursprungsberechtigungen anfordern. Wenn du beispielsweise *://*\/*
im Abschnitt optional_permissions
des Manifests angibst, kannst du http://example.com/
anfordern. Sollten beim Anfordern der Berechtigungen Probleme auftreten, wird runtime.lastError
festgelegt.
Parameters
-
Berechtigungen
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(granted: boolean) => void
-
Berechtigung erteilt
boolean
True, wenn der Nutzer die angegebenen Berechtigungen gewährt hat.
-
Rückgaben
-
Promise<boolean>
Chrome 96 oder höherPromise-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.
Veranstaltungen
onAdded
chrome.permissions.onAdded.addListener(
callback: function,
)
Wird ausgelöst, wenn die Erweiterung neue Berechtigungen erwirbt.
Parameters
-
callback
Funktion
Der Parameter
callback
sieht so aus:(permissions: Permissions) => void
-
Berechtigungen
-
onRemoved
chrome.permissions.onRemoved.addListener(
callback: function,
)
Wird ausgelöst, wenn der Erweiterung der Zugriff auf Berechtigungen entfernt wurde.
Parameters
-
callback
Funktion
Der Parameter
callback
sieht so aus:(permissions: Permissions) => void
-
Berechtigungen
-