chrome.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 necessárias.

Visão geral

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 avisos de permissão e introduzam novos recursos gradualmente, o que oferece aos usuários uma introdução segura à extensão. Assim, 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 substitui a página "Nova guia". Um recurso é mostrar a meta do dia do usuário. Esse recurso só exige a permissão de armazenamento, que não inclui um aviso. A extensão tem um recurso extra que pode ser ativado clicando no botão abaixo:

A exibição dos principais sites do usuário requer a permissão topSites, que tem o seguinte aviso.

Como 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, é necessário:

• 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 uma vez.
• Desenvolvimento mais simples:as permissões necessárias estão garantidas.

Vantagens das permissões opcionais:

• Melhor 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 ela precisa de uma permissão específica quando o usuário ativa o recurso relevante.
• Upgrade mais fácil:quando você faz upgrade da 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 permissões:

{
  "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 ela tenha um esquema correspondente.

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

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

Permissão	Descrição
"debugger"	A API chrome.debugger serve como um transporte alternativo para o protocolo de depuração remota do Chrome.
"declarativeNetRequest"	Concede à extensão acesso à API chrome.declarativeNetRequest.
"devtools"	Permite que a extensão expanda a funcionalidade das Chrome DevTools.
"experimental"	Canal Canary e canal de desenvolvedor somente. Concede à extensão acesso às APIs chrome.experimental.
"geolocation"	Permite que a extensão use a API geolocalização do HTML5.
"mdns"	Concede à extensão acesso à API chrome.mdns.
"proxy"	Concede à extensão acesso à API chrome.proxy para gerenciar as configurações de proxy do Chrome.
"tts"	A API chrome.tts reproduz a conversão de texto em voz (TTS) sintetizada.
"ttsEngine"	A API chrome.ttsEngine implementa um mecanismo de conversão de texto em voz (TTS) usando uma extensão.
"wallpaper"	Somente no ChromeOS. Use a API chrome.wallpaper para mudar o plano de fundo do ChromeOS.

Consulte Declarar permissões e avisar os usuários para mais informações sobre as permissões disponíveis e os avisos.

Etapa 3: solicitar permissões opcionais

Solicite as permissões em 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 solicita ao usuário se a adição das permissões resultar em mensagens de aviso diferentes das que o usuário já viu e aceitou. Por exemplo, o código anterior pode resultar em uma solicitação como esta:

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():

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, a chamada de 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 do 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()

Promessa PendenteMV3+

chrome.permissions.addHostAccessRequest(
  request: object,
  callback?: function,
)

Adiciona uma solicitação de acesso ao host. A solicitação só será sinalizada para o 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 aceito, 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 for fornecido, a solicitação será mostrada na guia do documento especificado e removida quando o documento navegar para uma nova origem. A adição de uma nova solicitação substitui qualquer solicitação existente de tabId. É preciso especificar esse ou tabId.

  • padrão

    string opcional

    O padrão de URL em que as solicitações de acesso ao host podem ser mostradas. Se for fornecido, as solicitações de acesso ao host só serão mostradas em URLs que correspondem a esse padrão.

  • tabId

    número opcional

    O ID da guia em que as solicitações de acesso ao host podem ser mostradas. Se fornecido, a solicitação é mostrada na guia especificada e removida quando a guia navega para uma nova origem. A adição de uma nova solicitação vai substituir uma solicitação existente para documentId. É preciso especificar esse ou documentId.

• callback

  função opcional

  O parâmetro callback tem este formato:

  () => void

Retorna

• Promise<void>

  As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 este formato:

  (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, ela retornará false, a menos que as duas permissões sejam concedidas.

Retorna

• Promise<boolean>

  Chrome 96 e versões mais recentes

  As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 este formato:

  (permissions: Permissions) => void

  • permissões

    Permissões

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

Retorna

• Promise<Permissions>

  Chrome 96 e versões mais recentes

  As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

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 este formato:

  (removed: boolean) => void

  • removido

    booleano

    Verdadeiro se as permissões foram removidas.

Retorna

• Promise<boolean>

  Chrome 96 e versões mais recentes

  As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

removeHostAccessRequest()

Promessa PendenteMV3+

chrome.permissions.removeHostAccessRequest(
  request: object,
  callback?: function,
)

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 a solicitação de acesso do host será removida. Precisa ser o documento de nível superior em uma guia. É preciso especificar esse ou tabId.

  • padrão

    string opcional

    O padrão de URL em que a solicitação de acesso ao host será removida. Se fornecido, ele precisa corresponder exatamente ao padrão de uma solicitação de acesso a host.

  • tabId

    número opcional

    O ID da guia em que a solicitação de acesso ao host será removida. É preciso especificar esse ou documentId.

• callback

  função opcional

  O parâmetro callback tem este formato:

  () => void

Retorna

• Promise<void>

  As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

request()

Promessa

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

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 serem 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, o valor runtime.lastError será definido.

Parâmetros

• permissões

  Permissões

• callback

  função opcional

  O parâmetro callback tem este formato:

  (granted: boolean) => void

  • concedido

    booleano

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

Retorna

• Promise<boolean>

  Chrome 96 e versões mais recentes

  As promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

Eventos

onAdded

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

É acionado quando a extensão adquire novas permissões.

Parâmetros

• callback

  função

  O parâmetro callback tem este formato:

  (permissions: Permissions) => void

  • permissões

    Permissões

onRemoved

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

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

Parâmetros

• callback

  função

  O parâmetro callback tem este formato:

  (permissions: Permissions) => void

  • permissões

    Permissões