chrome.permissions

Description

Utilisez l'API chrome.permissions pour demander des autorisations facultatives déclarées lors de l'exécution plutôt qu'au moment de l'installation, afin que les utilisateurs comprennent pourquoi ces autorisations sont nécessaires et n'accordent que celles qui sont nécessaires.

Concepts et utilisation

Des avertissements liés aux autorisations existent pour décrire les fonctionnalités accordées par une API, mais certains d'entre eux peuvent ne pas être évidents. L'API Permissions permet aux développeurs d'expliquer les avertissements d'autorisation 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 souhaitent accorder et les fonctionnalités qu'ils souhaitent activer.

Par exemple, la fonctionnalité de base de l'extension d'autorisations facultatives remplace celle de la page "Nouvel onglet". Une fonctionnalité permet d'afficher l'objectif de la journée de l'utilisateur. Cette fonctionnalité ne nécessite que l'autorisation de stockage, sans avertissement préalable. L'extension dispose d'une fonctionnalité supplémentaire que les utilisateurs peuvent activer en cliquant sur le bouton suivant:

<ph type="x-smartling-placeholder">
</ph> Bouton d&#39;extension qui active des fonctionnalités supplémentaires.
Bouton d'extension qui permet d'activer des fonctionnalités supplémentaires.

Pour afficher les sites les plus populaires de l'utilisateur, vous devez disposer de l'autorisation topSites, qui affiche l'avertissement suivant.

<ph type="x-smartling-placeholder">
</ph> Avertissement concernant l&#39;extension pour l&#39;API topSites.
Avertissement d'extension pour l'API 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 les autorisations facultatives lorsqu'elles sont nécessaires pour des fonctionnalités facultatives de votre extension.

Avantages des autorisations requises:

  • Moins d'invites:une extension peut inviter une seule fois l'utilisateur à accepter toutes les autorisations.
  • Développement simplifié:l'obtention des autorisations requises est garantie.

Avantages des autorisations facultatives:

  • Sécurité renforcée:les extensions s'exécutent avec moins d'autorisations, car les utilisateurs n'activent que les autorisations. nécessaires.
  • Meilleure information pour les utilisateurs:une extension peut expliquer pourquoi une autorisation particulière est nécessaire. 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 obligatoires.

Étape 2: Déclarer des autorisations facultatives dans le fichier manifeste

Déclarez des autorisations facultatives dans le fichier manifeste de l'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 d'un schéma.

Autorisations ne pouvant pas être spécifiées comme facultatives

La plupart des autorisations des extensions Chrome peuvent être spécifiées comme facultatives, à quelques exceptions près.

Autorisation Description
"debugger" L'API chrome.debugger sert de autre moyen de transport pour le débogage à distance de Chrome protocole.
"declarativeNetRequest" Accorde à l'extension l'accès au service chrome.declarativeNetRequest.
"devtools" Autorise l'extension à développer les Outils pour les développeurs Chrome de Google Cloud.
"geolocation" Permet à l'extension d'utiliser l'API de géolocalisation HTML5.
"mdns" Accorde à l'extension l'accès chrome.mdns.
"proxy" Accorde à l'extension l'accès à l'API chrome.proxy pour gérer le proxy de Chrome paramètres.
"tts" L'API chrome.tts lit des données synthétisées la synthèse vocale.
"ttsEngine" L'API chrome.ttsEngine met en œuvre une de synthèse vocale via une extension.
"wallpaper" ChromeOS uniquement. Utilisez l'API chrome.wallpaper pour modifier ChromeOS. un fond d'écran.

Consultez la section Déclarer des autorisations pour en savoir plus sur les autorisations disponibles et et leurs mises en garde.

Étape 3: Demandez des autorisations facultatives

Demandez les autorisations via 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à vu et accepté. Par exemple, le code précédent peut entraîner une invite telle que ceci:

<ph type="x-smartling-placeholder">
</ph> Exemple de requête de confirmation d&#39;autorisation
Exemple de requête de confirmation d'autorisation

É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écifiques, 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

Vous devez supprimer les autorisations lorsque vous n'en avez plus besoin. Après la suppression d'une autorisation, L'appel de permissions.request() ajoute généralement l'autorisation sans envoyer d'invite à l'utilisateur.

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 de l'hôte, y compris celles spécifiées dans les clés optional_permissions ou permissions 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()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

Vérifie si l'extension dispose des autorisations spécifiées.

Paramètres

  • autorisations

    Autorisations

  • rappel

    function facultatif

    Le paramètre callback se présente comme suit: 

    (result: boolean) => void

    • résultat

      booléen

      "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 format de correspondance de script de contenu, false est renvoyé, sauf si les deux autorisations sont accordées.

Renvoie

  • Promise&lt;boolean&gt;

    Chrome 96 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

getAll()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.permissions.getAll(
  callback?: function,
)

Récupère l'ensemble d'autorisations actuel de l'extension.

Paramètres

  • rappel

    function facultatif

    Le paramètre callback se présente comme suit: 

    (permissions: Permissions) => void

    • autorisations

      Autorisations

      Autorisations actives de l'extension. Notez que la propriété origins contient des origines autorisées à partir de celles spécifiées dans les clés permissions et optional_permissions du fichier manifeste, ainsi que celles associées aux scripts de contenu.

Renvoie

  • Promise&lt;Permissions&gt;

    Chrome 96 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

remove()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

Supprime l'accès aux autorisations spécifiées. En cas de problème lors de la suppression des autorisations, runtime.lastError sera défini.

Paramètres

  • autorisations

    Autorisations

  • rappel

    function facultatif

    Le paramètre callback se présente comme suit: 

    (removed: boolean) => void

    • supprimé

      booléen

      "True" si les autorisations ont été supprimées.

Renvoie

  • Promise&lt;boolean&gt;

    Chrome 96 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La la promesse est résolue avec le même type que celui transmis au rappel.

request()

<ph type="x-smartling-placeholder"></ph> Promesse 
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

Demande l'accès aux autorisations spécifiées, en affichant une invite à l'utilisateur si nécessaire. Ces autorisations doivent être définies dans le champ optional_permissions du fichier manifeste ou correspondre à des autorisations requises qui ont été masquées par l'utilisateur. Les chemins d'accès aux formats d'origine seront ignorés. Vous pouvez demander des sous-ensembles d'autorisations d'origine facultatives. Par exemple, si vous spécifiez *://*\/* dans la section optional_permissions du fichier manifeste, vous pouvez demander http://example.com/. Si vous rencontrez des problèmes pour demander les autorisations, runtime.lastError sera défini.

Paramètres

  • autorisations

    Autorisations

  • rappel

    function facultatif

    Le paramètre callback se présente comme suit: 

    (granted: boolean) => void

    • accordée

      booléen

      "True" si l'utilisateur a accordé les autorisations spécifiées.

Renvoie

  • Promise&lt;boolean&gt;

    Chrome 96 ou version ultérieure

    Les promesses sont prises en charge dans Manifest V3 et versions ultérieures, mais les rappels sont fournis pour rétrocompatibilité. Vous ne pouvez pas utiliser les deux sur le même appel de fonction. La 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 acquiert de nouvelles autorisations.

Paramètres

  • rappel

    fonction

    Le paramètre callback se présente comme suit: 

    (permissions: Permissions) => void

onRemoved

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

Déclenché lorsque l'accès aux autorisations a été supprimé pour l'extension.

Paramètres

  • rappel

    fonction

    Le paramètre callback se présente comme suit: 

    (permissions: Permissions) => void