Declarar permissões

Para usar a maioria das APIs de extensão e recursos, você precisa declarar a intenção 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"

Concedida pelo usuário durante a execução, em vez 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"

Concedida pelo usuário durante a execução, e não na 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 que eles deem consentimento antes da instalação ou durante a 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 vai explicar como declará-la. Para um exemplo, consulte API Storage.

Manifesto

Confira a seguir um exemplo da seção de permissões de um arquivo 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

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

• Faça solicitações fetch() do service worker e das páginas da extensão.
• Leia e consulte as propriedades sensíveis da guia (URL, título e favIconUrl) usando a API chrome.tabs.
• Injete um script de conteúdo de forma programática.
• Monitore e controle as solicitações de rede com a API chrome.webRequest.
• Acesse cookies com a API chrome.cookies.
• Redirecione e modifique solicitações e cabeçalhos de resposta usando a API chrome.declarativeNetRequest.

Em alguns casos especiais, as permissões de host não são necessárias. São eles:

• Usar a API chrome.tabs para acessar e modificar guias, incluindo o URL delas, se você tiver a permissão tabs.
• Interagir com o navegador usando a API chrome.debugger.
• Permitir a injeção de um script de conteúdo declarado no manifesto.

Permissões com avisos

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

Os usuários tendem a confiar mais em uma extensão com poucos avisos ou quando as permissões são explicadas. Considere implementar permissões opcionais ou uma API menos potente para evitar avisos alarmantes. Para conferir as práticas recomendadas sobre avisos, consulte as diretrizes de avisos de permissão. Os avisos específicos são listados com as permissões a que se aplicam na lista de referência Permissões.

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

Permitir acesso

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

Permitir acesso a URLs de arquivos e páginas anônimas

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

2. Escolha Gerenciar extensão.

   

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

   

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