Permission activeTab

Demander la permission activeTab

Votre extension demande activeTab en utilisant la clé de manifeste permissions :

"permissions": ["activeTab"]

activeTab est une permission d'API, et non une permission d'hôte.

Il est également possible d'inclure activeTab dans optional_permissions et de la demander à l'exécution en utilisant permissions.request(). C'est l'une des permissions accordées silencieusement, sans invite de l'utilisateur·ice.

Comment activeTab est accordée

Le navigateur accorde activeTab lorsque l'utilisateur·ice interagit avec l'extension. Ces interactions sont appelées actions de l'utilisateur·ice et incluent le fait que l'utilisateur·ice :

• cliquer sur le bouton de la barre d'outils ou sur l'action de page de l'extension.
• sélectionner un élément du menu contextuel de l'extension, ce qui déclenche l'évènement menus.onClicked.
• activer un raccourci clavier défini par l'extension avec l'API commands, ce qui déclenche l'évènement commands.onCommand.
• cliquer sur une suggestion d'extension dans la barre d'adresse (omnibox), ce qui déclenche l'évènement omnibox.onInputEntered (à partir de Firefox 142).

En général, l'onglet auquel activeTab est accordée est l'onglet actif. Il y a une exception : une extension peut utiliser l'API menus pour créer un élément de menu qui s'affiche lorsque l'utilisateur·ice effectue un clic contextuel sur un onglet dans la barre d'onglets. Si l'utilisateur·ice sélectionne cet élément de menu, activeTab est accordée pour l'onglet cliqué, même s'il n'est pas l'onglet actif.

Qu'est-ce que activeTab accorde

Lorsque activeTab est accordée pour un onglet, l'extension peut :

• Injecter du JavaScript ou du CSS dans l'onglet, en utilisant l'API scripting (ou tabs.executeScript() et tabs.insertCSS() dans le manifeste V2). Voir Charger des scripts de contenu.
• Lire les propriétés privilégiées de l'objet tabs.Tab de l'onglet : url, title et favIconUrl. Sinon, ces propriétés nécessitent la permission "tabs" ou une permission d'hôte correspondante.
• Capturer le contenu de l'onglet avec tabs.captureVisibleTab() (à partir de Firefox 126).
• Lire les règles correspondantes pour l'onglet avec declarativeNetRequest.getMatchedRules(), sans la permission "declarativeNetRequestFeedback".

Étendue de l'accès

activeTab accorde l'accès au script à la page de niveau supérieur dans l'onglet et aux cadres du même origine qu'elle contient. L'exécution de scripts ou la modification des styles à l'intérieur des cadres inter-origine nécessite des permissions d'hôte supplémentaires.

Les restrictions et limitations qui s'appliquent à des sites et schémas URI particuliers s'appliquent également à activeTab. Certaines pages spéciales n'autorisent pas l'injection de scripts, y compris la vue lecteur, view-source, le visualiseur PDF et d'autres pages de l'interface utilisateur intégrée du navigateur.

Quand l'accès prend fin

L'extension ne peut accéder qu'à l'onglet, ou aux données, qui existaient lorsque l'utilisateur·ice a interagi avec elle. Lorsque l'onglet navigue ailleurs, l'extension perd la permission d'y accéder. Cela signifie que l'extension doit terminer son travail avec l'onglet, ou capturer les données dont elle a besoin, pendant la période accordée. Si l'extension a besoin d'un nouvel accès, l'utilisateur·ice doit répéter l'action.

Le moment où l'accès prend fin varie selon le navigateur, voir Quand l'accès est révoqué.

Exemples

Cette extension injecte un script dans la page actuelle lorsque l'utilisateur·ice clique sur son bouton de barre d'outils. Elle n'a besoin d'aucune permission d'hôte.

manifest.json :

{
  "manifest_version": 3,
  "name": "Surbrillance des titres",
  "version": "1.0",
  "permissions": ["activeTab", "scripting"],
  "action": {
    "default_title": "Surbrillance des titres"
  },
  "background": {
    "scripts": ["background.js"]
  }
}

background.js :

