chrome.permissions

Descrição

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

Conceitos e uso

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

Por exemplo, o recurso principal da extensão de permissões opcionais é modificar a página "Nova guia". Um deles é exibir o objetivo do dia do usuário. 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 neste botão:

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

Para exibir os principais sites do usuário, é preciso ter a permissão topSites, que mostra o aviso a seguir.

Aviso de axtensão da API topSites.
Um aviso de extensão para a API topSites

Implementar permissões opcionais

Etapa 1: decidir quais permissões são necessárias e 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 sua 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 uma vez.
  • Desenvolvimento mais simples:é garantido que as permissões necessárias estarão presentes.

Vantagens das permissões opcionais:

  • Maior segurança:as extensões são executadas com menos permissões, já que os usuários só dão acesso a elas. necessários.
  • Informações melhores 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 adiciona permissões opcionais em vez de obrigatórias.

Etapa 2: declarar permissões opcionais no manifesto

Declare permissões opcionais no manifesto de extensões com a chave optional_permissions. com 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ó descobre durante a execução, inclua "https://*/*" no campo optional_host_permissions da extensão. Isso permite especificar qualquer origem em "Permissions.origins", desde que ela tenha uma esquema.

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

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

Permissão Descrição
"debugger" A API chrome.debugger serve como uma transporte alternativo para depuração remota do Google Chrome protocolo.
"declarativeNetRequest" Concede à extensão acesso ao chrome.declarativeNetRequest.
"devtools" Permite que a extensão expanda Chrome DevTools funcionalidade de armazenamento.
"geolocation" Permite que a extensão use a API geolocation do HTML5.
"mdns" Concede à extensão acesso ao chrome.mdns.
"proxy" Concede à extensão acesso à API chrome.proxy para gerenciar o proxy do Chrome configurações.
"tts" A API chrome.tts toca conversão de texto em voz (TTS).
"ttsEngine" A API chrome.ttsEngine implementa uma conversão de texto em voz (TTS) usando uma extensão.
"wallpaper" Somente ChromeOS. Usar a API chrome.wallpaper para mudar o ChromeOS plano de fundo.

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

Etapa 3: solicitar permissões opcionais

Solicite as permissões a partir de um gesto do usuário 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.
  chrome.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 avisa o usuário se a adição das permissões resulta em mensagens de aviso diferentes que o usuário já viu e aceitou. Por exemplo, o código anterior pode resultar em um comando como isso:

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 sua extensão tem uma permissão específica ou um conjunto de permissões, use permission.contains():

chrome.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 não precisar mais delas. Depois que uma permissão é removida, Chamar permissions.request() geralmente adiciona a permissão de volta sem solicitar ao usuário.

chrome.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

contains()

Promessa 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

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

Parâmetros

  • permissões

    Permissões

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (result: boolean) => void

    • resultado

      booleano

      Verdadeiro se a extensão tiver as permissões especificadas. Se uma origem for especificada como uma permissão opcional e um padrão de correspondência de script de conteúdo, será retornado false, a menos que as duas permissões sejam concedidas.

Retorna

  • Promise<boolean>

    Chrome 96 ou versão mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

getAll()

Promessa 
chrome.permissions.getAll(
  callback?: function,
)

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

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (permissions: Permissions) => void

    • permissões

      Permissões

      As permissões ativas da extensão. A propriedade origins vai conter origens concedidas daquelas especificadas nas chaves permissions e optional_permissions do manifesto e as associadas a scripts de conteúdo.

Retorna

  • Promise<Permissions>

    Chrome 96 ou versão mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

remove()

Promessa 
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

Remove o acesso às permissões especificadas. Se houver algum problema ao remover as permissões, runtime.lastError será definido.

Parâmetros

  • permissões

    Permissões

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (removed: boolean) => void

    • removida

      booleano

      Verdadeiro se as permissões foram removidas.

Retorna

  • Promise<boolean>

    Chrome 96 ou versão mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

request()

Promessa 
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

Solicita acesso às permissões especificadas, exibindo 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 algum problema ao solicitar as permissões, runtime.lastError será definido.

Parâmetros

  • permissões

    Permissões

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (granted: boolean) => void

    • concedido

      booleano

      Verdadeiro se o usuário tiver concedido as permissões especificadas.

Retorna

  • Promise<boolean>

    Chrome 96 ou versão mais recente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

Eventos

onAdded

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

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

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (permissions: Permissions) => void

onRemoved

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

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

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (permissions: Permissions) => void