chrome.permissions

Description

Présentation

Les avertissements relatifs aux autorisations décrivent les fonctionnalités accordées par une API, mais certains de ces avertissements peuvent ne pas être évidents. L'API Permissions permet aux développeurs d'expliquer les avertissements d'autorisation et d'introduire de nouvelles fonctionnalités progressivement, ce qui permet aux utilisateurs de découvrir l'extension sans risque. Ainsi, les utilisateurs peuvent spécifier le niveau d'accès qu'ils souhaitent accorder et les fonctionnalités qu'ils veulent activer.

Par exemple, la fonctionnalité principale de l'extension d'autorisations facultatives consiste à remplacer la page "Nouvel onglet". Une fonctionnalité affiche l'objectif de l'utilisateur pour la journée. Cette fonctionnalité ne nécessite que l'autorisation storage, qui n'inclut pas d'avertissement. L'extension comporte une fonctionnalité supplémentaire que les utilisateurs peuvent activer en cliquant sur le bouton suivant :

L'affichage des principaux sites de l'utilisateur nécessite l'autorisation topSites, qui comporte l'avertissement suivant.

Implémenter les autorisations facultatives

Étape 1 : Déterminez les autorisations requises et celles qui sont 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 aux fonctionnalités de base de votre extension.
• Utilisez les autorisations facultatives lorsqu'elles sont nécessaires pour les fonctionnalités facultatives de votre extension.

Avantages des autorisations requises :

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

Avantages des autorisations facultatives :

• Sécurité renforcée : les extensions s'exécutent avec moins d'autorisations, car les utilisateurs n'activent que celles dont ils ont besoin.
• Meilleures informations pour les utilisateurs : une extension peut expliquer pourquoi elle a besoin d'une autorisation spécifique 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 qu'obligatoires.

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

Déclarez les autorisations facultatives dans le fichier manifeste de votre 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 tant qu'elle possède un schéma correspondant.

Autorisations qui ne peuvent pas être spécifiées comme facultatives

La plupart des autorisations d'extension Chrome peuvent être spécifiées comme facultatives, à l'exception des suivantes.

Pour en savoir plus sur les autorisations disponibles et leurs avertissements, consultez Déclarer les autorisations et avertir les utilisateurs.

Étape 3 : Demander des autorisations facultatives

Demandez les autorisations à partir 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 qu'il a déjà vus et acceptés. Par exemple, le code précédent peut générer une invite comme celle-ci :

É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. 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).
  }
});

chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

chrome.permissions.getAll(
  callback?: function,
): Promise<Permissions>

chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
): Promise<boolean>

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

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