function surbrillanceTitres() {
  for (const heading of document.querySelectorAll("h1, h2, h3")) {
    heading.style.backgroundColor = "yellow";
  }
}

browser.action.onClicked.addListener((tab) => {
  // activeTab est accordé pour `tab` parce que l'utilisateur·ice a cliqué sur le bouton de la barre d'outils.
  browser.scripting.executeScript({
    target: { tabId: tab.id },
    func: surbrillanceTitres,
  });
});

Le même clic rend également les propriétés privilégiées de l'onglet lisibles, donc tab.url et tab.title contiennent de vraies valeurs plutôt que undefined.

Autres exemples

Ces autres exemples, disponibles dans le dépôt des extensions exemples à https://github.com/mdn/webextensions-examples, utilisent la permission activeTab :

Compatibilité des navigateurs

Firefox, Safari et les navigateurs basés sur Chromium, y compris Chrome et Edge, prennent en charge activeTab. Cependant, lorsque cette permission est accordée, ce qu'elle permet et le moment où elle est révoquée varient.

Actions qui accordent activeTab

Capacités accordées

Ceci dit, l'accès accordé par les navigateurs avec activeTab diffère :

• Firefox et Safari n'accordent l'accès qu'à l'onglet actif.
• Chrome accorde les permissions d'hôte dérivées de l'URL de l'onglet.

La logique de Chrome peut fournir plus d'accès que celle de Firefox, par exemple :

• Un autre onglet avec la même origine peut être scripté dans Chrome, mais pas dans Firefox.
• Un script d'extension (comme un script d'arrière-plan ou un script de fenêtre intrusive) peut effectuer une requête inter-origine vers l'URL de l'onglet dans Chrome, mais pas dans Firefox.
• L'API cookies nécessite des permissions d'hôte pour accéder aux cookies de domaines spécifiques. Chrome le permet avec activeTab, tandis que Firefox ne le permet pas.

Cette liste n'est pas exhaustive.

Quand l'accès est révoqué

Dans tous les navigateurs, la fermeture de l'onglet révoque l'accès. Cependant, les navigations au sein du même document, comme un changement de fragment (hash) ou un appel à History.pushState(), ne le font pas : le document et son origine restent inchangés, donc l'accès est préservé.

Pour les navigations qui chargent un nouveau document, le comportement diffère :

• Chrome : l'accès persiste tant que l'onglet reste sur la même origine, y compris lors des rechargements. Il est révoqué lorsque l'onglet navigue vers une origine différente.
• Safari : l'accès est lié au document qui se trouve dans l'onglet lorsque l'action de l'utilisateur·ice a eu lieu. Il est révoqué lorsque l'onglet navigue vers une URL différente.
• Firefox : l'accès est lié au document qui se trouve dans l'onglet lorsque l'action de l'utilisateur·ice a eu lieu. Toute navigation entraînant un nouveau document met fin à l'accès, et l'utilisateur·ice doit répéter l'action. Si ce document revient depuis le cache arrière/avant, son accès est restauré.

Autres différences

• Demandes de permission : Firefox et Chrome accordent à une extension les permissions d'hôte demandées lors de l'installation, donc activeTab évite un avertissement au moment de l'installation. Safari, en revanche, définit par défaut les permissions d'hôte sur « demander », et invite l'utilisateur·ice la première fois que l'extension tente d'accéder à un site, offrant Autoriser pour un jour ou Toujours autoriser. L'utilisation de activeTab évite cette invite, car Safari considère l'interaction de l'utilisateur·ice avec l'extension comme l'octroi.
• Manifest V2 et V3 : activeTab fonctionne de la même manière dans les navigateurs en Manifest V3. Dans Firefox Manifest V2, activeTab permet en outre à scripting.executeScript() d'accéder à un iframe avec une origine différente (voir Bogue 1839200 ^(angl.)), mais ce comportement a été supprimé dans MV3.

Voir aussi

• La clé de manifeste permissions
• La clé de manifeste optional_permissions
• Actions de l'utilisateur·ice
• Scripts de contenu
• Demander les bonnes permissions ^(angl.) sur Extension Workshop
• La permission « activeTab » ^(angl.) dans la documentation des extensions Chrome