O Chrome agora oferece suporte ao namespace browser.* padronizado (disponível no Chrome 148). Estamos atualizando a documentação gradualmente. Leia mais no nosso guia de transição.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

browser.permissions

Descrição

Use a API chrome.permissions para solicitar permissões opcionais declaradas no momento da execução, em vez de na instalação. Assim, os usuários entendem por que as permissões são necessárias e concedem apenas as que são essenciais.

Conceitos e uso

Os avisos de permissão existem para descrever os recursos concedidos por uma API, mas alguns deles podem não ser óbvios. A API Permissions permite que os desenvolvedores expliquem os avisos de permissão e introduzam novos recursos gradualmente, o que oferece aos usuários uma introdução sem riscos à extensão. Dessa forma, os usuários podem especificar o nível de acesso que querem conceder e quais recursos querem ativar.

Por exemplo, a funcionalidade principal da extensão de permissões opcionais é substituir a página "Nova guia". Um recurso mostra o objetivo do usuário para o dia. Esse recurso requer apenas a permissão storage, que não inclui um aviso. A extensão tem um recurso adicional que os usuários podem ativar clicando no seguinte botão:

Um botão de extensão que ativa recursos adicionais. — Um botão de extensão que ativa outros recursos.

Para mostrar os sites mais acessados pelo usuário, é preciso ter a permissão topSites, que tem o seguinte aviso.

Aviso de extensão para a API topSites. — Um aviso de extensão para a API `topSites`

Implementar permissões opcionais

Etapa 1: decidir quais permissões são obrigatórias e quais são opcionais

Uma extensão pode declarar permissões obrigatórias e opcionais. Em geral, você deve:

Use as permissões necessárias quando elas forem necessárias para a funcionalidade básica da extensão.
Use permissões opcionais quando elas forem necessárias para recursos opcionais na sua extensão.

Vantagens das permissões obrigatórias:

Menos solicitações: uma extensão pode solicitar que o usuário aceite todas as permissões de uma só vez.
Desenvolvimento mais simples: as permissões necessárias estão garantidas.

Vantagens das permissões opcionais:

Mais segurança: as extensões são executadas com menos permissões, já que os usuários só ativam as permissões necessárias.
Melhores informações para os usuários: uma extensão pode explicar por que precisa de uma permissão específica quando o usuário ativa o recurso relevante.
Upgrades mais fáceis: quando você faz upgrade da sua extensão, o Chrome não a desativa para os usuários se o upgrade adicionar permissões opcionais em vez de obrigatórias.

Etapa 2: declarar permissões opcionais no manifesto

Declare permissões opcionais no manifesto da extensão com a chave optional_permissions, usando o mesmo formato do campo permissions:

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "optional_host_permissions": ["https://www.google.com/"],
  ...
}

Se você quiser solicitar hosts que só são descobertos no momento da execução, inclua "https://*/*" no campo optional_host_permissions da extensão. Isso permite especificar qualquer origem em "Permissions.origins", desde que tenha um esquema correspondente.

Permissões que não podem ser especificadas como opcionais

A maioria das permissões de extensão do Chrome pode ser especificada como opcional, com as seguintes exceções.

Permissão	Descrição
`"debugger"`	A API browser.debugger serve como um transporte alternativo para o protocolo de depuração remota do Chrome.
`"declarativeNetRequest"`	Concede à extensão acesso à API browser.declarativeNetRequest.
`"devtools"`	Permite que a extensão amplie a funcionalidade do Chrome DevTools.
`"geolocation"`	Permite que a extensão use a API de geolocalização do HTML5.
`"mdns"`	Concede à extensão acesso à API browser.mdns.
`"proxy"`	Concede à extensão acesso à API browser.proxy para gerenciar as configurações de proxy do Chrome.
`"tts"`	A API browser.tts reproduz a conversão de texto em voz (TTS, na sigla em inglês) sintetizada.
`"ttsEngine"`	A API browser.ttsEngine implementa um mecanismo de conversão de texto em voz (TTS, na sigla em inglês) usando uma extensão.
`"wallpaper"`	Somente no ChromeOS. Use a API browser.wallpaper para mudar o plano de fundo do ChromeOS.

Consulte Declarar permissões para mais informações sobre as permissões disponíveis e os avisos delas.

Etapa 3: solicitar permissões opcionais

Solicite as permissões em uma interação inicial usando 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();
    }
  });
});

O Chrome vai perguntar ao usuário se a adição das permissões resulta em mensagens de aviso diferentes das que o usuário já viu e aceitou. Por exemplo, o código anterior pode resultar em um comando como este:

Exemplo de solicitação de confirmação de permissão. — Um exemplo de solicitação de confirmação de permissão.

Etapa 4: verificar as permissões atuais da extensão

Para verificar se a extensão tem uma permissão ou um conjunto de permissões específico, use 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.
  }
});

Etapa 5: remover as permissões

Remova as permissões quando elas não forem mais necessárias. Depois que uma permissão é removida, chamar permissions.request() geralmente adiciona a permissão de volta sem solicitar ao usuário.

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

