Declarar permissões

Para usar a maioria das APIs de extensão e recursos, declare a intent da extensão nos campos de permissões do manifesto. As extensões podem solicitar as seguintes categorias de permissões, especificadas usando as respectivas chaves de manifesto:

"permissions"

Contém itens de uma lista de strings conhecidas. As mudanças podem acionar um aviso.

"optional_permissions"

Concedido pelo usuário no momento da execução, em vez de no momento da instalação.

"content_scripts.matches"

Contém um ou mais padrões de correspondência que permitem que scripts de conteúdo sejam injetados em um ou mais hosts. As mudanças podem acionar um aviso.

"host_permissions"

Contém um ou mais padrões de correspondência que dão acesso a um ou mais hosts. As mudanças podem acionar um aviso.

"optional_host_permissions"

Concedido pelo usuário no momento da execução, em vez de no momento da instalação.

As permissões ajudam a limitar os danos se a extensão for comprometida por malware. Alguns avisos de permissão são mostrados aos usuários para consentimento antes da instalação ou no momento da execução, conforme detalhado em Permissão com avisos.

Considere usar permissões opcionais sempre que a funcionalidade da extensão permitir, para oferecer aos usuários controle informado sobre o acesso a recursos e dados.

Se uma API exigir uma permissão, a documentação dela explicará como declará-la. Para um exemplo, consulte a API Storage.

Manifesto

Confira a seguir um exemplo da seção de permissões de um arquivo de manifest:

manifest.json:

{
  "name": "Permissions Extension",
  ...
  "permissions": [
    "activeTab",
    "contextMenus",
    "storage"
  ],
  "optional_permissions": [
    "topSites",
  ],
  "host_permissions": [
    "https://www.developer.chrome.com/*"
  ],
  "optional_host_permissions":[
    "https://*/*",
    "http://*/*"
  ],
  ...
  "manifest_version": 3
}

Permissões do host

As permissões do host permitem que as extensões interajam com os padrões correspondentes do URL. Algumas APIs do Chrome exigem permissões de host, além das próprias permissões da API, que são documentadas em cada página de referência. Veja alguns exemplos:

• Fazer solicitações fetch() do service worker e das páginas de extensão.
• Ler e consultar as propriedades sensíveis da guia (URL, título e favIconUrl) usando a API chrome.tabs.
• Injetar um script de conteúdo de maneira programática.
• Monitorar e controlar as solicitações de rede com a chrome.webRequest API.
• Acessar cookies com a chrome.cookies API.
• Redirecionar e modificar solicitações e cabeçalhos de resposta usando chrome.declarativeNetRequest API.

Permissões com avisos

Quando uma extensão solicita várias permissões e muitas delas mostram avisos na instalação, o usuário verá uma lista de avisos, como no exemplo a seguir:

É mais provável que os usuários confiem em uma extensão com avisos limitados ou quando as permissões são explicadas a eles. Considere implementar permissões opcionais ou uma API menos poderosa para evitar avisos alarmantes. Para conferir as práticas recomendadas para avisos, consulte as diretrizes de avisos de permissão. Avisos específicos são listados com as permissões a que se aplicam na lista de referência de permissões.

Adicionar ou alterar padrões de correspondência nos campos "host_permissions" e "content_scripts.matches" do arquivo de manifesto também acionará um aviso. Para saber mais, consulte Atualizar permissões.

Permitir acesso

Se a extensão precisar ser executada em URLs file:// ou operar no modo de navegação anônima, os usuários precisarão conceder acesso à extensão na página de detalhes. Você pode encontrar instruções para abrir a página de detalhes em Gerenciar suas extensões.

Permitir acesso a URLs de arquivo e páginas de navegação anônima

1. Clique com o botão direito do mouse no ícone da extensão no Chrome.

2. Escolha Gerenciar extensão.

   

3. Role para baixo para ativar o acesso a URLs de arquivo ou ao modo de navegação anônima.

   

Para detectar se o usuário permitiu o acesso, chame extension.isAllowedIncognitoAccess() ou extension.isAllowedFileSchemeAccess().