browser.permissions

Description

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

Concepts et utilisation

Les avertissements d'autorisation décrivent 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 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 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". Une fonctionnalité affiche l'objectif du jour de l'utilisateur. Cette fonctionnalité ne nécessite que l'autorisation storage, 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 qui active des fonctionnalités supplémentaires.

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

Avertissement d'extension pour l'API topSites

Implémenter des autorisations facultatives

Étape 1 : Déterminez quelles autorisations sont obligatoires et lesquelles 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 pour les fonctionnalités de base de votre extension.
• Utilisez des 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 l'utilisateur une seule fois à accepter toutes les autorisations.
• 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 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é correspondante.
• 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é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", à 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, à l'exception des suivantes.

Autorisation	Description
"debugger"	L'API browser.debugger sert de transport alternatif pour le protocole de débogage à distance de Chrome.
"declarativeNetRequest"	Accorde à l'extension l'accès à l'API browser.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 géolocalisation HTML5.
"mdns"	Accorde à l'extension l'accès à l'API browser.mdns.
"proxy"	Accorde à l'extension l'accès à l'API browser.proxy pour gérer les paramètres de proxy de Chrome.
"tts"	L'API browser.tts lit la synthèse vocale (TTS).
"ttsEngine"	L'API browser.ttsEngine implémente un moteur de synthèse vocale à l'aide d'une extension.
"wallpaper"	ChromeOS uniquement. Utilisez l'API browser.wallpaper pour modifier le fond d'écran ChromeOS.

Pour en savoir plus sur les autorisations disponibles et les avertissements associés, consultez Déclarer des autorisations.

É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.
  browser.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 à ajouter les autorisations si cela entraîne des 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 générer une invite de ce type :

Exemple d'invite 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() :

browser.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 qu'une autorisation a été supprimée, l'appel de permissions.request() l'ajoute généralement de nouveau sans inviter l'utilisateur à le faire.

browser.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, 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

addHostAccessRequest()

Navigateur Chrome 133+ * depuis Chrome 148 MV3+

browser.permissions.addHostAccessRequest(
  request: object,
): Promise<void>

Ajoute une demande d'accès à l'hôte. La demande ne sera signalée à l'utilisateur que si l'extension peut être autorisée à accéder à l'hôte dans la demande. La requête sera réinitialisée lors de la navigation interorigine. Si elle est acceptée, elle 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 à l'hôte peuvent être affichées. Il doit s'agir du document de premier niveau d'un onglet. Si elle est fournie, la demande 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 demande remplacera toute demande existante pour tabId. Vous devez spécifier ce champ ou tabId.

  • modèle

    chaîne facultatif

    Format d'URL où les demandes d'accès à l'hôte peuvent être affichées. Si elle est fournie, les demandes d'accès à l'hôte ne seront affichées que sur les URL correspondant à ce format.

  • tabId

    number facultatif

    ID de l'onglet dans lequel les demandes d'accès à l'hôte peuvent être affichées. 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 demande remplacera une demande existante pour documentId. Vous devez spécifier ce champ ou documentId.

Renvoie

• Promise<void>

contains()

browser.permissions.contains(
  permissions: Permissions,
): Promise<boolean>

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

Paramètres

• autorisations

  Autorisations

Renvoie

• Promise<boolean>

  Chrome 96+ browser.* depuis Chrome 148

getAll()

browser.permissions.getAll(): Promise<Permissions>

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

Renvoie

• Promise<Permissions>

  Chrome 96+ browser.* depuis Chrome 148

remove()

browser.permissions.remove(
  permissions: Permissions,
): Promise<boolean>

Supprime l'accès aux autorisations spécifiées. Si des problèmes surviennent lors de la suppression des autorisations, la promesse sera rejetée.

Paramètres

• autorisations

  Autorisations

Renvoie

• Promise<boolean>

  Chrome 96+ browser.* depuis Chrome 148

removeHostAccessRequest()

Navigateur Chrome 133+ * depuis Chrome 148 MV3+

browser.permissions.removeHostAccessRequest(
  request: object,
): Promise<void>

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 d'un onglet. Vous devez spécifier ce champ ou tabId.

  • modèle

    chaîne facultatif

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

  • tabId

    number facultatif

    ID de l'onglet dans lequel la demande d'accès à l'hôte sera supprimée. Vous devez spécifier ce champ ou documentId.

Renvoie

• Promise<void>

request()

browser.permissions.request(
  permissions: Permissions,
): Promise<boolean>

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 d'accès des 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 des problèmes surviennent lors de la demande d'autorisations, la promesse sera rejetée.

Paramètres

• autorisations

  Autorisations

Renvoie

• Promise<boolean>

  Chrome 96+ browser.* depuis Chrome 148

Événements

onAdded

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

Se déclenche lorsque l'extension acquiert de nouvelles autorisations.

Paramètres

• callback

  fonction

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

  (permissions: Permissions) => void

  • autorisations

    Autorisations

onRemoved

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

Se déclenche lorsque l'accès aux autorisations a été supprimé de l'extension.

Paramètres

• callback

  fonction

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

  (permissions: Permissions) => void

  • autorisations

    Autorisations