Description
Utilisez l'API chrome.permissions
pour demander des autorisations facultatives déclarées au moment de l'exécution plutôt que lors de l'installation, afin que les utilisateurs comprennent pourquoi les autorisations sont nécessaires et n'accordent que celles qui sont nécessaires.
Concepts et utilisation
Les avertissements concernant les autorisations permettent de décrire les fonctionnalités accordées par une API, mais certains peuvent ne pas être évidents. L'API Permissions permet aux développeurs d'expliquer les avertissements liés aux autorisations et d'introduire progressivement de nouvelles fonctionnalités, ce qui permet aux utilisateurs de découvrir l'extension sans risque. De cette façon, les utilisateurs peuvent spécifier le niveau d'accès qu'ils sont prêts à accorder et les fonctionnalités qu'ils souhaitent activer.
Par exemple, la fonctionnalité de base de l'extension d'autorisation facultative remplace la page "Nouvel onglet". Une fonctionnalité consiste à afficher l'objectif de la journée de l'utilisateur. Cette fonctionnalité ne nécessite que l'autorisation storage. Aucun avertissement n'est affiché. L'extension comporte une fonctionnalité supplémentaire que les utilisateurs peuvent activer en cliquant sur le bouton suivant:
![Un bouton d'extension qui permet d'activer des fonctionnalités supplémentaires](https://developer.chrome.google.cn/static/docs/extensions/reference/api/permissions/images/extension-button-enables-c53fe17733b8f.png?authuser=9&hl=fr)
Pour afficher les sites les plus populaires de l'utilisateur, vous devez disposer de l'autorisation topSites, qui comporte l'avertissement suivant.
![Avertissement Axtension pour l'API topSites.](https://developer.chrome.google.cn/static/docs/extensions/reference/api/permissions/images/extension-warning-topsit-8927d6b7cb863.png?authuser=9&hl=fr)
topSites
Implémenter des autorisations facultatives
Étape 1: Déterminez les autorisations requises et facultatives
Une extension peut déclarer des autorisations obligatoires et facultatives. En règle générale, vous devez:
- Utilisez les autorisations requises lorsqu'elles sont nécessaires au fonctionnement de base de votre extension.
- Utilisez des autorisations facultatives lorsqu'elles sont nécessaires pour les fonctionnalités facultatives de votre extension.
Avantages des autorisations obligatoires:
- Moins d'invites:une extension peut inviter l'utilisateur une seule fois à accepter toutes les autorisations.
- Développement simplifié:la présence des autorisations requises est garantie.
Avantages des autorisations facultatives:
- Sécurité améliorée:les extensions s'exécutent avec moins d'autorisations, car les utilisateurs n'activent que les autorisations nécessaires.
- Informations plus utiles pour les utilisateurs:une extension peut expliquer pourquoi elle a besoin d'une autorisation particulière lorsque l'utilisateur active la fonctionnalité concernée.
- Mises à niveau plus faciles:lorsque vous mettez à niveau votre extension, Chrome ne la désactive pas pour vos utilisateurs si la mise à niveau ajoute des autorisations facultatives plutôt que requises.
Étape 2: Déclarez les autorisations facultatives dans le fichier manifeste
Déclarez des autorisations facultatives dans le fichier manifeste d'extension avec la clé optional_permissions
, en utilisant le même format que le champ permissions:
{
"name": "My extension",
...
"optional_permissions": ["tabs"],
"optional_host_permissions": ["https://www.google.com/"],
...
}
Si vous souhaitez demander des hôtes que vous ne découvrez qu'au moment de l'exécution, incluez "https://*/*"
dans le champ optional_host_permissions
de votre extension. Cela vous permet de spécifier n'importe quelle origine dans "Permissions.origins"
, à condition qu'elle ait un schéma correspondant.
Autorisations qui ne peuvent pas être spécifiées comme facultatives
La plupart des autorisations des extensions Chrome peuvent être spécifiées comme facultatives, avec les exceptions suivantes.
Autorisation | Description |
---|---|
"debugger" |
L'API chrome.debugger sert de moyen de transport alternatif pour le protocole de débogage à distance de Chrome. |
"declarativeNetRequest" |
Accorde à l'extension l'accès à l'API chrome.declarativeNetRequest. |
"devtools" |
Permet à l'extension d'étendre les fonctionnalités des Outils pour les développeurs Chrome. |
"geolocation" |
Permet à l'extension d'utiliser l'API de geolocation HTML5. |
"mdns" |
Accorde à l'extension l'accès à l'API chrome.mdns. |
"proxy" |
Permet à l'extension d'accéder à l'API chrome.proxy pour gérer les paramètres proxy de Chrome. |
"tts" |
L'API chrome.tts lit la synthèse vocale. |
"ttsEngine" |
L'API chrome.ttsEngine met en œuvre un moteur de synthèse vocale à l'aide d'une extension. |
"wallpaper" |
ChromeOS uniquement. Utilisez l'API chrome.wallpaper pour modifier le fond d'écran ChromeOS. |
Consultez la section Déclarer des autorisations pour en savoir plus sur les autorisations disponibles et les avertissements associés.
Étape 3: Demandez des autorisations facultatives
Demandez les autorisations d'un geste de l'utilisateur à l'aide de permissions.request()
:
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 invite l'utilisateur si l'ajout des autorisations entraîne l'affichage de messages d'avertissement différents de ceux que l'utilisateur a déjà vus et acceptés. Par exemple, le code précédent peut entraîner une invite comme celle-ci:
![Exemple d'invite de confirmation d'autorisation.](https://developer.chrome.google.cn/static/docs/extensions/reference/api/permissions/images/perms-optional.png?authuser=9&hl=fr)
Étape 4: Vérifiez les autorisations actuelles de l'extension
Pour vérifier si votre extension dispose d'une autorisation ou d'un ensemble d'autorisations spécifique, utilisez permission.contains()
:
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.
}
});
Étape 5: Supprimez les autorisations
Nous vous conseillons de supprimer les autorisations lorsque vous n'en avez plus besoin. Une fois qu'une autorisation a été supprimée, appeler permissions.request()
permet généralement de la rajouter sans afficher d'invite.
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).
}
});
Types
Permissions
Propriétés
-
origines
string[] facultatif
Liste des autorisations d'hôte, y compris celles spécifiées dans les clés
optional_permissions
oupermissions
du fichier manifeste, et celles associées aux scripts de contenu. -
autorisations
string[] facultatif
Liste des autorisations nommées (n'inclut pas les hôtes ni les origines).
Méthodes
contains()
chrome.permissions.contains(
permissions: Permissions,
callback?: function,
)
Vérifie si l'extension dispose des autorisations spécifiées.
Paramètres
-
autorisations
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(result: boolean) => void
-
résultat
boolean
"True" si l'extension dispose des autorisations spécifiées. Si une origine est spécifiée à la fois en tant qu'autorisation facultative et en tant que modèle de correspondance du script de contenu, la valeur
false
est renvoyée, sauf si les deux autorisations sont accordées.
-
Renvoie
-
Promise<boolean>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
getAll()
chrome.permissions.getAll(
callback?: function,
)
Récupère l'ensemble d'autorisations actuel de l'extension.
Paramètres
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(permissions: Permissions) => void
-
autorisations
Autorisations actives de l'extension. Notez que la propriété
origins
contiendra les origines autorisées à partir de celles spécifiées dans les cléspermissions
etoptional_permissions
du fichier manifeste et de celles associées aux scripts de contenu.
-
Renvoie
-
Promettre<Permissions>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
remove()
chrome.permissions.remove(
permissions: Permissions,
callback?: function,
)
Supprime l'accès aux autorisations spécifiées. Si vous rencontrez des problèmes pour supprimer les autorisations, runtime.lastError
sera défini.
Paramètres
-
autorisations
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(removed: boolean) => void
-
supprimé
boolean
"True" si les autorisations ont été supprimées.
-
Renvoie
-
Promise<boolean>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
request()
chrome.permissions.request(
permissions: Permissions,
callback?: function,
)
Demande l'accès aux autorisations spécifiées et affiche une invite si nécessaire. Ces autorisations doivent être définies dans le champ optional_permissions
du fichier manifeste ou correspondre à des autorisations requises qui n'ont pas été accordées à l'utilisateur. Les chemins d'accès au format d'origine seront ignorés. Vous pouvez demander des sous-ensembles d'autorisations facultatives liées à l'origine. Par exemple, si vous spécifiez *://*\/*
dans la section optional_permissions
du fichier manifeste, vous pouvez demander http://example.com/
. En cas de problème lors de la demande des autorisations, runtime.lastError
est défini.
Paramètres
-
autorisations
-
rappel
fonction facultative
Le paramètre
callback
se présente comme suit :(granted: boolean) => void
-
accordée
boolean
"True" si l'utilisateur a accordé les autorisations spécifiées.
-
Renvoie
-
Promise<boolean>
Chrome 96 et versions ultérieuresLes promesses sont compatibles avec Manifest V3 et les versions ultérieures, mais des rappels sont fournis pour assurer la rétrocompatibilité. Vous ne pouvez pas utiliser les deux dans le même appel de fonction. La promesse est résolue avec le même type que celui transmis au rappel.
Événements
onAdded
chrome.permissions.onAdded.addListener(
callback: function,
)
Déclenché lorsque l'extension obtient de nouvelles autorisations.
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(permissions: Permissions) => void
-
autorisations
-
onRemoved
chrome.permissions.onRemoved.addListener(
callback: function,
)
Déclenché lorsque l'accès aux autorisations a été supprimé de l'extension
Paramètres
-
rappel
function
Le paramètre
callback
se présente comme suit :(permissions: Permissions) => void
-
autorisations
-