chrome.permissions

Description

Utilisez l'API chrome.permissions pour demander les autorisations facultatives déclarées au moment de l'exécution plutôt qu'au moment de l'installation. Les utilisateurs comprendront ainsi pourquoi ces autorisations sont nécessaires et n'accorderont que celles qui sont nécessaires.

Présentation

Les avertissements d'autorisation permettent de 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 de présenter progressivement de nouvelles fonctionnalités, ce qui permet aux utilisateurs de découvrir l'extension sans risque. Les utilisateurs peuvent ainsi 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'autorisations facultatives remplace la page "Nouvel onglet". L'une des fonctionnalités affiche l'objectif de l'utilisateur pour la journée. Cette fonctionnalité ne nécessite que l'autorisation stockage, qui n'inclut pas d'avertissement. L'extension dispose d'une fonctionnalité supplémentaire que les utilisateurs peuvent activer en cliquant sur le bouton suivant:

Bouton d'extension permettant d'activer des fonctionnalités supplémentaires

L'affichage des sites les plus consultés par l'utilisateur nécessite l'autorisation topSites, qui est associée à l'avertissement suivant.

Avertissement concernant les extensions 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 général, vous devez:

  • Utilisez les autorisations requises lorsqu'elles sont nécessaires pour les fonctionnalités de base de votre extension.
  • Utilisez des autorisations facultatives lorsque celles-ci sont nécessaires pour les fonctionnalités facultatives de votre extension.

Avantages des autorisations requises:

  • Moins d'invites:une extension peut inviter l'utilisateur une seule fois à accepter toutes les autorisations.
  • Développement plus simple:les autorisations requises sont garanties.

Avantages des autorisations facultatives:

  • Meilleure sécurité:les extensions s'exécutent avec moins d'autorisations, car les utilisateurs n'activent que les autorisations nécessaires.
  • Meilleures informations pour les utilisateurs:une extension peut expliquer pourquoi elle a besoin d'une autorisation particulière lorsque l'utilisateur active la fonctionnalité concernée.
  • Mise à niveau plus facile: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éclarer les autorisations facultatives dans le fichier manifeste

Déclarez les autorisations facultatives dans votre fichier manifeste d'extension avec la clé optional_permissions, en utilisant le même format que le champ autorisations:

