chrome.permissions

Descrição

Conceitos e uso

Os avisos de permissão existem para descrever as capacidades concedidas 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 apresentem novos recursos gradualmente, o que oferece aos usuários uma introdução à extensão sem riscos. 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 é substituir a página "Nova guia". Um recurso é mostrar a meta do dia do usuário. Esse recurso só exige 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:

Para mostrar os principais sites do usuário, é necessário ter a permissão topSites, que tem a seguinte advertência.

Implementar permissões opcionais

Etapa 1: decidir quais permissões são necessárias e quais são opcionais

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

• 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 pedir 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 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 quiser solicitar hosts que você só descobre no tempo de 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 de extensão do Chrome pode ser especificada como opcional, com as seguintes exceções.

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

Etapa 3: pedir 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 ele já viu e aceitou. Por exemplo, o código anterior pode resultar em um prompt como este:

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, chamar permissions.request() geralmente adiciona a permissão novamente sem pedir confirmação 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).
  }
});

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

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

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

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

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

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

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

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