Tipos

Permissions

Propriedades

origens

string[] opcional

A lista de permissões de host, incluindo as especificadas nas chaves optional_permissions ou permissions no manifesto e as associadas a scripts de conteúdo.
permissões

string[] opcional

Lista de permissões nomeadas (não inclui hosts ou origens).

Métodos

addHostAccessRequest()

Chrome 133+ browser.* desde o Chrome 148 MV3+

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

Adiciona uma solicitação de acesso ao host. A solicitação só será sinalizada ao usuário se a extensão puder receber acesso ao host na solicitação. A solicitação será redefinida na navegação entre origens. Quando aceita, concede acesso persistente à origem principal do site.

Parâmetros

solicitação

objeto
- documentId
  
  string opcional
  
  O ID de um documento em que as solicitações de acesso ao host podem ser mostradas. Precisa ser o documento de nível superior em uma guia. Se fornecido, o pedido é mostrado na guia do documento especificado e é removido quando o documento navega para uma nova origem. Adicionar uma nova solicitação vai substituir qualquer solicitação atual para tabId. É preciso especificar este ou tabId.
- padrão
  
  string opcional
  
  O padrão do URL em que os pedidos de acesso ao host podem ser mostrados. Se fornecido, os pedidos de acesso do host só vão aparecer em URLs que correspondem a esse padrão.
- tabId
  
  número optional
  
  O ID da guia em que as solicitações de acesso do host podem ser mostradas. Se fornecido, o pedido é mostrado na guia especificada e removido quando a guia navega para uma nova origem. Adicionar uma nova solicitação vai substituir uma existente para documentId. É preciso especificar este campo ou documentId.

Retorna

Promessa<void>

contains()

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

Verifica se a extensão tem as permissões especificadas.

Parâmetros

permissões

Permissões

Retorna

Promise<boolean>

Chrome 96+ browser.* desde o Chrome 148

getAll()

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

Recebe o conjunto atual de permissões da extensão.

Retorna

Promise<Permissions>

Chrome 96+ browser.* desde o Chrome 148

remove()

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

Remove o acesso às permissões especificadas. Se houver algum problema ao remover as permissões, a promessa será rejeitada.

Parâmetros

permissões

Permissões

Retorna

Promise<boolean>

Chrome 96+ browser.* desde o Chrome 148

removeHostAccessRequest()

Chrome 133+ browser.* desde o Chrome 148 MV3+

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

Remove uma solicitação de acesso ao host, se houver.

Parâmetros

solicitação

objeto
- documentId
  
  string opcional
  
  O ID de um documento em que o pedido de acesso do host será removido. Precisa ser o documento de nível superior em uma guia. É preciso especificar este ou tabId.
- padrão
  
  string opcional
  
  O padrão do URL em que a solicitação de acesso do host será removida. Se fornecido, ele precisa corresponder exatamente ao padrão de uma solicitação de acesso de host atual.
- tabId
  
  número optional
  
  O ID da guia em que o pedido de acesso ao host será removido. É preciso especificar este ou documentId.

Retorna

Promessa<void>

request()

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

Solicita acesso às permissões especificadas, mostrando uma solicitação ao usuário, se necessário. Essas permissões precisam ser definidas no campo optional_permissions do manifesto ou ser permissões obrigatórias que foram retidas pelo usuário. Os caminhos nos padrões de origem serão ignorados. É possível solicitar subconjuntos de permissões de origem opcionais. Por exemplo, se você especificar *://*\/* na seção optional_permissions do manifesto, poderá solicitar http://example.com/. Se houver problemas ao solicitar as permissões, a promessa será rejeitada.

Parâmetros

permissões

Permissões

Retorna

Promise<boolean>

Chrome 96+ browser.* desde o Chrome 148

Eventos

onAdded

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

Disparado quando a extensão adquire novas permissões.

Parâmetros

callback

função

O parâmetro callback é semelhante a:
```
(permissions: Permissions) => void
```
- permissões
  
  Permissões

onRemoved

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

Disparado quando o acesso às permissões é removido da extensão.

Parâmetros

callback

função

O parâmetro callback é semelhante a:
```
(permissions: Permissions) => void
```
- permissões
  
  Permissões

browser.permissions Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Descrição

Conceitos e uso

Implementar permissões opcionais

Etapa 1: decidir quais permissões são obrigatórias e quais são opcionais

Etapa 2: declarar permissões opcionais no manifesto

Etapa 3: solicitar permissões opcionais

Etapa 4: verificar as permissões atuais da extensão

Etapa 5: remover as permissões

Tipos

Permissions

Propriedades

Métodos

addHostAccessRequest()

Parâmetros

Retorna

contains()

Parâmetros

Retorna

getAll()

Retorna

remove()

Parâmetros

Retorna

removeHostAccessRequest()

Parâmetros

Retorna

request()

Parâmetros

Retorna

Eventos

onAdded

Parâmetros

onRemoved

Parâmetros

browser.permissions