{
  "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. Vous pouvez ainsi spécifier n'importe quelle origine dans Permissions.origins, à condition qu'elle dispose d'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, à l'exception des cas suivants.

Autorisation Description
"debugger" L'API chrome.debugger sert 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 de développement Chrome.
"experimental" Canary et version en développement uniquement. Accorde à l'extension l'accès aux API chrome.experimental.
"geolocation" Permet à l'extension d'utiliser l'API géolocalisation HTML5.
"mdns" Accorde à l'extension l'accès à l'API chrome.mdns.
"proxy" Accorde à l'extension l'accès à l'API chrome.proxy pour gérer les paramètres proxy de Chrome.
"tts" L'API chrome.tts lit la synthèse vocale (TTS) synthétisée.
"ttsEngine" L'API chrome.ttsEngine implémente un moteur de synthèse vocale (TTS) à l'aide d'une extension.
"wallpaper" ChromeOS uniquement Utilisez l'API chrome.wallpaper pour modifier le fond d'écran ChromeOS.

Consultez Déclarer des autorisations et avertir les utilisateurs pour en savoir plus sur les autorisations disponibles et les avertissements associés.

Étape 3: Demander des autorisations facultatives

Demandez les autorisations à partir d'un geste 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 génère des messages d'avertissement différents de ceux qu'il a déjà vus et acceptés. Par exemple, le code précédent peut générer une invite comme suit:

exemple d'invite de confirmation d'autorisation

Étape 4: Vérifier 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. Une fois une autorisation supprimée, l'appel de permissions.request() la rétablit généralement sans demander à 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 d'hôte, y compris celles spécifiées dans les clés optional_permissions ou permissions du fichier manifeste, ainsi que 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

addHostAccessRequest()

Promesse En attenteMV3+ 
chrome.permissions.addHostAccessRequest(
  request: object,
  callback?: function,
)

Ajoute une demande d'accès à l'hôte. La requête ne sera signalée à l'utilisateur que si l'extension peut être autorisée à accéder à l'hôte dans la requête. La requête sera réinitialisée lors de la navigation inter-origines. Lorsqu'il est accepté, accorde un accès persistant à l'origine principale du site

Paramètres

  • request

    objet

    • documentId

      chaîne facultatif

      ID d'un document dans lequel les demandes d'accès hôte peuvent s'afficher. Il doit s'agir du document de premier niveau dans un onglet. Si elle est fournie, la requête s'affiche dans l'onglet du document spécifié et est supprimée lorsque le document accède à une nouvelle origine. L'ajout d'une nouvelle requête remplace toute requête existante pour tabId. Vous devez spécifier cet élément ou tabId.

    • modèle

      chaîne facultatif

      Format d'URL dans lequel les requêtes d'accès hôte peuvent s'afficher. Si cette information est fournie, les requêtes d'accès à l'hôte ne s'affichent que pour les URL correspondant à ce format.

    • tabId

      number facultatif

      ID de l'onglet dans lequel les requêtes d'accès à l'hôte peuvent s'afficher. Si elle est fournie, la requête s'affiche dans l'onglet spécifié et est supprimée lorsque l'onglet accède à une nouvelle origine. L'ajout d'une nouvelle requête remplace une requête existante pour documentId. Vous devez spécifier cet élément ou documentId.

  • rappel

    fonction facultatif

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

    () => void

Renvoie

  • Promise<void>

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

contains()

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

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

Paramètres

  • autorisations

    Autorisations

  • rappel

    fonction 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 modèle de correspondance de script de contenu, la valeur false est renvoyée, sauf si les deux autorisations sont accordées.

Renvoie

  • Promise<boolean>

    Chrome 96 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

getAll()

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

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

Paramètres

  • rappel

    fonction 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 les origines accordé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<Permissions>

    Chrome 96 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

remove()

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 est défini.

Paramètres

  • autorisations

    Autorisations

  • rappel

    fonction 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<boolean>

    Chrome 96 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

removeHostAccessRequest()

Promesse En attenteMV3+ 
chrome.permissions.removeHostAccessRequest(
  request: object,
  callback?: function,
)

Supprime une demande d'accès à l'hôte, le cas échéant.

Paramètres

  • request

    objet

    • documentId

      chaîne facultatif

      ID d'un document pour lequel la demande d'accès de l'hôte sera supprimée. Il doit s'agir du document de premier niveau dans un onglet. Vous devez spécifier cet élément ou tabId.

    • modèle

      chaîne facultatif

      Format d'URL pour lequel la demande d'accès de l'hôte sera supprimée. Si cette valeur est fournie, elle doit correspondre exactement au modèle d'une requête d'accès à l'hôte existante.

    • tabId

      number facultatif

      ID de l'onglet dont la demande d'accès à l'hôte sera supprimée. Vous devez spécifier cet élément ou documentId.

  • rappel

    fonction facultatif

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

    () => void

Renvoie

  • Promise<void>

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

request()

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 être des autorisations requises qui ont été refusées par l'utilisateur. Les chemins des formats d'origine sont 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/. En cas de problème lors de la demande des autorisations, runtime.lastError est défini.

Paramètres

  • autorisations

    Autorisations

  • rappel

    fonction 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<boolean>

    Chrome 96 ou version ultérieure

    Les promesses ne sont compatibles qu'avec Manifest V3 et versions ultérieures. Les autres plates-formes doivent utiliser des rappels.

É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é de l'extension.

Paramètres

  • rappel

    fonction

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

    (permissions: Permissions) => void